@clear-capabilities/agentic-security-scanner 0.130.0 → 0.133.0

package/src/sandbox/CLAUDE.md

@@ -50,27 +50,68 @@ verification tier) must not read `'ok'` as "ran unimpeded". The reliable
 negative evidence remains the one the escape tests use: check for the side
 effect (the out-of-root file does not exist), not the status.
 
-## Backend selection (`capabilities.js`)
+## Backend selection (`capabilities.js`) — functional, not presence-based
 
-`detectBackend({ force })` probes for one confinement primitive, cached after
-the first call (`resetCapabilityCache()` clears it, used between tests):
+`detectBackend({ force })` selects a backend by **executing a trivial command
+(`exit 0`) through that backend's real code path** and reporting the backend
+only if that run succeeds. Availability means "confinement demonstrably works
+here", never "the confinement binary is installed".
 
-| Platform | Primitive checked | Backend selected |
+| Platform | Candidate backend | Selected when |
 |---|---|---|
-| macOS family | userspace confinement binary present and executable | `'userspace'` |
-| Linux family | kernel-namespace tool present and executable | `'namespace'` |
-| neither found | — | `'disabled'` |
-
-Each primitive is probed across a **candidate list** of plausible install
-paths (`CONFINE_BINS_USERSPACE` / `CONFINE_BINS_NAMESPACE`), not a single
-hardcoded path. A miss still fails closed to `'disabled'`, which is safe — but
-a single path would be a false negative on any distribution that installs the
-binary elsewhere, silently costing that host its sandbox. The backends run the
-resolved path, not the canonical one.
+| macOS family | `'userspace'` | a trivial command ran confined and returned `status:'ok'` |
+| Linux family | `'namespace'` | a trivial command ran confined and returned `status:'ok'` |
+| any | `'disabled'` | no candidate's probe succeeded |
+
+A candidate whose probe fails is **skipped**, detection falls through to the
+next candidate, and with nothing left the answer is `'disabled'`. The probe is
+never allowed to pass by weakening confinement: there is no branch that drops a
+flag to get a green run, because a backend that can only succeed unconfined is
+not an available backend.
+
+**Why presence was the wrong question.** Verified on a Linux CI runner: the
+kernel-namespace tool is installed and executable, but the distribution
+restricts unprivileged user-namespace creation, so every privilege variant in
+`backend-namespace.js` fails and no confined command can start. Presence-based
+detection reported `'namespace'` and `sandboxAvailable()` answered `true` while
+every actual run failed. `sandboxAvailable()` is the signal callers use to
+decide whether it is safe to **execute untrusted code**; answering "the tool is
+installed" when the honest answer is "confinement does not work here" is false
+assurance of exactly the kind this module exists to prevent.
+
+**On a host that restricts unprivileged namespace creation, the backend
+therefore reports unavailable and the execution features that depend on it are
+DISABLED — not degraded.** `detectBackend()` returns `'disabled'`,
+`sandboxAvailable()` returns `false`, `runConfined` refuses to execute, and
+`execution-proof.js` leaves findings at their static tier with a reason naming
+the sandbox. Nothing runs unconfined and no weaker confinement is substituted.
+The sandbox-dependent tests in `sandbox-escape.test.js` and
+`execution-proof.test.js` skip there, each with an explicit
+"SKIPPED, NOT PASSED … UNVERIFIED here" reason — a skip is a declared gap in
+verification, never a pass.
+
+**Cost and bounds.** The probe costs one spawn and its result (positive *and*
+negative) is cached for the process, so ordinary scans pay it at most once;
+`resetCapabilityCache()` clears it. The probe runs with a short timeout
+(4 s default, `AGENTIC_SECURITY_SANDBOX_PROBE_TIMEOUT_MS` to override) and a
+throw is treated as a failure, so a capability check can never hang a scan.
+`force` bypasses probing entirely.
+
+`detectBackend` also accepts `{ probes, candidates }` — a test seam that drives
+the selection contract with stand-ins on any platform. It cannot produce
+unconfined execution: dispatch in `index.js` still goes to the real backend.
+
+Each primitive's binary is resolved across a **candidate list** of plausible
+install paths (`CONFINE_BINS_USERSPACE` / `CONFINE_BINS_NAMESPACE`), not a
+single hardcoded path, and that lookup now serves only as a cheap fast-negative
+before the real probe. A miss still fails closed to `'disabled'`, which is safe
+— but a single path would be a false negative on any distribution that installs
+the binary elsewhere, silently costing that host its sandbox. The backends run
+the resolved path, not the canonical one.
 
 ## Fail-closed rule
 
-If no primitive is found, `detectBackend` returns `'disabled'` and
+If no candidate backend's functional probe succeeds, `detectBackend` returns `'disabled'` and
 `runConfined` dispatches to `backend-disabled.js`, which **refuses to execute
 the command at all** — it returns `status: 'disabled'` without ever spawning
 a process. There is no code path in this module that runs target code
@@ -111,35 +152,138 @@ other.
   silently do nothing — an unenforced limit must never look like an enforced
   one.
 
-**Kernel-namespace backend (Linux family) — implemented, NOT verified on this
-platform.** The required namespace tool is absent on the macOS development
-host, so `backend-namespace.js`'s escape tests skip with a recorded reason
-rather than being asserted against. Nothing in this guide should be read as a
-claim that the namespace backend's isolation has been demonstrated by
-execution anywhere. It must be verified on a Linux host — with the same
-both-direction escape-attempt tests used for the userspace backend — before
-anything downstream (e.g. an R2 execution-verification tier) relies on it.
-
-**And it confines less than "unverified" suggests. Writes are NOT confined on
-this backend — that is false by inspection, not merely undemonstrated.** The
-backend enters new mount/PID/IPC/UTS namespaces and, by default, an empty
-network namespace. The empty network namespace is the *only* confinement it
-implements: it has no route anywhere, which denies egress. For the
-filesystem there is **no remount, no bind mount and no `pivot_root`** — only a
-`cd` into the sandbox root. `cd` sets the working directory; it does not
-restrict where a process may write. A confined command writing to an absolute
-path outside the root (a home directory, a system config path) will
-**succeed**, subject only to ordinary filesystem permissions. The new mount
-namespace isolates mount-table *changes* made by the confined process; it does
-not make the host filesystem read-only.
-
-On a Linux host `detectBackend()` selects this backend automatically, so a
-caller there gets network isolation and resource limits and **no write
-confinement at all**. Do not run anything on that path that must not touch the
-host filesystem. Closing the gap means implementing a read-only remount (or
-equivalent) *and* verifying it by execution on a Linux host with both-direction
-escape tests — the guide must not claim write confinement here before both
-have happened.
+**Kernel-namespace backend (Linux family) — verified by execution in CI.** The
+required namespace tool is absent on the macOS development host, so
+`backend-namespace.js`'s escape tests skip there with a recorded reason rather
+than being asserted against. The verification therefore lives in CI, and it has
+now run: on the `sandbox-linux` job the functional probe selected the
+`namespace` backend and the full escape suite executed and passed (Ubuntu
+24.04, kernel `6.17.0-1020-azure`, 41 assertions, 0 failures). All eight
+escape-attempt cases are asserted on that host in both directions — in-root
+write succeeds, out-of-root write is blocked and creates no file, a denied
+write is not reported as a clean run, the confined process cannot rebind the
+filesystem writable again, an ordinary non-zero exit stays `nonzero` rather
+than `blocked`, the parent environment is not handed over, outbound network is
+blocked, and the wall-clock behaviour is pinned as a KNOWN GAP (see below —
+the timeout does not actually stop the payload here).
+
+**The timeout: two wrong claims, settled by two CI runs.** This guide once
+carried the userspace caveat verbatim ("stops the direct child, not the process
+tree") and `backend-namespace.js` went further, reasoning that killing pid 1 of a
+PID namespace would reap everything and beat userspace. A test was added to check
+rather than assume, and CI corrected it twice:
+
+1. With the default **SIGTERM** the timeout did nothing: a 1200 ms budget against
+   a payload sleeping 30 s returned after `30057 ms`, payload run to completion.
+   The kernel drops default-action signals sent to a PID namespace's pid 1 from
+   outside it.
+2. With **SIGKILL** — which cannot be ignored — the call returns in about 1.2 s,
+   so the direct child IS bounded. A backgrounded grandchild still survived and
+   wrote its marker.
+
+**Settled behaviour: SIGKILL bounds the direct child promptly; it does not reap
+the process tree.** That is the same limitation the userspace backend carries —
+not better, which is what this module claimed for a long time. Confinement is
+unaffected: survivors stay inside the mount and network namespaces and can
+neither write out of root nor reach the network. What is missing is a bound on
+how long descendants run, so a caller needing one must impose it itself
+(`posture/prove-findings.js` does). Pinned by "KNOWN GAP: the timeout bounds the
+direct child but does NOT reap the tree", which fails in both directions.
+
+One further limit is unchanged: this is one kernel and one
+image: a different kernel is a different host fact, which is exactly why the
+job runs per push rather than being recorded once and trusted forever.
+
+**How it stays verified: the `sandbox-linux` CI job.** Hosted runners restrict
+unprivileged user-namespace creation at the kernel's access-control layer, so
+the functional probe fails by default and the escape suite would skip — which
+is why this backend went unverified for as long as it did. The `sandbox-linux`
+job in `.github/workflows/ci.yml` relaxes that **host policy** for itself (it
+has passwordless root) and then runs the existing suite unchanged. It relaxes a
+restriction on creating namespaces; it does not relax a single assertion or
+confinement flag. `scripts/sandbox-linux-verify.mjs` then prints the selected
+backend and `RAN`/`SKIPPED` for every test and **exits non-zero unless the
+kernel-namespace suite actually ran**, so a skip can never be mistaken for a
+pass in a green job. That guard is what makes the verification durable rather
+than a one-time observation: if a future runner image re-tightens the policy,
+the job fails rather than quietly reverting to "skipped, green".
+
+**Privilege: the namespaces are acquired unprivileged, and the flag set is
+probed rather than assumed.** Creating mount/PID/IPC/UTS/network namespaces
+directly requires `CAP_SYS_ADMIN`; an ordinary CI account does not have it, so
+asking for them bare fails with a permission error and the backend cannot start
+at all. `resolveNamespaceArgs()` therefore tries an ordered list of
+privilege-acquisition prefixes — user namespace with the invoking user mapped
+to root inside it, then user namespace with the user mapped to itself, then no
+prefix (which needs root) — and **executes a trivial command under each**,
+selecting the first that actually succeeds. The result is cached per
+binary/network shape and cleared by `resetCapabilityCache()`.
+
+The confinement flags are identical across every variant and are **never
+relaxed to make a run succeed**: `--net` is present in every probed variant
+whenever `allowNetwork` is false, and `--mount` unconditionally, because the
+write confinement is built inside that mount namespace — dropping either to
+get a green run would remove a confinement. If no variant succeeds the backend returns
+`status: 'error'` and **nothing is executed**, the same fail-closed rule as the
+disabled backend. The selection contract (flags always present, `allowNetwork`
+the only way `--net` is absent, `null` when every probe fails) is asserted by
+executing tests in `sandbox.test.js` driven with stand-in binaries, so it holds
+on any platform; whether a given kernel actually grants the namespaces is a
+per-host fact only that host can answer.
+
+**Write confinement: implemented and verified in CI** (see the escape-suite
+result above; cases 1–4 are exactly this mechanism). This backend used to confine
+network egress and nothing else — no remount, no bind mount, no `pivot_root`,
+just a `cd` — so an absolute out-of-root write succeeded. That gap is now
+closed in code:
+
+1. A **private mount namespace** in which every mount point present at setup
+   time is rebound **read-only**, and only the sandbox root is rebound
+   read-write. An out-of-root write therefore fails with `EROFS`, whose error
+   text is one of `result.js`'s denial patterns — so an escape attempt
+   surfaces as `status:'blocked'` + `denied:true`, the same shape the
+   userspace backend produces for the same attempt.
+2. A **capability drop** (whole bounding + inheritable set, plus the `noroot`
+   secure bits so uid 0 stops implying privilege) applied *after* the mounts
+   and *before* the caller's command. Without it the payload would hold
+   `CAP_SYS_ADMIN` over its own mount namespace — the namespaces are acquired
+   via a user namespace — and could simply rebind the tree writable again.
+3. A **per-run proof by execution**, not a reasoned expectation. The parent
+   seeds a canary path *outside* the sandbox root; the confined shell, already
+   in its final deprivileged state, attempts to create it and refuses to
+   `exec` the caller's command if that write succeeds. The parent then
+   re-checks the canary from outside, so the verdict does not depend on the
+   confined shell being honest about its own exit code.
+
+**Why read-only rebind and not `pivot_root`.** `pivot_root` is the stronger
+primitive — after detaching the old root, out-of-root paths are absent from
+the mount namespace rather than merely read-only. It was rejected for three
+concrete reasons. (a) It requires materialising a system tree (shell, C
+library, whatever a PoC invokes) inside the *caller's* sandbox root, polluting
+a directory the caller owns and reads back. (b) It changes path semantics —
+`$ROOT` becomes `/` — so the two backends stop being interchangeable for the
+same caller input. (c) An out-of-root write would then fail with `ENOENT`,
+indistinguishable from an ordinary missing path, which destroys the `denied`
+signal exactly where it matters most. The read-only rebind keeps paths, keeps
+the denial signal, and keeps both backends answering the same way.
+
+**Fail-closed throughout.** No namespace variant, no filesystem-attach
+utility, a mount tree that cannot be rebound read-only, a sandbox root that
+cannot be rebound writable, or a canary that turns out writable — each returns
+`status:'error'` with **nothing executed**. There is no branch that proceeds
+with the filesystem open.
+
+**The one hardening that can be absent, and it is declared.** If the
+privilege-dropping utility is not on the host, the command still runs under
+the read-only mount tree but the result carries `privilegeDrop` in the
+`unsupported` list (surfaced on stderr as `[sandbox] not enforceable here:
+privilegeDrop`), the same mechanism `limits.js` uses for an unenforceable
+limit. It is never silently skipped, and the escape test that covers the
+rebind attack fails if it is missing rather than quietly passing.
+
+**None of the above has been executed anywhere yet.** It is asserted by
+`sandbox-escape.test.js`'s kernel-namespace suite, which skips on macOS. Until
+a CI log shows that suite `RAN`, this section describes code, not evidence.
 
 ## Timeout does not kill the process tree
 
@@ -163,8 +307,8 @@ needs the same Linux-host verification as everything else on that backend.
 
 The userspace policy allows `(allow file-read*)` globally — that backend
 confines **writes**, network egress, and resource use, but **not reads**. (The
-kernel-namespace backend confines *less* than that: per the section above, it
-implements network isolation only and does **not** confine writes at all.)
+kernel-namespace backend has the same cut: per the section above its mount
+tree is rebound read-only, not detached, so everything on it stays readable.)
 A confined command can read any file on the host the OS-level
 permissions allow, including outside the sandbox root. Exfiltration of
 readable host files (writing what was read to network or to a location the