Files
marqdo-cli/docs/adr/0019-strict-mode-availability-gate.md
cflmy b6fc18233d 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
2026-11-20 15:01:49 +08:00

96 lines
4.3 KiB
Markdown

# ADR-0019: Strict-mode availability gate
Status: **Accepted; Linux availability superseded by ADR-0021**
Date: 2026-11-20
Relates to: ADR-0004 (strict mode refuses without isolation), blueprint §9
## Context
`strict` is the only mode that may claim isolation for untrusted documents.
The project must never advertise strict execution merely because an isolated
worker process or a cooperative path check exists. At the time of this ADR no
platform adapter has passed the required OS-level escape and resource tests.
The environment used for this stabilization work cannot create namespaces
(`unshare`/`bwrap` return "Operation not permitted"), so a real Linux adapter
cannot be built *and verified* here. Landlock is present but covers filesystem
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
`PlatformCapabilities::detect` reports `StrictIsolation::Unavailable` with a
platform-specific reason on every platform. `enforce` refuses strict before any
host or plugin is constructed. There is no fallback to `project`, no "warn and
continue", and no opt-in flag that silently disables the refusal.
This state is deliberate design output, not an incomplete branch: G-B does not
depend on it, and every unsupported platform must fail closed.
### 2. Availability is a per-platform, test-gated decision
A platform may report `Available { mechanism }` only when all of the following
hold on that platform and are covered by CI on a dedicated security lane:
* filesystem visibility restricted to the project and explicit grants;
escapes via `..`, absolute paths, symlinks and TOCTOU are denied;
* network socket creation/connection denied unless explicitly granted;
* process creation denied unless explicitly granted; the child tree is reaped
and leaves no orphans;
* resource limits for CPU, memory, file descriptors, process count, output and
wall clock are enforced;
* plugin workers and foreign kernels inherit the same restrictions, or strict
refuses to load them;
* the adapter is probed at runtime; failure to obtain the mechanisms leaves
strict `Unavailable` with the real reason;
* `--trust-native-plugin` and in-process native loading are rejected in strict,
since C ABI code shares the host address space;
* a probe/escape test suite demonstrates denial of reading `/etc/...`, writing
outside the project, connecting to the network and spawning a process.
Until then, `strict` must refuse even when other flags (`--allow-foreign`,
`--plugin`, `--trust-native-plugin`, read/write grants) are present.
### 3. Capability execution is not isolation
The broker executing `fs.read` for native and worker plugins (ADR-0018) is a
cooperative API contract with audit; it does not prevent a plugin from issuing
direct syscalls. It is not evidence for strict availability.
### 4. Observability
`marqdo inspect --platform --json` exposes the state and reason. The CLI test
suite asserts that the state is `unavailable` and that a strict run exits 1 with
a refusal message. Changing this contract requires this ADR to be superseded
together with the security test suite.
## Consequences
* No G-C claim is made. Documentation and CI must not describe worker
processes, Landlock-only filesystems or in-process brokers as a sandbox.
* A future adapter must add a new ADR, runtime probe, security lane and negative
tests before flipping `Unavailable` to `Available`.
* Platform-specific reasons remain actionable but do not leak secrets or host
layout details.
## Tests
* `strict_mode_refuses_without_isolation` (CLI): refusal, exit 1, no stdout,
JSON error envelope.
* `platform_reports_strict_unavailable` (CLI): `inspect --platform --json`
reports `state: unavailable` with a non-empty reason.
* Existing worker tests remain explicitly labelled crash isolation, not OS
isolation.