fix(security): upgrade bundled npm dependencies

[senthilr-nv]

Summary

Upgrade npm bundled with the pinned Node 22 and Node 24 base images to npm 11.18.0 before image-local npm consumers run. The upgrade verifies the npm archive and bundled dependency versions, and it rejects unreviewed source versions or dependency drift.

Changes

• Add a reviewed npm upgrade tool that downloads npm 11.18.0 over HTTPS and verifies its pinned SHA-512 integrity.
• Install the reviewed archive with lifecycle scripts disabled, then verify the expected npm, brace-expansion, picomatch, sigstore, and tar versions.
• Apply the upgrade after the node-tar bootstrap in the OpenClaw, Hermes, and Deep Agents Code base images.
• Include the upgrade tool in workflow triggers, optimized build contexts, and base-image source identity.
• Test archive integrity, source-version allowlisting, dependency drift rejection, build-context staging, and Dockerfile ordering.

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: The automatic base-image dependency upgrade does not change a user workflow, configuration, or supported contract.
• 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: Codex Desktop reviewed all nine security categories. Archive integrity, source-version allowlisting, lifecycle-script suppression, fail-closed dependency checks, and secret scans passed with no findings.
• 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: no-docs-needed
• Evidence: No documentation files changed. The upgrade is automatic and does not change user behavior or configuration.
• 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 check:diff passed when hooks were skipped or unavailable
• Targeted behavior tests pass for the current change set, or tests are marked not applicable above — command/result or justification: Vitest passed 64 tests across six affected files. After Dockerfile lint annotations, Vitest passed 20 tests across two affected files. After the CI guardrail fix, the focused test passed 7 tests.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Not applicable. Focused tests cover the base-image dependency upgrade and staging contracts.
• 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)
• Doc pages follow the style guide (doc changes only)
• New doc pages include SPDX header and frontmatter (new pages only)

---

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

Summary by CodeRabbit

• Security & Reliability
  • Base images now use a reviewed, verified npm distribution and automatically remediate the bundled npm dependency set during the image build.
  • Base-image rebuilds are retriggered when the npm remediation helper changes, ensuring updates propagate.
• Tests
  • Added/expanded unit and contract tests to validate the remediation sequence and enforce “fails closed” integrity/version checks.
• Chores
  • Updated sandbox build-context staging to include the npm remediation helper.
  • Refreshed base-image rebuild documentation/checklists.

[coderabbitai]

📝 Walkthrough

Walkthrough

The change adds a reviewed npm verification and upgrade script, runs it in three base-image Dockerfiles, tracks it in base-image inputs and staged build contexts, triggers image workflows on script changes, and adds unit and Dockerfile contract tests.

Changes

Bundled npm remediation

Layer / File(s)	Summary
Reviewed npm validation and upgrade engine scripts/upgrade-bundled-npm.mts, test/upgrade-bundled-npm.test.ts	Defines reviewed npm metadata, validates package trees and archive integrity, upgrades allowlisted versions, exposes CLI wiring, and tests replacement, reuse, and fail-closed behavior.
Base-image npm remediation integration Dockerfile.base, agents/hermes/Dockerfile.base, agents/langchain-deepagents-code/Dockerfile.base, test/node-tar-dockerfile-contract.test.ts, .github/workflows/base-image.yaml	Copies and runs the upgrade helper during image builds, updates rebuild notes, triggers the workflow for helper changes, and verifies Dockerfile ordering and npm consumers.
Base-image input and staging propagation src/lib/sandbox-base-image/source-identity.ts, src/lib/sandbox-base-image/source-identity.test.ts, src/lib/sandbox/build-context.ts, test/sandbox-build-context.test.ts	Adds the helper to base-image input tracking and optimized build-context staging, with updated expectations and fixtures.

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

Sequence Diagram(s)

sequenceDiagram
  participant BaseImageWorkflow
  participant DockerBuild
  participant UpgradeScript
  participant NpmRoot
  BaseImageWorkflow->>DockerBuild: rebuild on upgrade script changes
  DockerBuild->>UpgradeScript: run with npm root
  UpgradeScript->>NpmRoot: verify current bundled npm
  UpgradeScript->>UpgradeScript: download and verify reviewed archive
  UpgradeScript->>NpmRoot: install and re-verify reviewed npm
  DockerBuild->>NpmRoot: run later npm consumers

Loading

Possibly related PRs

• NVIDIA/NemoClaw#7332: Both modify the Dockerfile bundled npm remediation flow.
• NVIDIA/NemoClaw#7461: Both modify Hermes Dockerfile remediation ordering and contract tests.
• NVIDIA/NemoClaw#7486: Both modify the Dockerfile remediation contract’s stage selection and ordering checks.

Suggested labels: integration: openclaw, integration: hermes, integration: dcode, area: security

Suggested reviewers: prekshivyas, apurvvkumaria

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
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 matches the main change: upgrading bundled npm dependencies for security.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

scripts/upgrade-bundled-npm.mts (1)

24-34: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider a dependency-review evidence pointer for the npm pins.

The OpenClaw and mcporter pins in Dockerfile.base each cite a review-evidence doc (docs/security/openclaw-2026.7.1-dependency-review.md, agents/openclaw/dependency-review.md). The reviewed npm version/integrity/package-version pins here have no equivalent pointer, making it harder for a future auditor to see why 11.18.0 and these four sub-package versions were selected as the security floor.

🤖 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/upgrade-bundled-npm.mts` around lines 24 - 34, The npm pins in
REVIEWED_NPM_VERSION, REVIEWED_NPM_INTEGRITY, REVIEWED_NPM_TARBALL, and
REVIEWED_NPM_PACKAGES need an auditable dependency-review evidence pointer. Add
a nearby comment referencing a dedicated review document that records why npm
11.18.0, its integrity, and the four package versions form the security floor.

🤖 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/upgrade-bundled-npm.test.ts`:
- Around line 93-126: Replace the if statement inside the commandRunner callback
in the upgradeBundledNpm test with a linear ternary expression that preserves
the existing verifyReviewedNpm assertion for “npm” and “npx” commands while
avoiding any added conditional statement in the test body.

---

Nitpick comments:
In `@scripts/upgrade-bundled-npm.mts`:
- Around line 24-34: The npm pins in REVIEWED_NPM_VERSION,
REVIEWED_NPM_INTEGRITY, REVIEWED_NPM_TARBALL, and REVIEWED_NPM_PACKAGES need an
auditable dependency-review evidence pointer. Add a nearby comment referencing a
dedicated review document that records why npm 11.18.0, its integrity, and the
four package versions form the security floor.

🪄 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: d4c9473e-e8cb-4f66-b305-b7a3f5fdbd0c

📥 Commits

Reviewing files that changed from the base of the PR and between fac91e6 and 999dac9.

📒 Files selected for processing (11)

• .github/workflows/base-image.yaml
• Dockerfile.base
• agents/hermes/Dockerfile.base
• agents/langchain-deepagents-code/Dockerfile.base
• scripts/upgrade-bundled-npm.mts
• src/lib/sandbox-base-image/source-identity.test.ts
• src/lib/sandbox-base-image/source-identity.ts
• src/lib/sandbox/build-context.ts
• test/node-tar-dockerfile-contract.test.ts
• test/sandbox-build-context.test.ts
• test/upgrade-bundled-npm.test.ts

[github-actions]

PR Review Advisor — Informational

Advisor assessment: Informational / high confidence
Next action: Review the warnings below.
Findings: 0 blockers · 1 warning · 0 suggestions
Status: Canonical ledger: 0 blocker(s), 1 warning(s), 0 suggestion(s).

Model lanes

• GPT-5.6 Terra (primary): Completed · high confidence · 0 blockers · 1 warning · 0 suggestions
• Nemotron 3 Ultra (second opinion): Failed after a partial review · low confidence · 0 blockers · 14 warnings · 3 suggestions

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, full-e2e, hermes-e2e, security-posture, state-backup-restore, upgrade-stale-sandbox

2 optional E2E recommendations

• rebuild-openclaw
• rebuild-hermes

1 warning · 0 suggestions

Warnings

Warnings do not block.

PRA-1 Warning — Cover cleanup after npm installation fails

• Location: test/upgrade-bundled-npm.test.ts:91
• Category: tests
• Problem: The replacement-path test covers successful installation only. It does not prove that an installation failure runs the prepared-archive cleanup.
• Impact: A future change can bypass cleanup of the downloaded archive after a failed replacement without unit-test detection.
• Recommendation: Add a test whose installArchive throws. Assert that cleanup runs before the error propagates.
• Verification: Inspect test/upgrade-bundled-npm.test.ts and confirm a failing installArchive test asserts cleanup and preserves the thrown failure.
• Test coverage: A unit test for npm 10.9.8 or 11.13.0 where installArchive throws, then asserts cleanup ran and the installation error propagates.
• Evidence: test/upgrade-bundled-npm.test.ts:91-128 tests only a successful installArchive replacement and cleanup sequence. scripts/upgrade-bundled-npm.mts:246-255 invokes installArchive inside try/finally, so failed-install cleanup is a changed error-path contract. scripts/upgrade-bundled-npm.mts:246-255 invokes installArchive inside try/finally and does not implement npm-root rollback. test/upgrade-bundled-npm.test.ts:91-128 covers only the successful installArchive sequence and cleanup.

Workflow run details

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