fix(onboard): reject incompatible OpenClaw base images

[sandl99]

Summary

OpenClaw onboarding now rejects a release base image that lacks the immutable security package inventory. The resolver refreshes the selected release once, then builds the current base locally instead of failing in the completed image's final layer.

Related Issue

Fixes #7605

Changes

• Validate the OpenClaw base image's security inventory before completed-image construction.
• Run the validation probe without network access, Linux capabilities, writable filesystem access, or privilege escalation.
• Use the existing release resolver to refresh the exact selected release and build the current local base when it remains incompatible.
• Preserve the resolver contract that does not substitute mutable latest for a selected release.
• Add tests for the inventory probe and the release-to-local fallback.

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 commands reference already documents refresh-once, local-build fallback, disabled-build failure, and no mutable latest substitution.
• 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:
• 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: docs/reference/commands.mdx already documents the resolver behavior. The latest source-loader fixture fix changes no command, option, required user action, or output contract.
• 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: npx vitest run --project cli src/lib/onboard/base-image.test.ts src/lib/sandbox-base-image-release-resolution.test.ts passed 12 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 run; the change is scoped to OpenClaw base-image resolution and has focused coverage.
• 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: San Dang sdang@nvidia.com

Summary by CodeRabbit

• Bug Fixes

  • Improved sandbox base-image validation by adding a security-inventory probe that verifies the inventory file exists, is not a symlink, matches expected ownership/permissions, and contains exact expected contents.
  • Enhanced sandbox base-image release resolution to correctly handle cases where the selected release predates the security inventory.

• Tests

  • Added/extended tests to cover the security-inventory probe behavior and the local-image fallback scenario.
  • Updated Docker/subprocess test stubs and added a sandbox-hardening test to ensure consistent probe detection and runner capture handling.

[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

The change adds security inventory validation for OpenClaw base images, integrates it into release resolution, and tests local-build fallback when a pulled release image lacks the required inventory.

Changes

Base image validation

Layer / File(s)	Summary
Security inventory probe src/lib/onboard/base-image.ts, src/lib/onboard/base-image.test.ts	Adds a restricted Docker probe validating the inventory file and tests successful and empty probe results.
Release resolution fallback src/lib/onboard/base-image.ts, src/lib/sandbox-base-image-release-resolution.test.ts	Uses the probe during image resolution and verifies local-build fallback for an incompatible release image.
Integration test harness support test/helpers/onboard-script-mocks.cjs, test/shellquote-sandbox.test.ts, test/gateway-state-reconcile-2276.test.ts, test/rebuild-*.test.ts, test/repro-2201.test.ts	Updates mocked Docker handlers to detect the security-inventory probe and emit its expected marker.

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

Suggested reviewers: cv, apurvvkumaria, prekshivyas

Sequence Diagram(s)

sequenceDiagram
  participant Onboarding
  participant BaseImageResolver
  participant Docker
  participant LocalBuilder
  Onboarding->>BaseImageResolver: resolve sandbox base image
  BaseImageResolver->>Docker: pull exact release reference
  BaseImageResolver->>Docker: run security inventory validation
  Docker-->>BaseImageResolver: validation result
  BaseImageResolver->>LocalBuilder: build current base image when invalid
  LocalBuilder-->>BaseImageResolver: local image result
  LocalBuilder-->>Onboarding: return resolved base image

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	The changes validate the security inventory, retry the exact release once, and fall back to a local build when the release remains incompatible, matching #7605.
Out of Scope Changes check	✅ Passed	The diff appears scoped to the onboarding validation change and its supporting tests and mocks.
Docstring Coverage	✅ Passed	Docstring coverage is 80.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly matches the main change: onboarding now rejects incompatible OpenClaw base images.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/openclaw-base-security-inventory

---

_{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 d22283e in the fix/openclaw-base-se... branch remains at 96%, unchanged from commit 87270de in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit d22283e in the fix/openclaw-base-se... branch is 81%. The coverage in commit 0b18549 in the main branch is 80%.

Show a code coverage summary of the most impacted files.

File	main 0b18549	fix/openclaw-base-se... d22283e	+/-
src/lib/domain/.../connect-env.ts	97%	89%	-8%
src/lib/shields/index.ts	71%	72%	+1%
src/lib/onboard...eway-service.ts	81%	82%	+1%
src/lib/actions...dbox/destroy.ts	93%	95%	+2%
src/lib/actions...e-validation.ts	81%	84%	+3%
src/lib/onboard...shboard-port.ts	90%	93%	+3%
src/lib/actions...x/mcp-bridge.ts	35%	41%	+6%
src/lib/actions...lution-probe.ts	88%	95%	+7%
src/lib/actions...-add-restart.ts	10%	19%	+9%
src/lib/actions...time-command.ts	82%	100%	+18%

---

_{Updated July 27, 2026 07:03 UTC}

[coderabbitai]

Actionable comments posted: 2

🤖 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/onboard/base-image.test.ts`:
- Around line 22-40: Strengthen the test for
openClawBaseImageHasSecurityInventory by explicitly asserting every mandatory
probe safeguard in the dockerMocks.capture command: --cap-drop ALL,
no-new-privileges, the pinned shell entrypoint, and the symlink, ownership, and
content validation fragments, while retaining the existing network, read-only,
inventory-path, and timeout assertions.

In `@src/lib/sandbox-base-image-release-resolution.test.ts`:
- Around line 211-235: Update the test around resolveSandboxBaseImage to assert
dockerMocks.pull is called exactly once and state.validateImage receives
RELEASE_REF twice in order, proving both the initial and post-refresh
validations while retaining the existing local-build expectations.

🪄 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: 3c973110-57aa-4805-bad8-8b913c6c8890

📥 Commits

Reviewing files that changed from the base of the PR and between 0b18549 and 4eee7a0.

📒 Files selected for processing (3)

• src/lib/onboard/base-image.test.ts
• src/lib/onboard/base-image.ts
• src/lib/sandbox-base-image-release-resolution.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 · medium confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 1 blocker · 2 warnings · 1 suggestion
• Model comparison: normalized findings differ; normalized E2E selections differ; Nemotron reported 1 more blocker, 2 more warnings, 1 more suggestion.

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: onboard-repair, onboard-resume, cloud-onboard

1 optional E2E recommendation

• rebuild-openclaw

Workflow run details

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

[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/helpers/onboard-script-mocks.cjs`:
- Around line 71-77: Strengthen the inventory probe validation in
mockOnboardRunCapture and the embedded Docker stubs so success requires the
complete probe contract, including Docker isolation and the expected
inventory-check arguments, not merely the success marker. Reuse shared helper
logic where practical. Apply this in
test/helpers/onboard-script-mocks.cjs:71-77,
test/gateway-state-reconcile-2276.test.ts:275,
test/rebuild-credential-preflight.test.ts:305,
test/rebuild-shields-auto-unlock.test.ts:249,
test/rebuild-stale-recovery.test.ts:187, and test/repro-2201.test.ts:313-316;
preserve success only for valid probes and reject weakened commands.

🪄 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: dcbc2c37-801e-4b8e-a597-b83ef1174d9e

📥 Commits

Reviewing files that changed from the base of the PR and between 4eee7a0 and 13586f8.

📒 Files selected for processing (8)

• src/lib/onboard/base-image.test.ts
• src/lib/sandbox-base-image-release-resolution.test.ts
• test/gateway-state-reconcile-2276.test.ts
• test/helpers/onboard-script-mocks.cjs
• test/rebuild-credential-preflight.test.ts
• test/rebuild-shields-auto-unlock.test.ts
• test/rebuild-stale-recovery.test.ts
• test/repro-2201.test.ts

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

• src/lib/onboard/base-image.test.ts
• src/lib/sandbox-base-image-release-resolution.test.ts