fix(security): align SSRF denylists and reject endpoint userinfo

[apurvvkumaria]

Summary

NemoClaw now applies the same expanded special-purpose address protections across the CLI and plugin SSRF validators. Direct blueprint runs also reject endpoint URLs with embedded credentials before DNS resolution, preventing credential-bearing URLs from reaching the resolver.

This hardens an existing supported security boundary. It does not add a product integration or require a product, business, or architecture decision.

Changes

• Block reserved and special-purpose IPv4 and IPv6 destinations, including metadata and benchmarking ranges.
• Reject metadata hostnames and endpoint URL userinfo before DNS resolution.
• Keep the CLI, plugin, policy data, and package-contract behavior aligned.
• Document the expanded endpoint validation behavior and add boundary and parity coverage.

Type of Change

• Code change (feature, bug fix, or refactor)
• Code change with doc updates
• Doc only (prose changes, no code sample modifications)
• Doc only (includes code sample changes)

Quality Gates

• Tests added or updated for changed behavior
• Existing tests cover changed behavior — justification:
• Tests not applicable — justification:
• Docs updated for user-facing behavior changes
• Docs not applicable — justification:
• Sensitive paths changed (security, policy, credentials, preflight, onboarding, inference, runner, sandbox, or messaging)
• Sensitive-path review completed or maintainer-approved waiver recorded — reviewer/approval link/justification: Nine-category security review for the current branch passed at abee3d4a1f2c8812a05af7f04372870adbda9c21; no blocking finding or waiver remains.
• Non-success, skipped, or missing CI check accepted by maintainer — check name, approval link, and follow-up issue:

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: Updated docs/inference/custom-endpoint-security.mdx documents rejection of embedded endpoint credentials before DNS and the aligned special-purpose IPv4, IPv6, and metadata destination restrictions. Reviewed the writing rules and documentation style at refreshed head abee3d4a1f2c8812a05af7f04372870adbda9c21; all nine PR-owned paths are byte-identical to the prior reviewed head, and attribution remains preserved. Generated and inspected the OpenClaw, Hermes, and Deep Agents variants, confirmed shared security guidance, correct agent-specific CLI names, omitted the section that does not apply to Deep Agents, and found no unresolved <AgentOnly> markers. The full docs build passed with 0 errors and 2 non-failing Fern warnings; 355 focused SSRF, MCP, and parity tests, both builds, both typechecks, and diff and cleanliness validation also passed.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit:
• Station profile/scenario:
• Result:
• Supporting evidence:

Verification

• PR description includes a Signed-off-by: line and every commit appears as Verified in GitHub
• Normal pre-commit, commit-msg, and pre-push hooks passed, or npm run validate:pr passed after refreshing origin/main when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — plugin SSRF 102/102; package-contract SSRF parity 219/219; MCP target integration 34/34; CLI and plugin builds and typechecks passed at the refreshed exact head.
• Applicable broad gate passed — not applicable; the full validate:pr fallback and focused SSRF, cross-package parity, and MCP integration suites exercise the affected consumers.
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs builds without warnings (doc changes only) — build passed with 0 errors and 2 non-failing Fern warnings.
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

Signed-off-by: Ayush7614 ayushknj3@gmail.com
Signed-off-by: Apurv Kumaria akumaria@nvidia.com

Summary by CodeRabbit

• Security
  • Expanded protection against requests to special-purpose, metadata, multicast, documentation, and deprecated network addresses.
  • Blocked public hostnames resolving to restricted destinations.
  • Rejected endpoint URLs containing embedded usernames or passwords before DNS lookup, without exposing credentials.
  • Added protection for the IANA Dummy IPv6 range and the metadata hostname.
• Documentation
  • Updated URL validation guidance and clarified that credentials must be configured separately.

[apurvvkumaria]

Security review: PASS

Reviewed revision 8cbb092a7 across all changed source, policy, test, and documentation files.

Category	Result	Evidence
Secrets and credentials	Pass	No credentials are added. Endpoint userinfo is rejected before DNS resolution, and the fixed error does not echo the URL.
Authentication and authorization	Pass	No authentication or authorization boundary changes.
Input validation	Pass	IPv4, IPv6, hostname, and userinfo validation fail closed; boundary and credential-form tests cover the new cases.
Injection and execution	Pass	No new command, shell, template, or code-execution path.
Cryptography	Pass	No cryptographic behavior changes.
Dependencies and supply chain	Pass	No dependency or lockfile changes.
Network and SSRF controls	Pass	CLI and plugin denylists now cover the same reserved and special-purpose destinations, including metadata targets; DNS results are checked against the expanded set.
Data exposure and logging	Pass	Credential-bearing endpoint URLs are rejected without being included in the validation error.
Privilege and sandbox boundaries	Pass	No new privilege, capability, mount, or sandbox escape surface. Network policy becomes more restrictive.

Validation completed successfully:

• Plugin SSRF tests: 101/101
• Package-contract SSRF parity tests: 219/219
• MCP target integration tests: 34/34
• Plugin build, CLI typecheck, repository checks, hooks, secret scan, and documentation build

No blocking security findings remain.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change expands SSRF blocklists for special-purpose IPv4, IPv6, and metadata destinations. Endpoint validation rejects embedded URL credentials before DNS lookup. Tests add boundary, parity, and credential-redaction coverage.

Changes

SSRF policy and endpoint validation

Layer / File(s)	Summary
Special-purpose destination policy nemoclaw-blueprint/private-networks.yaml, src/lib/security/mcp-url-target.ts, test/mcp-url-target.test.ts, test/package-contract/ssrf-parity.test.ts, nemoclaw/src/blueprint/private-networks.ts, src/lib/private-networks.ts	The blocklists add special-purpose IPv4 and IPv6 ranges and the metadata hostname. MCP and shared-network tests cover boundary and parity behavior.
Embedded credential rejection nemoclaw/src/blueprint/ssrf.ts, nemoclaw/src/blueprint/ssrf.test.ts, docs/inference/custom-endpoint-security.mdx	validateEndpointUrl rejects usernames and passwords before DNS lookup. Tests verify credential redaction, and documentation describes separate credential configuration.

Estimated code review effort: 3 (Moderate) | ~20 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely summarizes the two main changes: aligned SSRF denylists and rejection of endpoint userinfo.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/pr7764-verified

---

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

[github-code-quality]

Code Coverage Overview

Languages: TypeScript

TypeScript / code-coverage/plugin

The overall coverage in commit abee3d4 in the codex/pr7764-verifie... branch remains at 96%, unchanged from commit 2b68aa1 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit abee3d4 in the codex/pr7764-verifie... branch remains at 81%, unchanged from commit 2b68aa1 in the main branch.

Show a code coverage summary of the most impacted files.

File	main 2b68aa1	codex/pr7764-verifie... abee3d4	+/-
src/lib/inferen...er-discovery.ts	88%	87%	-1%
src/lib/actions...air-approval.ts	90%	89%	-1%
src/lib/onboard...-transaction.ts	94%	94%	0%
src/lib/private-networks.ts	93%	93%	0%
src/lib/runner.ts	79%	79%	0%
src/lib/sandbox...rce-identity.ts	87%	87%	0%
src/lib/securit...p-url-target.ts	100%	100%	0%
src/lib/shields/index.ts	73%	74%	+1%
src/lib/onboard...box-recovery.ts	87%	89%	+2%
src/lib/inferen...a/model-size.ts	83%	96%	+13%

---

_{Updated August 05, 2026 13:30 UTC}

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-8321.docs.buildwithfern.com/nemoclaw

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@nemoclaw/src/blueprint/ssrf.ts`:
- Around line 63-67: Update the URL parse-error handling near the credential
check in ssrf.ts to avoid exposing raw userinfo when new URL(url) rejects
malformed credential-bearing input; use a generic parse error or redact all
username and password values before including the URL. In ssrf.test.ts, add a
malformed credential case asserting the thrown error omits every credential
value.

🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: bc1bac98-51e7-4b65-a2fe-4afb26cd8369

📥 Commits

Reviewing files that changed from the base of the PR and between a82887e and 8cbb092.

📒 Files selected for processing (9)

• docs/inference/custom-endpoint-security.mdx
• nemoclaw-blueprint/private-networks.yaml
• nemoclaw/src/blueprint/private-networks.ts
• nemoclaw/src/blueprint/ssrf.test.ts
• nemoclaw/src/blueprint/ssrf.ts
• src/lib/private-networks.ts
• src/lib/security/mcp-url-target.ts
• test/mcp-url-target.test.ts
• test/package-contract/ssrf-parity.test.ts

[github-actions]

PR Review Advisor — No blocking findings reported

Advisor assessment: No blocking advisor findings reported
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 1 warning · 0 suggestions
• Model comparison: normalized findings differ; normalized terminology decisions differ; normalized E2E selections match; Nemotron reported the same number of blockers, 1 more warning, the same number of suggestions.

5 terminology differences from the second opinion

Advisory only. These are normalized differences from the primary terminology receipt.

• special-purpose at docs/inference/custom-endpoint-security.mdx:30: selected only by the second-opinion lane as justified.
• SRv6 at nemoclaw-blueprint/private-networks.yaml:134: selected only by the second-opinion lane as justified.
• AS112 at nemoclaw-blueprint/private-networks.yaml:67: selected only by the second-opinion lane as justified.
• Dummy IPv6 Prefix at nemoclaw-blueprint/private-networks.yaml:116: selected only by the second-opinion lane as justified.
• metadata at nemoclaw-blueprint/private-networks.yaml:154: selected only by the second-opinion lane as justified.

Second-opinion terminology and E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

2 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• established — userinfo at docs/inference/custom-endpoint-security.mdx:34: Keep `userinfo`; the changed sentence defines the term with an embedded username or password example.
• justified — special-purpose address at docs/inference/custom-endpoint-security.mdx:30: Keep `special-purpose address`; the modifier identifies the added non-private address classes.

E2E guidance

Advisory only. E2E / PR Gate selects and runs jobs independently.

Recommended E2E: cloud-inference, full-e2e, hermes-e2e, hermes-inference-switch, managed-image-multiarch-startup, security-posture, inference-routing, network-policy

Workflow run details

This automated review informs maintainers. Warnings and suggestions do not require a response. A maintainer decides whether to merge.

[apurvvkumaria]

Security review update: PASS

Reviewed revision 3e07ed163 after the malformed-URL feedback fix.

The earlier nine-category review remains valid. The additional change improves the secrets-and-credentials and input-validation findings: URL parse failures now return a generic message instead of including attacker-controlled input, so malformed username/password forms cannot expose credential values through the error path. The regression covers combined, username-only, and password-only malformed forms and confirms DNS is not queried.

Validation passed:

• Plugin SSRF tests: 102/102
• Package-contract SSRF parity tests: 219/219
• Plugin build, diff-scoped hooks, secret scan, and push type checks
• Documentation writer review and docs build: 0 errors, 2 existing warnings

No blocking security findings remain.

[apurvvkumaria]

The Nemotron advisor lane failed after completing its analysis because its own receipt validator rejected a not_applicable entry that retained a finding identifier. This is an advisor-runtime failure, not a failure in the PR implementation. I reran that failed lane once and will reconcile the result before merge. The remaining merge blocker is independent approval after the required checks settle.

[apurvvkumaria]

Follow-up: the one permitted rerun of the Nemotron advisor lane passed. The current branch now has 44 passing checks, no pending or failed checks, and no unresolved review threads. The remaining merge blocker is independent approval.

[cv]

Sensitive-Path Security Review

Result: PASS

• Reviewed commit: abee3d4a1f2c8812a05af7f04372870adbda9c21
• Base commit: 2b68aa1d5c7f75c12b4739fd59655dd2d08a0226
• Scope: SSRF destination policy parity and direct-blueprint endpoint URL validation. The three refreshes from main changed no PR-owned path.

Nine-Category Assessment

1. Secrets and credentials: PASS. Malformed URL errors are generic, embedded user information is rejected before DNS, and tests confirm credential values are not exposed.
2. Input validation: PASS. URL parsing, scheme, user information, hostname, DNS result, and expanded special-purpose CIDR checks fail closed.
3. Authentication and authorization: PASS. The change does not alter an authentication or authorization boundary.
4. Dependencies and supply chain: PASS. The PR adds no dependency or fetched artifact.
5. Error handling and logging: PASS. Errors do not echo endpoint credentials. Resolver failures identify only the hostname.
6. Cryptography: PASS. The PR adds or changes no cryptographic behavior.
7. Configuration and deployment: PASS. Network policy becomes more restrictive and adds no port, permission, or debug exposure.
8. Tests: PASS. For the reviewed commit, 102 plugin SSRF tests, 34 MCP URL-target tests, and 219 compiled-artifact parity tests passed. Both builds, both type checks, the full PR validation fallback, and the docs build also passed.
9. System security: PASS. The SSRF boundary is strengthened consistently across policy data and consumers. DNS pinning remains intact, and no time-of-check/time-of-use protection is weakened.

No blocking security finding or waiver remains. Attribution is preserved because all refreshes are signed merge commits and do not rewrite contributor commits.

[cv]

Historical gate result for PR commit 272eda70e78db7ba6a0448569cc02562e03c23e9 against base commit d71d892aa5df46e25b67120f9e654a727abd49db:

• Ordinary required checks passed.
• Six selected E2E jobs in run 31008776090 failed at Restore exact-commit CLI artifact before PR behavior ran.
• Merged PR fix(ci): restore complete CLI build artifact #8335 corrected that trusted-workflow bootstrap defect.

This evidence is superseded by current PR commit abee3d4a1f2c8812a05af7f04372870adbda9c21, which includes #8335. Security review, documentation writer review, local validation, both builds and type checks, and 355 focused tests pass for that commit. The new required E2E run is pending. No result is waived. No bypass or unsafe auto-merge is requested.

[apurvvkumaria]

CI classification: the validated CLI artifact restore step fails before this PR’s target tests because node bin/nemoclaw.js --version cannot load nemoclaw/dist/shared/sandbox-name.cjs. The same deterministic failure appears in inference routing, network policy, Hermes E2E, Hermes inference switch, cloud inference, and full E2E; artifact download, digest, and provenance validation succeeded first.

This PR does not modify CLI artifact packaging or name-validation paths, so the failure is not caused by its SSRF/private-network changes. The shared packaging defect has been corrected on main by #8335. Refreshing this branch from current main should bring in that correction before the required E2E checks are run again.

This PR still requires an independent approval and successful required checks before merge.

[apurvvkumaria]

Follow-up: the repaired E2E run completed successfully across all selected lanes, including managed-image startup on both architectures, inference routing, network policy, Hermes, cloud inference, full E2E, and both security-posture variants. All 45 current checks now pass, the one advisor protocol retry passed, and no review threads remain unresolved. Independent approval is the only remaining merge gate.

[cv]

Approved at head abee3d4 against base 2b68aa1. This hardens the existing supported SSRF boundary. The repository gate checker reports all 60 current checks green, no conflicts, no unresolved major or critical CodeRabbit findings, risky-path test coverage, a valid DCO declaration, and all nine commits GitHub Verified. The documentation writer and nine-category security reviews are current, the trusted E2E gate passed, and contributor attribution is preserved.