fix(security): remove gosu from managed images

[senthilr-nv]

Summary

Replace the standalone gosu binary in all NemoClaw managed base images with the Debian-pinned setpriv implementation from util-linux. Root entrypoints now use one reviewed privilege-transition mechanism and fail closed rather than starting an agent service as root when it is unavailable.

Changes

• Remove the downloaded gosu binary from the OpenClaw and Hermes base images and explicitly pin util-linux=2.41-5 across all three managed bases.
• Use setpriv for build-time and runtime transitions to the sandbox and gateway users while preserving supplementary groups.
• Drop the remaining privilege-separation capabilities during the transition when CAP_SETPCAP is available; otherwise retain the runtime-provided bounding set and still change identity.
• Fail closed when a root entrypoint requires an identity transition but setpriv or the target user is unavailable.
• Add regression coverage for the setpriv-only contract and update the sandbox security documentation.

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: Exact-head security review at fe77d7434 passed all nine categories with no findings. The change adds no secrets or untrusted parsing, pins util-linux, uses the managed /usr/bin/setpriv boundary, preserves supplementary groups, and fails closed for required root identity transitions.
• 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: docs/deployment/sandbox-hardening.mdx, docs/reference/troubleshooting.mdx, and docs/security/best-practices.mdx accurately document the managed-image setpriv requirement, supplementary-group initialization, and fail-closed root identity transitions. The merge refresh preserves the previously reviewed PR patch; prior focused test and documentation validation evidence remains applicable. Fresh CI is running.
• 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 — focused setpriv and sandbox-init suites passed 60 tests with 1 skipped at faa243566; CLI build, CLI typecheck, repository checks, documentation build, and normal hooks passed across the reviewed change set.
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result: Not selected. An additional macOS integration batch passed 194 tests and hit 29 existing platform-harness failures in two files (stat -c, GNU timeout, and mktemp suffix behavior). Linux CI and multi-architecture image builds remain the merge gates.
• 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

  • Replaced legacy privilege-transition handling with setpriv for safer root-to-user switching.
  • Privilege transitions now fail closed when required tooling or target identities are unavailable.
  • Added best-effort capability removal with clear warnings when full hardening is unavailable.

• Documentation

  • Updated deployment, troubleshooting, and security guidance to describe the new privilege-separation requirements.

• Tests

  • Expanded coverage for identity transitions, capability handling, container isolation, and runtime tool requirements.
  • Added validation that managed images include the required setpriv runtime support.

[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

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: 47b18567-55ee-41bb-aa63-f3b68ca0107e

📥 Commits

Reviewing files that changed from the base of the PR and between faa2435 and fe77d74.

📒 Files selected for processing (3)

• docs/reference/troubleshooting.mdx
• docs/security/best-practices.mdx
• test/e2e/live/hermes-e2e.test.ts

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

• test/e2e/live/hermes-e2e.test.ts
• docs/reference/troubleshooting.mdx
• docs/security/best-practices.mdx

---

📝 Walkthrough

Walkthrough

The change replaces gosu with pinned Debian util-linux and /usr/bin/setpriv across container images, privilege-transition scripts, application launch paths, Hermes probes, documentation, and security tests. Root transitions now fail closed when setpriv is unavailable.

Changes

setpriv migration

Layer / File(s)	Summary
Managed image runtime contract Dockerfile, Dockerfile.base, agents/hermes/Dockerfile.base, agents/langchain-deepagents-code/Dockerfile.base, test/sandbox-base-*	Images install pinned util-linux, validate /usr/bin/setpriv, and use it for sandbox Homebrew operations. Tests verify the package and reject gosu.
Core privilege-step-down behavior scripts/lib/sandbox-init.sh, docs/deployment/sandbox-hardening.mdx, docs/security/best-practices.mdx, docs/reference/troubleshooting.mdx, test/sandbox-init.test.ts	Privilege prefixes use setpriv, optional capability removal, warnings, and fail-closed behavior when prerequisites are missing.
Application identity transitions src/lib/agent/*, src/lib/onboard/managed-startup/*, src/lib/shields/openclaw-config-lock.*, scripts/nemoclaw-start.sh, test/nemoclaw-start*	Gateway, sandbox, configuration validation, and launch fixtures use explicit setpriv identity and group arguments. Trusted executable and identity validation is tested.
Hermes image and live checks agents/hermes/Dockerfile, test/e2e/live/*, test/hermes-discord-recovery-permissions.test.ts	Hermes probes and live checks use setpriv for gateway and sandbox execution.
Gateway isolation validation test/e2e-gateway-isolation.sh	Isolation tests use setpriv for identity, capability, filesystem, proxy, recovery, and race-condition checks.

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

Sequence Diagram(s)

sequenceDiagram
  participant RootEntrypoint
  participant sandbox-init.sh
  participant setpriv
  participant TargetUser
  RootEntrypoint->>sandbox-init.sh: initialize privilege-step-down prefixes
  sandbox-init.sh->>setpriv: configure UID, GID, groups, and capabilities
  setpriv->>TargetUser: execute the target command
  sandbox-init.sh-->>RootEntrypoint: refuse transition when setpriv is unavailable

Loading

Suggested labels: platform: container

Suggested reviewers: apurvvkumaria

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 9.09% 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the primary change: removing gosu from managed images for security.
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.

✨ 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/remove-gosu

---

_{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 fe77d74 in the codex/remove-gosu branch remains at 96%, unchanged from commit 9b6b8df in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit fe77d74 in the codex/remove-gosu branch remains at 81%, unchanged from commit fdd6828 in the main branch.

Show a code coverage summary of the most impacted files.

File	main fdd6828	codex/remove-gosu fe77d74	+/-
src/lib/shields/index.ts	73%	70%	-3%
src/lib/shields...-config-lock.ts	86%	83%	-3%
src/lib/onboard...der/registry.ts	97%	97%	0%
src/lib/state/r...try/workload.ts	98%	98%	0%
src/lib/onboard...vider/docker.ts	91%	91%	0%
src/lib/onboard...-transaction.ts	96%	96%	0%
src/lib/onboard...mage-runtime.ts	50%	53%	+3%
src/lib/onboard...ive-artifact.ts	86%	93%	+7%
src/lib/agent/g...cript-shared.ts	86%	93%	+7%
src/lib/domain/.../connect-env.ts	89%	97%	+8%

---

_{Updated August 05, 2026 06:55 UTC}

[github-actions]

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

[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 · 3 suggestions
• Model comparison: normalized findings differ; normalized terminology decisions differ; normalized E2E selections differ; Nemotron reported the same number of blockers, 1 more warning, 3 more suggestions.

3 terminology differences from the second opinion

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

• init-groups at scripts/lib/sandbox-init.sh:480: selected only by the second-opinion lane as established.
• setpriv at Dockerfile.base:263: selected only by the second-opinion lane as established.
• load-bearing at scripts/lib/sandbox-init.sh:428: selected only by the second-opinion lane as established.

3 additional E2E selections from the second opinion

Advisory only. The primary lane did not select these E2E jobs or targets.

• gateway-guard-recovery: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• rebuild-hermes: The completed second-opinion lane identified E2E coverage that the primary lane omitted.
• rebuild-openclaw: The completed second-opinion lane identified E2E coverage that the primary lane omitted.

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 — managed image at docs/deployment/sandbox-hardening.mdx:51: Keep the existing term. Use “NemoClaw-managed image” where ownership needs emphasis.
• justified — privilege-separation capabilities at docs/security/best-practices.mdx:442: Keep the modifier and state the CAP_SETPCAP condition, as the changed documentation does.

E2E guidance

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

Recommended E2E: cloud-inference, cloud-onboard, full-e2e, hermes-e2e, hermes-inference-switch, managed-image-multiarch-startup, security-posture, device-auth-health, issue-4462-scope-upgrade-approval, onboard-repair, onboard-resume, openclaw-inference-switch, ubuntu-repo-cloud-langchain-deepagents-code

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 `@src/lib/onboard/managed-startup-sandbox-prefix.test.ts`:
- Around line 66-69: Split the parameterized test around the lstatSync mock into
separate cases: keep only non-null fs.Stats inputs and unconditional returns in
the parameterized test, and add a dedicated it block covering the missing-file
ENOENT behavior without the stat conditional.

🪄 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: 0b6d95a4-3a93-48a5-88b6-1388f7610605

📥 Commits

Reviewing files that changed from the base of the PR and between 8f56c4f and 38c15f2.

📒 Files selected for processing (2)

• src/lib/onboard/managed-startup-sandbox-prefix.test.ts
• src/lib/onboard/managed-startup/image-runtime.ts

[senthilr-nv]

Addressed the automated review findings: added focused managed-startup setpriv trust tests in 38c15f2, kept the missing-file case linear in 7a01fd8, and removed the unused stderr capture in faa2435. The focused setpriv suite passes 12/12; sandbox-init passes 48 tests with 1 skipped. All current inline threads are resolved.

[apurvvkumaria]

Approve — reviewed current head faa2435 with focus on privilege transitions, capability handling, managed-image compatibility, recovery paths, and regression coverage. No blocking defect found. Focused privilege-transition tests pass locally; required CI, image builds, CodeQL, advisor, and E2E checks remain merge gates.

[cv]

Maintainer evidence update for PR commit fe77d7434162d20d0cc54760d0d9eea97a38fd48:

• The selected child workflow 30980315615 passed on attempt 2. Its full-e2e job passed the live test (1/1) and uploaded the evidence artifact.
• The parent E2E / PR Gate check remains failed because it recorded attempt 1 and did not reconcile the successful rerun.
• The PR needs a new event to start the gate again for this commit. The branch applies to current main without conflicts. Repository validation also requires lowering the recorded src/lib/state/registry.ts fan-in ceiling from 99 to 98 in ci/source-architecture-budget.json.

No required-check waiver is proposed. The PR remains blocked until the parent E2E / PR Gate and all other required checks pass for the next PR commit.