docs(security): gate strict-mode availability behind a security test lane (H3-B)
Add ADR-0019 freezing the strict availability contract: strict remains unavailable with an actionable reason on every platform until runtime probes and filesystem/network/process/resource escape tests pass in a dedicated security lane. Add a CLI test asserting inspect --platform reports unavailable and worker processes are not presented as isolation. No G-C claim is made.
This commit is contained in:
1 parent
1099ed6160
commit
e966b7661f
3 files changed
+113
-1
No files matched your search
@@ -739,3 +739,28 @@ fn runtime_error_in_imported_module_reports_that_module() {
|
||||
.unwrap_or_default();
|
||||
assert!(primary.contains("physics.mq.md"), "{primary}");
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn platform_reports_strict_unavailable_until_security_gate_passes() {
|
||||
let root = repo_root();
|
||||
let hello = root.join("examples").join("hello.mq.md");
|
||||
let output = cli(
|
||||
&root,
|
||||
&["inspect", hello.to_str().unwrap(), "--platform", "--json"],
|
||||
);
|
||||
assert_exit(&output, 0, "inspect --platform");
|
||||
let value = json_stdout(&output);
|
||||
let strict = &value["platform"]["strict"];
|
||||
assert_eq!(
|
||||
strict["state"], "unavailable",
|
||||
"strict must stay unavailable until the ADR-0019 security gate passes: {strict}"
|
||||
);
|
||||
assert!(
|
||||
strict["reason"]
|
||||
.as_str()
|
||||
.map(|reason| !reason.trim().is_empty())
|
||||
.unwrap_or(false),
|
||||
"unavailable strict needs an actionable reason: {strict}"
|
||||
);
|
||||
assert_eq!(value["platform"]["worker_processes"], true);
|
||||
}
|
||||
+2
-1
@@ -232,7 +232,8 @@ Foreign provider integrity and environment metadata:
|
||||
| S3-A/H2-C Tool protocol | **Done** | SemVer negotiation at install+dispatch, whole-bundle manifest/digest verification, atomic install/remove, reserved record file (see §S3-A/H2-C) |
|
||||
| S4-A/B-13 B-14 quality gates | **Partial** | real schema instance validation + negative mutations in CI; Windows/macOS runtime tests for core/Analysis/Trace and strict refusal. Tool/C-ABI/worker runtime evidence remains Unix-only (see §S4-A) |
|
||||
| S5-A/B-12 foreign integrity | **Done for pinned provider+environment** | provider and environment-directory digests verified at registration and before spawn; environment bin/PATH injection. uv/npm environment generation, lock-v3 integration and H3-B remain open (see §S5-A/B-12) |
|
||||
| S5-B/H3-A broker execution | **Done for fs.read (native+worker)** | registered plugin capability requests execute `fs.read` through `ProjectFs` with audit; unsupported capabilities fail unavailable. Session identity breadth and H3-B OS isolation remain open and are not claimed (ADR-0018) |
|
||||
| S5-B/H3-A broker execution | **Done for fs.read (native+worker)** | registered plugin capability requests execute `fs.read` through `ProjectFs` with audit; unsupported capabilities fail unavailable. Session identity breadth remains open (ADR-0018) |
|
||||
| S5-C/H3-B strict gate | **Gate implemented; isolation deferred** | ADR-0019 + test: strict stays unavailable with an actionable reason until a per-platform security lane passes; refusal is enforced before host/plugin creation. No G-C claim |
|
||||
| R0 baseline + ADRs | **Done** | this section; `docs/adr/0008`–`0012`; full workspace gate |
|
||||
| R1 package-aware identity + callable registry | **Done for statics; superseded by S1 lock v3** | `ModuleId { instance, relative_path }`; `PackageResolver` path sources; lock v3 transitive graph (ADR-0016) replaces the flat v2 lock; `CallableRegistry` for builtins/marqdo/declared ABI exports; external manifest wiring is R2 |
|
||||
| R2 ABI/Kernel/Broker | **Done (worker = crash isolation)** | `KernelRegistry` external providers; complete-name export routing; `CapabilityBroker`; static `check --plugin`; multi-export C test; isolated worker with timeout/crash tests; host handle table. Native/worker are not an OS sandbox |
|
||||
|
||||
@@ -0,0 +1,86 @@
|
||||
# ADR-0019: Strict-mode availability gate
|
||||
|
||||
Status: **Accepted**
|
||||
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.
|
||||
|
||||
## 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.
|
||||
Reference in new issue
Block a user