Summary

Follow-up to #3328, which dropped 5/8 of the caps named in issue #3280 and left CAP_FOWNER, CAP_SETUID, CAP_SETGID present because the entrypoint's gosu-based privilege separation prevented dropping them from the bounding set (gosu needs CAP_SETUID in permitted to do its setuid() syscall, but the bounding set can only be modified with CAP_SETPCAP, which only root holds — there's no point in the entrypoint where the drop can happen without breaking either gosu or the privilege transition).

This PR resolves the chicken-and-egg by replacing gosu with setpriv (util-linux, already present in the image). setpriv does reuid + bounding-set drop atomically inside a single process: setuid first (still holds CAP_SETUID), then strip the bounding set (still root long enough to hold CAP_SETPCAP), then exec — no exec between the setuid and the bounding-set drop.

After this PR, all 8 caps named in issue #3280 are absent from the sandbox-user process's CapBnd (verified live; see Test plan).

Stacking note

Stacked on PR #3328. The full PR diff shows 4 commits:

Reviewers should focus on the bottom two commits. Merge after #3328 lands; I'll rebase if #3328 changes during review.

Changes

scripts/lib/sandbox-init.sh

Add init_step_down_prefixes() and two file-scope arrays:

• STEP_DOWN_PREFIX_SANDBOX — defaults to (gosu sandbox); upgraded by init_step_down_prefixes() to (setpriv --reuid=sandbox --regid=sandbox --init-groups --bounding-set=-setuid,-setgid,-fowner,-chown,-kill --) when setpriv + CAP_SETPCAP are available.
• STEP_DOWN_PREFIX_GATEWAY — same shape, gateway user.

If setpriv is missing or CAP_SETPCAP is unavailable, the arrays stay at the gosu fallback (matching the previous behavior) and a [SECURITY WARNING] is logged so the residual cap retention surfaces in the entrypoint log (matches report_residual_capabilities() from #3328).

Implementation notes:

• File-scope default is (gosu …), not () — hardens against a theoretical privesc regression: if init_step_down_prefixes() were ever skipped by a future refactor, an empty array would expand to nothing, and exec "${STEP_DOWN_PREFIX_SANDBOX[@]}" "${NEMOCLAW_CMD[@]}" would run the agent as root. The gosu default makes the failure mode safe.
• --init-groups (not --clear-groups) — gateway is a member of the sandbox group via usermod -aG sandbox gateway in Dockerfile.base:99, required to write the chmod 660 /sandbox/.openclaw/openclaw.json (setgid'd config dir per OpenClaw UI "Enable Dreaming" doesn't work because of GatewayRequestError: EACCES: permission denied #2681). --clear-groups would strip that membership and break mutateConfigFile with EACCES. --init-groups matches gosu's setgroups + initgroups behaviour. (Addresses CodeRabbit comment.)
• Plain array assignment (no declare -ga) — bash 3.2 on macOS rejects declare -g, which would break macOS CI when any test sources sandbox-init.sh. File-scope ARR=() is global by default in bash 3.2+; the function-internal reassignment without local targets the same global. (Addresses CodeRabbit comment.)
• setpriv uses unprefixed cap names (per setpriv --list), unlike capsh which uses cap_*. The arrays follow the setpriv convention.
• Per-assignment # shellcheck disable=SC2034 — the prefix arrays are consumed cross-file (by scripts/nemoclaw-start.sh and agents/hermes/start.sh), which shellcheck cannot follow from sandbox-init.sh alone.

scripts/nemoclaw-start.sh (4 sites) and agents/hermes/start.sh (3 sites)

Replace all gosu <user> invocations with "${STEP_DOWN_PREFIX_<USER>[@]}":

Non-root fallback path in nemoclaw-start.sh (lines 1488+) and the no-new-privileges history comments at 138-139 / 1490-1493 are unchanged — that path doesn't use a privilege-step-down tool at all.

test/e2e-gateway-isolation.sh

Flip CAP_FOWNER / CAP_SETUID / CAP_SETGID in test 14 from allowed to must-drop. Rewrite the test to exercise the full two-stage drop end-to-end: source sandbox-init.sh, run drop_capabilities() (stage 1: capsh), then exec STEP_DOWN_PREFIX_SANDBOX (stage 2: setpriv), then capture CapBnd.

test/sandbox-init.test.ts

Two new unit tests for init_step_down_prefixes():

• Falls back to gosu when setpriv/capsh are unavailable
• Uses setpriv with the issue-3280 bounding-set drop when available

Update the existing start_discord_facade snapshot test to expect the new STEP_DOWN_PREFIX_GATEWAY invocation instead of the legacy gosu gateway sh -c.

test/nemoclaw-start.test.ts

Initialise STEP_DOWN_PREFIX_SANDBOX=(gosu sandbox) and STEP_DOWN_PREFIX_GATEWAY=(gosu gateway) in the test scaffolding for both runLaunchBlock() and runPreGatewaySetup(). The extracted launch / setup blocks reference these arrays, and the test scaffolding doesn't source sandbox-init.sh, so without an explicit initialisation set -u fails on the unbound array and the stubbed gosu() never receives the call (this caused the user=gateway CI failure on the prior push).

Test plan

Forward case (full production image, post-build)

Built nemoclaw-3329-test directly from this branch's Dockerfile (63 steps, no overlay). Ran the full two-stage drop end-to-end with --cap-add CAP_SYS_ADMIN --cap-add CAP_SYS_PTRACE (worst-case permissive runtime):

Stage 1 (root, post-capsh):   CapBnd=00000000000001e9
Stage 2 (sandbox, post-setpriv): uid=998(sandbox) gid=998(sandbox) groups=sandbox
                                 CapBnd=0000000000000100  → cap_setpcap only
Issue #3280 caps absent: cap_sys_admin / cap_sys_ptrace / cap_net_raw /
                         cap_net_bind_service / cap_dac_override /
                         cap_fowner / cap_setuid / cap_setgid  ✅ (8/8)

Gateway path (full production image, post-build)

Same image, but invoking STEP_DOWN_PREFIX_GATEWAY instead:

uid=999(gateway) gid=999(gateway) groups=gateway sandbox   ← --init-groups OK
CapBnd=0000000000000100  → cap_setpcap only
/sandbox/.openclaw/openclaw.json (mode 660, sandbox:sandbox) writable by gateway ✅

This is the exact case CodeRabbit flagged: gateway must retain sandbox group membership to write the chmod 660 setgid'd config (per #2681). Confirmed.

Negative case (live container)

Rebuilt with -setuid removed from the setpriv --bounding-set arg. CapBnd=0x180 (bit 7 set = CAP_SETUID). Test correctly fails with "CAP_SETUID still present in sandbox-user CapBnd (issue #3280)" — matches the regression signature this PR is designed to catch.

Full regression baseline

npm test on this branch vs upstream/main:

Net: 2 new passing tests (the new init_step_down_prefixes cases), zero new failures. All 67 baseline failures pre-date this PR (stale dist/, unrelated TypeScript files).

Targeted

• npx vitest run test/{sandbox-init,nemoclaw-start,seccomp-guard,service-env}.test.ts → 132/132 pass.
• bash -n clean on all 4 touched shell files.
• shfmt -d -i 2 -ci -bn clean.

Security review

Net assessment: no new CWEs introduced. Sandbox-user CapBnd: 6 entries → 1 entry. Attack surface for setuid-root-binary cap regain: reduced to empty.

Risks and notes for review

• setpriv vs gosu setuid semantics. Both use the setuid syscall. setpriv --reuid sets ruid+euid but not saved UID (gosu uses setresuid which sets all three). Saved-UID=0 is inert here because using it requires CAP_SETUID in permitted, which is empty after the bounding-set drop on exec.
• No-new-privs interaction. setpriv performs the setuid syscall as root, which is unrestricted regardless of no_new_privs. Different failure mode from gosu (documented at nemoclaw-start.sh:138-139 and :1490-1493). Worth verifying on Spark/arm64 in CI.
• Defense-in-depth, not user-facing behaviour change. The agent shell continues to run as the sandbox user with the same supplementary groups; the only observable difference is cat /proc/self/status showing an empty CapBnd (apart from CAP_SETPCAP itself, which is harmless in an unprivileged process).
• Fallback warning is a log line, not an exit. If a runtime lacks setpriv or CAP_SETPCAP, the sandbox still boots (under the legacy gosu path) but emits [SECURITY WARNING] so the residual surfaces in docker logs.

Review feedback addressed

1. CodeRabbit: Bash 3.2 incompat (declare -ga) → replaced with plain array assignment.
2. CodeRabbit: --clear-groups removes gateway from sandbox group → switched to --init-groups; verified live.
3. Self-review: unset-array privesc regression risk → file-scope default initialised to (gosu …) instead of (); init_step_down_prefixes() only upgrades.
4. CI: shellcheck SC2034 → per-assignment # shellcheck disable=SC2034 with cross-file-consumption note.
5. CI: test/nemoclaw-start.test.ts:1201 user=gateway → scaffolding initialises STEP_DOWN_PREFIX_* in fallback form so the stubbed gosu still receives the call.

Closes #3280.

Signed-off-by: Dongni Yang dongniy@nvidia.com

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

• Security Improvements

  • Enhanced sandbox isolation through improved removal of dangerous capabilities from restricted environments
  • Updated privilege separation mechanism with better fallback handling and more flexible configuration
  • Improved capability-dropping logic for comprehensive restriction of high-risk permissions

• Tests

  • Updated integration tests to verify capability restrictions work as expected