feat(sandbox): honor OCI image working directories

[matthewgrossman]

Summary

This PR lets a Docker sandbox use the non-root user and working directory already declared by an ordinary container image instead of requiring /sandbox to be its one blessed workspace.

For example, this small Ubuntu image now works as-is:

FROM ubuntu:24.04

RUN apt-get update \
    && apt-get install -y iproute2 \
    && install -d -o ubuntu -g ubuntu /workspace

USER ubuntu
WORKDIR /workspace

OpenShell runs the agent as the image's ubuntu user with both its current directory and HOME set to /workspace. The user can write there because the image already grants that access. OpenShell does not create /sandbox, change ownership or permissions, or grant the user new filesystem authority.

Previously, OpenShell ignored this usable OCI WORKDIR and still treated /sandbox as the workspace. Images therefore needed to be modified around OpenShell's directory convention even when they already declared a valid non-root user and writable workdir.

Images with an empty workdir, WORKDIR /, or WORKDIR /sandbox retain the existing OpenShell-managed /sandbox compatibility behavior. Podman, Kubernetes/OpenShift, and VM also retain /sandbox in this PR.

This work was originally developed as a stack on #2509, which added policy-first OCI image identity and has since merged. The original scope also included Podman support; that work was extracted into #2563, which is stacked on this PR because Podman's persistent workspace volume requires additional validation machinery.

Related Issue

Part of #2526

Changes

• inspect WorkingDir and User from the same immutable Docker image and pass the resolved workspace through the existing supervisor workdir argument
• enforce a path-independent no-authority-expansion invariant: the final OCI UID, GID, and supplementary groups must already be able to traverse every parent and write and enter the workdir
• use no-follow file-descriptor traversal and kernel effective-access checks so symlinks, ACLs, and LSM decisions are honored
• keep /sandbox compatibility behavior unchanged for images with an empty, root, or explicit /sandbox workdir
• reject Docker image VOLUME declarations and OpenShell control mounts that would mask or collide with the resolved workdir
• use filesystem.include_workdir instead of automatically granting literal /sandbox
• discover the canonical remote workspace over SSH for upload defaults, download containment, and editor launch
• preserve fixed /sandbox behavior for Podman, Kubernetes/OpenShift, and VM
• update architecture, Docker driver, policy, CLI, and agent guidance

Why kernel-effective access checks

Linux access is not determined by ownership and chmod mode bits alone. A POSIX ACL can grant a particular image user access that mode-bit inspection would reject, while an enforcing Linux Security Module such as SELinux or AppArmor can deny access that mode bits appear to allow.

OpenShell does not add ACL or LSM policy management in this PR. Instead, a one-shot validator assumes the final sandbox UID, GID, and supplementary groups and asks the Linux kernel whether that identity can traverse the path and write and enter the workdir. This delegates the decision to the same authority the workload will encounter, avoids maintaining an incomplete permission model in OpenShell, and preserves the central rule that selecting an image workdir must not expand the image user's authority.

Testing

• mise run pre-commit passes
• Focused Docker, core, policy/prover, sandbox, supervisor-process, and Podman compatibility unit suites pass
• Unit tests cover final-identity access, supplementary groups, POSIX ACL grants, enforcing LSM denials, symlink/restrictive-parent rejection, mount collisions, and compatibility fallback
• Docker E2E coverage includes OCI WorkingDir behavior, direct/SSH access, transfers, and nested volumes
• Manually built the Ubuntu image above through openshell sandbox create; verified UID/GID 1000, PWD=/workspace, HOME=/workspace, write access, and full iproute2

Checklist

• Follows Conventional Commits
• Commits are signed off (DCO)
• Architecture docs updated (if applicable)

[github-actions]

🌿 Preview your docs: https://nvidia-preview-pr-2530.docs.buildwithfern.com/openshell

[drew]

gator-agent

Blocked

Gator is blocked because PR #2530 currently has merge conflicts (mergeStateStatus: DIRTY) against its base branch.

Next action: @matthewgrossman, please rebase or merge the base branch and resolve the conflicts, then push an updated head SHA so gator can run the independent review.

[drew]

gator-agent

PR Review Status

Validation: PR #2530 implements linked issue #2526, which is already marked state:agent-ready / state:pr-opened, and the current head is open, ready for review, and no longer conflict-blocked.
Head SHA: 493abe06869d41a5b161a1a97abc21c0c3ce6436

Review findings:

• Warning: Docker/Podman pass the resolved workspace to the supervisor, but the create specs still appear to inherit the image process cwd. For hand-crafted OCI images where Config.WorkingDir is missing on disk or is not a directory, the container runtime may fail before the supervisor can run the intended workspace validation/preparation path. Please consider starting the supervisor from a known-safe cwd such as / while passing --workdir <resolved-root> separately, and add coverage for missing/non-directory WorkingDir.
• See the inline warning about accepting whitespace/control-character OCI WorkingDir values before SSH discovery and shell-text flows consume the path.

Docs: Fern docs and relevant agent skill guidance were updated; no docs navigation change appears required because no new page was added.

Next state: gator:in-review

[github-actions]

Label test:e2e applied for 41b25a7. Open the existing run and click Re-run all jobs to execute with the label set. The run will execute the standard E2E suite after building the required gateway and supervisor images once. The matching required CI gate status on this PR will flip green automatically once the run finishes.

[drew]

gator-agent

PR Review Status

Validation: PR #2530 implements linked issue #2526, which is already marked state:agent-ready / state:pr-opened. The PR is open, ready for review, and no longer conflict-blocked.
Head SHA: 41b25a7415a4b502412b5e92926ac9730deac14f

Review findings:

• No blocking findings remain from the independent review.
• The previous gator ledger item about whitespace/control-character OCI WorkingDir handling appears addressed in this head.

Docs: Fern docs and relevant agent skill guidance were updated; no docs navigation change appears required because no new page was added.

E2E: Applied test:e2e because this change affects sandbox lifecycle, policy behavior, Docker/Podman driver behavior, and SSH transfer/editor workspace behavior.

Checks: Required checks are not green yet. OpenShell / Branch Checks is still in progress; the Rust jobs are currently failing, but the run is still active and failed logs are not available until it completes, so gator will classify the failure on the next reconciliation cycle.

Next state: gator:watch-pipeline

[drew]

gator-agent

PR Review Status

Validation: PR #2530 implements maintainer-authored, agent-ready issue #2526 and remains open, non-draft, mergeable, and project-valid.
Head SHA: 6bafbb649530f60871f7b4a545a6c56bfde5ead0

Review findings:

• One warning remains about guaranteeing that an existing OCI workspace is writable after ownership preparation; see the inline comment.
• The prior whitespace/control-character OCI WorkingDir finding remains addressed and was not re-raised.

Docs: Fern docs and relevant agent skill guidance are updated; no navigation change is needed because no page was added.

E2E: test:e2e remains appropriate for the sandbox lifecycle, policy, Docker/Podman, and SSH workspace changes.

Next state: gator:in-review

[drew]

gator-agent

PR Review Status

Validation: PR #2530 implements maintainer-authored, agent-ready issue #2526 and remains open, non-draft, mergeable, and project-valid.
Head SHA: ad58a35413db4717d8d487b782d2f45465d9bd18

Review findings:

• One warning remains about guaranteeing that an existing OCI workspace is writable after ownership preparation; see the inline comment.
• The new head addresses the SSH connection-limit path, but it does not change the workspace ownership/preparation code behind the unresolved warning.
• The prior whitespace/control-character OCI WorkingDir finding remains addressed and was not re-raised.

Docs: Fern docs and relevant agent skill guidance are updated; no navigation change is needed because no page was added.

E2E: test:e2e remains appropriate for the sandbox lifecycle, policy, Docker/Podman, and SSH workspace changes.

Next state: gator:in-review

[drew]

gator-agent

PR Review Status

Validation: PR #2530 implements agent-ready issue #2526 and remains open, non-draft, mergeable, and project-valid.
Head SHA: ccba5bb168afa4d7b554bb1b42b121871c745fd0

Thanks @matthewgrossman. I checked your latest replies against the current diff: the whitespace/control-character validation and existing 0555 workspace permission findings are resolved and were not re-raised.

Review findings:

• Three distinct warnings remain; see the inline comments for the Docker pre-inspection mount check, inaccessible workspace ancestors, and incomplete protection of system paths selected through OCI WorkingDir.

Docs: Fern docs and the relevant generate-sandbox-policy / openshell-cli skill guidance are updated; no navigation change is needed because no page was added or moved.

E2E: test:e2e remains appropriate for the sandbox lifecycle, policy, Docker/Podman, and SSH workspace changes.

Next state: gator:in-review

[drew]

gator-agent

PR Review Status

Validation: PR #2530 implements agent-ready issue #2526 and remains open, non-draft, mergeable, and project-valid.
Head SHA: babd6ba679067f40eaacbf5bfad4a65283e4acaa

Thanks @matthewgrossman. I checked your current-head replies against the diff: the Docker placeholder-metadata mount collision, inaccessible 0700 ancestor case, and protected-system-tree coverage are addressed and were not re-raised.

Review findings:

• One distinct warning remains for workspace ancestors traversable only through a named user's supplementary groups; see the inline comment.
• One docs wording correction is suggested; see the inline comment.

Docs: Relevant Fern docs and agent skill guidance are updated, and no navigation change is needed because no page was added or moved. The baseline-filesystem wording should be qualified as noted inline.

E2E: test:e2e remains appropriate for the sandbox lifecycle, policy, Docker/Podman, SSH, transfer, and editor-workspace changes.

Next state: gator:in-review

[drew]

gator-agent

Review Convergence Checkpoint

Head SHA: 79706d62106b791779850923111c8153accfcd21
Base SHA: 596d729e3fbe4f828424cadbe0bf1b3c5b307ada
Merge base SHA: 596d729e3fbe4f828424cadbe0bf1b3c5b307ada
Patch ID: 0ea5dd473e2aecbfc5dff89e11d10ddf6c9a0c87
Gator payload: 2

Thirteen finding-bearing review rounds have completed, so Gator remains at the mandatory maintainer convergence checkpoint.

Thanks @matthewgrossman. I checked the merge-from-main commit after checkpoint head 6b706bf5ecd6932d6ecfdcef07b7ebf3ad1b8cea. The feedback ledger reports the same effective patch ID as that reviewed checkpoint head, so there is no new author-only delta and no additional autonomous reviewer run is warranted.

Root-cause findings:

• gator-inline-3678664540: the earlier forged workspace-attestation route remains absent from the current Docker implementation.
• gator-inline-3678664544: the current implementation still uses ownership and POSIX mode metadata for workspace access validation. Because the convergence checkpoint prohibits another autonomous Warning round, this remains a maintainer scope decision.
• Earlier workspace-resolution, identity, mount-collision, prover, docs, and E2E history retains its durable disposition. Podman implementation remains split into follow-up PR feat(podman): honor OCI image working directories #2563.

Scope growth:

• The effective patch is unchanged by this merge-from-main commit and adds no subsystem, public configuration, or policy surface.
• The Docker/Podman scope split and remaining access-validation obligation still need explicit maintainer disposition.

Reviewer-quality signals:

• Ledger telemetry remains 14 review rounds, 13 finding-bearing rounds, 17 unique findings, 0 duplicate finding-ID occurrences, and 0 findings repeated across review heads.
• No reviewer was run for this upstream-only head update because its effective patch matches the already-reviewed checkpoint patch.

Maintainer action: please accept the current Docker-only scope, confirm the Podman split, waive the remaining access-validation obligation, or explicitly authorize another autonomous review round.

Next state: gator:blocked

[drew]

gator-agent

Re-check After Maintainer Update

Thanks @matthewgrossman. I verified your repository-admin authority and re-evaluated current head 7306dd7b24b862a4b5c1330e35158f1d9f85ab69 after your update confirming the Podman split and the effective-access remediation.

Head SHA: 7306dd7b24b862a4b5c1330e35158f1d9f85ab69
Base SHA: 596d729e3fbe4f828424cadbe0bf1b3c5b307ada
Merge base SHA: 596d729e3fbe4f828424cadbe0bf1b3c5b307ada
Patch ID: ec6d61c7623c6322f502beaa75aae0aed2efe3df
Gator payload: 2
Review mode: human_checkpoint

What I checked:

• The complete durable feedback ledger and the author-only delta after checkpoint head 79706d62106b791779850923111c8153accfcd21.
• The one-shot validator added in fe98793f and its ACL/LSM-focused coverage in 7240e3fc.
• A bounded independent Critical-only checkpoint review, which found no new Critical security, data-loss, or correctness defect.
• Your explicit split of the Podman work into follow-up PR feat(podman): honor OCI image working directories #2563.

Checkpoint disposition: resolved. The Podman split supplies the requested maintainer scope decision, and the current delta addresses the remaining kernel-effective access obligation. Earlier durable findings retain their recorded dispositions.

Pipeline disposition: author action is still required. OpenShell / Branch Checks fails in both Rust lint jobs because the new tests do not compile:

• crates/openshell-supervisor-process/src/process.rs:3150 and :3156 call crate::sandbox::prepare_current_user and crate::sandbox::enforce, but those functions are exported under crate::sandbox::linux.
• crates/openshell-supervisor-process/src/process.rs:3090 leaves the ACL permission literal type ambiguous for to_ne_bytes.
• The same test code also triggers unused_qualifications for std::ffi::CString and the sandbox calls.

Please fix the compile/clippy errors and push a new head. OpenShell / E2E is still pending; Helm Lint and GPU E2E are green.

Reviewer-quality signals: 0 proposed findings, 0 unchanged-code proposals, 0 duplicate invariants, and 0 missing-reproducer downgrades. Ledger telemetry remains 14 review rounds, 13 finding-bearing rounds, 17 unique findings, and no duplicate finding IDs.

Next state: gator:in-review

[drew]

gator-agent

Re-check After Author and Maintainer Update

Thanks @matthewgrossman. I re-evaluated current head a554b062ced98a045a2e2181e77c3bd0412a7173 after your compile/clippy repair and your current-head review questions.

Head SHA: a554b062ced98a045a2e2181e77c3bd0412a7173
Base SHA: 596d729e3fbe4f828424cadbe0bf1b3c5b307ada
Merge base SHA: 596d729e3fbe4f828424cadbe0bf1b3c5b307ada
Patch ID: 459ade88e4b124009a14d5a49b056d0ef1d61573
Gator payload: 2
Review mode: human_checkpoint
Previous reviewed SHA: 7306dd7b24b862a4b5c1330e35158f1d9f85ab69

What I checked:

• The complete durable feedback ledger and the author-only delta after 7306dd7b24b862a4b5c1330e35158f1d9f85ab69.
• The real effective-identity write probe added in this head and the compile/clippy corrections requested in the previous disposition.
• A bounded independent Critical-only checkpoint review. It found no new Critical security, data-loss, or correctness defect introduced by this delta.
• Your current questions about whether the protected supervisor-path set can drift, how OCI VOLUME can shadow a WORKDIR and how the PR detects that collision, and why the identity-related change belongs in this PR.

Disposition: the previous compile/clippy blocker is resolved. OpenShell / Branch Checks, DCO, Helm Lint, and the other completed required gates are green. OpenShell / E2E is still pending.

Remaining items:

• The three trusted maintainer review questions above still need a reply or explicit resolution before gator can hand the PR to pipeline-only monitoring.

Durable earlier findings retain their recorded dispositions. Reviewer telemetry for this round: 0 proposed findings, 0 blockers, 0 unchanged-code proposals, 0 duplicate invariants, and 0 missing-reproducer downgrades. Ledger telemetry is 15 review rounds, 13 finding-bearing rounds, 17 unique findings, 0 duplicate finding-ID occurrences, and 0 findings repeated across review heads.

Next state: gator:in-review

[drew]

gator-agent

Re-check After Author and Maintainer Update

Thanks @matthewgrossman. I re-evaluated current head 4b3530c51173140ac8dde97a52b9028eabfd9297 after your replies about protected-path drift and Docker VOLUME/WORKDIR shadowing.

Head SHA: 4b3530c51173140ac8dde97a52b9028eabfd9297
Base SHA: 596d729e3fbe4f828424cadbe0bf1b3c5b307ada
Merge base SHA: 596d729e3fbe4f828424cadbe0bf1b3c5b307ada
Patch ID: 769c0f375b488d736d2c68dfac3b461e7306ee01
Gator payload: 2
Review mode: human_checkpoint
Previous reviewed SHA: a554b062ced98a045a2e2181e77c3bd0412a7173

What I checked:

• The complete durable feedback ledger and the five-file author-only delta after a554b062ced98a045a2e2181e77c3bd0412a7173.
• The new stable control-root reservations, ancestor/descendant overlap checks, runtime-configured SSH-socket validation, and focused image-volume/user-mount regressions.
• Your explanation that Docker creates an image-declared anonymous volume before entrypoint and that the pinned-image metadata plus component-aware path checks reject a volume that masks the resolved workdir.
• A bounded independent Critical-only checkpoint review, which found no new Critical security, data-loss, or correctness defect introduced by this delta.

Disposition: the protected-path drift concern and the VOLUME/WORKDIR shadowing question are resolved by the current implementation and explanation. Durable earlier findings retain their recorded dispositions.

Remaining item:

• Your trusted review question about why the identity-related change in crates/openshell-supervisor-process/src/identity.rs belongs in this PR rather than the earlier OCI USER PR still needs a reply or explicit maintainer resolution.

Checks: OpenShell / Branch Checks and OpenShell / E2E are currently pending; Helm Lint and GPU E2E are green.

Reviewer telemetry for this round: 0 proposed findings, 0 blockers, 0 unchanged-code proposals, 0 duplicate invariants, and 0 missing-reproducer downgrades. Ledger telemetry is 16 review rounds, 13 finding-bearing rounds, 17 unique findings, 0 duplicate finding-ID occurrences, and 0 findings repeated across review heads.

Next state: gator:in-review

[drew]

gator-agent

Re-check After Author Update

Thanks @matthewgrossman. I re-evaluated current head 044179777de560d4a7025cfff0d990aeb92a5955 after your control-path centralization commit.

Head SHA: 044179777de560d4a7025cfff0d990aeb92a5955
Base SHA: 596d729e3fbe4f828424cadbe0bf1b3c5b307ada
Merge base SHA: 596d729e3fbe4f828424cadbe0bf1b3c5b307ada
Patch ID: df65a4aed32ef5a7a5ae43eed9a68a07d219e25f
Gator payload: 2
Review mode: human_checkpoint
Previous reviewed SHA: 4b3530c51173140ac8dde97a52b9028eabfd9297

What I checked:

• The complete durable feedback ledger and the 19-file author-only delta after 4b3530c51173140ac8dde97a52b9028eabfd9297.
• The new container_paths source of truth and its replacements of fixed OpenShell control paths across core, Docker, Kubernetes, Podman, VM, policy, sandbox, and supervisor code.
• A bounded independent Critical-only checkpoint review, which found no new Critical security, data-loss, or correctness defect introduced by this delta.

Disposition: the refactor does not materially invalidate prior finding resolutions and introduces no new Critical blocker. Durable earlier findings retain their recorded dispositions.

Remaining item:

• Your trusted review question about why the identity-related change in crates/openshell-supervisor-process/src/identity.rs belongs in this PR rather than the earlier OCI USER PR still needs a reply or explicit maintainer resolution. This delta does not change that file or answer the scope question.

Checks: OpenShell / Branch Checks, OpenShell / Helm Lint, and OpenShell / E2E are currently pending; GPU E2E is green.

Reviewer telemetry for this round: 0 proposed findings, 0 blockers, 0 unchanged-code proposals, 0 duplicate invariants, and 0 missing-reproducer downgrades. Ledger telemetry is 17 review rounds, 13 finding-bearing rounds, 17 unique findings, 0 duplicate finding-ID occurrences, and 0 findings repeated across review heads.

Next state: gator:in-review

[drew]

gator-agent

Re-check After Author Update

Thanks @matthewgrossman. I re-evaluated current head 27eea969d48ab6714f707c07e846b94e1dc8e856 after your fix(sandbox): reserve OCI runtime mount roots commit.

Head SHA: 27eea969d48ab6714f707c07e846b94e1dc8e856
Base SHA: 596d729e3fbe4f828424cadbe0bf1b3c5b307ada
Merge base SHA: 596d729e3fbe4f828424cadbe0bf1b3c5b307ada
Patch ID: 1234065b2d32c600d4c9d109d2d41812e7cfed09
Gator payload: 2
Review mode: human_checkpoint
Previous reviewed SHA: 044179777de560d4a7025cfff0d990aeb92a5955

What I checked:

• The complete durable feedback ledger and the six-file author-only delta after 044179777de560d4a7025cfff0d990aeb92a5955.
• The new /proc, /sys, and /dev OCI runtime namespace reservations and the replacement of filesystem-type rejection with path-based validation.
• A bounded independent Critical-only checkpoint review, which found no new Critical security, data-loss, or correctness defect introduced by this delta.

Disposition: no new technical blocker was found, and durable earlier findings retain their recorded dispositions. Reviewer telemetry for this round is 0 proposed findings, 0 blockers, 0 unchanged-code proposals, 0 duplicate invariants, and 0 missing-reproducer downgrades. Ledger telemetry is 18 review rounds, 13 finding-bearing rounds, 17 unique findings, 0 duplicate finding-ID occurrences, and 0 findings repeated across review heads.

Checks: OpenShell / Branch Checks and OpenShell / E2E are pending. OpenShell / Helm Lint and OpenShell / GPU E2E are green. Maintainer approval is still missing.

Next state: gator:watch-pipeline

[matthewgrossman]

Independent context review:

PR review: #2530
No new security vulnerabilities or merge-blocking correctness issues found.
The security-sensitive design looks sound:
OCI metadata comes from the inspected immutable image, preventing tag-swap inconsistencies.
Working directories are normalized and rejected when they overlap OCI runtime mounts or OpenShell control paths.
Image VOLUME declarations and configured mounts cannot mask the workspace or supervisor resources.
Custom workspaces are validated under the final UID, GID, and supplementary groups using no-follow descriptor traversal and an actual kernel-enforced write probe.
The managed /sandbox fallback remains the only workspace whose ownership or permissions OpenShell expands.
Filesystem policy grants the resolved workspace through include_workdir, rather than accidentally retaining writable /sandbox.
SSH downloads perform both lexical containment and remote symlink resolution against the discovered workspace.
The earlier critical concern—allowing image-controlled environment variables to forge workspace prevalidation—does not exist at the current head; Docker always performs its own final-identity validation.
Residual risk: download containment still has the pre-existing cross-command TOCTOU window between realpath and the later tar operation. This PR changes the workspace root but does not introduce that race, so I would not block #2530 on it.
All required branch and E2E checks are green. The PR is currently blocked only on maintainer approval.