docs: explain SSRF egress interaction

[omribz156]

Summary

Fixes #4209.

This clarifies that adding a host to the sandbox egress policy does not bypass OpenShell's separate SSRF protection. The network-policy page now calls out that endpoint, port, method, and binary policy checks are separate from internal-address blocking, and points runtime binary/download failures toward build-time sandbox image installation with nemoclaw onboard --from.

The security best-practices page also adds a short cross-reference from Network Controls back to the detailed policy page.

Related Issue

Closes #4209.

Changes

• Documentation update
• Code change
• Test update
• Bug fix
• New feature

Verification

• I have tested the changes locally
• I have updated relevant documentation
• I have added/updated tests
• All tests pass

Verification run:

• git diff --check
• rg -n "SSRF|internal-address|onboard --from|egress policy permits" docs/network-policy/customize-network-policy.mdx docs/security/best-practices.mdx
• npx --yes fern-api@5.35.4 check from fern/ reported Found 0 errors and 2 warnings, then exited with a Windows libuv assertion (Assertion failed: !(handle->flags & UV_HANDLE_CLOSING))

Implemented with Codex assistance; I manually scoped and reviewed the docs-only patch.

Signed-off-by: Omri SirComp omribz156@gmail.com

Summary by CodeRabbit

• Documentation
  • Clarified how SSRF protection continues to apply alongside egress allowlists.
  • Explained interaction between egress rules and internal-address blocking, with a link to network policy guidance.
  • Recommended onboarding installers/binaries at image build time when runtime egress is blocked.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: 0a10d162-b1e2-42ce-aef1-2ff18088089b

📥 Commits

Reviewing files that changed from the base of the PR and between 33b94cb and b8df878.

📒 Files selected for processing (2)

• docs/network-policy/customize-network-policy.mdx
• docs/security/best-practices.mdx

💤 Files with no reviewable changes (2)

• docs/security/best-practices.mdx
• docs/network-policy/customize-network-policy.mdx

---

📝 Walkthrough

Walkthrough

This PR adds documentation clarifications explaining that OpenShell's SSRF protection operates independently from the network egress whitelist. A warning in the network policy guide and a note in security best practices explain the interaction and advise onboarding binaries at image build time when SSRF denials occur.

Changes

SSRF Protection and Egress Policy Interaction

Layer / File(s)	Summary
Warning callout and best-practices cross-reference docs/network-policy/customize-network-policy.mdx, docs/security/best-practices.mdx	Adds a warning that allowing a host in egress requires matching endpoint/port/method/binary rules and that OpenShell's SSRF protection can still block responses that resolve to internal addresses; directs developers to install/onboard binaries at image build time (e.g., nemoclaw onboard --from) when runtime downloads fail.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Poem

🐰 A whitelist says "go," but the guard says "no,"
OpenShell watches where your responses go.
If downloads stall and SSRF bars the gate,
Onboard your tools before runtime's late.
Hop in the Dockerfile — save yourself the wait.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'docs: explain SSRF egress interaction' directly captures the main change: documenting how OpenShell's SSRF protection interacts with egress policies, which is the primary objective.
Linked Issues check	✅ Passed	The PR fully addresses all coding requirements from issue #4209: adds a Warning note to customize-network-policy.mdx explaining SSRF and egress separation, adds a cross-reference in best-practices.mdx, and clarifies the build-time install pattern.
Out of Scope Changes check	✅ Passed	All changes are directly scoped to issue #4209: documentation additions explaining SSRF egress interaction in two specified files. No extraneous modifications are present.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[wscurran]

✨ Thanks for submitting this detailed PR that clarifies the interaction between SSRF protection and the sandbox egress policy. This proposes a fix for the documentation issue reported in #4209 and updates the security best-practices page to include a cross-reference to the detailed policy page.

---

Related open issues:

• #4209 [docs] Explain that SSRF protection blocks CDN binary downloads independently of the egress whitelist