feat: preserve image-declared identity in Docker and Podman

[matthewgrossman]

Problem Statement

Docker and Podman start the OpenShell supervisor as root and replace the image
entrypoint. Today, agent identity then falls back to the policy's named
sandbox:sandbox account, which requires every image to bake that exact user
and group.

The first implementation attempt in #2335 replaced that requirement with a
gateway-wide numeric identity, defaulting every local image to 10001:10001.
That is also the wrong local-driver abstraction: it discards the image's normal
OCI USER, can break image file ownership, and unnecessarily copies the
platform-assigned identity model used by Kubernetes/OpenShift.

Docker and Podman should preserve a sandbox image's declared non-root OCI
USER for agent children while continuing to run only the privileged
supervisor as 0:0.

This remains the Docker/Podman portion of #1959. PR #2335 is closed and
superseded by this design.

Design Decisions

• Reject newly created images with no OCI USER; OCI defaults those images to
  root.
• Reject USER root, USER 0, or any name resolving to UID or GID 0.
• Use image identity by default for Docker and Podman.
• Keep an explicit operator-controlled fixed identity mode for shared-storage
  deployments.
• Block creator-selected bind and named-volume mounts in image mode.
• Do not change Kubernetes/OpenShift or VM identity behavior.

User Contract

Image declaration	Agent behavior
USER app	Resolve app from the image passwd file and use its UID and primary GID.
USER app:staff	Resolve both names from the image account files.
USER 1234:1235	Use the numeric pair without requiring passwd or group entries.
USER 1234 with a passwd entry	Use UID 1234 and that entry's primary GID.
USER 1234 without a passwd entry	Reject and require an explicit group.
No USER	Reject and require a non-root declaration.
An identity resolving to UID/GID 0	Reject.

A passwd-less image therefore needs only:

USER 1234:1235

It does not need useradd, groupadd, or a user named sandbox.

Identity Modes

Local drivers expose an operator-selected identity source:

• image is the default. The agent uses OCI Config.User and may use only the
  driver-owned per-sandbox workspace plus immutable image mounts.
• fixed requires an explicit validated UID and GID. It supports deployments
  that intentionally attach external or shared storage under an
  operator-controlled principal.

The unshipped implicit 10001:10001 default and standalone Podman UID/GID flags
from #2335 must not return.

Image Inspection

Resolve or pull the final image before container creation, then inspect it and
carry both its immutable image ID and OCI Config.User through provisioning.
Create the container from that immutable ID so a mutable tag cannot change
between identity inspection and rootfs selection.

• Docker already calls Bollard inspect_image() and currently discards
  ImageInspect; read inspect.config.user and retain the image ID.
• Podman needs a typed wrapper for
  GET /v5.0.0/libpod/images/{name}/json, reading the image ID and
  Config.User.
• Podman create must not perform another pull decision after an immutable local
  image ID has been selected.
• Docker keeps container user = "0"; Podman keeps user = "0:0". Those
  values apply only to the supervisor.

Pass the raw OCI user declaration, immutable image ID, and identity source to
the supervisor through protected driver-owned metadata inserted after image and
request environment.

Supervisor Resolution

This extends an existing mechanism. The supervisor already runs inside the
sandbox image rootfs and resolves the legacy sandbox:sandbox identity before
filesystem preparation and the verified setgid/setuid sequence. Direct and
SSH children already share that privilege-drop boundary.

Do not reuse the current libc NSS path unchanged for arbitrary image users.
Resolve names with a bounded file-only parser:

• Open /etc/passwd and /etc/group without following symlinks.
• Require regular files and cap total, line, and field sizes.
• Reject malformed or duplicate matching names and IDs.
• Do not call getpwnam, getgrnam, NSS modules, or initgroups from the
  privileged supervisor.
• Resolve every accepted form to one complete numeric UID/GID.
• Use the passwd primary GID when the OCI declaration omits a group.
• Require an explicit group for an accountless numeric UID.
• Reject resolved UID/GID 0.

The resulting internal record contains at least:

ResolvedAgentIdentity {
    uid,
    gid,
    presentation_user,
    source,
    image_id,
}

Agent children receive no supplementary groups. Clear and verify the group list
before setgid/setuid for both named and numeric image declarations. Preserve
HOME=/sandbox; use the declared name for USER/LOGNAME when available and
the numeric UID otherwise.

OpenShell must not create or rewrite /etc/passwd or /etc/group.

Storage Boundary

The image is untrusted and may select any valid non-root UID/GID. That identity
may authorize access to its rootfs and isolated workspace, but it must not
select the principal used for unrelated storage.

In image mode, reject all creator-selected bind mounts and named-volume mounts.
The driver-owned per-sandbox /sandbox volume and immutable image mounts remain
allowed. A global bind-mount enable switch is not sufficient authorization for
image-selected IDs.

Operators that require external or shared storage must select fixed mode until
OpenShell has operator-authored mount grants binding storage sources to allowed
identities.

The supervisor may chown /sandbox itself and missing paths OpenShell creates.
It must not recursively chown existing descendants or nested mounts. Privileged
directory creation must use no-symlink ancestor traversal rather than checking
only the final path before create_dir_all.

Policy And Observability

Creator policy must not claim authority over an identity the managed runtime
ignores.

• Reject explicitly supplied run_as_user and run_as_group for new managed
  Docker/Podman sandboxes before default normalization.
• Retain those fields only for existing containers and unmanaged/offline
  execution.
• Persist and expose the resolved identity separately: source, immutable image
  ID, UID, GID, and supplementary groups.
• Emit the same record as an OCSF configuration-state event, but do not use logs
  as the authoritative API.

Resolve and persist an identity-versioned record before launching the first
agent. Restarts consume that record instead of re-resolving a mutable tag or
account file. Existing containers without the new metadata continue using their
legacy launch-effective policy and are not reinterpreted during upgrade.

User Namespaces

Validate resolved IDs against /proc/self/uid_map and
/proc/self/gid_map before chown or privilege drop. This covers rootless
Podman, rootless Docker, Docker userns-remap, and nested or remote setups.
Report the image declaration and unmapped ID without silently substituting a
different identity.

Respect /proc/self/setgroups: a denied clear is acceptable only if the current
supplementary-group list is already empty.

Compatibility And Documentation

• First-party images already declaring USER sandbox retain their baked
  identity.
• First-party and documented images with no final non-root USER must add one.
• The BYOC and private-IP-routing examples need explicit users.
• The userless fixture should declare a distinct numeric UID/GID without
  account entries.
• Existing sandboxes retain their creation-time identity. Changing identity
  mode or fixed IDs applies only to newly created sandboxes; persisted
  workspaces require recreation or an explicit migration.
• Update architecture docs, driver READMEs, BYOC documentation, gateway config
  reference, and examples. Clearly distinguish local image identity from
  Kubernetes/OpenShift platform-assigned identity.

Test Plan

Unit

• Parse named, numeric, named-group, numeric-group, and mixed OCI forms.
• Resolve named users to passwd UID and primary GID.
• Reject missing declarations, accountless UID-only declarations, root aliases,
  malformed input, duplicate entries, symlinks, non-regular files, and
  oversized account databases.
• Verify all image forms clear supplementary groups.
• Verify /sandbox root ownership changes without touching descendants.
• Verify passwd/group files remain unchanged.
• Verify old containers without identity metadata retain legacy behavior.

Driver Integration

• Docker inspects after local hits and every pull policy, carries the immutable
  image ID, and preserves supervisor user = 0.
• Podman image inspection handles compatible response shapes and escaping,
  carries the immutable image ID, disables a second pull decision, and
  preserves supervisor user = 0:0.
• Image mode rejects creator-selected external mounts; fixed mode uses explicit
  validated UID/GID.
• Image and request environment cannot spoof protected identity metadata.

E2E

• Passwd-less USER 1234:1235 runs as 1234:1235, has no supplementary
  groups or account entries, and writes to /sandbox.
• Named USER app uses the image account's UID and primary GID.
• Explicit named and mixed group forms resolve correctly.
• Missing USER, explicit root, and root aliases fail clearly.
• Rootless Podman, rootless Docker, and Docker userns-remap report unmapped IDs.
• Direct and SSH-launched children use the same identity and environment.
• Existing sandbox resume retains its persisted identity.

Alternatives Considered

• Fixed 10001:10001 by default: rejected because it breaks normal local
  image ownership and incorrectly copies the OpenShift model.
• Continue requiring sandbox:sandbox: rejected because it prevents
  passwd-less numeric images and arbitrary valid image users.
• Allow image identity with creator-selected external mounts: rejected
  because an untrusted image could choose the principal owning unrelated
  storage.
• Run the supervisor as OCI USER: rejected because namespace, mount,
  network, filesystem, and privilege-drop setup require root.
• Resolve names through NSS: rejected because privileged resolution must not
  invoke image-controlled NSS configuration or modules.

Scope

This issue covers Docker, Podman, shared supervisor identity resolution,
creation-time identity persistence and observability, affected policy handling,
tests, examples, and documentation.

Kubernetes/OpenShift and VM identity selection are out of scope except for
regression tests protecting their existing behavior.

[matthewgrossman]

🏗️ build-plan

Implementation Plan

Issue type: feat
Complexity: High
Confidence: Medium — the identity contract is approved, but implementation crosses image lifecycle, privileged supervisor setup, persisted runtime metadata, public policy semantics, and local-driver mount authorization.

Summary

Make OCI image USER the default agent identity for Docker and Podman while keeping the supervisor at 0:0. Resolve image names safely inside the image rootfs, normalize to a persisted numeric identity, reject root and missing declarations, and retain an explicit fixed mode for operator-controlled shared storage.

Scope

• crates/openshell-driver-docker/: inspect and pin the final image, add image/fixed identity modes, pass protected image metadata, and reject external mounts in image mode.
• crates/openshell-driver-podman/: add image inspection, pin the selected image, mirror identity modes and mount restrictions, and avoid a second create-time pull.
• crates/openshell-supervisor-process/: safely parse image passwd/group files, normalize identities, clear supplementary groups, harden workspace ownership, and share direct/SSH environment behavior.
• crates/openshell-sandbox/ and shared core/proto surfaces: resolve and persist creation-time identity, preserve legacy resume behavior, and expose the actual runtime identity separately from creator policy.
• crates/openshell-policy/ and server validation: reject creator-selected process identity for new managed Docker/Podman sandboxes without changing Kubernetes/VM behavior.
• e2e/, examples, architecture docs, driver READMEs, and published docs: cover and document named, passwd-less numeric, missing/root, fixed-mode, mapping, mount, and restart behavior.

Implementation Steps

1. Add shared internal identity-source and resolved-identity types, protected metadata keys, strict OCI USER parsing, and root/user-namespace validation.
2. Replace privileged libc NSS resolution for image identity with bounded no-follow /etc/passwd and /etc/group parsing; normalize named and numeric forms to one numeric privilege-drop path with empty supplementary groups.
3. Add versioned creation-time identity persistence and legacy fallback for existing containers; make direct and SSH children consume the same persisted identity and environment.
4. Update Docker provisioning to inspect after pull/local resolution, pin immutable image ID, preserve supervisor root, implement image/fixed modes, and reject creator-selected external mounts in image mode.
5. Add Podman image-inspect support and the equivalent pinned-image, identity-mode, mount, and pull-policy behavior.
6. Separate managed runtime identity from creator policy and expose the resolved source/image/UID/GID record through runtime status plus OCSF configuration logging.
7. Restrict privileged workspace preparation to /sandbox itself and safely created paths without recursive ownership changes or symlinked ancestor traversal.
8. Add unit, driver integration, and Docker/Podman E2E coverage, then update first-party examples and all affected architecture/published configuration docs.

Test Plan

• Unit: OCI forms, bounded account-file parsing, root/malformed/duplicate rejection, supplementary-group clearing, user-namespace maps, persistence/legacy resume, root-only workspace ownership, and policy authority.
• Integration: Docker and Podman inspect/pull/pin behavior, root supervisor override, protected metadata precedence, image/fixed modes, and external-mount rejection.
• E2E: passwd-less numeric and named images, missing/root failures, workspace writes, direct/SSH identity agreement, restart persistence, Docker, and rootless Podman when available.

Risks & Open Questions

• Runtime identity observability may require a proto/API extension; keep it narrowly scoped to the resolved identity record.
• Existing creator policy normalization loses omission provenance; managed-driver validation must occur before default normalization.
• SELinux/AppArmor hosts may reject privileged fork/exec test techniques. Keep parser tests pure and gate privileged identity-drop tests to compatible Linux environments.
• Existing containers must never be silently reinterpreted. New identity metadata applies only to newly created containers.
• Image mode cannot safely coexist with creator-selected external mounts until independent storage grants exist; fixed mode is the supported bridge.

Documentation Impact

• Required: docs/reference/gateway-config.mdx, docs/reference/sandbox-compute-drivers.mdx, BYOC docs/examples, Docker and Podman READMEs, and relevant architecture docs.
• Document that Kubernetes/OpenShift and VM retain their existing identity contracts.

---

Revision 2 — replace fixed 10001:10001 design with approved OCI USER architecture; add persistence, storage boundary, policy authority, and observability.
Revision 1 — initial fixed-identity plan for #2331.

[matthewgrossman]

🏗️ build-from-issue-agent

Implementation Complete

PR: #2335

What was built

Docker and Podman now choose a validated numeric sandbox UID/GID, inject it as protected supervisor configuration, and launch agent processes with consistent identity environment variables. A userless image fixture verifies that images no longer need a baked-in sandbox account.

Tests

• Unit: driver identity defaulting, overrides, range validation, and environment precedence; supervisor child identity environment behavior
• Integration: Docker and Podman custom_image feature variants compile
• E2E: Docker userless-image path passed locally; rootless Podman runtime validation is covered by CI because Podman is unavailable on the development host

Docs updated

• Runtime and sandbox architecture overviews
• Docker and Podman driver READMEs
• Gateway configuration reference and Docker sample
• Bring-your-own-container example

The issue will auto-close when the PR is merged.

[matthewgrossman]

🏗️ build-from-issue-agent

PR blocked by vouch workflow

PR #2335 was created successfully, but the Vouch Check workflow closed it twice while reporting matthewgrossman as unvouched. GitHub reports the author's repository association as member; the workflow's org-membership bypass did not take effect.

The implementation, signed-off commit, full pre-commit suite, and local Docker userless-image E2E are complete. To resume CI, add matthewgrossman to the dedicated vouched branch through the normal /vouch process (or repair the workflow's ORG_READ_TOKEN membership check), then reopen #2335.