sandbox: an S1 executor — a native program confined by the operating system, earning the rung by probe #281

Merged

dcharlot merged 1 commit from feat/sandbox-exec-os into main 2026-10-17 04:02:09 -04:00

Conversation 0 Commits 1 Files changed 8 +773 -19

2026-10-16

Transaction Science

sandbox: an S1 executor — a native program confined by the operating system, earning the rung by probe ...

The ladder had no executor between a bare child process (S0) and a managed
runtime (S2). `sandbox-exec-os` runs a native program under the operating
system's sandbox, with a deny-by-default policy derived from the unit's
grants:
- the program may read and write exactly the granted storage paths;
- it has no network;
- it cannot spawn a process;
- it reaches no device beyond the host CPU.

Why S1 and no more. S1's guarantee is that no resource is reachable without
a capability, and that holds for every resource grants govern. A native
process holds a stated residue: the system libraries read-only, the root
directory's listing, /dev/null, the clock and randomness. Because the clock
and randomness cannot be withheld, a grant that withholds either is refused,
never run with a capability it denies. So are network grants (egress cannot
be limited to named endpoints) and everything that needs S2: subprocesses,
browser, display, accelerators, key-value store. S2 itself needs fuel and
memory caps, which a native process cannot have.

The rung is earned per host. A probe, run once per process, runs a program
under a policy that grants nothing. It must succeed at a control run, and be
denied a file outside the policy, a write, a subprocess and a loopback
connection to a listener the probe opened. Only then is the tier S1, with
SPEC §7.9's mechanism: `seatbelt/<macOS version>` and a commitment to the
exact policy applied. Anywhere else the program runs unconfined at S0 with
no mechanism. Linux is S0 for now: a namespace sandbox there also needs a
system-call filter to enforce "no subprocess", and the fleet's Linux hosts
refuse the network namespace, so it could not be verified.

Energy is the child's share of the host's CPU reading (`run_attributed`):
ModelBased where that reading is a hardware one, Estimator otherwise.

sandbox-build: a command step runs confined at S1 where the confinement
holds and can enforce the step's grants, sealed with its mechanism. Any
other step falls back to the existing unconfined child process (S0), so
today's steps, whose grants withhold the clock, are unchanged.

CI: the macOS energy job runs sandbox-exec-os and fails unless the S1
branch ran (the probe's confinement line and a denied read). Every other
runner takes the S0 branch, which the same tests assert.

Checked on the build host (macOS 27.0.1): `seatbelt/27.0.1` probes S1. A
granted copy succeeds, a read outside the grants is denied, run_and_seal
seals S1 with the mechanism, and a unit withholding the clock is refused
before it runs. The sandbox-rs workspace passes 407 tests, conformance
passes all classes, and clippy is clean on both crates.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

cdd809ca7b

• View at this point in history

2026-10-16 10:09:35 -04:00