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

dcharlot commented 2026-10-16 10:12:47 -04:00

Owner

Copy link

What was missing

The isolation ladder had no executor between a bare child process (S0) and a managed runtime (S2). As a result, sandbox-build's command steps ran either unconfined or in a microVM, with nothing in between.

What this adds

sandbox-exec-os runs a native program under the operating system's sandbox. The policy is derived from the unit's grants and denies by default:

• 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 higher. S1's guarantee (spec/tiers.md) is that no resource is reachable without a capability, and that holds for every resource grants govern. A native process keeps a residue, which the crate documents:

• the system libraries, read-only;
• the root directory's listing;
• /dev/null;
• the clock and randomness.

The clock and randomness cannot be withheld from a native process, so a grant that withholds either one is refused, never run with a capability it denies. Also refused:

• network grants, because egress cannot be limited to the named endpoints;
• everything that needs S2: subprocesses, a browser, a display, accelerators, the key-value store.

S2 itself needs fuel metering and memory caps, which a native process cannot have.

The rung is earned on each host. A probe, run once per process, runs a program under a policy that grants nothing. The control run must succeed, and the program must be denied:

• a file outside the policy;
• a write;
• a subprocess;
• a loopback connection to a listener the probe opened.

Only when all of that holds is the tier S1, sealed with the SPEC §7.9 mechanism: seatbelt/<macOS version> plus 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 would also need a system-call filter to enforce "no subprocess", and the fleet's Linux hosts refuse the network namespace (bubblewrap fails to set up loopback under the AppArmor user-namespace restriction), so it could not be verified.

Energy is the child's share of the host's CPU reading (sandbox_meter::run_attributed). It is ModelBased where that reading comes from hardware, and Estimator otherwise.

sandbox-build: a command step runs confined, and seals S1 with its mechanism, when the confinement holds here and can enforce the step's grants. Every other step falls back to the existing unconfined child process. Today's steps withhold the clock, so they are unchanged.

CI: the macOS energy job gains a step that sets SANDBOX_EXEC_OS_EXPECT_S1=1. With that set, the tests fail if the probe does not hold, and the step requires the confinement line and a denied read in the output. Every other runner takes the S0 branch, which the same tests also assert. check-tests-in-ci.py passes.

Checked

On the build host, macOS 27.0.1:

• Probe: seatbelt/27.0.1 probes S1.
• Confinement: a granted copy succeeds and a read outside the grants is denied.
• Sealing: Host::run_and_seal seals S1 with the mechanism.
• Refusal: a unit that withholds the clock is refused before it runs.
• Suites: the sandbox-rs workspace passes 407 tests, conformance passes all classes, and clippy is clean on both crates.

Each of these mutations fails a test:

• the policy allows the network;
• a withheld clock is accepted;
• the mechanism commits to another policy;
• sandbox-build never confines;
• the policy reads everything. The probe catches this one: it drops to S0, and SANDBOX_EXEC_OS_EXPECT_S1 makes that a failure.

🤖 Generated with Claude Code

## What was missing The isolation ladder had no executor between a bare child process (S0) and a managed runtime (S2). As a result, sandbox-build's command steps ran either unconfined or in a microVM, with nothing in between. ## What this adds **`sandbox-exec-os`** runs a native program under the operating system's sandbox. The policy is derived from the unit's grants and denies by default: - 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 higher.** S1's guarantee (`spec/tiers.md`) is that no resource is reachable without a capability, and that holds for every resource grants govern. A native process keeps a residue, which the crate documents: - the system libraries, read-only; - the root directory's listing; - `/dev/null`; - the clock and randomness. The clock and randomness cannot be withheld from a native process, so a grant that withholds either one is **refused**, never run with a capability it denies. Also refused: - **network grants**, because egress cannot be limited to the named endpoints; - **everything that needs S2:** subprocesses, a browser, a display, accelerators, the key-value store. S2 itself needs fuel metering and memory caps, which a native process cannot have. **The rung is earned on each host.** A probe, run once per process, runs a program under a policy that grants nothing. The control run must succeed, and the program must be denied: - a file outside the policy; - a write; - a subprocess; - a loopback connection to a listener the probe opened. Only when all of that holds is the tier S1, sealed with the SPEC §7.9 mechanism: `seatbelt/<macOS version>` plus 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 would also need a system-call filter to enforce "no subprocess", and the fleet's Linux hosts refuse the network namespace (bubblewrap fails to set up loopback under the AppArmor user-namespace restriction), so it could not be verified. **Energy** is the child's share of the host's CPU reading (`sandbox_meter::run_attributed`). It is `ModelBased` where that reading comes from hardware, and `Estimator` otherwise. **sandbox-build:** a command step runs confined, and seals S1 with its mechanism, when the confinement holds here and can enforce the step's grants. Every other step falls back to the existing unconfined child process. Today's steps withhold the clock, so they are unchanged. **CI:** the macOS energy job gains a step that sets `SANDBOX_EXEC_OS_EXPECT_S1=1`. With that set, the tests fail if the probe does not hold, and the step requires the confinement line and a denied read in the output. Every other runner takes the S0 branch, which the same tests also assert. `check-tests-in-ci.py` passes. ## Checked On the build host, macOS 27.0.1: - **Probe:** `seatbelt/27.0.1` probes S1. - **Confinement:** a granted copy succeeds and a read outside the grants is denied. - **Sealing:** `Host::run_and_seal` seals S1 with the mechanism. - **Refusal:** a unit that withholds the clock is refused before it runs. - **Suites:** the sandbox-rs workspace passes 407 tests, conformance passes all classes, and clippy is clean on both crates. Each of these mutations fails a test: - the policy allows the network; - a withheld clock is accepted; - the mechanism commits to another policy; - sandbox-build never confines; - the policy reads everything. The probe catches this one: it drops to S0, and `SANDBOX_EXEC_OS_EXPECT_S1` makes that a failure. 🤖 Generated with [Claude Code](https://claude.com/claude-code)

dcharlot added 1 commit 2026-10-16 10:12:47 -04:00

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

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]>

dcharlot merged commit f1c47aafce into main 2026-10-17 04:02:09 -04:00

dcharlot referenced this pull request from a commit 2026-10-17 04:02:11 -04:00

Merge pull request 'sandbox: an S1 executor — a native program confined by the operating system, earning the rung by probe' (#281) from feat/sandbox-exec-os into main

dcharlot referenced this pull request from a commit 2026-10-18 07:19:04 -04:00

Merge remote-tracking branch 'origin/main' into wai/d2c-m7a

Sign in to join this conversation.

Reviewers

No reviewers

Labels

Clear labels

No items

No labels

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

1 participant

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

Transaction-Science/open-standards!281

No description provided.