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

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 });
+}

package/src/sandbox/backend-userspace.js

@@ -0,0 +1,100 @@
+// Userspace confinement backend (macOS family). Applies a deny-by-default
+// policy profile: reads allowed, writes confined to the sandbox root, no
+// network egress unless explicitly opted in.
+//
+// TIMEOUT SCOPE — read before trusting `status:'timeout'`. The wall-clock
+// timeout is `spawnSync`'s, which signals only the DIRECT child. Verified by
+// execution on this platform: with `timeoutMs: 1200`, a command that
+// backgrounded a 4-second child returned `status:'timeout'` while the
+// grandchild survived the timeout and completed its work afterwards. So
+// 'timeout' means "we stopped waiting and killed the process we spawned", NOT
+// "the process tree was terminated". Anything left running is still inside the
+// policy profile (its writes and network stay confined), but it is still
+// running. Callers that need a hard tree kill must supply it themselves.
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import { resolveUserspaceBin } from './capabilities.js';
+import { buildLimitPrelude } 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)',
+    '(deny default)',
+    '(allow process-exec process-fork)',
+    '(allow sysctl-read)',
+    '(allow file-read*)',
+    '(allow file-write* (subpath (param "ROOT")))',
+    allowNetwork ? '(allow network*)' : '',
+  ].filter(Boolean).join('\n');
+}
+
+export function runUserspace(argv, {
+  root,
+  timeoutMs = 10000,
+  allowNetwork = false,
+  limits = {},
+  env = {},
+  maxBuffer = 8 * 1024 * 1024,
+} = {}) {
+  // Documented shape, never a throw: a caller that wraps this in try/catch and
+  // "falls back" is a classic route to unconfined execution.
+  if (!root) return errorResult('userspace', 'runUserspace requires a sandbox root');
+
+  const bin = resolveUserspaceBin();
+  if (!bin) return errorResult('userspace', 'no userspace confinement binary found on this host');
+
+  let resolvedRoot;
+  try {
+    // Resolve symlinks (e.g. macOS /var -> /private/var) so the profile's
+    // subpath param matches the path the kernel actually sees.
+    resolvedRoot = fs.realpathSync(root);
+  } catch (e) {
+    return errorResult('userspace', `sandbox root is not usable: ${e.message}`);
+  }
+
+  const effectiveLimits = {
+    ...limits,
+    maxProcs: limits.maxProcs ?? (_ambientProcCount() + 64),
+  };
+
+  let prelude, unsupported;
+  try {
+    ({ prelude, unsupported } = buildLimitPrelude(effectiveLimits));
+  } catch (e) {
+    return errorResult('userspace', `invalid resource limit: ${e.message}`);
+  }
+  const inner = `${prelude}exec "$@"`;
+
+  const r = spawnSync(
+    bin,
+    ['-p', _profile({ allowNetwork }), '-D', `ROOT=${resolvedRoot}`,
+     '/bin/sh', '-c', inner, '_sbx', ...argv],
+    {
+      encoding: 'utf8',
+      timeout: timeoutMs,
+      maxBuffer,
+      cwd: resolvedRoot,
+      env: buildConfinedEnv({ root: resolvedRoot, env }),
+    },
+  );
+
+  return buildResult({ backend: 'userspace', spawnResult: r, unsupported });
+}

package/src/sandbox/capabilities.js

@@ -0,0 +1,53 @@
+// 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.
+import fs from 'node:fs';
+
+// Referenced by path, never by product name (see Global Constraints).
+//
+// Each family lists every plausible install location, probed in order. A
+// single hardcoded path is safe (a miss fails closed to 'disabled') but it is
+// a FALSE NEGATIVE: a host that does have the primitive somewhere else loses
+// the sandbox silently. Probing the candidate set removes that failure mode.
+export const CONFINE_BINS_USERSPACE = Object.freeze([
+  '/usr/bin/sandbox-exec',
+  '/usr/local/bin/sandbox-exec',
+]);
+export const CONFINE_BINS_NAMESPACE = Object.freeze([
+  '/usr/bin/unshare',
+  '/bin/unshare',
+  '/usr/local/bin/unshare',
+  '/sbin/unshare',
+  '/usr/sbin/unshare',
+]);
+
+// 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; }
+
+/** First executable candidate, or null when none of them exists. */
+export function resolveConfineBin(candidates) {
+  for (const p of candidates) if (_isExecutable(p)) return p;
+  return null;
+}
+
+export function resolveUserspaceBin() { return resolveConfineBin(CONFINE_BINS_USERSPACE); }
+export function resolveNamespaceBin() { return resolveConfineBin(CONFINE_BINS_NAMESPACE); }
+
+export function detectBackend({ force } = {}) {
+  if (force) return force;
+  if (_cached) return _cached;
+  let b = 'disabled';
+  if (process.platform === 'darwin' && resolveUserspaceBin()) b = 'userspace';
+  else if (process.platform === 'linux' && resolveNamespaceBin()) b = 'namespace';
+  _cached = b;
+  return b;
+}
+
+function _isExecutable(p) {
+  try { fs.accessSync(p, fs.constants.X_OK); return true; } catch { return false; }
+}

package/src/sandbox/index.js

@@ -0,0 +1,30 @@
+// Single entry point for confined execution.
+//
+// Fail-closed by construction: when no confinement primitive is available the
+// disabled backend is selected, which REFUSES to execute. There is deliberately
+// no code path that runs target code unconfined.
+//
+// Result shape (identical for every backend):
+//   { status, denied, stdout, stderr, exitCode, timedOut, backend }
+// status: 'ok' | 'blocked' | 'nonzero' | 'timeout' | 'disabled' | 'error'.
+// See result.js for what 'blocked' vs 'nonzero' mean and, importantly, what
+// `denied:false` does NOT prove. runConfined never throws — a bad root or an
+// invalid limit returns status 'error', because a caller that catches and
+// falls back is a route to unconfined execution.
+import { detectBackend } from './capabilities.js';
+import { runDisabled } from './backend-disabled.js';
+import { runUserspace } from './backend-userspace.js';
+import { runNamespace } from './backend-namespace.js';
+
+export { detectBackend, resetCapabilityCache } from './capabilities.js';
+
+export function sandboxAvailable() {
+  return detectBackend() !== 'disabled';
+}
+
+export function runConfined(argv, opts = {}) {
+  const backend = detectBackend({ force: opts.force });
+  if (backend === 'userspace') return runUserspace(argv, opts);
+  if (backend === 'namespace') return runNamespace(argv, opts);
+  return runDisabled(argv, opts);
+}

package/src/sandbox/limits.js

@@ -0,0 +1,42 @@
+// Resource caps applied as a shell prelude, shared by every real backend.
+//
+// Address-space capping (`ulimit -v`) is NOT enforced on the macOS family —
+// 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.
+export function buildLimitPrelude({
+  maxProcs = 64,
+  maxFileSizeKb = 65536,
+  maxAddressSpaceKb = null,
+} = {}) {
+  const parts = [];
+  const unsupported = [];
+
+  if (maxProcs != null) parts.push(`ulimit -u ${_num('maxProcs', maxProcs)}`);
+  if (maxFileSizeKb != null) parts.push(`ulimit -f ${_num('maxFileSizeKb', maxFileSizeKb)}`);
+
+  if (maxAddressSpaceKb != null) {
+    if (process.platform === 'linux') parts.push(`ulimit -v ${_num('maxAddressSpaceKb', maxAddressSpaceKb)}`);
+    else unsupported.push('maxAddressSpaceKb');
+  }
+
+  const prelude = parts.length ? parts.join('; ') + '; ' : '';
+  return { prelude, unsupported };
+}
+
+/**
+ * Limit values are interpolated into a shell fragment, so a non-numeric value
+ * is shell text. Verified by execution: `maxProcs: '999; echo INJECTED'`
+ * emitted `ulimit -u 999; echo INJECTED` and the payload ran. That is not a
+ * sandbox escape (the prelude runs INSIDE the confinement) but it lets a
+ * config-derived value silently DISABLE the very limits it was meant to set —
+ * e.g. `'0 2>/dev/null; true'` swallows the failure. Coerce and reject
+ * anything that is not a finite, non-negative number.
+ */
+function _num(name, v) {
+  const n = Number(v);
+  if (!Number.isFinite(n) || n < 0) {
+    throw new RangeError(`${name} must be a finite, non-negative number (got ${JSON.stringify(v)})`);
+  }
+  return Math.floor(n);
+}

package/src/sandbox/result.js

@@ -0,0 +1,104 @@
+// Shared result construction for every real backend.
+//
+// WHY THIS EXISTS (the misread it prevents): status used to be derived purely
+// from the exit code — `exitCode !== 0` was reported as `'blocked'`. That
+// conflates two entirely different outcomes:
+//
+//   1. A program that ran fine and chose to exit non-zero (a failing test, a
+//      grep with no match) was labelled 'blocked' — a false confinement claim.
+//   2. A program whose out-of-root write was DENIED but which still exited 0
+//      was labelled 'ok' — the caller saw a clean run and could not tell that
+//      the sandbox had refused something. Verified by execution: the denied
+//      write returns exit 0 when the command swallows the failure.
+//
+// So the two signals are now separated:
+//
+//   - `denied`  — a confinement violation was OBSERVED in the child's error
+//                 output. Best effort, see the honesty note below.
+//   - `status`  — 'blocked' when a denial was observed, 'nonzero' when the
+//                 command merely exited non-zero with no denial signal, 'ok'
+//                 only when it exited 0 with no denial signal.
+//
+// HONESTY NOTE — what `denied:false` does and does not mean. The denial signal
+// is read from the confined process's own stderr (the OS primitives here do
+// not hand the parent a structured violation channel). A program that writes
+// out of root and swallows its own error message produces NO signal, so
+// `denied:false` means "no denial was observed", NOT "no denial occurred".
+// Never treat `status:'ok'` as proof that nothing was refused. It is proof
+// only that the command exited 0 and said nothing about a refusal.
+
+const DENIAL_PATTERNS = [
+  /operation not permitted/i,
+  /permission denied/i,
+  /read-only file system/i,
+  /deny file-write/i,
+  /deny network/i,
+  /network is unreachable/i,
+];
+
+/** True iff the confined process's error output shows an observed denial. */
+export function detectDenial(stderr) {
+  const s = String(stderr || '');
+  return DENIAL_PATTERNS.some((re) => re.test(s));
+}
+
+/**
+ * Build the single result shape every backend returns. `status` is one of
+ * 'ok' | 'blocked' | 'nonzero' | 'timeout' | 'disabled' | 'error'.
+ */
+export function buildResult({ backend, spawnResult, unsupported = [] }) {
+  const r = spawnResult;
+  const rawStderr = r.stderr ?? '';
+  const timedOut = r.error?.code === 'ETIMEDOUT';
+  const denied = detectDenial(rawStderr);
+
+  let status;
+  if (timedOut) status = 'timeout';
+  else if (r.error) status = 'error';
+  else if (denied) status = 'blocked';
+  else if (r.status !== 0) status = 'nonzero';
+  else status = 'ok';
+
+  return {
+    status,
+    denied,
+    stdout: r.stdout ?? '',
+    stderr: rawStderr + (unsupported.length ? `\n[sandbox] limits not enforceable here: ${unsupported.join(', ')}` : ''),
+    exitCode: r.status ?? null,
+    timedOut,
+    backend,
+  };
+}
+
+/** Documented-shape error result: runConfined never throws at its callers. */
+export function errorResult(backend, message) {
+  return {
+    status: 'error',
+    denied: false,
+    stdout: '',
+    stderr: `agentic-security: ${message}`,
+    exitCode: null,
+    timedOut: false,
+    backend,
+  };
+}
+
+/**
+ * Minimal environment handed to untrusted code. The parent environment is NOT
+ * forwarded: it routinely carries credentials (tokens, cloud keys, registry
+ * auth) and the confined program can read and exfiltrate them. This is a
+ * distinct exposure from the accepted "reads are not confined" scope cut —
+ * that one is about files on disk, this one is about secrets the parent hands
+ * over for free. Callers that need extra variables pass them explicitly via
+ * `opts.env`, which is merged on top of this base.
+ */
+export function buildConfinedEnv({ root, env = {} } = {}) {
+  return {
+    PATH: '/usr/bin:/bin:/usr/sbin:/sbin',
+    ROOT: root,
+    HOME: root,
+    TMPDIR: root,
+    LANG: 'C',
+    ...env,
+  };
+}

package/src/sca/dep-confusion.js

@@ -9,7 +9,7 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import * as yaml from 'js-yaml';
+import * as yaml from '../util/yaml.js';
 import { createRequire } from 'node:module';
 
 const _require = createRequire(import.meta.url);