mirror of
https://github.com/openai/codex.git
synced 2026-11-17 22:10:37 +00:00
## What changed Allow transparent TCP with `--linux-sandbox-pid-namespace=inherit` while keeping PID isolation as the default. In inherited mode, use the existing `/proc` view and verify socket visibility before starting the command. Run the relay and workload as separate supervised children, protect relay descriptors from inspection, and kill the workload's process group if the relay exits first. Document cleanup behavior and the limits on terminating background descendants in inherited mode. ## Testing Extend managed TCP integration coverage to inherited PID namespaces, including namespace identity, existing network and filesystem restrictions, and workload process-group cleanup after relay failure. GitOrigin-RevId: c40befb95f10af39e9607235c3d78a04142ac168
165 lines
9.4 KiB
Markdown
165 lines
9.4 KiB
Markdown
# codex-linux-sandbox
|
|
|
|
This crate is responsible for producing:
|
|
|
|
- a `codex-linux-sandbox` standalone executable for Linux that is bundled with the Node.js version of the Codex CLI
|
|
- a lib crate that exposes the business logic of the executable as `run_main()` so that
|
|
- the `codex-exec` CLI can check if its arg0 is `codex-linux-sandbox` and, if so, execute as if it were `codex-linux-sandbox`
|
|
- this should also be true of the `codex` multitool CLI
|
|
|
|
The helper uses bubblewrap for filesystem and namespace isolation, and seccomp
|
|
for syscall filtering. `src/seccomp.rs` installs `PR_SET_NO_NEW_PRIVS` and the
|
|
seccomp filters; it also retains the legacy Landlock filesystem implementation.
|
|
`src/linux_run_main.rs` coordinates these stages through `LinuxSandboxCommand`.
|
|
End-to-end coverage lives in `tests/suite/sandbox.rs` and the other suite modules.
|
|
|
|
### Transparent TCP
|
|
|
|
```sh
|
|
codex sandbox --transparent-tcp --permission-profile db -- psql -h pg.example
|
|
```
|
|
|
|
The Rust sandbox helper includes the TCP stack. Codex starts it automatically.
|
|
The Linux host needs distro `bwrap` on `PATH`, user and network namespaces, IPv6,
|
|
and read/write access to `/dev/net/tun`.
|
|
Use full managed SOCKS5 mode for native database ports. Transparent TCP uses
|
|
PID isolation by default and also supports exec-server's
|
|
`--linux-sandbox-pid-namespace=inherit` in dedicated environments.
|
|
For proxy configuration, executor-wide capture and HTTP CONNECT routing, see the [exec-server setup](../exec-server/README.md#transparent-tcp).
|
|
|
|
The private DNS stub maps up to 8,192 names to stable addresses in `198.18.0.0/15`
|
|
and `fdc0:de00::/96`. The relay sends the original name and port to the attributed proxy;
|
|
literal addresses, including entries from a hosts file, are checked as IPs. Unknown
|
|
synthetic addresses are rejected. Loopback stays local. Each bridge permits 128 concurrent
|
|
connections. When the TCP stack is full, clients retry their opening SYN. The relay identifies each
|
|
native socket by both endpoints and its inode in the private namespace TCP tables. Closing that
|
|
socket cancels its pending approval connection, including when other clients use the same
|
|
destination. A client that shuts down only its write side can still receive a reply. General UDP,
|
|
QUIC, ICMP, legacy Landlock, and procfs fallback are outside this mode.
|
|
|
|
With PID isolation, the relay runs in the namespace's PID 1 process. When it
|
|
exits, the kernel kills the remaining processes in the PID namespace.
|
|
With PID inheritance, a supervisor runs the relay and the command as separate
|
|
children. Cleanup depends on which process exits first.
|
|
|
|
- If the relay dies first, the supervisor sends `SIGKILL` to the command's
|
|
process group and the command itself. Descendants that left the group can
|
|
survive.
|
|
- If the supervisor dies first, the relay and the command receive the
|
|
parent-death `SIGKILL`. Background descendants can survive even if they
|
|
stayed in the command's process group. This is an existing limitation of
|
|
inherited-PID mode when the launcher dies.
|
|
|
|
With transparent TCP off, Codex prefers the first `bwrap` found on `PATH`
|
|
outside the current working directory whenever it is available. If `bwrap` is
|
|
present but too old to support
|
|
`--argv0`, the helper keeps using system bubblewrap and switches to a
|
|
no-`--argv0` compatibility path for the inner re-exec. If `bwrap` is missing,
|
|
the helper falls back to the bundled `codex-resources/bwrap` binary shipped
|
|
with Codex.
|
|
Codex also surfaces a startup warning when `bwrap` is missing so users know it
|
|
is falling back to the bundled helper. Codex surfaces the same startup warning
|
|
path when bubblewrap cannot create user namespaces. WSL2 follows the normal
|
|
Linux bubblewrap path. WSL1 is not supported for bubblewrap sandboxing because
|
|
it cannot create the required user namespaces, so Codex rejects sandboxed shell
|
|
commands that would enter the bubblewrap path.
|
|
|
|
**Current Behavior**
|
|
|
|
- Legacy `sandbox_mode` configs remain supported and are converted to
|
|
`PermissionProfile` before sandbox execution.
|
|
- Bubblewrap is the default filesystem sandbox.
|
|
- If `bwrap` is present on `PATH` outside the current working directory, the
|
|
helper uses it.
|
|
- If `bwrap` is present but too old to support `--argv0`, the helper uses a
|
|
no-`--argv0` compatibility path for the inner re-exec.
|
|
- If `bwrap` is missing, the helper falls back to the bundled
|
|
`codex-resources/bwrap` path.
|
|
- If `bwrap` is missing, Codex also surfaces a startup warning instead of
|
|
printing directly from the sandbox helper.
|
|
- If bubblewrap cannot create user namespaces, Codex surfaces a startup warning
|
|
instead of waiting for a runtime sandbox failure.
|
|
- WSL2 uses the normal Linux bubblewrap path.
|
|
- WSL1 is not supported for bubblewrap sandboxing; Codex rejects sandboxed
|
|
shell commands that would require the bubblewrap path before invoking `bwrap`.
|
|
- Filesystem-restricted execution requires bubblewrap. The legacy Landlock
|
|
option is rejected for these policies because it cannot isolate app-server
|
|
Unix sockets. Disable `features.use_legacy_landlock` when upgrading.
|
|
- Bubblewrap preserves nested read-only and denied filesystem rules from
|
|
`PermissionProfile`.
|
|
- When bubblewrap is active, the helper applies `PR_SET_NO_NEW_PRIVS` and a
|
|
seccomp filter in-process after establishing the filesystem view. Restricted
|
|
network policies block network syscalls; filesystem-restricted policies with
|
|
otherwise unrestricted networking still block `AF_VSOCK` sockets. All filter
|
|
modes block `io_uring` to prevent bypassing socket-family restrictions.
|
|
- When bubblewrap is active, the filesystem is read-only by default via `--ro-bind / /`.
|
|
- When bubblewrap is active, writable roots are layered with `--bind <root> <root>`.
|
|
- When bubblewrap is active, protected subpaths under writable roots (for
|
|
example `.git`,
|
|
resolved `gitdir:`, and `.codex`) are re-applied as read-only via `--ro-bind`.
|
|
- When bubblewrap is active, overlapping split-policy
|
|
entries are applied in path-specificity order so narrower writable children
|
|
can reopen broader read-only or denied parents while narrower denied subpaths
|
|
still win. For example, `/repo = write`, `/repo/a = none`, `/repo/a/b = write`
|
|
keeps `/repo` writable, denies `/repo/a`, and reopens `/repo/a/b` as
|
|
writable again.
|
|
- When bubblewrap is active, unreadable glob entries are expanded before
|
|
launching the sandbox and matching files are masked in bubblewrap:
|
|
|
|
```text
|
|
Prefer: rg --files --hidden --no-ignore --glob <pattern> -- <search-root>
|
|
Fallback: internal globset walker when rg is not installed
|
|
Failure: any other rg failure aborts sandbox construction
|
|
```
|
|
|
|
Users can cap the scan depth per permissions profile:
|
|
|
|
```toml
|
|
[permissions.workspace.filesystem]
|
|
glob_scan_max_depth = 2
|
|
|
|
[permissions.workspace.filesystem.":workspace_roots"]
|
|
"**/*.env" = "none"
|
|
```
|
|
|
|
- When bubblewrap is active, symlink-in-path and non-existent protected paths inside
|
|
writable roots are blocked by mounting `/dev/null` on the symlink or first
|
|
missing component.
|
|
- When bubblewrap is active, the helper explicitly isolates the user namespace via
|
|
`--unshare-user`. By default it also creates a PID namespace via `--unshare-pid`.
|
|
- When bubblewrap is active and network is restricted without proxy routing, the helper also
|
|
isolates the network namespace via `--unshare-net`.
|
|
- In managed proxy mode, the helper uses `--unshare-net` plus an internal
|
|
TCP->UDS->TCP routing bridge so tool traffic reaches only configured proxy
|
|
endpoints.
|
|
- In managed proxy mode, after the bridge is live, seccomp allows IP sockets
|
|
inside the isolated network namespace and blocks new standalone `AF_UNIX`
|
|
sockets unless `dangerously_allow_all_unix_sockets` is granted. Unix socket
|
|
pairs remain allowed for communication between related processes.
|
|
- When bubblewrap is active, it mounts a fresh `/proc` via `--proc /proc` by default.
|
|
Transparent TCP with PID isolation requires this mount and aborts the launch
|
|
if it fails. With PID inheritance it uses the existing `/proc` view and checks
|
|
that the relay can see socket identities before starting the command.
|
|
In other modes, if that mount is denied, it retains the inherited `/proc` and still creates a
|
|
PID namespace, preserving the existing fallback. `--no-proc` also retains the
|
|
inherited `/proc` without disabling PID isolation. In these cases, process IDs
|
|
inside the sandbox can differ from those exposed by `/proc`. Default invocations
|
|
send no new helper flags and remain compatible with older helpers.
|
|
- Trusted provisioning of a dedicated environment can start
|
|
`codex exec-server --linux-sandbox-pid-namespace=inherit`. This startup-only
|
|
setting applies to both process and filesystem helpers; repository config and
|
|
command environment variables cannot enable it. The helper receives the new
|
|
`--inherit-pid-namespace` option, which requires an updated helper; deploy the
|
|
helper and startup flag together.
|
|
Inheritance reuses the caller's PID namespace and `/proc` together, omitting
|
|
`--unshare-pid` and `--as-pid-1`. This preserves process lookups but allows
|
|
sandboxed commands to signal other same-UID processes, including the executor.
|
|
With `:minimal`, the existing `/proc` is bound read-only, preserving its
|
|
container masks; explicit filesystem denials are applied afterward.
|
|
Filesystem, user, IPC, network, seccomp, and existing container `/proc` masks
|
|
remain in force. The default `isolate` mode retains PID isolation.
|
|
|
|
**Notes**
|
|
|
|
- The CLI surface is `codex sandbox`; the host OS selects the sandbox backend.
|