ci(security): add reviewed npm audit exceptions

[senthilr-nv]

Summary

Keep npm audit running for reviewed production graphs while allowing only explicit, exact, short-lived exceptions for future high or critical advisories. The exception registry is empty in this PR. Current main includes the OpenClaw 2026.7.1 dependency remediation, and the reviewed OpenClaw graph reports zero known vulnerabilities.

Changes

• Add an empty-by-default ci/npm-audit-exceptions.json registry and a shared evaluator for the reviewed CI graph and OpenClaw image builds.
• Require each future exception to match the advisory, graph, package, installed version, and severity, with a decision, rationale, owner, NemoClaw tracker, expiry within 30 days, and compensating controls for temporary risk acceptance.
• Fail closed for malformed, expired, overlong, duplicate, mismatched, unused, or unknown-graph entries while continuing to report lower-severity findings without blocking.
• Upload raw npm reports plus normalized policy results, retain registry signature verification as a separate control, and bind the exception-policy hash, audit status, and accepted advisory IDs into base-image provenance.
• Protect the policy and evaluator with security and maintainer CODEOWNERS and rebuild the OpenClaw base image when either changes.
• Stage the shared evaluator in optimized sandbox build contexts so local and CI image assembly use the same policy path.
• Revalidate the exception registry with the shared expiry-enforcing parser before a child image can reuse matching trusted-base provenance.

The current consumers are the required reviewed npm audit job and the mcporter install in Dockerfile.base and Dockerfile. A raw npm audit --audit-level=high command cannot express one-advisory risk acceptance without suppressing unrelated findings, so the shared evaluator performs exact matching. test/reviewed-npm-audit.test.ts, the mcporter supply-chain test, the OpenClaw provenance suites, and sandbox build-context tests protect this contract.

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 — pending security-maintainer review
• Non-success, skipped, or missing CI check accepted by maintainer — E2E / PR Gate requires maintainer approval of the credentialed cloud-onboard skip in https://github.com/NVIDIA/NemoClaw/actions/runs/30031620717

Documentation Writer Review

• Documentation writer subagent reviewed the completed changes
• Result: docs-updated
• Evidence: agents/openclaw/dependency-review.md, docs/security/openclaw-2026.6.10-dependency-review.md, and docs/security/openclaw-2026.7.1-dependency-review.md; the final fix enforces their existing fail-closed expiry contract before trusted-base reuse and requires no additional documentation.
• Agent: Codex Desktop

DGX Station Hardware Evidence

• Tested on DGX Station
• Tested commit: Not applicable; scripts/prepare-dgx-station-host.sh is unchanged.
• Station profile/scenario: Not applicable.
• Result: Not applicable.
• Supporting evidence: Not applicable.

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; official Hadolint v2.14.0 was run manually because it is unavailable on the host
• Targeted behavior tests pass for the current change set — 69 tests passed across the fetch-guard Docker harness, reviewed-audit, and OpenClaw provenance suites on the final change set
• Applicable broad gate passed — primary CI, all eight CLI shards, CodeQL, macOS, and WSL passed; the credentialed fork E2E skip still requires maintainer approval
• Quality Gates section completed with required justifications or waivers
• No secrets, API keys, or credentials committed
• npm run docs passed (Fern reported zero errors and two non-blocking warnings)
• Doc pages follow the style guide
• New doc pages include SPDX header and frontmatter — not applicable to this PR against current main

Current main contains the dependency remediations that previously blocked this PR. This PR deliberately adds no audit exception; it adds only the empty-by-default framework for future reviewed exceptions.

---

Signed-off-by: Senthil Ravichandran senthilr@nvidia.com

Summary by CodeRabbit

• Security & Reliability
  • Added a reviewed npm audit gate that blocks on high/critical findings using a validated exception registry (including expiration and exact advisory matching).
  • Build and provenance now include audit exception policy details, accepted advisories, and updated audit/provenance recipe/schema.
  • Improved fail-closed behavior when audit evidence or audit-policy/provenance markers don’t align.
• CI
  • CI now re-runs relevant image builds when audit exception inputs are changed.
• Documentation
  • Updated dependency review/audit gate guidance to match the new reviewed audit flow and failure modes.
• Tests
  • Expanded tests for audit exceptions, threshold outcomes, provenance integrity, and build-context artifacts.

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

This change adds reviewed npm audit policy evaluation, integrates it into mcporter graph audits and Docker builds, records audit metadata in provenance, and expands related tests, documentation, build triggers, and ownership rules.

Changes

Reviewed npm audit and provenance

Layer / File(s)	Summary
Audit policy and graph evaluation scripts/lib/reviewed-npm-audit.mts, scripts/audit-reviewed-npm-graph.mts, ci/*.json, test/reviewed-npm-audit.test.ts	Adds strict exception parsing, audit-report evaluation, blocking-finding detection, policy results, CLI execution, schema validation, repository-bounded paths, and coverage for matching, expiry, graph restrictions, and fail-closed behavior.
Docker audit integration Dockerfile, Dockerfile.base, src/lib/sandbox/build-context.ts, test/fetch-guard-patch-regression.test.ts, test/mcporter-supply-chain.test.ts, .github/workflows/base-image.yaml, .github/CODEOWNERS	Copies reviewed audit assets into build contexts, replaces low-threshold npm audit commands with the reviewed evaluator, passes exception policies during reinstalls, and updates build triggers and ownership.
Provenance contract validation test/openclaw-integrity-pin-suite.ts, test/openclaw-dependency-review.test.ts, docs/security/*.md, agents/openclaw/dependency-review.md	Updates schema 3 provenance expectations with audit policy hashes, statuses, accepted advisories, and reviewed-audit recipes, including corresponding documentation and failure-mode tests.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant DockerBuild
  participant ReviewedAudit as reviewed-npm-audit.mts
  participant Npm
  participant Provenance
  DockerBuild->>ReviewedAudit: audit mcporter-runtime with exceptions
  ReviewedAudit->>Npm: run npm audit --json
  Npm-->>ReviewedAudit: report and findings
  ReviewedAudit-->>DockerBuild: policy status, accepted advisories, policy SHA
  DockerBuild->>Provenance: write audit fields and recipe

Loading

Possibly related PRs

• NVIDIA/NemoClaw#7354: Both changes modify the reviewed npm graph audit and provenance pipeline.

Suggested labels: feature, dependencies

Suggested reviewers: cv

🚥 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 accurately summarizes the main change: adding reviewed npm audit exceptions for CI/security workflows.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: No advisor follow-up needed.
Findings: 0 blockers · 0 warnings · 0 suggestions
Status: No actionable findings remain in the canonical review ledger.

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 · 0 warnings · 0 suggestions
• Model comparison: normalized findings match; normalized E2E selections differ; severity counts match.

Nemotron output stays in workflow artifacts and does not change the assessment above.

E2E guidance

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

Recommended E2E: cloud-onboard

Workflow run details

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

[senthilr-nv]

@apurvvkumaria Could you please confirm whether this approach will cover our needs for upcoming CVEs?

The default exception list is empty, and any temporary exception must match the exact advisory, production graph, package, installed version, and severity. It also requires an owner, tracker, rationale, compensating controls, and an expiry within 30 days, while unrelated or future findings continue to fail the audit.

Does this give us the reviewable control needed to proceed with E2E for a known, temporarily accepted CVE without weakening the audit gate for other vulnerabilities? Please flag any additional control you think is required.

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

scripts/lib/reviewed-npm-audit.mts (1)

455-461: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

Add a timeout to the npm audit spawn. spawnSync currently has no bound, so a stalled registry or hung npm process can block this security gate indefinitely. Since result.error is already thrown, a timed-out run fails closed.

♻️ Suggested change

   const result = spawnSync("npm", ["audit", "--omit=dev", "--json"], {
     cwd: options.directory,
     encoding: "utf-8",
     env: { ...process.env, NPM_CONFIG_UPDATE_NOTIFIER: "false" },
     maxBuffer: 64 * 1024 * 1024,
     stdio: ["ignore", "pipe", "pipe"],
+    timeout: 5 * 60 * 1000,
   });

🤖 Prompt for 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.

In `@scripts/lib/reviewed-npm-audit.mts` around lines 455 - 461, Update the
spawnSync invocation in the npm audit execution flow to include an appropriate
timeout option, while preserving the existing result.error handling so timed-out
audits fail closed. Keep the current command, environment, buffering, and stdio
configuration unchanged.

🤖 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 `@src/lib/sandbox/build-context.ts`:
- Around line 276-279: Update the sandbox build-context staging flow around the
reviewed-npm-audit script copy to also stage ci/npm-audit-exceptions.json for
optimized contexts. Extend the corresponding fixture and assertion in the
sandbox build-context test so the policy file’s staged path and presence are
verified.

---

Nitpick comments:
In `@scripts/lib/reviewed-npm-audit.mts`:
- Around line 455-461: Update the spawnSync invocation in the npm audit
execution flow to include an appropriate timeout option, while preserving the
existing result.error handling so timed-out audits fail closed. Keep the current
command, environment, buffering, and stdio configuration unchanged.

🪄 Autofix (Beta)

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: f96555b0-f42f-47a7-97c1-34b7e0945fb1

📥 Commits

Reviewing files that changed from the base of the PR and between f992494 and 57a91e5.

📒 Files selected for processing (18)

• .github/CODEOWNERS
• .github/workflows/base-image.yaml
• Dockerfile
• Dockerfile.base
• agents/openclaw/dependency-review.md
• ci/npm-audit-exceptions.json
• ci/reviewed-npm-audit.json
• docs/security/openclaw-2026.6.10-dependency-review.md
• docs/security/openclaw-2026.7.1-dependency-review.md
• scripts/audit-reviewed-npm-graph.mts
• scripts/lib/reviewed-npm-audit.mts
• src/lib/sandbox/build-context.ts
• test/fetch-guard-patch-regression.test.ts
• test/mcporter-supply-chain.test.ts
• test/openclaw-dependency-review.test.ts
• test/openclaw-integrity-pin-suite.ts
• test/reviewed-npm-audit.test.ts
• test/sandbox-build-context.test.ts

[apurvvkumaria]

Blocking: expired exceptions do not fail closed on trusted-base reuse.

Dockerfile lines 320-357 hashes and directly parses the registry, derives the expected provenance, and reuses a matching trusted base without invoking the shared evaluator. If an exception was valid when Dockerfile.base produced the marker but is expired when this child image is built, the bytes/hash and accepted-advisory list still match, so USE_REVIEWED_BASE_RUNTIME becomes 1 and the expired high/critical exception remains accepted indefinitely. This contradicts the PR’s core contract that expired exceptions fail closed.

Please validate the registry with the shared policy parser at child-build time before provenance reuse (or bind and enforce a freshness/expiry value in provenance), and add a regression where a matching schema-3 base marker plus an expired mcporter exception cannot take the reuse path.

Non-blocking/fix-forward: bounding the npm audit spawn with a timeout would improve gate availability, but it need not block this PR.

[senthilr-nv]

@apurvvkumaria Addressed the blocking trusted-base expiry finding in 8e52364. The child build now parses the exception registry through the shared parseAuditExceptionRegistry path before it can construct matching provenance or reuse the base runtime, so an expired entry fails closed at child-build time. Added a regression with matching schema-3 provenance and an expired mcporter exception; it exits nonzero before either OpenClaw or mcporter reuse. After syncing current main, the focused audit/provenance/dependency-review/build-context suite passes 61/61. Please re-review when convenient.

[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 `@test/openclaw-integrity-pin-suite.ts`:
- Around line 273-290: Update the embedded audit parser exported as
parseAuditExceptionRegistry to validate each entry.expires before constructing
expiresAt. Reject values that are not YYYY-MM-DD strings or produce a non-finite
date, while preserving the existing expired-date error for valid past dates and
the clean result flow for valid future dates.

🪄 Autofix (Beta)

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: 3bfc2aba-4f50-4947-9f7b-ed73b350cfb6

📥 Commits

Reviewing files that changed from the base of the PR and between 99b05ef and c07ed0e.

📒 Files selected for processing (2)

• Dockerfile
• test/openclaw-integrity-pin-suite.ts

🚧 Files skipped from review as they are similar to previous changes (1)

• Dockerfile