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

package/src/sandbox/backend-namespace.js

@@ -1,36 +1,242 @@
 // 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.
-//
-// 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.
-//
-// 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.
-//
-// 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.
+// 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 CONFINES.
+//
+//   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 — SETTLED BY TWO CI RUNS, AFTER TWO WRONG CLAIMS.
+//
+// This comment asserted for a long time that killing the direct child would
+// reap the whole namespace, since that child is pid 1 of a new PID namespace
+// (`--pid --fork`) — and that this made the backend BETTER than the userspace
+// one. A test was written to check rather than assume. What CI actually found,
+// in two rounds:
+//
+//   1. With the default SIGTERM the timeout did nothing at all: a 1200 ms
+//      budget against a payload sleeping 30 s returned after `30057 ms`, having
+//      run the payload to completion. The kernel does not deliver
+//      default-action signals to a PID namespace's pid 1 from outside it, so
+//      with no handler installed SIGTERM is simply dropped.
+//   2. With `killSignal: 'SIGKILL'` — which cannot be ignored — the call
+//      returns in about 1.2 s. The DIRECT CHILD is bounded. But a backgrounded
+//      grandchild still outlived it and wrote its marker, so the PID namespace
+//      does NOT reap the tree here.
+//
+// Settled: SIGKILL bounds the direct child promptly; it does not kill the tree.
+// That is the SAME limitation the userspace backend carries, not an improvement
+// on it. Confinement is unaffected — survivors remain inside the mount and
+// network namespaces and can neither write out of root nor reach the network —
+// but there is no bound on how long descendants run, and any caller needing one
+// must impose it (see `posture/prove-findings.js`, which does). Pinned by
+// "KNOWN GAP: the timeout bounds the direct child but does NOT reap the tree"
+// in `sandbox-escape.test.js`, which fails in both directions.
+//
+// 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 +251,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 +268,96 @@ 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,
+        // SIGKILL, not the SIGTERM default, and this is the whole reason the
+        // timeout did not work here. The direct child is pid 1 of a new PID
+        // namespace (`--pid --fork`), and the kernel does not deliver
+        // default-action signals to a namespace's pid 1 from outside it — a
+        // process with no handler installed for SIGTERM simply does not die.
+        // SIGKILL is the one signal that cannot be ignored or blocked, so it
+        // is the only signal that can bound a payload here.
+        //
+        // Found by CI, not by reasoning: the first Linux run of the tree-kill
+        // test recorded duration_ms 30057 against a 1200 ms budget with the
+        // payload run to completion. The comment above this function used to
+        // claim the opposite.
+        killSignal: 'SIGKILL',
+        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,
+  });
 }

package/src/sandbox/backend-userspace.js

@@ -14,26 +14,9 @@
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
 import { resolveUserspaceBin } from './capabilities.js';
-import { buildLimitPrelude } from './limits.js';
+import { buildLimitPrelude, ambientRelativeMaxProcs } from './limits.js';
 import { buildResult, errorResult, buildConfinedEnv } from './result.js';
 
-// `ulimit -u` (RLIMIT_NPROC) is a per-uid, system-wide cap on this platform,
-// not a per-process-tree cap (verified by execution in Task 2). A fixed
-// default like the 64 in buildLimitPrelude() breaks ordinary, non-adversarial
-// runs on any host whose user already has more than ~64 ambient processes —
-// which is common. So unless the caller passes an explicit maxProcs, we
-// compute one relative to the ambient count for this uid, the same
-// workaround Task 2 used in its own test, to keep default behavior usable
-// without pretending a low fixed cap is real containment.
-function _ambientProcCount() {
-  try {
-    const out = spawnSync('/bin/sh', ['-c', 'ps -U "$(id -un)" -o pid= | wc -l'], { encoding: 'utf8' });
-    return Number(String(out.stdout || '').trim()) || 200;
-  } catch {
-    return 200;
-  }
-}
-
 function _profile({ allowNetwork }) {
   return [
     '(version 1)',
@@ -72,7 +55,7 @@ export function runUserspace(argv, {
 
   const effectiveLimits = {
     ...limits,
-    maxProcs: limits.maxProcs ?? (_ambientProcCount() + 64),
+    maxProcs: limits.maxProcs ?? ambientRelativeMaxProcs(),
   };
 
   let prelude, unsupported;
@@ -90,6 +73,10 @@ export function runUserspace(argv, {
     {
       encoding: 'utf8',
       timeout: timeoutMs,
+      // Match the namespace backend: SIGKILL cannot be ignored, SIGTERM can.
+      // A payload that installs a SIGTERM handler would otherwise outlive its
+      // own budget while the caller is told it timed out.
+      killSignal: 'SIGKILL',
       maxBuffer,
       cwd: resolvedRoot,
       env: buildConfinedEnv({ root: resolvedRoot, env }),

package/src/sandbox/capabilities.js

@@ -1,7 +1,28 @@
 // Detects which OS confinement primitive is available. Fail-closed: when none
 // is found we report 'disabled', which REFUSES execution rather than running
 // target code unconfined.
+//
+// DETECTION IS FUNCTIONAL, NOT PRESENCE-BASED. An earlier version concluded
+// "available" from "the confinement binary is executable". That is a different
+// question from the one callers are actually asking. 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 fails and no confined command can start. Presence-based
+// detection reported the backend as available anyway, and `sandboxAvailable()`
+// — the signal callers use to decide whether it is safe to EXECUTE UNTRUSTED
+// CODE — answered true while nothing could actually be confined. False
+// assurance about confinement is precisely the failure this module exists to
+// prevent, so a backend now counts as available only if it just ran a trivial
+// command through its real code path.
+//
+// The probe result is cached for the process (one spawn, not one per call —
+// detection sits on the path of ordinary scans) and cleared by
+// `resetCapabilityCache()`.
 import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { runUserspace } from './backend-userspace.js';
+import { runNamespace } from './backend-namespace.js';
 
 // Referenced by path, never by product name (see Global Constraints).
 //
@@ -21,13 +42,49 @@ export const CONFINE_BINS_NAMESPACE = Object.freeze([
   '/usr/sbin/unshare',
 ]);
 
+// The filesystem-attach utility used by the namespace backend to establish
+// write confinement (read-only rebind of the whole mount tree, read-write
+// rebind of the sandbox root). Resolved by path for the same reason as the
+// others. Absent => the namespace backend cannot establish write confinement
+// and fails closed; it never runs a command with the filesystem open.
+export const CONFINE_BINS_MOUNT = Object.freeze([
+  '/usr/bin/mount',
+  '/bin/mount',
+  '/sbin/mount',
+  '/usr/sbin/mount',
+]);
+
+// The privilege-dropping utility used to remove CAP_SYS_ADMIN (and everything
+// else) from the confined process *after* the mounts are in place, so the
+// payload cannot simply undo the read-only rebinds. Best-effort hardening on
+// top of the mount confinement, not the confinement itself: when it is absent
+// the run still happens under the read-only mount tree and the result declares
+// `privilegeDrop` unenforced rather than staying silent about it.
+export const CONFINE_BINS_PRIVDROP = Object.freeze([
+  '/usr/bin/setpriv',
+  '/bin/setpriv',
+  '/sbin/setpriv',
+  '/usr/sbin/setpriv',
+]);
+
 // Back-compat single-path exports: the first (canonical) candidate.
 export const CONFINE_BIN_USERSPACE = CONFINE_BINS_USERSPACE[0];
 export const CONFINE_BIN_NAMESPACE = CONFINE_BINS_NAMESPACE[0];
 
 let _cached = null;
 
-export function resetCapabilityCache() { _cached = null; }
+// Which namespace-flag variant actually works on this host, keyed by the
+// requested confinement shape. Probing costs a process spawn, so it is done
+// once; `undefined` means "not probed yet", `null` means "probed and nothing
+// worked" (which the backend turns into a fail-closed error, never a run).
+const _nsVariant = new Map();
+
+export function resetCapabilityCache() { _cached = null; _nsVariant.clear(); }
+
+export function cachedNamespaceVariant(key) {
+  return _nsVariant.has(key) ? _nsVariant.get(key) : undefined;
+}
+export function cacheNamespaceVariant(key, value) { _nsVariant.set(key, value); }
 
 /** First executable candidate, or null when none of them exists. */
 export function resolveConfineBin(candidates) {
@@ -37,13 +94,84 @@ export function resolveConfineBin(candidates) {
 
 export function resolveUserspaceBin() { return resolveConfineBin(CONFINE_BINS_USERSPACE); }
 export function resolveNamespaceBin() { return resolveConfineBin(CONFINE_BINS_NAMESPACE); }
+export function resolveMountBin() { return resolveConfineBin(CONFINE_BINS_MOUNT); }
+export function resolvePrivDropBin() { return resolveConfineBin(CONFINE_BINS_PRIVDROP); }
 
-export function detectBackend({ force } = {}) {
+// Bounded on purpose: a capability check must never hang a scan. The probe is
+// a single `exit 0` under confinement, so anything beyond a couple of seconds
+// is a host that is not going to answer.
+const PROBE_TIMEOUT_MS = Math.max(
+  250,
+  Number(process.env.AGENTIC_SECURITY_SANDBOX_PROBE_TIMEOUT_MS) || 4000,
+);
+
+/**
+ * Run a trivial command through a backend's real code path and report whether
+ * confinement actually worked. Anything other than a clean confined run — a
+ * missing binary, a refused namespace, a timeout, a throw — is `false`. There
+ * is deliberately no branch that relaxes confinement to make a probe pass: a
+ * backend that can only succeed with a flag dropped is not available, it is
+ * `'disabled'`.
+ */
+function _probeThroughBackend(runner) {
+  let root = null;
+  try {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'agsec-sbx-probe-'));
+    const r = runner(['/bin/sh', '-c', 'exit 0'], { root, timeoutMs: PROBE_TIMEOUT_MS });
+    return r?.status === 'ok';
+  } catch {
+    return false;
+  } finally {
+    if (root) { try { fs.rmSync(root, { recursive: true, force: true }); } catch { /* best effort */ } }
+  }
+}
+
+/**
+ * The real probes, one per backend. The binary check stays only as a cheap
+ * pre-filter that avoids a pointless temp dir on a host that plainly lacks the
+ * primitive — it is no longer the answer, just the fast negative.
+ */
+export function defaultProbes() {
+  return {
+    userspace: () => (resolveUserspaceBin() ? _probeThroughBackend(runUserspace) : false),
+    namespace: () => (resolveNamespaceBin() ? _probeThroughBackend(runNamespace) : false),
+  };
+}
+
+/** Backends worth probing on a platform, most-appropriate first. */
+export function backendCandidates(platform = process.platform) {
+  if (platform === 'darwin') return ['userspace'];
+  if (platform === 'linux') return ['namespace'];
+  return [];
+}
+
+/**
+ * @param {object}   [o]
+ * @param {string}   [o.force]      Bypass detection entirely (tests, and callers
+ *                                  that want the disabled path deliberately).
+ * @param {object}   [o.probes]     Probe map override — a seam for tests to drive
+ *                                  the selection contract with stand-ins on any
+ *                                  platform. Cannot cause unconfined execution:
+ *                                  dispatch still goes to the real backend.
+ * @param {string[]} [o.candidates] Candidate order override (same seam).
+ */
+export function detectBackend({ force, probes, candidates } = {}) {
   if (force) return force;
   if (_cached) return _cached;
+
+  const probeMap = probes || defaultProbes();
+  const order = candidates || backendCandidates();
+
   let b = 'disabled';
-  if (process.platform === 'darwin' && resolveUserspaceBin()) b = 'userspace';
-  else if (process.platform === 'linux' && resolveNamespaceBin()) b = 'namespace';
+  for (const name of order) {
+    const probe = probeMap[name];
+    if (typeof probe !== 'function') continue;
+    let works = false;
+    try { works = probe() === true; } catch { works = false; }
+    if (works) { b = name; break; }
+    // Otherwise fall through to the next candidate, and ultimately to
+    // 'disabled' — never to "run it anyway".
+  }
   _cached = b;
   return b;
 }

package/src/sandbox/limits.js

@@ -4,6 +4,27 @@
 // verified by execution. We therefore DECLARE it unsupported rather than
 // emitting a limit that silently does nothing, which would be a false
 // assurance of containment.
+import { spawnSync } from 'node:child_process';
+
+// `ulimit -u` (RLIMIT_NPROC) is charged per *uid*, system-wide, on both
+// platforms this module supports — it is not a per-process-tree cap. A fixed
+// default like the 64 below therefore breaks ordinary, non-adversarial runs on
+// any host whose user already owns more than ~64 processes, which is most of
+// them: the confined shell cannot even fork the helpers it needs to set itself
+// up, and the failure looks like a broken sandbox rather than a cap doing its
+// job. So unless a caller passes an explicit `maxProcs`, both real backends
+// derive one from the ambient count for this uid. That keeps default behaviour
+// usable without pretending a low fixed cap is real containment — see the
+// "fork-storm containment is weak" note in the module guide.
+export function ambientRelativeMaxProcs(headroom = 64) {
+  let ambient = 200;
+  try {
+    const out = spawnSync('/bin/sh', ['-c', 'ps -U "$(id -un)" -o pid= | wc -l'], { encoding: 'utf8' });
+    ambient = Number(String(out.stdout || '').trim()) || 200;
+  } catch { /* fall through to the conservative default */ }
+  return ambient + headroom;
+}
+
 export function buildLimitPrelude({
   maxProcs = 64,
   maxFileSizeKb = 65536,