@clear-capabilities/agentic-security-scanner 0.161.0 → 0.162.0

package/src/sandbox/supervise.js

@@ -0,0 +1,201 @@
+// Supervised execution: every process the target starts, and all of its
+// descendants, end when the run ends (CORE-003.AC02).
+//
+// `spawnSync`'s timeout signals only the direct child (see CLAUDE.md, "Timeout
+// does not kill the process tree"). This module is the repair for the backends
+// where it can be proved:
+//
+//   1. The child starts in its own process group and session (`detached`), so
+//      one signal to the negative pid reaches every member that did not move.
+//   2. While it runs, the process table is swept on a short interval and every
+//      descendant seen is remembered, so a member that left the group (for
+//      example via setsid) while its parent was still alive is still killed.
+//   3. Termination is SIGTERM to the group and the tracked set, a grace period,
+//      then SIGKILL, then a poll that CONFIRMS nothing is left. Survivors are
+//      reported, never assumed away.
+//   4. The same cleanup runs on a normal exit, so a backgrounded grandchild
+//      cannot outlive a run that "succeeded".
+//
+// KNOWN GAP (not hidden): a descendant that double-forks and calls setsid
+// between two sweeps, with its parent exiting before the next sweep, is
+// reparented away from the tree and is not found. The sweep interval bounds the
+// window; it does not close it. Only a PID-namespace or cgroup boundary closes
+// it, and neither is available on the macOS backend.
+import { spawn, spawnSync } from 'node:child_process';
+import { detectBackend } from './capabilities.js';
+import { runDisabled } from './backend-disabled.js';
+import { buildUserspaceInvocation } from './backend-userspace.js';
+import { buildResult, errorResult } from './result.js';
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+function alive(pid) {
+  try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+function groupAlive(pgid) {
+  try { process.kill(-pgid, 0); return true; } catch (e) { return e.code === 'EPERM'; }
+}
+function signalPid(pid, sig) { try { process.kill(pid, sig); } catch { /* already gone */ } }
+function signalGroup(pgid, sig) { try { process.kill(-pgid, sig); } catch { /* already gone */ } }
+
+/** Descendants of `rootPid` plus members of its group, from one `ps` snapshot. */
+function snapshotTree(rootPid) {
+  const r = spawnSync('ps', ['-A', '-o', 'pid=,ppid=,pgid='], { encoding: 'utf8', timeout: 2000 });
+  if (r.error || r.status !== 0) return [];
+  const rows = [];
+  for (const line of String(r.stdout).split('\n')) {
+    const m = line.trim().split(/\s+/).map(Number);
+    if (m.length === 3 && m.every(Number.isFinite)) rows.push({ pid: m[0], ppid: m[1], pgid: m[2] });
+  }
+  const kids = new Map();
+  for (const x of rows) { if (!kids.has(x.ppid)) kids.set(x.ppid, []); kids.get(x.ppid).push(x.pid); }
+  const found = new Set();
+  const queue = [rootPid];
+  while (queue.length) {
+    const p = queue.pop();
+    for (const c of kids.get(p) || []) if (!found.has(c)) { found.add(c); queue.push(c); }
+  }
+  for (const x of rows) if (x.pgid === rootPid && x.pid !== process.pid) found.add(x.pid);
+  return [...found];
+}
+
+function _emptyTermination() { return { signalled: null, killedPids: [], survivors: [] }; }
+
+/**
+ * Spawn `bin args` as a supervised process tree.
+ * @returns {Promise<object>} never rejects.
+ */
+export function superviseSpawn(bin, args, {
+  cwd, env, timeoutMs = 10000, graceMs = 1000, signal, maxOutputBytes = 8 * 1024 * 1024, sweepMs = 100,
+} = {}) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(bin, args, { cwd, env, detached: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (e) {
+      resolve({ spawnError: e.message, exitCode: null, stdout: '', stderr: '', timedOut: false, cancelled: false, outputCapped: false, termination: _emptyTermination() });
+      return;
+    }
+    const pgid = child.pid;
+    const tracked = new Set();
+    let stdout = '', stderr = '', outBytes = 0;
+    let timedOut = false, cancelled = false, outputCapped = false, spawnError = null;
+    let exitCode = null, exitSignal = null;
+    let finishing = null;
+    let timer = null;
+
+    const sweep = () => { if (pgid) for (const p of snapshotTree(pgid)) tracked.add(p); };
+    const sweeper = setInterval(sweep, sweepMs);
+
+    const survivors = () => {
+      sweep();
+      return { live: [...tracked].filter(alive), group: groupAlive(pgid) };
+    };
+
+    async function terminate() {
+      const t = _emptyTermination();
+      const before = survivors();
+      if (!before.group && before.live.length === 0) return t;
+      t.signalled = 'SIGTERM';
+      signalGroup(pgid, 'SIGTERM');
+      for (const p of tracked) signalPid(p, 'SIGTERM');
+      const deadline = Date.now() + graceMs;
+      while (Date.now() < deadline) {
+        const s = survivors();
+        if (!s.group && s.live.length === 0) return t;
+        await sleep(25);
+      }
+      // Grace expired: SIGKILL cannot be ignored. Repeat until nothing is left,
+      // because a dying process can fork once more before it is reaped.
+      t.signalled = 'SIGKILL';
+      const hard = Date.now() + 3000;
+      while (Date.now() < hard) {
+        const s = survivors();
+        if (!s.group && s.live.length === 0) break;
+        signalGroup(pgid, 'SIGKILL');
+        for (const p of s.live) { signalPid(p, 'SIGKILL'); if (!t.killedPids.includes(p)) t.killedPids.push(p); }
+        await sleep(25);
+      }
+      const s = survivors();
+      t.survivors = s.live.length ? s.live : (s.group ? [-pgid] : []);
+      return t;
+    }
+
+    function finish() {
+      if (finishing) return finishing;
+      finishing = (async () => {
+        clearInterval(sweeper); clearTimeout(timer);
+        const termination = await terminate();
+        try { child.stdout?.destroy(); child.stderr?.destroy(); } catch { /* ignore */ }
+        resolve({ spawnError, exitCode, exitSignal, stdout, stderr, timedOut, cancelled, outputCapped, termination });
+      })();
+      return finishing;
+    }
+
+    const collect = (which) => (d) => {
+      outBytes += d.length;
+      if (outBytes > maxOutputBytes) {
+        if (!outputCapped) { outputCapped = true; finish(); }
+        return;
+      }
+      if (which === 'out') stdout += d.toString('utf8'); else stderr += d.toString('utf8');
+    };
+    child.stdout.on('data', collect('out'));
+    child.stderr.on('data', collect('err'));
+    child.on('error', (e) => { spawnError = e.message; finish(); });
+    child.on('exit', (code, sig) => {
+      exitCode = code; exitSignal = sig;
+      // Let buffered output drain, then clean up any survivors.
+      setTimeout(finish, 50);
+    });
+    timer = setTimeout(() => { timedOut = true; finish(); }, timeoutMs);
+    if (signal) {
+      if (signal.aborted) { cancelled = true; finish(); }
+      else signal.addEventListener('abort', () => { cancelled = true; finish(); }, { once: true });
+    }
+  });
+}
+
+/**
+ * `runConfined`, plus a guarantee about the process tree. Same result shape as
+ * every backend, with extra `cancelled`, `outputCapped`, `termination` and
+ * `supervised: true`. Never throws.
+ *
+ * Backend coverage, stated plainly:
+ *   userspace  supervised (verified by execution on macOS)
+ *   namespace  REFUSED: tree termination has not been implemented and executed
+ *              on the kernel-namespace backend, so the run does not happen
+ *   disabled   refused, as always
+ */
+export async function runConfinedSupervised(argv, opts = {}) {
+  const backend = detectBackend({ force: opts.force });
+  if (backend === 'disabled') return runDisabled(argv, opts);
+  if (backend !== 'userspace') {
+    return errorResult(backend, `process-tree termination is not implemented or verified on the ${backend} backend; refusing to execute`);
+  }
+  const inv = buildUserspaceInvocation(argv, opts);
+  if (inv.error) return inv.error;
+  const r = await superviseSpawn(inv.bin, inv.args, {
+    cwd: inv.cwd, env: inv.env, timeoutMs: opts.timeoutMs ?? 10000, graceMs: opts.graceMs ?? 1000,
+    signal: opts.signal, maxOutputBytes: opts.maxOutputBytes,
+  });
+  const res = buildResult({
+    backend: 'userspace',
+    spawnResult: {
+      status: r.exitCode,
+      stdout: r.stdout,
+      stderr: r.stderr,
+      error: r.timedOut ? { code: 'ETIMEDOUT' } : r.spawnError ? { code: 'SPAWN', message: r.spawnError } : null,
+    },
+    unsupported: inv.unsupported,
+  });
+  let status = res.status;
+  let stderr = res.stderr;
+  if (r.cancelled) status = 'cancelled';
+  if (r.outputCapped) { status = 'error'; stderr += '\n[sandbox] output cap exceeded; process tree terminated'; }
+  if (r.termination.survivors.length) { status = 'error'; stderr += '\n[sandbox] processes survived termination'; }
+  return {
+    ...res, status, stderr, cancelled: r.cancelled, outputCapped: r.outputCapped,
+    supervised: true, termination: r.termination,
+  };
+}

package/src/sandbox/trust-boundary.js

@@ -0,0 +1,113 @@
+// The execution boundary between target/worker code and the verifier
+// (CORE-003). Every verifier-side execution of untrusted code goes through
+// `runInBoundary`; it is where the trust domains are ENFORCED rather than
+// described.
+//
+// Order of operations, and why each step exists:
+//   1. Refuse secret material in the environment bound for the target.
+//   2. Refuse a workspace that overlaps a protected path (a root that CONTAINS
+//      the key directory would hand the target the keys by construction).
+//   3. Probe the backend's controls actively (cached per process). Any required
+//      control that is not `proved` makes the result `blocked` and NOTHING runs.
+//      Insufficient isolation is never a pass and never a warning.
+//   4. Run supervised, with protected paths read-denied, a scrubbed environment
+//      and a process-tree deadline.
+//   5. Report. The status is formed from what the boundary observed, never from
+//      what the target printed; target output is returned labelled untrusted.
+import fs from 'node:fs';
+import path from 'node:path';
+import { detectBackend } from './capabilities.js';
+import { runConfinedSupervised } from './supervise.js';
+import { probeControls, unmetControls } from './control-probes.js';
+import {
+  protectedReadPaths, assertNoSecretMaterial, classifyRun, countStatusLikeLines,
+} from './trust-domains.js';
+
+export const DEFAULT_REQUIRED_CONTROLS = Object.freeze([
+  'write-confinement', 'read-denial', 'env-scrub', 'tree-termination', 'file-size-limit',
+]);
+
+function _real(p) { try { return fs.realpathSync(p); } catch { return path.resolve(p); } }
+function _overlaps(a, b) {
+  const x = _real(a), y = _real(b);
+  return x === y || x.startsWith(y + path.sep) || y.startsWith(x + path.sep);
+}
+
+function _blocked(reasons, extra = {}) {
+  return {
+    status: 'blocked', blocked: true, executed: false, denied: false, reasons,
+    verificationStatus: 'not-run', targetOutput: null, ...extra,
+  };
+}
+
+/**
+ * @param {string[]} argv
+ * @param {object}   o
+ * @param {string}   o.root          the target's only writable directory
+ * @param {string[]} [o.labelDirs]     sealed-label directories (read-denied)
+ * @param {string[]} [o.evidenceDirs]  authoritative-evidence directories (read-denied, and write-denied by confinement)
+ * @param {string[]} [o.denyReadPaths] further host paths to read-deny
+ * @param {object}   [o.env]           explicit variables for the target; secret-looking ones are refused
+ * @param {string[]} [o.require]       controls that must be `proved`
+ * @param {string}   [o.home]          home directory whose credential dirs are denied
+ * @param {boolean}  [o.allowNetwork]
+ * @param {AbortSignal} [o.signal]     cancel
+ * @param {object}   [o.controlProbes] probe overrides (test seam)
+ */
+export async function runInBoundary(argv, o = {}) {
+  const {
+    root, labelDirs = [], evidenceDirs = [], denyReadPaths = [], env = {},
+    allowNetwork = false, timeoutMs = 10000, graceMs = 1000, signal, force, limits,
+    maxOutputBytes, controlProbes,
+  } = o;
+  const required = [...(o.require || DEFAULT_REQUIRED_CONTROLS)];
+  if (!allowNetwork && !required.includes('network')) required.push('network');
+
+  if (!root || typeof root !== 'string') return _blocked(['no workspace root']);
+  const backend = detectBackend({ force });
+  if (backend === 'disabled') {
+    return _blocked(['no confinement backend works on this host; the target was not executed'], { backend });
+  }
+
+  const secrets = assertNoSecretMaterial(env);
+  if (!secrets.ok) {
+    return _blocked([`secret-looking variables refused for the target: ${secrets.offenders.join(', ')}`], { backend });
+  }
+
+  const protectedPaths = protectedReadPaths({
+    ...(o.home ? { home: o.home } : {}), labelDirs, evidenceDirs, extra: denyReadPaths,
+  });
+  const clash = protectedPaths.filter((p) => _overlaps(root, p));
+  if (clash.length) {
+    return _blocked([`the workspace overlaps protected path(s): ${clash.join(', ')}`], { backend });
+  }
+
+  const report = await probeControls({ force, probes: controlProbes || {} });
+  const unmet = unmetControls(report, required);
+  if (unmet.length) {
+    return _blocked(
+      unmet.map((u) => `control '${u.control}' is ${u.state}: ${u.reason}`),
+      { backend, controls: report.controls },
+    );
+  }
+
+  const r = await runConfinedSupervised(argv, {
+    root, timeoutMs, graceMs, signal, force, allowNetwork, limits, maxOutputBytes,
+    env, denyReadPaths: protectedPaths,
+  });
+  const executed = r.status !== 'disabled' && !(r.status === 'error' && !r.supervised);
+  const run = { ...r, executed };
+  return {
+    status: r.status, blocked: false, executed, denied: r.denied, backend: r.backend,
+    reasons: [], controls: report.controls,
+    verificationStatus: classifyRun(run),
+    // Target output is DATA. It is capped and labelled; it is never parsed for
+    // a status. The count below is informational only.
+    targetOutput: {
+      trust: 'untrusted', stdout: r.stdout, stderr: r.stderr,
+      statusLikeLines: countStatusLikeLines(r.stdout) + countStatusLikeLines(r.stderr),
+    },
+    exitCode: r.exitCode, timedOut: r.timedOut, cancelled: !!r.cancelled,
+    outputCapped: !!r.outputCapped, termination: r.termination,
+  };
+}

package/src/sandbox/trust-domains.js

@@ -0,0 +1,171 @@
+// Trust domains for verification (CORE-003).
+//
+// Four domains stay separate, and this module is the single place that says
+// which one may do what. It is deliberately data plus small pure functions: the
+// ENFORCEMENT lives at the process boundary (`trust-boundary.js`, the sandbox
+// profile, file modes), not here. A table nobody consults at the boundary would
+// be documentation pretending to be a control, so every entry below has an
+// attack test that tries the forbidden action through the real boundary.
+//
+//   target    analyzed code and anything it spawns. Adversarial by assumption.
+//   worker    the model/agent that proposes hypotheses, scenarios and patches.
+//             Adversarial for authority purposes: may be prompt-injected by the
+//             target. Authors proposals, never truth.
+//   verifier  the protected verifier / evaluation custodian. Holds sealed labels,
+//             runs oracles, writes authoritative evidence.
+//   signer    holds signing key material and issues signatures over evidence the
+//             verifier produced. Never executes target or worker code.
+//
+// What a lower-trust domain may NEVER do, whatever it prints or writes:
+//   - read signing keys, the install HMAC key or sealed labels
+//   - write authoritative evidence
+//   - set a verification status (only verifier-observed evidence can)
+//   - read host paths unrelated to its own workspace (credential directories)
+import os from 'node:os';
+import path from 'node:path';
+
+export const DOMAINS = Object.freeze({
+  TARGET: 'target',
+  WORKER: 'worker',
+  VERIFIER: 'verifier',
+  SIGNER: 'signer',
+});
+
+export const RESOURCES = Object.freeze({
+  SIGNING_KEY: 'signing-key',
+  HMAC_KEY: 'hmac-key',
+  SEALED_LABELS: 'sealed-labels',
+  AUTHORITATIVE_EVIDENCE: 'authoritative-evidence',
+  VERIFICATION_STATUS: 'verification-status',
+  HOST_CREDENTIALS: 'host-credentials',
+  WORKSPACE: 'workspace',
+});
+
+// domain -> resource -> allowed actions. Absence means DENIED (default deny).
+const POLICY = Object.freeze({
+  [DOMAINS.TARGET]: { [RESOURCES.WORKSPACE]: ['read', 'write'] },
+  [DOMAINS.WORKER]: { [RESOURCES.WORKSPACE]: ['read', 'write'] },
+  [DOMAINS.VERIFIER]: {
+    [RESOURCES.WORKSPACE]: ['read'],
+    [RESOURCES.SEALED_LABELS]: ['read'],
+    [RESOURCES.AUTHORITATIVE_EVIDENCE]: ['read', 'write'],
+    [RESOURCES.VERIFICATION_STATUS]: ['write'],
+    [RESOURCES.HMAC_KEY]: ['read'],
+  },
+  [DOMAINS.SIGNER]: {
+    [RESOURCES.SIGNING_KEY]: ['read'],
+    [RESOURCES.AUTHORITATIVE_EVIDENCE]: ['read'],
+  },
+});
+
+/** Default-deny policy lookup. */
+export function mayDo(domain, resource, action) {
+  return !!POLICY[domain]?.[resource]?.includes(action);
+}
+
+/** Domains that execute or are influenced by untrusted content. */
+export function isUntrusted(domain) {
+  return domain === DOMAINS.TARGET || domain === DOMAINS.WORKER;
+}
+
+// ---- protected host paths --------------------------------------------------
+
+/** Config directory holding the Ed25519 keys and the install HMAC key. */
+export function keyDirectory(env = process.env) {
+  const xdg = env.XDG_CONFIG_HOME;
+  const base = xdg && xdg.length ? xdg : path.join(os.homedir(), '.config');
+  return path.join(base, 'agentic-security');
+}
+
+// Credential locations under the user's home that no target has a reason to
+// read. A denylist can never be complete, so it is the floor, not the claim:
+// the caller adds sealed-label and evidence directories explicitly.
+const HOME_CREDENTIAL_PATHS = Object.freeze([
+  '.ssh', '.aws', '.gnupg', '.azure', '.kube', '.docker', '.netrc', '.npmrc',
+  '.pypirc', '.git-credentials', '.claude', '.config/gcloud', '.config/gh',
+]);
+
+/**
+ * Every host path a target process must not read. The signing/HMAC key
+ * directory is always included.
+ */
+export function protectedReadPaths({
+  home = os.homedir(), env = process.env, labelDirs = [], evidenceDirs = [], extra = [],
+} = {}) {
+  const out = [keyDirectory(env)];
+  for (const rel of HOME_CREDENTIAL_PATHS) out.push(path.join(home, rel));
+  for (const p of [...labelDirs, ...evidenceDirs, ...extra]) if (p) out.push(path.resolve(p));
+  return [...new Set(out)];
+}
+
+// ---- secret material in worker environments --------------------------------
+
+const SECRET_NAME = /(?:^|_)(?:secret|token|password|passwd|api_?key|private_?key|credential|hmac|signing|auth)(?:_|$)|^(?:AWS_|GITHUB_|NPM_|ANTHROPIC_|OPENAI_)/i;
+const PEM_PRIVATE = /-----BEGIN [A-Z ]*PRIVATE KEY-----/;
+// An explicit allowlist wins over the name heuristic: these carry no secret.
+const SAFE_NAMES = new Set(['PATH', 'HOME', 'TMPDIR', 'LANG', 'ROOT', 'LC_ALL', 'TZ', 'CI']);
+
+/** Names (never values) of environment entries that look like secret material. */
+export function secretEnvNames(env = {}) {
+  const out = [];
+  for (const [k, v] of Object.entries(env || {})) {
+    if (SAFE_NAMES.has(k)) continue;
+    if (SECRET_NAME.test(k) || PEM_PRIVATE.test(String(v ?? ''))) out.push(k);
+  }
+  return out.sort();
+}
+
+/** `{ ok:false, offenders }` when an environment bound for a worker holds secrets. */
+export function assertNoSecretMaterial(env = {}) {
+  const offenders = secretEnvNames(env);
+  return { ok: offenders.length === 0, offenders };
+}
+
+/** Copy of `env` without secret-looking entries. */
+export function scrubEnv(env = {}) {
+  const drop = new Set(secretEnvNames(env));
+  return Object.fromEntries(Object.entries(env || {}).filter(([k]) => !drop.has(k)));
+}
+
+// ---- verification status ---------------------------------------------------
+
+// Mirrors the PRD state model. Only this module decides how a status is formed
+// from a boundary run, and it never reads target output.
+export const VERIFICATION_STATUSES = Object.freeze(
+  ['not-run', 'unsupported', 'inconclusive', 'error', 'refuted', 'confirmed'],
+);
+
+/**
+ * Status from what the BOUNDARY observed (did it run, did it error). A run on
+ * its own can never confirm anything: that takes verifier-observed evidence
+ * (`settleVerification`).
+ */
+export function classifyRun(run) {
+  if (!run || run.executed !== true) return 'not-run';
+  if (run.status === 'error') return 'error';
+  return 'inconclusive';
+}
+
+/**
+ * Settle a verification status. `evidence` must come from verifier-domain code
+ * (`observedBy: 'verifier'`) that examined state the target cannot write (for
+ * example by re-running the oracle outside the target's reach). Target stdout,
+ * stderr and workspace files are NOT evidence. `confirmed` is only reachable
+ * from an executed run plus satisfied verifier evidence; `refuted` needs the
+ * oracle to declare its preconditions held.
+ */
+export function settleVerification(run, evidence) {
+  const base = classifyRun(run);
+  if (base !== 'inconclusive') return base;
+  if (!evidence || evidence.observedBy !== DOMAINS.VERIFIER) return base;
+  if (evidence.satisfied === true) return 'confirmed';
+  if (evidence.satisfied === false && evidence.preconditionsHeld === true) return 'refuted';
+  return base;
+}
+
+const STATUS_LIKE = /\b(?:verified|confirmed|execution-proven|status\s*[:=])\b/i;
+
+/** Count of target-output lines that merely LOOK like a status claim (informational). */
+export function countStatusLikeLines(text) {
+  return String(text || '').split('\n').filter((l) => STATUS_LIKE.test(l)).length;
+}