@clear-capabilities/agentic-security-scanner 0.163.1 → 0.165.0

package/src/sandbox/control-probes.js

@@ -53,7 +53,7 @@ function probeWrite() {
 }
 
 function probeReadDenial(backend) {
-  if (backend !== 'userspace') return { state: 'unsupported', reason: `read denial of host paths is not implemented on the ${backend} backend` };
+  if (backend !== 'userspace' && backend !== 'namespace') return { state: 'unsupported', reason: `read denial of host paths is not implemented on the ${backend} backend` };
   const root = mk('agsec-probe-r-'); const secretDir = mk('agsec-probe-rs-');
   try {
     const secret = path.join(secretDir, 'sealed.txt');
@@ -103,7 +103,11 @@ async function probeNetwork() {
   } finally { server.close(); rm(root); }
 }
 
-async function probeTree() {
+async function probeTree(backend) {
+  // Inside a PID namespace the pids a payload records are not host pids, so the
+  // pid-based check below would test unrelated host processes. The namespace
+  // backend gets a probe that never turns a recorded pid into a signal.
+  if (backend === 'namespace') return probeTreeHeartbeat();
   const root = mk('agsec-probe-t-');
   try {
     // Three tree shapes: a plain background child, a grandchild, and one that
@@ -115,7 +119,7 @@ async function probeTree() {
       'wait',
     ].join('\n');
     const r = await runConfinedSupervised(['/bin/sh', '-c', script], { root, timeoutMs: 1500, graceMs: 300 });
-    if (r.backend !== 'userspace' || !r.supervised) {
+    if (!r.supervised) {
       return { state: 'unsupported', reason: `supervised tree termination is not implemented on the ${r.backend} backend (${r.status})` };
     }
     const pids = ['p1', 'p2', 'p3'].map((f) => { try { return Number(fs.readFileSync(path.join(root, f), 'utf8')); } catch { return NaN; } });
@@ -128,6 +132,52 @@ async function probeTree() {
   } finally { rm(root); }
 }
 
+/**
+ * A shell loop that appends a counter line to `$ROOT/hb<n>` every 200 ms and
+ * stops by itself after `max` lines, so a probe that finds a survivor cannot
+ * leave it running for ever.
+ */
+export function heartbeatShell(n, max = 300) {
+  return `i=0; while [ $i -lt ${max} ]; do i=$((i+1)); echo $i >> "$ROOT/hb${n}"; sleep 0.2; done`;
+}
+
+// Tree termination by heartbeat, for a backend whose payload pids are not host
+// pids. Four tree shapes each append a line to their own file every 200 ms: a
+// plain background loop, a grandchild, one that ignores SIGTERM, and a
+// double-forked member that left the session with setsid. After the supervised
+// run returns, a process that survived keeps appending. The positive control is
+// the same files: each must have advanced during the run, so a heartbeat that
+// could never advance cannot pass for a tree that was terminated.
+export async function probeTreeHeartbeat({ run = runConfinedSupervised, settleMs = 700 } = {}) {
+  const root = mk('agsec-probe-th-');
+  try {
+    const beat = (n) => heartbeatShell(n);
+    const script = [
+      `( ${beat(1)} ) &`,
+      `( ( ${beat(2)} ) & wait ) &`,
+      `( trap '' TERM; ${beat(3)} ) &`,
+      `( setsid /bin/sh -c '${beat(4)}' >/dev/null 2>&1 & ) &`,
+      'wait',
+    ].join('\n');
+    const r = await run(['/bin/sh', '-c', script], { root, timeoutMs: 1800, graceMs: 300 });
+    if (!r.supervised) {
+      return { state: 'unsupported', reason: `supervised tree termination is not implemented on the ${r.backend} backend (${r.status})` };
+    }
+    const lines = (n) => { try { return fs.readFileSync(path.join(root, `hb${n}`), 'utf8').split('\n').filter(Boolean).length; } catch { return 0; } };
+    const names = [1, 2, 3, 4];
+    const atReturn = names.map(lines);
+    const stalled = names.filter((n, i) => atReturn[i] < 3);
+    if (stalled.length) return notProved(`positive control failed: heartbeat ${stalled.join(',')} did not advance while the run was live`);
+    await sleep(settleMs);
+    const mid = names.map(lines);
+    await sleep(settleMs);
+    const late = names.map(lines);
+    const alive = names.filter((n, i) => late[i] > mid[i]);
+    if (alive.length) return notProved(`members of the tree were still running after the run ended (heartbeat ${alive.join(',')})`);
+    return proved('four tree shapes (background, grandchild, SIGTERM-ignoring, setsid double fork) all stopped when the run ended');
+  } finally { rm(root); }
+}
+
 function probeFileSize() {
   const root = mk('agsec-probe-f-');
   try {
@@ -145,9 +195,41 @@ function probeFileSize() {
 
 const UNPROBED_PROCESS_CAP = {
   state: 'unverified',
-  reason: 'a process-count cap is per-uid and system-wide on macOS (a soft brake, not a wall) and did not refuse on the hosted Linux runner in the last release; no enforcement is claimed on any backend',
+  reason: 'a process-count cap is per-uid and system-wide on macOS (a soft brake, not a wall); no enforcement is claimed on that backend. On the Linux namespace backend the cap is probed (see probeProcessCap)',
 };
 
+const PROC_CAP_FORKS = 6;
+/** Forks `PROC_CAP_FORKS` concurrent children; each child announces itself, so a refusal shows as missing announcements. */
+export const PROC_CAP_SCRIPT = `i=0; while [ $i -lt ${PROC_CAP_FORKS} ]; do i=$((i+1)); ( echo CHILD_$i; sleep 1 ) & done; wait; echo DONE`;
+
+const countChildren = (r) => (String(r.stdout || '').match(/CHILD_\d/g) || []).length;
+
+/**
+ * The process-count cap on the namespace backend. A command that forks six
+ * concurrent children is run twice through the real backend: under a generous cap
+ * every child must start (the positive control: the probe can succeed, and the cap
+ * mechanism itself does not break ordinary forking), and under a cap far below
+ * what it needs the kernel must refuse some of them. RLIMIT_NPROC is not enforced
+ * for a process holding CAP_SYS_RESOURCE in the initial namespace, so whether it
+ * binds inside the user namespace is exactly what this measures rather than assumes.
+ *
+ * `run` is a seam so a test can hand it a runner that ignores the cap (or one that
+ * refuses everything) and see the probe say so.
+ */
+export function probeProcessCap({ run = runConfined, mode = {} } = {}) {
+  const root = mk('agsec-probe-p-');
+  try {
+    const cmd = ['/bin/sh', '-c', PROC_CAP_SCRIPT];
+    const generous = run(cmd, { root, ...mode, timeoutMs: 10000, limits: { maxProcs: 512 } });
+    const gOk = countChildren(generous);
+    if (gOk !== PROC_CAP_FORKS) return notProved(`positive control failed: only ${gOk} of ${PROC_CAP_FORKS} children started under a generous cap (${generous.status})`);
+    const tight = run(cmd, { root, ...mode, timeoutMs: 10000, limits: { maxProcs: 3 } });
+    const tOk = countChildren(tight);
+    if (tOk >= PROC_CAP_FORKS) return notProved(`the process-count cap did not refuse: all ${tOk} children started under a cap of 3`);
+    return proved(`${gOk} of ${PROC_CAP_FORKS} children started under a cap of 512; only ${tOk} under a cap of 3`);
+  } finally { rm(root); }
+}
+
 const _cache = new Map();
 export function resetProbeCache() { _cache.clear(); }
 
@@ -177,9 +259,11 @@ export async function probeControls({ force, probes = {} } = {}) {
     await run('read-denial', () => probeReadDenial(backend));
     await run('env-scrub', probeEnv);
     await run('network', probeNetwork);
-    await run('tree-termination', probeTree);
+    await run('tree-termination', () => probeTree(backend));
     await run('file-size-limit', probeFileSize);
-    controls['process-cap'] = probes['process-cap'] ? await probes['process-cap']() : UNPROBED_PROCESS_CAP;
+    if (probes['process-cap']) controls['process-cap'] = await probes['process-cap']();
+    else if (backend === 'namespace') await run('process-cap', () => probeProcessCap());
+    else controls['process-cap'] = UNPROBED_PROCESS_CAP;
   }
   const report = { platform: process.platform, backend, controls };
   if (!Object.keys(probes).length) _cache.set(backend, report);
@@ -209,7 +293,7 @@ export function capabilityReport(report) {
     notes: [
       'A state of proved was established by an active probe on THIS host in THIS process; it is not inherited from another platform.',
       'Linux enforcement cannot be exercised on a macOS host. It is evidenced only where the sandbox-linux CI job ran this same probe set.',
-      'Process-count caps are not claimed enforced on any backend.',
+      'A process-count cap is claimed only where its probe reports proved (the Linux namespace backend, on the hosted job); it is never claimed on the macOS backend.',
     ],
   };
 }

package/src/sandbox/limits.js

@@ -54,6 +54,8 @@ export function buildLimitPrelude({
  * e.g. `'0 2>/dev/null; true'` swallows the failure. Coerce and reject
  * anything that is not a finite, non-negative number.
  */
+export function validateMaxProcs(v) { return _num('maxProcs', v); }
+
 function _num(name, v) {
   const n = Number(v);
   if (!Number.isFinite(n) || n < 0) {

package/src/sandbox/linux-probes.js

@@ -0,0 +1,179 @@
+// Active probes specific to the Linux namespace backend (X-502, X-503, CORE-003).
+//
+// These are the controls that are only true because of what the kernel does
+// with namespaces, each established the way `control-probes.js` establishes the
+// others: an ATTACK that must fail, paired with a POSITIVE CONTROL showing the
+// same probe succeeds when the control is off, so a probe that can never
+// succeed cannot pass for a working control.
+//
+//   pid-namespace              the payload is pid 1 and cannot see host pids
+//   init-kill-reaps-detached   killing the namespace's supervisor (or its init)
+//                              ends a double-forked, setsid member that no
+//                              process-group or sweep logic could find
+//   protected-canary-masked    a protected file and directory under a DECLARED
+//                              read root are unreadable (masked), and readable
+//                              when not protected
+//   capability-network         in capability mode a loopback listener is
+//                              reachable only when network is allowed
+//
+// Each takes a `run` seam so a test can hand it a runner that is deliberately
+// wrong and see the probe say so. Nothing here asserts a result in advance: a
+// probe that cannot establish its own positive control reports `not-proved`.
+import { spawn, spawnSync } from 'node:child_process';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import net from 'node:net';
+import os from 'node:os';
+import path from 'node:path';
+import { runConfined } from './index.js';
+import { buildNamespaceInvocation } from './backend-namespace.js';
+import { heartbeatShell, probeProcessCap } from './control-probes.js';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const NODE = process.execPath;
+const proved = (evidence) => ({ state: 'proved', evidence });
+const notProved = (reason) => ({ state: 'not-proved', reason });
+
+function mk(prefix) { return fs.realpathSync(fs.mkdtempSync(path.join(os.tmpdir(), prefix))); }
+function rm(p) { try { fs.rmSync(p, { recursive: true, force: true }); } catch { /* best effort */ } }
+const token = (p) => `${p}-${crypto.randomBytes(8).toString('hex')}`;
+
+/** The payload is pid 1 of its own PID namespace and sees no host process. */
+export async function probePidNamespace({ run = runConfined } = {}) {
+  const root = mk('agsec-lp-pid-');
+  try {
+    // A host process that certainly exists and is not in the payload's tree.
+    const r = run(['/bin/sh', '-c', 'echo PID=$$; ls /proc'], { root, timeoutMs: 8000 });
+    const out = String(r.stdout || '');
+    const m = /PID=(\d+)/.exec(out);
+    if (!m) return notProved(`positive control failed: the probe payload did not report (${r.status})`);
+    if (m[1] !== '1') return notProved(`the payload is pid ${m[1]}, not pid 1 of a new PID namespace`);
+    const visible = out.split('\n').map((l) => l.trim()).filter((l) => /^\d+$/.test(l));
+    if (!visible.length) return notProved('positive control failed: /proc listed no processes, so host visibility could not be judged');
+    if (visible.includes(String(process.pid)) || visible.includes(String(process.ppid))) {
+      return notProved('the payload can see host processes in /proc');
+    }
+    return proved(`the payload is pid 1; /proc lists ${visible.length} process(es) and none of the host's`);
+  } finally { rm(root); }
+}
+
+function heartbeatLines(root, n) {
+  try { return fs.readFileSync(path.join(root, `hb${n}`), 'utf8').split('\n').filter(Boolean).length; } catch { return 0; } // agentic-security-ignore: CWE-400
+}
+
+function childrenOf(pid) {
+  const r = spawnSync('ps', ['-o', 'pid=', '--ppid', String(pid)], { encoding: 'utf8', timeout: 3000 });
+  return String(r.stdout || '').split('\n').map((x) => Number(x.trim())).filter(Number.isFinite).filter(Boolean);
+}
+
+/**
+ * Start a namespace-confined tree that includes a double-forked, setsid member,
+ * then kill ONE process from the host: the supervisor (`unshare`) or the
+ * namespace's init (its child). Either way the kernel must take every member
+ * of the namespace with it.
+ *
+ * @param {'supervisor'|'init'} victim
+ */
+export async function probeInitKillReapsDetached({ victim = 'supervisor', settleMs = 700, deps } = {}) {
+  const root = mk('agsec-lp-init-');
+  let inv = null; let child = null;
+  try {
+    const script = [
+      `( ${heartbeatShell(1)} ) &`,
+      `( setsid /bin/sh -c '${heartbeatShell(2)}' >/dev/null 2>&1 & ) &`,
+      `( trap '' TERM; ${heartbeatShell(3)} ) &`,
+      'wait',
+    ].join('\n');
+    inv = buildNamespaceInvocation(['/bin/sh', '-c', script], { root }, deps);
+    if (inv.error) return { state: 'unsupported', reason: String(inv.error.stderr || '').split('\n')[0] };
+    if (!inv.treeKill) return { state: 'unsupported', reason: 'this host cannot make the kernel kill the namespace with its supervisor' };
+    child = spawn(inv.bin, inv.args, { cwd: inv.cwd, env: inv.env, stdio: 'ignore' });
+    const lines = (n) => heartbeatLines(root, n);
+    const names = [1, 2, 3];
+    const deadline = Date.now() + 8000;
+    while (Date.now() < deadline && !names.every((n) => lines(n) >= 3)) await sleep(100);
+    if (!names.every((n) => lines(n) >= 3)) return notProved('positive control failed: the tree did not start and heartbeat before the kill');
+
+    let targets = [child.pid];
+    if (victim === 'init') {
+      // The namespace's init is the supervisor's direct child (unshare forks
+      // it). Kill every direct child, never the supervisor itself.
+      targets = childrenOf(child.pid);
+      if (!targets.length) return notProved('positive control failed: no namespace init found under the supervisor');
+    }
+    for (const t of targets) { try { process.kill(t, 'SIGKILL'); } catch { /* already gone */ } }
+    await sleep(settleMs);
+    const mid = names.map(lines);
+    await sleep(settleMs);
+    const late = names.map(lines);
+    const alive = names.filter((n, i) => late[i] > mid[i]);
+    if (alive.length) return notProved(`members of the namespace outlived the kill of its ${victim} (heartbeat ${alive.join(',')})`);
+    return proved(`SIGKILL of the namespace ${victim} ended a plain member, a double-forked setsid member and a SIGTERM-ignoring member`);
+  } finally {
+    try { if (child) child.kill('SIGKILL'); } catch { /* gone */ }
+    if (inv && !inv.error) { try { inv.finish('', { hadError: true }); } catch { /* best effort */ } }
+    rm(root);
+  }
+}
+
+/** A protected file and directory under a declared read root are unreadable, and readable when unprotected. */
+export async function probeProtectedCanaryMasked({ run = runConfined } = {}) {
+  const root = mk('agsec-lp-prot-'); const base = mk('agsec-lp-pbase-');
+  try {
+    const dirTok = token('SEALEDDIR'); const fileTok = token('SEALEDFILE'); const pubTok = token('PUBLIC');
+    fs.mkdirSync(path.join(base, 'sealed'));
+    fs.writeFileSync(path.join(base, 'sealed', 'k.txt'), dirTok);
+    fs.writeFileSync(path.join(base, 'sealed-file.txt'), fileTok);
+    fs.writeFileSync(path.join(base, 'public.txt'), pubTok);
+    const cmd = ['/bin/sh', '-c', `cat '${base}/public.txt' '${base}/sealed/k.txt' '${base}/sealed-file.txt' 2>&1; true`];
+    const open = run(cmd, { root, readRoots: [base], timeoutMs: 8000 });
+    const o = String(open.stdout || '');
+    if (!(o.includes(pubTok) && o.includes(dirTok) && o.includes(fileTok))) {
+      return notProved(`positive control failed: the files were not readable without protection (${open.status})`);
+    }
+    const closed = run(cmd, { root, readRoots: [base], denyReadPaths: [path.join(base, 'sealed'), path.join(base, 'sealed-file.txt')], timeoutMs: 8000 });
+    const c = String(closed.stdout || '');
+    if (!c.includes(pubTok)) return notProved(`positive control failed: the unprotected file stopped being readable (${closed.status})`);
+    if (c.includes(dirTok)) return notProved('a protected directory under a declared root was readable');
+    if (c.includes(fileTok)) return notProved('a protected file under a declared root was readable');
+    return proved('a protected directory and file under a declared read root were unreadable; the unprotected file and both canaries were readable without protection');
+  } finally { rm(root); rm(base); }
+}
+
+/** In capability mode a loopback listener is reachable with network allowed and unreachable otherwise. */
+export async function probeCapabilityNetwork({ run = runConfined } = {}) {
+  const root = mk('agsec-lp-net-');
+  let hits = 0;
+  const server = net.createServer((s) => { hits += 1; s.destroy(); });
+  try {
+    await new Promise((res, rej) => { server.once('error', rej); server.listen(0, '127.0.0.1', res); });
+    const port = server.address().port;
+    const script = `require('net').connect(${port},'127.0.0.1').on('error',()=>process.exit(0)).on('connect',()=>process.exit(0));setTimeout(()=>process.exit(0),1500)`;
+    const exeReal = fs.realpathSync(NODE);
+    run([NODE, '-e', script], { root, readRoots: [exeReal], allowNetwork: true, timeoutMs: 8000 });
+    await sleep(200);
+    const open = hits;
+    if (open < 1) return notProved('positive control failed: the loopback listener saw no connection with network allowed');
+    const denied = run([NODE, '-e', script], { root, readRoots: [exeReal], allowNetwork: false, timeoutMs: 8000 });
+    await sleep(200);
+    if (hits > open) return notProved('a connection reached a loopback listener with network denied');
+    void denied;
+    return proved('a connection was seen with network allowed and none with network denied (capability mode)');
+  } finally { server.close(); rm(root); }
+}
+
+/** Every Linux-specific probe, in a fixed order. */
+export async function runLinuxProbes() {
+  const out = {};
+  const step = async (name, fn) => {
+    try { out[name] = await fn(); } catch (e) { out[name] = notProved(`probe threw: ${String(e.message).split('\n')[0]}`); }
+  };
+  await step('pid-namespace', () => probePidNamespace());
+  await step('init-kill-reaps-detached:supervisor', () => probeInitKillReapsDetached({ victim: 'supervisor' }));
+  await step('init-kill-reaps-detached:init', () => probeInitKillReapsDetached({ victim: 'init' }));
+  await step('protected-canary-masked:default', () => probeProtectedCanaryMasked({ run: (a, o) => runConfined(a, { ...o, readRoots: undefined }) }));
+  await step('protected-canary-masked:capability', () => probeProtectedCanaryMasked());
+  await step('capability-network', () => probeCapabilityNetwork());
+  await step('process-cap:capability', () => probeProcessCap({ mode: { readRoots: [] } }));
+  return out;
+}

package/src/sandbox/linux-rootfs.js

@@ -0,0 +1,263 @@
+// Pure construction of the Linux root filesystem the namespace backend pivots
+// into (capability mode, X-502).
+//
+// Nothing in this file touches the kernel. It turns declared roots into a PLAN
+// (which host paths are made visible, read-only or read-write, and which are
+// masked) and a POSIX shell script that carries the plan out inside fresh user,
+// mount and PID namespaces. Keeping it pure is the point: the construction can
+// be unit-tested on any host, with stand-in mount tools, and the claim that the
+// kernel then enforces it is made only by the active probes that run on a Linux
+// host (`linux-probes.js`, the `sandbox-linux` CI job).
+//
+// The model, in one paragraph. A new mount namespace gets a tmpfs root that
+// holds NOTHING. Only the paths in the plan are bind-mounted into it, at the
+// same absolute path they have on the host: the minimal runtime baseline
+// (interpreter, libraries, a few identity files) and the declared read roots
+// read-only, the declared write roots read-write, then a fresh /proc and a
+// minimal /dev. The skeleton is remounted read-only and the process pivots into
+// it; the old root is detached. A protected path is not denied, it is ABSENT:
+// the kernel has no name for it, so there is nothing to open, to follow a link
+// to, or to reach with `..`. Paths keep their meaning, so a caller's absolute
+// paths mean the same thing on this backend as on the userspace one.
+import fs from 'node:fs';
+import path from 'node:path';
+
+// What every confined process needs just to start: the dynamic loader, system
+// libraries, the shell and coreutils. Mounted read-only. Directories that are
+// symlinks on the host (`/bin -> usr/bin`) are recreated as symlinks.
+export const BASELINE_DIRS = Object.freeze([
+  '/usr', '/bin', '/sbin', '/lib', '/lib32', '/lib64', '/libx32', '/etc/alternatives',
+]);
+// Identity and loader files; no credentials. Read-only. A missing one is skipped.
+export const BASELINE_FILES = Object.freeze([
+  '/etc/ld.so.cache', '/etc/ld.so.conf', '/etc/localtime', '/etc/nsswitch.conf', '/etc/passwd', '/etc/group',
+]);
+// Device nodes a process legitimately needs. Nothing else from /dev.
+export const DEV_NODES = Object.freeze(['null', 'zero', 'full', 'random', 'urandom', 'tty']);
+
+const BAD_CHARS = /[\0\n\t]/;
+
+/** True for a path the plan format can carry (absolute, no NUL/newline/tab, not the root). */
+export function isPlanPath(p) {
+  return typeof p === 'string' && p.startsWith('/') && p !== '/' && !BAD_CHARS.test(p);
+}
+
+function realOrResolved(p, realpath) {
+  const abs = path.resolve(p);
+  try { return realpath(abs); } catch { return abs; }
+}
+
+function within(parent, child) {
+  return child === parent || child.startsWith(parent.endsWith('/') ? parent : parent + '/');
+}
+
+/**
+ * Build the plan.
+ * @param {object} o
+ * @param {string}   o.root            the sandbox root (always read-write)
+ * @param {string[]} [o.readRoots]     read-only roots (directories or files)
+ * @param {string[]} [o.writeRoots]    read-write roots
+ * @param {string[]} [o.denyReadPaths] paths that must not be readable
+ * @param {string}   [o.cwd]           working directory (must lie inside a bound path)
+ * @param {boolean}  [o.baseline=true] include the runtime baseline
+ * @param {(p:string)=>string} [o.realpath]  seam for tests
+ * @returns {{ok:true, entries:{path:string, mode:'ro'|'rw'}[], masks:string[], cwd:string} | {ok:false, error:string}}
+ */
+export function buildRootPlan({
+  root, readRoots = [], writeRoots = [], denyReadPaths = [], cwd = null, baseline = true,
+  realpath = fs.realpathSync,
+} = {}) {
+  if (!root) return { ok: false, error: 'a sandbox root is required' };
+  const want = new Map(); // path -> 'ro' | 'rw' (rw wins)
+  const add = (p, mode) => {
+    if (want.get(p) === 'rw') return;
+    want.set(p, mode);
+  };
+  const clean = (p, what) => {
+    if (typeof p !== 'string' || !p) return { error: `${what} must be a non-empty path` };
+    const real = realOrResolved(p, realpath);
+    if (real === '/') return { error: `${what} may not be the filesystem root` };
+    if (!isPlanPath(real)) return { error: `${what} cannot be carried into a mount plan (${JSON.stringify(p)})` };
+    return { path: real };
+  };
+
+  if (baseline) {
+    for (const p of [...BASELINE_DIRS, ...BASELINE_FILES]) add(p, 'ro');
+  }
+  const rootC = clean(root, 'the sandbox root');
+  if (rootC.error) return { ok: false, error: rootC.error };
+  add(rootC.path, 'rw');
+  for (const p of readRoots || []) {
+    const c = clean(p, 'a read root');
+    if (c.error) return { ok: false, error: c.error };
+    add(c.path, 'ro');
+  }
+  for (const p of writeRoots || []) {
+    const c = clean(p, 'a write root');
+    if (c.error) return { ok: false, error: c.error };
+    add(c.path, 'rw');
+  }
+
+  // Drop an entry already covered by a bound ancestor with at least its access:
+  // binding a file over a path inside a read-only mount would have to create it
+  // there, which a read-only mount refuses, and it adds nothing.
+  const all = [...want.entries()].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+  const entries = [];
+  for (const [p, mode] of all) {
+    const covered = entries.some((e) => e.path !== p && within(e.path, p) && (e.mode === 'rw' || mode === 'ro'));
+    if (!covered) entries.push({ path: p, mode });
+  }
+
+  const masks = [];
+  for (const p of denyReadPaths || []) {
+    if (typeof p !== 'string' || !p) continue;
+    const real = realOrResolved(p, realpath);
+    if (!isPlanPath(real)) {
+      if (real === '/' || BAD_CHARS.test(real)) return { ok: false, error: `a denied path cannot be carried into a mount plan (${JSON.stringify(p)})` };
+      continue;
+    }
+    // A denied path that contains a bound root would hide the root; refuse
+    // rather than guess which of the two the caller meant.
+    const hides = [rootC.path, ...[...(readRoots || []), ...(writeRoots || [])].map((r) => realOrResolved(r, realpath))]
+      .find((r) => within(real, r));
+    if (hides) return { ok: false, error: `a denied path overlaps a bound root (${real})` };
+    if (!masks.includes(real)) masks.push(real);
+  }
+
+  let workdir = rootC.path;
+  if (cwd) {
+    const c = clean(cwd, 'the working directory');
+    if (c.error) return { ok: false, error: c.error };
+    if (!entries.some((e) => within(e.path, c.path))) return { ok: false, error: `the working directory is outside every bound path (${c.path})` };
+    workdir = c.path;
+  }
+  return { ok: true, entries, masks, cwd: workdir };
+}
+
+/** The plan as the tab-separated text the setup script reads. */
+export function serializePlan(plan) {
+  const lines = [];
+  for (const e of plan.entries) lines.push(`B\t${e.mode}\t${e.path}`);
+  for (const m of plan.masks) lines.push(`M\t-\t${m}`);
+  return lines.join('\n');
+}
+
+export const MARK_SETUP_FAILED = 'AGSEC_SANDBOX_SETUP_FAILED:';
+export const MARK_NO_PRIVDROP = 'AGSEC_SANDBOX_PRIVDROP_UNAVAILABLE';
+
+/**
+ * The setup script for capability mode. Runs inside the new namespaces as the
+ * mapped root, before anything of the caller's. Reads, from the environment:
+ *   SBX_MOUNT SBX_UMOUNT SBX_PIVOT SBX_PRIVDROP   absolute tool paths
+ *   SBX_NEWROOT   an empty host directory to become the new root
+ *   SBX_PLAN      the serialized plan
+ *   SBX_FINAL     the second-stage script (final privilege state)
+ * Every step is fail-closed: a failure prints the marker and exits before the
+ * caller's command is exec'd.
+ */
+export const PIVOT_SETUP_SCRIPT = `
+_fail() { echo "${MARK_SETUP_FAILED} $1" >&2; exit 91; }
+# Make one bind mount read-only. A plain remount is tried first; some kernels
+# lock the flags a bind inherits inside a user namespace (nosuid, nodev, ...),
+# in which case the remount must restate them, so the second attempt reads the
+# mount's current options and replaces only the access mode.
+_ro() {
+  "$SBX_MOUNT" -o remount,bind,ro "$1" 2>/dev/null && return 0
+  _cur=$(while read -r _a _b _c _d _mp _o _rest; do if [ "$_mp" = "$1" ]; then echo "$_o"; break; fi; done < /proc/self/mountinfo)
+  case "$_cur" in *,*) "$SBX_MOUNT" -o "remount,bind,ro,\${_cur#*,}" "$1" ;; *) "$SBX_MOUNT" -o remount,bind,ro "$1" ;; esac
+}
+NR="$SBX_NEWROOT"
+[ -n "$NR" ] && [ -d "$NR" ] || _fail "no new root directory"
+"$SBX_MOUNT" --make-rprivate / || _fail "mount propagation could not be made private"
+"$SBX_MOUNT" -t tmpfs -o mode=0755,size=16m tmpfs "$NR" || _fail "the new root could not be created"
+_tab=$(printf '\\t')
+while IFS="$_tab" read -r _op _mode _p; do
+  [ -n "$_op" ] || continue
+  case "$_op" in
+    B)
+      if [ -L "$_p" ]; then
+        mkdir -p "$NR\${_p%/*}" || _fail "could not prepare a link"
+        ln -s "$(readlink "$_p")" "$NR$_p" || _fail "could not recreate a link"
+      elif [ -d "$_p" ]; then
+        mkdir -p "$NR$_p" || _fail "could not prepare a mount point"
+        "$SBX_MOUNT" --bind "$_p" "$NR$_p" || _fail "a path could not be made visible"
+        if [ "$_mode" = ro ]; then
+          _ro "$NR$_p" || _fail "a path could not be made read-only"
+        fi
+      elif [ -e "$_p" ]; then
+        mkdir -p "$NR\${_p%/*}" || _fail "could not prepare a mount point"
+        [ -e "$NR$_p" ] || : > "$NR$_p" || _fail "could not prepare a file mount point"
+        "$SBX_MOUNT" --bind "$_p" "$NR$_p" || _fail "a file could not be made visible"
+        if [ "$_mode" = ro ]; then
+          _ro "$NR$_p" || _fail "a file could not be made read-only"
+        fi
+      fi
+      ;;
+  esac
+done <<SBX_PLAN_EOF
+$SBX_PLAN
+SBX_PLAN_EOF
+mkdir -p "$NR/proc" "$NR/dev" || _fail "could not prepare /proc and /dev"
+"$SBX_MOUNT" -t proc proc "$NR/proc" 2>/dev/null || true
+"$SBX_MOUNT" -t tmpfs -o mode=0755,size=64k tmpfs "$NR/dev" || _fail "could not create /dev"
+for _n in ${DEV_NODES.join(' ')}; do
+  [ -e "/dev/$_n" ] || continue
+  : > "$NR/dev/$_n" || continue
+  "$SBX_MOUNT" --bind "/dev/$_n" "$NR/dev/$_n" 2>/dev/null || { [ "$_n" = null ] && _fail "/dev/null could not be provided"; }
+done
+while IFS="$_tab" read -r _op _mode _p; do
+  [ "$_op" = M ] || continue
+  if [ -d "$NR$_p" ]; then
+    "$SBX_MOUNT" -t tmpfs -o size=4k,mode=000 tmpfs "$NR$_p" || _fail "a protected directory could not be masked"
+  elif [ -e "$NR$_p" ]; then
+    "$SBX_MOUNT" --bind /dev/null "$NR$_p" || _fail "a protected file could not be masked"
+  fi
+done <<SBX_PLAN_EOF
+$SBX_PLAN
+SBX_PLAN_EOF
+mkdir "$NR/.old" || _fail "could not prepare the old-root mount point"
+_ro "$NR" || _fail "the new root could not be made read-only"
+cd "$NR" || _fail "could not enter the new root"
+"$SBX_PIVOT" "$NR" "$NR/.old" || _fail "pivot_root failed"
+cd / || _fail "could not enter the pivoted root"
+"$SBX_UMOUNT" -l /.old || _fail "the old root could not be detached"
+if [ -z "$SBX_PRIVDROP" ] || ! "$SBX_PRIVDROP" --no-new-privs --securebits=+noroot,+noroot_locked --bounding-set=-all --inh-caps=-all /bin/sh -c 'exit 0' 2>/dev/null; then
+  _fail "privilege drop is unavailable, and capability mode does not run without it"
+fi
+exec "$SBX_PRIVDROP" --no-new-privs --securebits=+noroot,+noroot_locked --bounding-set=-all --inh-caps=-all /bin/sh -c "$SBX_FINAL" _sbx "$@"
+`;
+
+/**
+ * Second stage, in the final privilege state. Both directions are checked by
+ * execution on every run: the host canary and the filesystem root are refused,
+ * the sandbox root is writable. Either check failing means the sandbox is not
+ * what it claims, so the command is not run.
+ */
+export 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 [ -n "$SBX_STRICT" ]; then
+  if ( : > /.agsec-rootcheck ) 2>/dev/null; then
+    _fail "the filesystem root is writable; refusing to execute"
+  fi
+  if [ -e /.old/usr ]; then
+    _fail "the old root is still reachable; refusing to execute"
+  fi
+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"
+_cwd="\${SBX_CWD:-$ROOT}"
+_nproc="$SBX_NPROC"; _prlimit="$SBX_PRLIMIT"
+unset SBX_PLAN SBX_FINAL SBX_MOUNT SBX_UMOUNT SBX_PIVOT SBX_PRIVDROP SBX_NEWROOT SBX_MASKS SBX_CANARY SBX_STRICT SBX_CWD SBX_NPROC SBX_PRLIMIT
+# The process-count cap is applied last, to the caller's command only: the checks
+# above fork, and so does the setup before them. A prlimit that cannot run stops
+# the command (the exec fails), never lets it run uncapped.
+if [ -n "$_nproc" ]; then
+  cd "$_cwd" && exec "$_prlimit" --nproc="$_nproc" -- "$@"
+fi
+cd "$_cwd" && exec "$@"
+`;