fix(state): keep the confidentiality root traversable by the sandbox group

[Dongni-Yang]

Summary

With shields up, the state-dir guard locked the confidentiality directories (credentials, identity, pairing) to root:root 700, so OpenClaw's startup lstat of the optional legacy credentials/oauth.json failed with EACCES instead of ENOENT — the gateway restart then failed with GATEWAY_HEALTH_TIMEOUT and Telegram dispatch kept retrying (#7545). Lock now sets only the confidentiality root to root:sandbox 710 (group execute, no read): a probe for a missing top-level name resolves as missing, while the directory stays unlistable and nested directories and every file keep the sealed root:root posture with no group or world bits.

Related Issue

Closes #7545 — together with #7602 (the sessions-carveout half, Refs), this resolves both filed symptoms. If this PR merges first, #7602 still tracks the remaining EACCES: mkdir agents/main/sessions symptom on the issue's thread.

Changes

• scripts/state-dir-guard.py: an is_confidentiality_root flag threads through _expected_ids, _expected_dir_mode, _set_dir_metadata, _verify_metadata, and _verify_dir. During lock, the mutation pass and the independent verification pass both expect root:sandbox 710 on the confidentiality root and the unchanged root:root 700 on nested confidentiality directories. Confidentiality file modes and ownership are untouched (old_mode & 0o700, root:root), so the live E2E contract for locked credential files (uid 0, gid 0, 0600 in test/e2e/live/state-dir-guard-metadata.test.ts) holds without modification. Scoping the group-execute bit to the root keeps the widened surface to one directory level of known-name metadata — resolving the oauth.json probe needs search permission on credentials/ alone.
• test/state-dir-guard.test.ts: the distinct-modes test now pins the root at 0o710 and a nested credentials/providers/ directory at 0o700; a new driver runs the guard with a distinct sandbox gid (a supplementary group of the current user, skipped when none exists) and asserts the group ownership lands only on the confidentiality root, not on nested directories or files. Both fail on the pre-change guard.
• test/e2e/live/state-dir-guard-metadata.test.ts: the real container probe asserts a distinct sandbox-group member gets ENOENT for a missing direct child while root listing, nested traversal, and secret reads all remain EACCES.
• docs/security/best-practices.mdx: the secret-bearing-directories paragraph now states the root/nested split, the known-name metadata visibility, and the missing-probe behavior.

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: nine-category security review passed for commit 2dd194dd5; the current-main merge did not change the effective PR diff. No secrets, dependency, authentication, cryptography, network, or logging surface was added. The root-only 0710 scope is mirrored by independent verification and negative traversal and read tests.
• 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/security/best-practices.mdx accurately documents the confidentiality-root behavior for OpenClaw and Hermes. The independent review covered commit 2dd194dd5, passed the docs build with 0 errors, verified the generated OpenClaw and Hermes variants, confirmed the guidance is absent from the Deep Agents variant, and passed git diff --check.
• Agent: Codex Desktop documentation writer subagent

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 — command/result or justification: npx vitest run --project integration test/state-dir-guard.test.ts → 31 passed / 1 host-capability skip; disposable Linux DAC probe confirmed root root:sandbox 0710, nested directory root:root 0700, secret root:root 0600, direct-child ENOENT, and listing/nested/read EACCES; npm run typecheck:cli, npm run docs, and npx prek run --from-ref origin/main --to-ref HEAD passed
• Applicable broad gate passed — npm test for broad runtime/test-harness changes; npm run check for repo-wide validation/coverage changes — command/result:
• 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: Dongni Yang dongniy@nvidia.com

🤖 Generated with Claude Code

Summary by CodeRabbit

• Security
  • Updated lockdown behavior for secret-bearing confidentiality directories: the confidentiality root is now set to root:sandbox with restricted directory permissions, while nested directories and files are locked to root:root with no group/world access.
  • Probes now report missing immediate entries as “missing” rather than permission failures.
• Bug Fixes
  • Improved metadata verification to treat the confidentiality root differently from nested confidentiality entries.
• Tests
  • Expanded unit and e2e coverage, including nested permission checks and new confidentiality-root access evidence.
• Documentation
  • Refreshed security best practices to match the updated lockdown rules.

[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 confidentiality lock workflow now assigns distinct metadata to protected root directories and nested secret content, propagates root context during verification, adds group-ID and access-contract tests, and updates lockdown documentation.

Changes

Confidentiality root locking

Layer / File(s)	Summary
Confidentiality metadata contract and mutation scripts/state-dir-guard.py	Expected ownership and directory modes now distinguish confidentiality roots, and lock mutations pass the root-specific context.
Root-aware metadata verification scripts/state-dir-guard.py	Verification propagates root context through directory traversal and validates the special confidentiality-root mode.
Behavior validation and access contract test/state-dir-guard.test.ts, test/e2e/live/state-dir-guard-metadata.test.ts, docs/security/best-practices.mdx	Tests cover nested secret entries, distinct group ownership, denied access, missing-entry behavior, and the updated lockdown permissions documented for confidentiality roots.

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

Sequence Diagram(s)

sequenceDiagram
  participant StateDirGuard
  participant LockedCredentials
  participant ConfidentialityProbe
  StateDirGuard->>LockedCredentials: apply root and nested metadata
  ConfidentialityProbe->>LockedCredentials: probe missing child, listing, traversal, and secret read
  LockedCredentials-->>ConfidentialityProbe: return ENOENT or EACCES evidence
  ConfidentialityProbe-->>StateDirGuard: report UID, GID, mode, and errno evidence

Loading

Suggested labels: bug-fix, area: e2e, platform: container

Suggested reviewers: cv

🚥 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 describes the primary change: allowing the sandbox group to traverse confidentiality root directories.

✨ 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/7545-confidentiality-dir-traversal

---

_{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 2dd194d in the fix/7545-confidentia... branch remains at 96%, unchanged from commit 962f1c3 in the main branch.

TypeScript / code-coverage/cli

The overall coverage in commit 2dd194d in the fix/7545-confidentia... branch remains at 81%, unchanged from commit 962f1c3 in the main branch.

---

_{Updated August 05, 2026 05:30 UTC}

[github-actions]

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

[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 `@docs/security/best-practices.mdx`:
- Around line 300-303: Rewrite the four sentences in the secret-directory
behavior description using direct second-person wording and active present
tense, addressing the reader as “you” while preserving the existing permissions,
visibility, metadata, and missing-path behavior.

🪄 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: e708883c-dc92-4c87-ac2c-d51c3c6278d6

📥 Commits

Reviewing files that changed from the base of the PR and between fdf14f5 and 1b2495e.

📒 Files selected for processing (3)

• docs/security/best-practices.mdx
• scripts/state-dir-guard.py
• test/state-dir-guard.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 · high confidence · 0 blockers · 0 warnings · 0 suggestions
• Nemotron 3 Ultra (second opinion): Completed · high confidence · 0 blockers · 3 warnings · 3 suggestions
• Model comparison: normalized findings differ; normalized terminology decisions differ; normalized E2E selections match; Nemotron reported the same number of blockers, 3 more warnings, 3 more suggestions.

4 terminology differences from the second opinion

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

• confidentiality root at docs/security/best-practices.mdx:301: primary classified it as established; the second opinion classified it as define.
• known-name at docs/security/best-practices.mdx:355: selected only by the second-opinion lane as justified.
• traversable at docs/security/best-practices.mdx:354: selected only by the second-opinion lane as justified.
• unlistable at docs/security/best-practices.mdx:354: selected only by the second-opinion lane as define.

Second-opinion terminology and E2E selections are advisory. They do not change the primary assessment or E2E / PR Gate.

3 semantic terminology decisions

Terminology decisions are advisory. They affect the assessment only when a separate finding identifies concrete semantic impact.

• established — confidentiality root at docs/security/best-practices.mdx:301: Keep `confidentiality root` for the direct protected root and distinguish it from nested confidentiality entries.
• justified — known-name probe at docs/security/best-practices.mdx:355: Keep `known-name probe` with the stated direct-child contrast and errno outcomes.
• established — sealed posture at scripts/state-dir-guard.py:905: Keep `sealed posture` for the existing restrictive descendant metadata contract.

E2E guidance

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

Recommended E2E: cloud-inference, cloud-onboard, managed-image-multiarch-startup, security-posture

Workflow run details

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

[Dongni-Yang]

On advisor warning PRA-1 (non-owner access probes): the unit harness cannot model a second UID — its stub identity maps root and sandbox to the current user, which is why the changed tests pin the posture (modes and the gid split via a supplementary group) rather than access behavior. The observable access contract is partially covered in the live lane already: test/e2e/live/state-dir-guard-metadata.test.ts probes read/write denial of a locked credentials file as a named non-owner user (expectNamedUserAccessState, locked → credentials: { read: false, write: false }). The delta the warning asks for — lstat of an absent credentials/oauth.json → ENOENT, readdir(credentials) → EACCES, nested traversal → EACCES, as a sandbox-group member — belongs in that live target next to the existing probes. I did not extend it in this PR because the e2e-live lane cannot be exercised locally and I did not want to land unverified assertions in the pre-tag lane; happy to add the probes here if a maintainer prefers them in this change, or as a follow-up.

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

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[prekshivyas]

/ok to test 4bbfa71

[cv]

Maintainer gate snapshot for v0.0.96:

• exact head: b946e51157da6b1b32dfa7286eee359c55a9e4a4
• recorded base: 77e6e388c350a27d81f811c6ff67b8e4c1bb18bd
• current main: 921e1b0fff778343cfbe3c1daae91bb56c0bfa14
• current-main merge tree: clean
• DCO / commit verification: all 7 commits verified
• CodeRabbit: no unresolved actionable thread

The canonical merge gate blocks approval while the branch is behind, and this PR does not allow maintainer edits. Please merge current main into the branch normally (no rebase or force-push), refresh the exact-head docs/security/test receipts, and let the fresh required CI/E2E complete. I will resume the security and merge review on that new head.

[cjagwani]

Babysitting status for exact head 2e236bf (plain comment; no Changes Requested review from me): the deterministic gate currently reports a failed E2E / PR Gate, pending E2E coordination, and a stale base c4c020c versus current main da1b103. Maintainer edits are disabled. Please refresh and obtain clean exact-head E2E evidence; I will re-gate the next head after its one-hour quiet window.

[cjagwani]

Correction to my prior handoff: conflict-free base refreshes are explicitly waived. Please do not merge main solely for base currency; preserving exact-head evidence is preferred unless GitHub reports a real conflict or reviewed behavior requires a change. The substantive blocker or missing evidence described in the earlier handoff remains, but base age by itself is not a blocker. This is a plain coordination comment, not Changes Requested.

[cjagwani]

@cv @ericksoa — this exact head is still blocked only on the legacy protected-environment E2E authorization. GitHub lists you as the authorized reviewers and reports that my account cannot approve it. Please open controller run 30401679121 and approve the pending approve-credentialed-e2e-for-internal-pr deployment for PR head 2e236bf582bafacde65e538a26c15a0ff35673ee, base c4c020ca561bacadd3aa309ba5dffef7e5aa09ed, plan 260f9489649ccfab505e93ca3835082ec7caff837af961286f0c3bf5cd280419 (selected: cloud-inference, cloud-onboard, security-posture). This is a coordination comment, not Changes Requested; no branch refresh is requested.

[apurvvkumaria]

Security review PASS for revision c2553b7. Categories reviewed: secrets, input validation, authorization and filesystem authority, dependencies, logging, cryptography, configuration, tests, and failure modes. Traversal-only group access is limited to each confidentiality root; roots remain unlistable, descendants remain root-only, and negative tests preserve denial of nested traversal and secret reads. The current-main synchronization is conflict-free and does not alter the feature boundary. Python compilation, focused tests, CLI build and type checks, repository checks, documentation validation, commit hooks, and pre-push hooks pass. No findings remain; required CI must still complete before merge.

[cjagwani]

Exact-head follow-up for 3f8bba830a49b46a18be6e74b510846e8c3c053d: the reviewed npm audit failed deterministically (1 unaccepted high finding in the reviewed archive, 4 in OpenClaw 2026.7.1, and 2 in mcporter 0.7.3), which leaves checks and the required E2E gate red. I am not treating this as infrastructure noise or rerunning it. This head needs a commit that resolves the audit policy failure, or a refresh incorporating an accepted policy update, before exact-head validation can continue. This is a coordination comment, not a Changes Requested review.

[cjagwani]

Release gate refresh needed for the current v0.0.102 queue:

• exact head: 3f2847b3fb8db384495486ca4c9dd5d60fae27a5
• recorded merge base: 8295d2069e1b4336a00573e717c838c2e04d62ee
• GitHub compare result against current main: diverged, 16 commits behind
• exact-head checks: green; review decision: approved

Please merge current main into this branch normally, refresh the exact-head documentation/security/test receipts, and let required CI/E2E complete on the new head. This is a release-gate refresh request, not a request to change the approved behavior.