@clear-capabilities/agentic-security-scanner 0.130.0 → 0.132.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,116 @@ 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 a wall-clock overrun stops the direct child.
+
+Two limits carry over unchanged and are **not** claims this verification
+retires. The wall-clock case stops the *direct child*, not the process tree —
+the same caveat the userspace backend carries. And 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 +285,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

package/src/sandbox/backend-namespace.js

@@ -1,36 +1,227 @@
 // Kernel-namespace confinement backend (Linux family).
 //
-// STATUS: implemented, not verified on this platform — the required
-// kernel-namespace tool is not present here, so its escape tests skip with a
-// recorded reason. Verify on a Linux host before relying on it for R2.
+// STATUS. This backend cannot be exercised on the macOS development host — the
+// required kernel-namespace tool is absent, so its escape tests skip with a
+// recorded reason there. Whether the confinement described below actually
+// holds is a per-host fact that only a Linux host can answer, and only by
+// EXECUTING the escape suite. Do not read this comment as a verification
+// claim; read `src/sandbox/CLAUDE.md` for what has and has not been executed.
 //
-// WHAT THIS BACKEND ACTUALLY CONFINES — do not overstate it. It enters new
-// mount/PID/IPC/UTS namespaces and, unless `allowNetwork`, an empty network
-// namespace. The empty network namespace has no route anywhere, and that is
-// the ONE confinement this backend implements: network egress.
+// WHAT THIS BACKEND CONFINES.
 //
-// It does NOT confine writes. There is no remount, no bind mount and no
-// pivot_root here — only a `cd` into the sandbox root. A `cd` sets the working
-// directory; it does not restrict where a process may write. A confined
-// command that writes 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 from the host; it does not make the host filesystem
-// read-only. Treat filesystem confinement as ABSENT on this backend until a
-// read-only remount is implemented AND verified by execution on a Linux host.
+//   1. NETWORK EGRESS — an empty network namespace (`--net`, unless the caller
+//      passes `allowNetwork`). It has no route anywhere.
+//
+//   2. FILESYSTEM WRITES — 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. That 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, which is the main reason
+//      this shape was chosen over `pivot_root` (see below).
+//
+//   3. RESOURCE CAPS — the shared `ulimit` prelude.
+//
+// WHY READ-ONLY REBIND RATHER THAN pivot_root. `pivot_root` into the sandbox
+// root is the stronger primitive: after detaching the old root, out-of-root
+// paths are not merely read-only, they are absent from the mount namespace
+// entirely. It was rejected here for three concrete reasons. (a) It requires
+// materialising a system tree (the shell, the C library, the utilities a PoC
+// invokes) inside the caller's sandbox root, which pollutes a directory the
+// caller owns and reads back. (b) It changes path semantics: `$ROOT` becomes
+// `/`, so a caller's absolute paths mean something different on this backend
+// than on the userspace one, and the two backends stop being interchangeable.
+// (c) An out-of-root write would then fail with ENOENT, which is
+// indistinguishable from an ordinary missing path and cannot be reported as a
+// confinement denial — the caller loses the `denied` signal precisely where it
+// matters most. The read-only rebind keeps paths, keeps the denial signal, and
+// keeps both backends returning the same thing for the same escape attempt.
+//
+// HONEST LIMIT OF THE READ-ONLY REBIND. The namespaces are acquired by
+// creating a user namespace, and the confined process is therefore (initially)
+// privileged inside it — it holds CAP_SYS_ADMIN over the mount namespace it
+// runs in, and could rebind the tree read-write again. That would gut the
+// confinement, so after the mounts are established and before the caller's
+// command is executed, the backend drops the whole capability set (bounding,
+// inheritable, and — via the `noroot` secure bits — the implicit privileges of
+// uid 0) and only then executes. If the privilege-dropping utility is not
+// present on the host the command still runs under the read-only mount tree,
+// but the result DECLARES `privilegeDrop` unenforced (in `unsupported`, the
+// same mechanism `limits.js` uses) rather than pretending the hardening
+// applied. It is never silently skipped.
+//
+// FAIL-CLOSED, AND VERIFIED PER RUN RATHER THAN ASSUMED. Every step that
+// establishes confinement aborts the run on failure: no namespace variant, no
+// filesystem-attach utility, a mount tree that cannot be made read-only, a
+// sandbox root that turns out not to be writable — each returns
+// `status:'error'` with nothing executed. Beyond that, the confinement is PROVEN by execution on
+// every single run: the parent creates a canary path OUTSIDE the sandbox root,
+// and the confined shell — already in its final, deprivileged state —
+// attempts to create it. If that write succeeds, confinement is not in force
+// and the shell exits WITHOUT running the caller's command. A reasoned
+// expectation that "the remount should have worked" is exactly the class of
+// claim this module exists to refuse.
 //
 // TIMEOUT SCOPE. The wall-clock timeout is `spawnSync`'s, which signals only
 // the direct child. On this backend the direct child is the namespace tool
 // running as pid 1 of a new PID namespace (`--pid --fork`), so killing it is
 // expected to take the whole namespace's processes with it — better than the
 // userspace backend, where a backgrounded grandchild demonstrably survives.
-// "Expected", not verified: like everything else here it needs a Linux host.
+// "Expected", NOT verified, and this one did not clear with the rest: the
+// escape suite has now RUN and passed on a Linux runner, but its wall-clock
+// case asserts only that the DIRECT CHILD is stopped. No test observes whether
+// a backgrounded grandchild dies with the PID namespace, so tree-kill remains
+// a reasoned expectation. Do not state it as a guarantee until a test asserts
+// the grandchild is gone.
+//
+// PRIVILEGE. Creating mount/PID/IPC/UTS/network namespaces directly requires
+// CAP_SYS_ADMIN, which an ordinary CI account does not have — asking for them
+// bare fails with a permission error and the backend cannot start at all. The
+// unprivileged route is to create a USER namespace first and take the
+// requested namespaces inside it, where the invoking user holds the
+// capabilities. So the flag set is chosen by PROBE, not assumed: each variant
+// below is executed with a trivial command and the first one that actually
+// succeeds is used (and cached). Fail-closed: if no variant works the backend
+// returns status 'error' and nothing runs. The confinement flags are NEVER
+// relaxed to make a run succeed — dropping `--net` would remove the network
+// confinement, so `--net` is part of every probed variant when `allowNetwork`
+// is false, and `--mount` is in every variant unconditionally because the
+// write confinement is built inside it.
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
-import { resolveNamespaceBin } from './capabilities.js';
-import { buildLimitPrelude } from './limits.js';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  resolveNamespaceBin, resolveMountBin, resolvePrivDropBin,
+  cachedNamespaceVariant, cacheNamespaceVariant,
+} from './capabilities.js';
+import { buildLimitPrelude, ambientRelativeMaxProcs } from './limits.js';
 import { buildResult, errorResult, buildConfinedEnv } from './result.js';
 
+// Ordered most-portable-first. Each entry is only the PRIVILEGE-acquisition
+// prefix; the namespace flags themselves are appended identically to all of
+// them by `_nsArgs`, so no variant can quietly confine less than another.
+//
+//   1. user namespace with the invoking user mapped to root inside it — the
+//      unprivileged route, and the one a standard CI runner needs. It is also
+//      the only variant under which the write confinement can be built, since
+//      rebinding the mount tree needs CAP_SYS_ADMIN in the owning namespace.
+//   2. user namespace with the invoking user mapped to itself — for hosts
+//      whose policy permits a user namespace but not the root mapping.
+//   3. no prefix — the direct route, which needs CAP_SYS_ADMIN (i.e. root).
+//      Last so an unprivileged host never pays for a doomed attempt first.
+const NS_PRIVILEGE_VARIANTS = Object.freeze([
+  Object.freeze(['--user', '--map-root-user']),
+  Object.freeze(['--user', '--map-current-user']),
+  Object.freeze([]),
+]);
+
+function _nsArgs(privilegeFlags, allowNetwork) {
+  const a = [...privilegeFlags, '--mount', '--pid', '--ipc', '--uts', '--fork'];
+  if (!allowNetwork) a.push('--net');
+  return a;
+}
+
+// Markers the confined shell writes to its own stderr so the parent can tell
+// a confinement-setup failure from ordinary program output. They are stripped
+// from the stderr handed back to the caller.
+//
+// A payload that PRINTS one of these strings can force `status:'error'` (or a
+// false `privilegeDrop` unenforced note). That is the safe direction: the
+// worst it achieves is making its own run look like it did not happen, which
+// no downstream tier reads as evidence of anything. It cannot make an
+// unconfined run look confined.
+const MARK_SETUP_FAILED = 'AGSEC_SANDBOX_SETUP_FAILED:';
+const MARK_NO_PRIVDROP = 'AGSEC_SANDBOX_PRIVDROP_UNAVAILABLE';
+
+// Runs inside the namespaces, still privileged, before the caller's command.
+// Builds the write confinement, then hands off to $SBX_FINAL with the
+// capability set dropped.
+//
+// Order matters: the sandbox root is bound onto itself while the tree is still
+// writable, so the read-only pass and the read-write rebind of the root never
+// have to fight each other. Individual sub-mounts are best-effort (some pseudo
+// filesystems legitimately refuse a rebind); the canary check in $SBX_FINAL is
+// what actually decides whether the result is trustworthy.
+const SETUP_SCRIPT = `
+_fail() { echo "${MARK_SETUP_FAILED} $1" >&2; exit 91; }
+"$SBX_MOUNT" --make-rprivate / || _fail "mount propagation could not be made private"
+"$SBX_MOUNT" -t proc proc /proc 2>/dev/null || true
+"$SBX_MOUNT" --bind "$ROOT" "$ROOT" || _fail "the sandbox root could not be bind-mounted"
+_mps=$(while read -r _a _b _c _d _mp _rest; do printf '%s\\n' "$_mp"; done < /proc/self/mountinfo)
+for _mp in $_mps; do
+  [ "$_mp" = "/" ] && continue
+  [ "$_mp" = "$ROOT" ] && continue
+  case "$_mp" in "$ROOT"/*) continue ;; esac
+  "$SBX_MOUNT" -o remount,bind,ro "$_mp" 2>/dev/null || true
+done
+"$SBX_MOUNT" -o remount,bind,ro / || _fail "the root filesystem could not be rebound read-only"
+# Belt and braces: the root was bound before the read-only pass and skipped by
+# it, so this is normally a no-op. Its return code is NOT the gate — the
+# executed in-root write check in $SBX_FINAL is, and that one fails closed.
+"$SBX_MOUNT" -o remount,bind,rw "$ROOT" 2>/dev/null || true
+if [ -n "$SBX_PRIVDROP" ] && "$SBX_PRIVDROP" --securebits=+noroot,+noroot_locked --bounding-set=-all --inh-caps=-all /bin/sh -c 'exit 0' 2>/dev/null; then
+  exec "$SBX_PRIVDROP" --securebits=+noroot,+noroot_locked --bounding-set=-all --inh-caps=-all /bin/sh -c "$SBX_FINAL" _sbx "$@"
+fi
+echo "${MARK_NO_PRIVDROP}" >&2
+exec /bin/sh -c "$SBX_FINAL" _sbx "$@"
+`;
+
+// Runs in the FINAL privilege state, immediately before the caller's command.
+// Both directions are checked by execution, every run: the out-of-root canary
+// must be refused, and an in-root write must succeed. Either check failing
+// means the sandbox is not what it claims, so the command is not run.
+const FINAL_SCRIPT = `
+_fail() { echo "${MARK_SETUP_FAILED} $1" >&2; exit 91; }
+if ( : > "$SBX_CANARY" ) 2>/dev/null; then
+  _fail "an out-of-root write is still possible; refusing to execute"
+fi
+if ! ( : > "$ROOT/.agsec-sbx-wcheck" ) 2>/dev/null; then
+  _fail "the sandbox root is not writable; refusing to execute"
+fi
+rm -f "$ROOT/.agsec-sbx-wcheck"
+cd "$ROOT" && exec "$@"
+`;
+
+/**
+ * The first privilege variant under which the requested namespaces can
+ * actually be created on this host, or null when none can. Probed by running
+ * a trivial command — a reasoned expectation about which flags "should" work
+ * is exactly what made this backend unusable on an unprivileged runner.
+ */
+export function resolveNamespaceArgs(bin, allowNetwork, { probeTimeoutMs = 5000 } = {}) {
+  const key = `${bin}:${allowNetwork ? 'net' : 'nonet'}`;
+  const cached = cachedNamespaceVariant(key);
+  if (cached !== undefined) return cached;
+
+  let chosen = null;
+  for (const variant of NS_PRIVILEGE_VARIANTS) {
+    const args = _nsArgs(variant, allowNetwork);
+    const probe = spawnSync(bin, [...args, '/bin/sh', '-c', 'exit 0'], {
+      encoding: 'utf8', timeout: probeTimeoutMs, stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (!probe.error && probe.status === 0) { chosen = args; break; }
+  }
+  cacheNamespaceVariant(key, chosen);
+  return chosen;
+}
+
+/** Strip the internal markers from stderr before it reaches the caller. */
+function _cleanStderr(s) {
+  return String(s || '')
+    .split('\n')
+    .filter((l) => !l.includes(MARK_SETUP_FAILED) && l.trim() !== MARK_NO_PRIVDROP)
+    .join('\n');
+}
+
+function _setupFailureReason(stderr) {
+  for (const line of String(stderr || '').split('\n')) {
+    const i = line.indexOf(MARK_SETUP_FAILED);
+    if (i !== -1) return line.slice(i + MARK_SETUP_FAILED.length).trim();
+  }
+  return null;
+}
+
 export function runNamespace(argv, {
   root,
   timeoutMs = 10000,
@@ -45,6 +236,14 @@ export function runNamespace(argv, {
   const bin = resolveNamespaceBin();
   if (!bin) return errorResult('namespace', 'no kernel-namespace binary found on this host');
 
+  // Write confinement is built with this utility. No utility, no confinement,
+  // no run — there is deliberately no branch that proceeds without it.
+  const mountBin = resolveMountBin();
+  if (!mountBin) {
+    return errorResult('namespace',
+      'no filesystem-attach binary found on this host, so write confinement cannot be established; refusing to execute unconfined');
+  }
+
   let resolvedRoot;
   try {
     // Resolve symlinks so the path the kernel actually sees matches what we
@@ -54,30 +253,83 @@ export function runNamespace(argv, {
     return errorResult('namespace', `sandbox root is not usable: ${e.message}`);
   }
 
+  // Same per-uid RLIMIT_NPROC trap as the userspace backend, and worse here:
+  // the confined shell has to fork several helpers to BUILD its confinement,
+  // so a fixed cap below the ambient count for this uid makes the setup itself
+  // fail and the sandbox look broken. See `ambientRelativeMaxProcs`.
+  const effectiveLimits = { ...limits, maxProcs: limits.maxProcs ?? ambientRelativeMaxProcs() };
+
   let prelude, unsupported;
   try {
-    ({ prelude, unsupported } = buildLimitPrelude(limits));
+    ({ prelude, unsupported } = buildLimitPrelude(effectiveLimits));
   } catch (e) {
     return errorResult('namespace', `invalid resource limit: ${e.message}`);
   }
-  // `cd` only sets the working directory — it is NOT write confinement. See
-  // the header note.
-  const inner = `${prelude}cd "$ROOT" && exec "$@"`;
-
-  const nsArgs = ['--mount', '--pid', '--ipc', '--uts', '--fork'];
-  if (!allowNetwork) nsArgs.push('--net');
-
-  const r = spawnSync(
-    bin,
-    [...nsArgs, '/bin/sh', '-c', inner, '_sbx', ...argv],
-    {
-      encoding: 'utf8',
-      timeout: timeoutMs,
-      maxBuffer,
-      cwd: resolvedRoot,
-      env: buildConfinedEnv({ root: resolvedRoot, env }),
-    },
-  );
-
-  return buildResult({ backend: 'namespace', spawnResult: r, unsupported });
+
+  // Fail closed: no usable variant means the confinement cannot be
+  // established, so nothing is executed. There is deliberately no path that
+  // drops confinement flags and runs anyway.
+  const nsArgs = resolveNamespaceArgs(bin, allowNetwork);
+  if (!nsArgs) {
+    return errorResult('namespace', 'kernel namespaces could not be created on this host (unprivileged user-namespace creation appears to be denied); refusing to execute unconfined');
+  }
+
+  // The canary lives OUTSIDE the sandbox root, in a directory this process
+  // just created and can write. If the confined shell can create it, the
+  // confinement is not in force and the command is not run.
+  let canaryDir = null;
+  try {
+    canaryDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agsec-sbx-canary-'));
+  } catch (e) {
+    return errorResult('namespace', `could not create the confinement canary: ${e.message}`);
+  }
+  const canary = path.join(canaryDir, 'out-of-root.canary');
+
+  let r;
+  try {
+    r = spawnSync(
+      bin,
+      [...nsArgs, '/bin/sh', '-c', prelude + SETUP_SCRIPT, '_sbx', ...argv],
+      {
+        encoding: 'utf8',
+        timeout: timeoutMs,
+        maxBuffer,
+        cwd: resolvedRoot,
+        env: {
+          ...buildConfinedEnv({ root: resolvedRoot, env }),
+          SBX_MOUNT: mountBin,
+          SBX_PRIVDROP: resolvePrivDropBin() || '',
+          SBX_CANARY: canary,
+          SBX_FINAL: FINAL_SCRIPT,
+        },
+      },
+    );
+
+    // Parent-side confirmation of the same fact the canary check asserts from
+    // the inside. Cheap, and it does not depend on the confined shell being
+    // honest about its own exit code.
+    if (fs.existsSync(canary)) {
+      return errorResult('namespace',
+        'the confined process created a file outside the sandbox root: write confinement is NOT in force on this host');
+    }
+  } finally {
+    try { fs.rmSync(canaryDir, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+
+  const rawStderr = r.stderr ?? '';
+  const setupFailure = _setupFailureReason(rawStderr);
+  if (setupFailure && !r.error) {
+    // Confinement could not be established (or could not be proven). Nothing
+    // ran: the shell exits before `exec`ing the caller's command.
+    return errorResult('namespace', `confinement could not be established: ${setupFailure}`);
+  }
+
+  const effectiveUnsupported = [...unsupported];
+  if (rawStderr.includes(MARK_NO_PRIVDROP)) effectiveUnsupported.push('privilegeDrop');
+
+  return buildResult({
+    backend: 'namespace',
+    spawnResult: { ...r, stderr: _cleanStderr(rawStderr) },
+    unsupported: effectiveUnsupported,
+  });
 }