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

package/src/posture/test-runner.js

@@ -0,0 +1,147 @@
+// R5 (partial, roadmap) — the project's own test suite as a verification
+// stage for `verifyFix()` (see `fix-verify.js`). Closes the gap where a
+// "verified" fix only proved a finding's stableId stopped firing — a patch
+// that deletes the feature entirely would satisfy that just as well as a
+// real fix. Running the project's own tests is the cheapest available check
+// that the application still works.
+//
+// Execution-safety note: this spawns the TARGET PROJECT's own test command
+// in the target project's own directory. That is deliberately NOT routed
+// through the R1 confinement sandbox (`../sandbox/`). That sandbox exists to
+// contain untrusted proof-of-concept exploit code the scanner itself
+// synthesizes — code nobody has vetted, being run for the first time. A
+// project's pre-existing test suite is the opposite case: it is the
+// project's own trusted source, already sitting on disk, and running it is
+// exactly what a human developer does by hand before trusting a fix.
+// Wrapping "npm test" / "pytest" / "go test" in the PoC sandbox's
+// syscall/network/filesystem restrictions would break the large majority of
+// real test suites (they bind local ports, spawn child processes, write temp
+// fixtures, etc.) for no corresponding security benefit.
+
+import { spawnSync } from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const DEFAULT_TIMEOUT_MS = 300_000;
+const NPM_PLACEHOLDER = /Error: no test specified/i;
+
+function _exists(scanRoot, rel) {
+  try { return fs.existsSync(path.join(scanRoot, rel)); } catch { return false; }
+}
+
+function _isDir(scanRoot, rel) {
+  try { return fs.statSync(path.join(scanRoot, rel)).isDirectory(); } catch { return false; }
+}
+
+function _binaryAvailable(cmd) {
+  try {
+    const r = spawnSync(cmd, ['--version'], { timeout: 5_000, stdio: 'ignore' });
+    return !(r.error && r.error.code === 'ENOENT');
+  } catch {
+    return false;
+  }
+}
+
+// Detect the project's test command. Read-only — never spawns the actual
+// test run, only (optionally) a cheap `--version` probe to confirm a tool
+// like `pytest` is actually installed before committing to it. Returns
+// `null` when nothing detectable is found — most scanned repos will hit
+// this path, and that must not be treated as a failure by callers.
+export function detectTestCommand(scanRoot) {
+  if (!scanRoot) return null;
+
+  // JS/TS — package.json with a real (non-placeholder) `scripts.test`.
+  let pkg = null;
+  try { pkg = JSON.parse(fs.readFileSync(path.join(scanRoot, 'package.json'), 'utf8')); } catch { pkg = null; }
+  const testScript = pkg && pkg.scripts && pkg.scripts.test;
+  if (testScript && !NPM_PLACEHOLDER.test(String(testScript))) {
+    if (_exists(scanRoot, 'pnpm-lock.yaml')) return { cmd: 'pnpm', args: ['test'], kind: 'pnpm' };
+    if (_exists(scanRoot, 'yarn.lock')) return { cmd: 'yarn', args: ['test'], kind: 'yarn' };
+    if (_exists(scanRoot, 'bun.lockb') || _exists(scanRoot, 'bun.lock')) return { cmd: 'bun', args: ['test'], kind: 'bun' };
+    return { cmd: 'npm', args: ['test', '--silent'], kind: 'npm' };
+  }
+
+  // Python — pytest.ini / pyproject.toml / tox.ini / a tests/ dir, and the
+  // `pytest` binary actually available. If pytest isn't installed we do NOT
+  // report a python test command — falling through lets a later language
+  // marker (e.g. go.mod in a polyglot repo) still be detected.
+  const pyMarker = _exists(scanRoot, 'pytest.ini') || _exists(scanRoot, 'pyproject.toml') ||
+    _exists(scanRoot, 'tox.ini') || _isDir(scanRoot, 'tests');
+  if (pyMarker && _binaryAvailable('pytest')) {
+    return { cmd: 'pytest', args: ['-q'], kind: 'pytest' };
+  }
+
+  // Go
+  if (_exists(scanRoot, 'go.mod')) {
+    return { cmd: 'go', args: ['test', './...'], kind: 'go' };
+  }
+
+  return null;
+}
+
+// Run the detected test command with a walltime budget. Always returns a
+// result object — never throws. Distinguishes four outcomes:
+//   - no detectable/runnable command  -> status: 'skipped'  (does NOT fail)
+//   - ran and exited 0                -> status: 'passed'
+//   - ran and exited non-zero         -> status: 'failed'
+//   - ran past the timeout budget     -> status: 'failed', timedOut: true
+export function runProjectTests(scanRoot, { timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const startedAt = Date.now();
+  const command = detectTestCommand(scanRoot);
+  if (!command) {
+    return {
+      status: 'skipped', passed: null, skipped: true,
+      reason: 'no-test-command-detected', exitCode: null, timedOut: false,
+      durationMs: Date.now() - startedAt,
+    };
+  }
+
+  let r;
+  try {
+    r = spawnSync(command.cmd, command.args, {
+      cwd: scanRoot,
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      env: { ...process.env, CI: '1' },
+    });
+  } catch (e) {
+    // The spawn call itself threw (rare — e.g. cwd vanished). Treat as
+    // "could not run", not "ran and failed".
+    return {
+      status: 'skipped', passed: null, skipped: true,
+      reason: `spawn-error: ${e.message}`, exitCode: null, timedOut: false,
+      durationMs: Date.now() - startedAt,
+    };
+  }
+  const durationMs = Date.now() - startedAt;
+
+  if (r.error && r.error.code === 'ENOENT') {
+    // The detected tool isn't actually installed on this machine. Not a
+    // test failure — the suite never ran.
+    return {
+      status: 'skipped', passed: null, skipped: true,
+      reason: `${command.kind}-not-installed`, exitCode: null, timedOut: false, durationMs,
+    };
+  }
+
+  if (r.status === null) {
+    // spawnSync sets status:null both on timeout-kill and on being killed by
+    // another signal; either way the run did not complete, which is a
+    // verification failure, never a skip — we asked for a result and the
+    // process was terminated before producing one.
+    return {
+      status: 'failed', passed: false, skipped: false,
+      reason: 'timed-out', exitCode: null, timedOut: true, durationMs,
+    };
+  }
+
+  return {
+    status: r.status === 0 ? 'passed' : 'failed',
+    passed: r.status === 0,
+    skipped: false,
+    reason: r.status === 0 ? null : 'test-failures',
+    exitCode: r.status,
+    timedOut: false,
+    durationMs,
+  };
+}

package/src/posture/verification-separation.js

@@ -0,0 +1,131 @@
+// R7 — adversarial verification with ENFORCED SEPARATION.
+//
+// The falsification pass (`falsification.js`) already tries to DISPROVE a
+// finding. What it could not previously do is *prove* that whoever checked the
+// finding was not whoever produced it. That guarantee is what this module adds,
+// plus a recorded multi-perspective verdict for contested findings.
+//
+// The property that matters: a verifier is structurally unable to rubber-stamp
+// its own finding.
+//   - `recordProducer` stamps who produced the finding, WRITE-ONCE. A later
+//     party cannot re-stamp itself as the producer to manufacture separation.
+//   - `assertSeparation` refuses when the verifier id equals the recorded
+//     producer id, and FAILS CLOSED when no producer was recorded at all
+//     (separation that cannot be established is not separation).
+//   - `recordVerdict` runs that check itself, so there is no code path that
+//     records a verdict without it. One verifier gets one vote per lens: a
+//     re-vote replaces the previous one rather than stuffing the ballot.
+//
+// RECALL-PRESERVING, same precedent as `falsification.js` and
+// `dataflow/proof-gate.js`: nothing here ever removes a finding and nothing
+// here ever touches `severity`. A `refuted` consensus is a triage signal, not
+// a deletion — absence of proof is not proof of absence.
+//
+// NO THROWING (posture/CLAUDE.md convention): every entry point returns a
+// refusal object `{ ok:false, refused:true, reason }` instead of throwing, so
+// an annotator can call it inside the engine's pipeline without a guard.
+
+export const VERIFICATION_VERDICTS = ['upheld', 'refuted', 'undecided'];
+
+// Verifier ids are namespaced so they can never collide with a producer id.
+export const VERIFIER_FALSIFICATION = 'verifier:falsification';
+export const VERIFIER_LLM_REVIEW = 'verifier:llm-review';
+
+function _refuse(reason) { return { ok: false, refused: true, reason }; }
+
+/** Namespaced id for whoever produced a finding — derived from its detector. */
+export function producerIdOf(finding) {
+  const p = finding && finding.parser ? String(finding.parser) : 'unknown';
+  return `detector:${p}`;
+}
+
+/**
+ * Stamp who produced this finding. Write-once: a second call with a different
+ * id is REFUSED (this is what stops a verifier reassigning provenance to
+ * itself). A repeat call with the same id is a no-op success.
+ */
+export function recordProducer(finding, producerId) {
+  if (!finding || typeof finding !== 'object') return _refuse('no finding');
+  const id = producerId ? String(producerId) : '';
+  if (!id) return _refuse('no producer id');
+  if (!finding.verification || typeof finding.verification !== 'object') {
+    finding.verification = { producer: id, verdicts: [] };
+    return { ok: true, producer: id };
+  }
+  if (!finding.verification.producer) {
+    finding.verification.producer = id;
+    if (!Array.isArray(finding.verification.verdicts)) finding.verification.verdicts = [];
+    return { ok: true, producer: id };
+  }
+  if (finding.verification.producer === id) return { ok: true, producer: id };
+  return _refuse(`producer already recorded as "${finding.verification.producer}" — write-once`);
+}
+
+/**
+ * The separation check. `{ ok:true, producer }` when the verifier is a party
+ * other than the producer; a refusal otherwise. Fails closed when no producer
+ * has been recorded.
+ */
+export function assertSeparation(finding, verifierId) {
+  if (!finding || typeof finding !== 'object') return _refuse('no finding');
+  const vid = verifierId ? String(verifierId) : '';
+  if (!vid) return _refuse('no verifier id');
+  const producer = finding.verification && finding.verification.producer;
+  if (!producer) {
+    return _refuse('no producer recorded — separation cannot be established');
+  }
+  if (producer === vid) {
+    return _refuse(`verifier "${vid}" is the producer of this finding — separation violated`);
+  }
+  return { ok: true, producer };
+}
+
+/**
+ * Record one verifier's verdict from one perspective (`lens`, e.g.
+ * 'reachability' | 'control-flow' | 'data-shape'). Refuses — recording
+ * nothing — when separation fails or the verdict is not one of
+ * VERIFICATION_VERDICTS. Never touches severity, never removes anything.
+ */
+export function recordVerdict(finding, { verifierId, lens, verdict, reason } = {}) {
+  if (!finding || typeof finding !== 'object') return _refuse('no finding');
+  if (!lens) return _refuse('no lens');
+  if (!VERIFICATION_VERDICTS.includes(verdict)) {
+    return _refuse(`unknown verdict "${verdict}" — expected one of ${VERIFICATION_VERDICTS.join('|')}`);
+  }
+  const sep = assertSeparation(finding, verifierId);
+  if (!sep.ok) return sep;
+
+  const entry = {
+    verifierId: String(verifierId),
+    lens: String(lens),
+    verdict,
+    ...(reason ? { reason: String(reason) } : {}),
+  };
+  const list = finding.verification.verdicts;
+  const i = list.findIndex(v => v.verifierId === entry.verifierId && v.lens === entry.lens);
+  if (i >= 0) list[i] = entry; else list.push(entry);
+  return { ok: true, recorded: entry };
+}
+
+/**
+ * Majority across every recorded verdict. Ties — including "no verdicts at
+ * all" — are 'undecided'. `lenses` is the sorted set of perspectives that
+ * actually voted, so a caller can see whether a verdict is one-eyed or a panel.
+ */
+export function consensusOf(finding) {
+  const list = (finding && finding.verification && Array.isArray(finding.verification.verdicts))
+    ? finding.verification.verdicts : [];
+  let upheld = 0, refuted = 0, undecided = 0;
+  const lenses = new Set();
+  for (const v of list) {
+    if (!v) continue;
+    if (v.lens) lenses.add(String(v.lens));
+    if (v.verdict === 'upheld') upheld++;
+    else if (v.verdict === 'refuted') refuted++;
+    else if (v.verdict === 'undecided') undecided++;
+  }
+  let verdict = 'undecided';
+  if (upheld > refuted) verdict = 'upheld';
+  else if (refuted > upheld) verdict = 'refuted';
+  return { verdict, upheld, refuted, undecided, lenses: [...lenses].sort() };
+}

package/src/pr-comment.js

@@ -25,6 +25,8 @@
 // route through an LLM for richer prose when AGENTIC_SECURITY_LLM_ENDPOINT
 // is configured.
 
+import { escapeMarkdown } from './util/untrusted.js';
+
 const SEVERITY_GLYPH = {
   critical: '🟥',
   high:     '🟧',
@@ -136,7 +138,7 @@ export function renderPrComment(delta, { repoName, prNumber, prTitle } = {}) {
     const sev = SEVERITY_GLYPH[f.severity] || '⬜';
     const route = _route(f);
     const where = route ? `\`${route}\` (\`${f.file}:${f.line}\`)` : `\`${f.file}:${f.line}\``;
-    lines.push(`${sev} **${meta?.name || f.vuln}** — ${where}`);
+    lines.push(`${sev} **${meta?.name || escapeMarkdown(f.vuln)}** — ${where}`);
     if (meta) lines.push(`  > ${meta.why}`);
     if (f.remediation) {
       const onelineFix = String(f.remediation).split('\n')[0].slice(0, 240);

package/src/report/index.js

@@ -180,6 +180,11 @@ export function normalizeFindings(scan){
         paramKeyConfidence: f.poc.paramKeyConfidence || null,
         paramKeyInferred: typeof f.poc.paramKeyInferred === 'boolean' ? f.poc.paramKeyInferred : null,
       } : null,
+      // R2: execution-proof tier — copied through only when the annotator
+      // (posture/proof-tier.js) actually attached it. Never synthesised here;
+      // a finding with no proof backing simply omits these fields.
+      ...(f.proofTier !== undefined ? { proofTier: f.proofTier } : {}),
+      ...(f.proofEvidence !== undefined ? { proofEvidence: f.proofEvidence } : {}),
       // Phase-1 next-gen P1.3 (FR-UX-1, FR-UX-2): calibrated probability +
       // 95% Wilson CI + sample size. Null when N < MIN_SAMPLES_FOR_CALIBRATION
       // for this family; `calibration_reason` explains why.
@@ -401,6 +406,12 @@ export function toJSON(scan, meta={}, opts={}){
     // threw and were skipped. The findings still ship; downstream consumers
     // see the gap.
     annotatorErrors: Array.isArray(scan.annotatorErrors) ? scan.annotatorErrors : [],
+    // R4 — run attestation: a stable, order-independent digest over this
+    // finding set bound to the engine/ruleset/bundle that produced it.
+    // Attached by the CLI (posture/attestation.js); null when not computed.
+    // It carries its own `proves` / `doesNotProve` statement — do not quote
+    // the digest as cross-machine reproducibility, which it is not.
+    attestation: scan.attestation || null,
     _scanMeta: scan._scanMeta || null,
   };
   if (opts.includeSuppressed) out.suppressed = scan.suppressions||[];

package/src/runScan.js

@@ -122,7 +122,9 @@ export async function runScan(rootDir, opts = {}) {
     }
   }
 
-  const scan = await runFullScan({ fileContents, depFileContents, scanRoot: root }, opts.onProgress || (()=>{}));
+  // R8: `resume` is opt-in. Left undefined here, runFullScan falls back to the
+  // AGENTIC_SECURITY_RESUME=1 env var, which is off by default.
+  const scan = await runFullScan({ fileContents, depFileContents, scanRoot: root, resume: opts.resume }, opts.onProgress || (()=>{}));
   // Premortem 2R4.2: stamp ruleset version + source on the scan result, and
   // notify if the operator pinned a different version than what's installed.
   try { stampScan(root, scan); } catch {}

package/src/sandbox/CLAUDE.md

@@ -0,0 +1,218 @@
+# src/sandbox/
+
+Confined execution facility for running untrusted target code and candidate
+exploits (R1 of `docs/ROADMAP.md`). This is a hard prerequisite for anything
+that executes code the scanner did not write — no other module in this
+repository runs target code, confined or otherwise.
+
+## Entry point
+
+Everything goes through `index.js`:
+
+- `sandboxAvailable() -> boolean` — true iff a real confinement primitive was
+  detected on this host.
+- `runConfined(argv, opts) -> { status, denied, stdout, stderr, exitCode, timedOut, backend }`
+  — dispatches to whichever backend `detectBackend()` selected. `opts.force`
+  overrides detection (used by tests, and by any caller that wants to force
+  the disabled path deliberately).
+
+`status` is one of `'ok' | 'blocked' | 'nonzero' | 'timeout' | 'disabled' |
+'error'`. All three backends return the identical shape, so callers never
+branch on which backend ran. **`runConfined` never throws** — a missing
+`root`, an unresolvable root, a missing confinement binary, or an invalid
+resource limit all return `status: 'error'` in the normal shape. (A caller
+that wraps it in `try`/`catch` and "falls back" is a classic route to
+unconfined execution, so there is nothing to catch.)
+
+## `blocked` vs `nonzero` vs `ok` — and the limit of what is observable
+
+An earlier version derived `status` purely from the exit code, which conflated
+two unrelated outcomes: a program that ran fine and exited 3 was reported
+`'blocked'`, while a program whose out-of-root write was **denied** but which
+exited 0 was reported `'ok'` — a clean run, as far as the caller could tell.
+Both are now separated:
+
+| Field | Meaning |
+|---|---|
+| `denied: true` | A confinement violation was **observed** in the confined process's error output. |
+| `status: 'blocked'` | `denied` was true — something was refused. |
+| `status: 'nonzero'` | The command exited non-zero with **no** denial observed. Ordinary program failure, not a confinement event. |
+| `status: 'ok'` | Exited 0 with no denial observed. |
+
+**What `denied: false` does not mean.** The signal is read from the confined
+process's own stderr — these OS primitives give the parent no structured
+violation channel. A program that writes outside the root and swallows its own
+error message produces no signal at all, so `denied: false` means "no denial
+was observed", **not** "no denial occurred". `status: 'ok'` is proof that the
+command exited 0 and said nothing about a refusal; it is **not** proof that
+the sandbox refused nothing. Downstream consumers (e.g. an R2 execution
+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`)
+
+`detectBackend({ force })` probes for one confinement primitive, cached after
+the first call (`resetCapabilityCache()` clears it, used between tests):
+
+| Platform | Primitive checked | Backend selected |
+|---|---|---|
+| 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.
+
+## Fail-closed rule
+
+If no primitive is found, `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
+unconfined. An unavailable sandbox disables the execution feature; it never
+silently degrades to running the command directly. This is proven by an
+executing test (`sandbox.test.js`): the disabled backend is invoked with a
+command that would create a marker file, and the test asserts the file does
+not exist afterward.
+
+## What is verified on which platform
+
+This module was developed and its tests run on a macOS host. Guarantees below
+are stated per platform — do not extrapolate one platform's result to the
+other.
+
+**Userspace backend (macOS family) — verified by execution on this platform:**
+- A write outside the sandbox root is blocked; the target file is never
+  created.
+- Outbound network connections are blocked.
+- A wall-clock overrun stops the **direct child** (`status: 'timeout'`,
+  `timedOut: true`) — but see "Timeout does not kill the process tree" below.
+  This is not full termination and must not be described as such.
+- Benign in-root work (writes inside the root, ordinary commands) still
+  succeeds — the gate holds in both directions, not just the blocking one.
+- Fork-storm containment is **weak, not strong, on this platform**. The
+  process-count limit (`ulimit -u` / `RLIMIT_NPROC`) is a per-uid, **system-wide**
+  cap here, not a per-process-tree cap — it counts every process the user
+  owns on the whole machine, not just the sandboxed subtree. Ambient process
+  count for a normal user on this host is on the order of several hundred, so
+  any usable cap has to sit at "ambient + margin" or it starves the user's own
+  unrelated processes before the sandboxed command even starts. That means a
+  fork storm inside the sandbox can still spawn a meaningful number of
+  processes — bounded to ambient-plus-margin, not to some small absolute
+  number — before the cap bites. Treat this as a soft brake, not a hard wall.
+- Address-space capping (`ulimit -v`) is **not enforceable** on this platform.
+  `limits.js` (`buildLimitPrelude`) detects this and reports the limit in its
+  `unsupported` array instead of emitting a `ulimit -v` line that would
+  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.
+
+## Timeout does not kill the process tree
+
+`timeoutMs` is enforced with `spawnSync`'s timeout, which signals **only the
+process this module spawned**. Verified by execution on the macOS family: with
+`timeoutMs: 1200`, a command that backgrounded a 4-second child returned
+`status: 'timeout'` and the grandchild survived, completing its work *after*
+the result was returned. So `'timeout'` means "we stopped waiting and killed
+the process we spawned", not "the process tree was terminated". Survivors stay
+inside the policy profile — their writes and egress remain confined — but they
+are still running and still consuming resources. A caller that needs a hard
+tree kill must implement it.
+
+The namespace backend is structurally better here: it runs the confined
+command under `--pid --fork`, so the direct child is pid 1 of a new PID
+namespace and killing it should take the namespace's processes with it. That
+is a reasoned expectation from the flags, **not** an executed result — it
+needs the same Linux-host verification as everything else on that backend.
+
+## Known limitation, deliberately accepted: reads are not confined
+
+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.)
+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
+attacker later reads through some other channel) is **out of scope for this
+module**. This is a deliberate R1 scope cut, not an oversight: tightening
+reads requires a threat model for what a confined process may legitimately
+need to read, which belongs with the execution-verification work that
+consumes this sandbox, not with the sandbox primitive itself.
+
+### The parent environment is NOT one of the things a confined process may read
+
+Secrets carried in the parent process's environment (API tokens, cloud keys,
+registry auth) are a *distinct* exposure from unconfined file reads — the
+sandbox would be handing them over rather than merely failing to hide them —
+so they are not covered by the scope cut above. Every real backend therefore
+runs the command with a **minimal constructed environment**
+(`buildConfinedEnv` in `result.js`): `PATH`, `ROOT`, `HOME`, `TMPDIR`, `LANG`,
+with `HOME`/`TMPDIR` pointed at the sandbox root. `process.env` is not
+forwarded. A caller that genuinely needs a variable inside passes it
+explicitly as `opts.env`, which is merged on top of the base — an opt-in, one
+variable at a time, not a blanket export.
+
+## Resource limits (`limits.js`)
+
+`buildLimitPrelude({ maxProcs, maxFileSizeKb, maxAddressSpaceKb })` returns
+`{ prelude, unsupported }`. `prelude` is a shell fragment of `ulimit` calls to
+prefix before the confined command; `unsupported` lists any requested limit
+that the current platform cannot enforce, so a caller can log or surface that
+degradation rather than assume the limit applied silently.
+
+Limit values are interpolated into a shell fragment, so they are **coerced
+with `Number()` and rejected unless finite and non-negative** (`RangeError`,
+which the backends turn into `status: 'error'`). Before that, a
+config-supplied string such as `'999; echo INJECTED'` was emitted verbatim and
+its payload ran — not an escape (the prelude runs inside the confinement) but
+a way for a config-derived value to silently *disable* the limits it was
+supposed to set.
+
+## Extending this module
+
+- Both real backends (`backend-userspace.js`, `backend-namespace.js`) must
+  keep returning the exact same result shape as each other and as
+  `backend-disabled.js` — callers dispatch on `status`/`backend`, not on
+  which module ran.
+- Any new backend must add its own both-direction escape test
+  (`sandbox-escape.test.js`) before being wired into `index.js`: a `GOOD` case
+  showing legitimate in-root work still succeeds, and one `BAD` case per
+  escape vector the backend claims to block.
+- Do not add a code path that runs a command when `detectBackend()` returns
+  `'disabled'`. If a future backend needs a new capability check, add it to
+  `detectBackend`, not around it.

package/src/sandbox/backend-disabled.js

@@ -0,0 +1,14 @@
+// Fail-closed backend. Selected when no confinement primitive is available.
+// It must NEVER execute the command — an unavailable sandbox disables
+// execution features, it does not bypass them.
+export function runDisabled(_argv, _opts) {
+  return {
+    status: 'disabled',
+    denied: false,
+    stdout: '',
+    stderr: 'agentic-security: refusing to execute — no confinement primitive available on this host.',
+    exitCode: null,
+    timedOut: false,
+    backend: 'disabled',
+  };
+}

package/src/sandbox/backend-namespace.js

@@ -0,0 +1,83 @@
+// 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.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import { resolveNamespaceBin } from './capabilities.js';
+import { buildLimitPrelude } from './limits.js';
+import { buildResult, errorResult, buildConfinedEnv } from './result.js';
+
+export function runNamespace(argv, {
+  root,
+  timeoutMs = 10000,
+  allowNetwork = false,
+  limits = {},
+  env = {},
+  maxBuffer = 8 * 1024 * 1024,
+} = {}) {
+  // Documented shape, never a throw — see the same note in backend-userspace.
+  if (!root) return errorResult('namespace', 'runNamespace requires a sandbox root');
+
+  const bin = resolveNamespaceBin();
+  if (!bin) return errorResult('namespace', 'no kernel-namespace binary found on this host');
+
+  let resolvedRoot;
+  try {
+    // Resolve symlinks so the path the kernel actually sees matches what we
+    // hand to the child.
+    resolvedRoot = fs.realpathSync(root);
+  } catch (e) {
+    return errorResult('namespace', `sandbox root is not usable: ${e.message}`);
+  }
+
+  let prelude, unsupported;
+  try {
+    ({ prelude, unsupported } = buildLimitPrelude(limits));
+  } 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 });
+}