feat(sandbox): implement probe-gated Linux strict isolation (ADR-0021)
Strict mode now re-executes the CLI inside a Bubblewrap supervisor with user/mount/PID/net/UTS/IPC namespaces, no-new-privs, all capabilities dropped, a read-only /project, private /proc and /dev, rlimits, output capture and wall-clock process-group cleanup. The child verifies PID 1, NoNewPrivs, empty CapEff, an unshared uid map and loopback-only networking before project code. - PlatformCapabilities::detect runs a real bwrap probe; no probe, no strict - strict L1 supports pure Marqdo + Math; Foreign/ABI/worker/kernel/grants/trace are rejected with exit 2 before sandboxing - forged MARQDO_STRICT_ACTIVE is rejected; missing bwrap fails closed - add adversarial helper, 7-test escape/resource matrix, seeded security lane script and self-hosted security workflow - executed G-C lane as uid 1000 in a disposable Ubuntu 26.04 VM: 7/7 PASS plus positive CLI and refusal matrix; evidence in docs/evidence - ADR-0021, spec/security.md, STATUS/COMPATIBILITY/README/CHANGELOG updated; ADR-0019 remains for non-Linux/fail-closed rules
This commit is contained in:
1 parent
9b001a33a5
commit
b6fc18233d
22 files changed
+1886
-132
No files matched your search
@@ -1,6 +1,6 @@
|
||||
# ADR-0019: Strict-mode availability gate
|
||||
|
||||
Status: **Accepted**
|
||||
Status: **Accepted; Linux availability superseded by ADR-0021**
|
||||
Date: 2026-11-20
|
||||
Relates to: ADR-0004 (strict mode refuses without isolation), blueprint §9
|
||||
|
||||
@@ -18,6 +18,15 @@ rules only; it does not by itself satisfy the network/process/resource and
|
||||
child-tree requirements in `docs/CORE_STABILIZATION_AND_ECOSYSTEM_GATE.md`
|
||||
§13.
|
||||
|
||||
## Superseding note (2026-11-20)
|
||||
|
||||
The fail-closed principle and the per-platform, test-gated availability rule in
|
||||
this ADR remain in force. A concrete Linux adapter has since passed the
|
||||
security matrix in a disposable Ubuntu VM and is specified by **ADR-0021**:
|
||||
strict becomes `Available` only when the Bubblewrap probe succeeds at runtime.
|
||||
This ADR remains authoritative for every other platform and for the rule that
|
||||
availability must never be assumed.
|
||||
|
||||
## Decision
|
||||
|
||||
### 1. Strict stays unavailable until the gate passes
|
||||
|
||||
@@ -0,0 +1,103 @@
|
||||
# ADR-0021: Linux strict isolation via Bubblewrap, namespaces and rlimits
|
||||
|
||||
Status: **Accepted**
|
||||
Date: 2026-11-20
|
||||
Relates to: ADR-0004, ADR-0019, `spec/security.md`, stable-release plan §10
|
||||
Security evidence: `docs/evidence/2026-11-20-strict-gc.md`
|
||||
|
||||
## Context
|
||||
|
||||
ADR-0019 kept strict mode `Unavailable` everywhere because no adapter had been
|
||||
executed against the full escape/resource matrix, and the first development
|
||||
host could not create any namespace. A disposable Ubuntu 26.04 VM with a real
|
||||
kernel, writable cgroup2, passwordless sudo for test setup and the packaged
|
||||
Bubblewrap AppArmor profile became available. It can create user, mount, PID,
|
||||
network, UTS and IPC namespaces as an ordinary user through `bwrap`.
|
||||
|
||||
## Decision
|
||||
|
||||
### 1. Dynamic, probe-gated availability
|
||||
|
||||
`PlatformCapabilities::detect()` on Linux runs a real Bubblewrap smoke test
|
||||
(`--unshare-all --as-pid-1`, read-only runtime bind, private `/proc` and
|
||||
`/dev`). Strict is `Available { mechanism: "bubblewrap ..." }` only when that
|
||||
probe succeeds; otherwise it stays `Unavailable` with the real reason. There is
|
||||
still no fallback to `project`.
|
||||
|
||||
### 2. L1 scope: pure language and native Math only
|
||||
|
||||
Strict accepts `run`/`call` of documents using the interpreter, console and
|
||||
native Math. It rejects `--allow-read`, `--allow-write`, `--allow-foreign`,
|
||||
`--allow-plugin`, `--plugin`, `--trust-native-plugin`, `--kernel` and
|
||||
`--trace-file` with exit 2 before any sandbox starts. Native ABI, worker
|
||||
plugins and Foreign kernels are therefore not reachable in strict mode in this
|
||||
release; L2 inheritance is future work.
|
||||
|
||||
### 3. Construction
|
||||
|
||||
The trusted supervisor is this process; the restricted child is the same
|
||||
`marqdo` executable re-executed under Bubblewrap:
|
||||
|
||||
* `--unshare-all --as-pid-1 --die-with-parent --new-session` — user, mount,
|
||||
PID, network, UTS, IPC and cgroup namespaces; the child is PID 1;
|
||||
* read-only binds of `/usr`, `/bin`, `/sbin`, `/lib`, `/lib64` and
|
||||
`/etc/ld.so.cache`, and of the project tree at `/project`;
|
||||
* a read-only bind of the program at `/run/marqdo-program`; no host `/root`,
|
||||
`$HOME`, `/etc` or other project directories are visible;
|
||||
* private `/proc`, minimal `/dev`, tmpfs `/tmp`;
|
||||
* `--clearenv`, `no_new_privs`, `--cap-drop ALL`;
|
||||
* hard rlimits: CPU, address space (512 MiB), file size, open files (64),
|
||||
processes (64), stack (8 MiB), core (0);
|
||||
* a supervisor deadline that kills the process group, and bounded capture of
|
||||
stdout/stderr.
|
||||
|
||||
The document argument is rewritten to `/project/...`; only the document token
|
||||
changes, all other arguments are preserved.
|
||||
|
||||
### 4. Child self-verification
|
||||
|
||||
The child accepts `MARQDO_STRICT_ACTIVE=1` only if it can verify all of:
|
||||
`getpid() == 1`, `NoNewPrivs: 1`, empty `CapEff`, a non-initial uid map, and no
|
||||
non-loopback network interface. A forged marker outside the sandbox fails
|
||||
before project code runs.
|
||||
|
||||
### 5. Threat model and non-goals
|
||||
|
||||
This protects against untrusted Marqdo documents that use the language,
|
||||
interpreter, Math, console, or attempt direct syscalls. It does not sandbox
|
||||
native plugins (rejected), Foreign kernels (rejected), or a malicious kernel.
|
||||
Bubblewrap is the construction mechanism, not a certificate; the runtime probe
|
||||
and self-verification are part of the contract.
|
||||
|
||||
Known limits: rlimits are used instead of cgroup-v2 accounting (the VM has
|
||||
writable cgroups, but the released adapter does not yet claim cgroup
|
||||
enforcement); filesystem TOCTOU is limited by read-only mounts but not proven
|
||||
against a racing host user; the project tree is exposed read-only in full;
|
||||
network is isolated by a network namespace rather than a seccomp allowlist. No
|
||||
worker/Foreign L2 claim is made.
|
||||
|
||||
## Evidence
|
||||
|
||||
Executed in a disposable Ubuntu 26.04 VM (kernel 7.0.0, `container: none`,
|
||||
Bubblewrap 0.11.1, AppArmor `bwrap-userns-restrict` profile, ordinary user
|
||||
`dev`):
|
||||
|
||||
* 7/7 adversarial tests: identity, host reads, writes, `/proc`/privileges,
|
||||
network, fd/process limits, memory/CPU/output limits;
|
||||
* CLI: `run`, `call`, absolute paths, multi-module, default `index.mq.md` and
|
||||
`--json` all succeed under strict; Foreign/ABI/plugin/kernel/trace flags are
|
||||
rejected with exit 2;
|
||||
* forged `MARQDO_STRICT_ACTIVE=1` outside the sandbox exits 1;
|
||||
* removing `/usr/bin/bwrap` makes strict `Unavailable` and the run exits 1 with
|
||||
no project execution.
|
||||
|
||||
## Consequences
|
||||
|
||||
* Linux strict is available **only where the probe succeeds**; this container
|
||||
still reports unavailable.
|
||||
* `worker_processes` remains true for crash isolation, but that is not part of
|
||||
the strict claim.
|
||||
* A future L2 ADR must extend the same supervisor to worker/Foreign processes,
|
||||
with its own escape tests, before those may run under strict.
|
||||
* A remote self-hosted security-lane URL is still required before a release
|
||||
calls G-C CI-verified; the local VM evidence is recorded separately.
|
||||
Reference in new issue
Block a user