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

package/src/posture/verifier.js

@@ -33,6 +33,7 @@ import * as os from 'node:os';
 import { runConfined, sandboxAvailable } from '../sandbox/index.js';
 import { isExplicitlyNoPoc } from './poc-cwe-map.js';
 import { isSafeStateDir, stateDir, statePath, stateWritesEnabled } from './state-dir.js';
+import { emitVerification } from './verification/emit.js';
 
 // ─── PoC static validation ──────────────────────────────────────────────────
 //
@@ -218,6 +219,21 @@ export function annotateVerifierVerdicts(findings, opts = {}) {
   }
 }
 
+// ─── Verification records (X-201) ───────────────────────────────────────────
+//
+// The version-1 record for each annotated finding. Returned, never written onto the finding: `verifier_verdict` and
+// its siblings stay exactly as they were, and a finding that later lands in last-scan.json is not changed by this.
+// None of the verdicts above ran under the trusted boundary, so none maps to `confirmed` or `refuted`.
+export function verifierVerificationRecords(findings, { commit = null } = {}) {
+  const out = [];
+  for (const f of findings || []) {
+    if (!f || typeof f !== 'object' || !f.verifier_verdict) continue;
+    const e = emitVerification('verifier', f, { finding: f, commit });
+    if (e.ok) out.push(e.record);
+  }
+  return out;
+}
+
 // ─── Summary helpers ────────────────────────────────────────────────────────
 
 export function verifierCoverageSummary(findings) {

package/src/report/index.js

@@ -12,6 +12,10 @@ import { applyLegacyCompat, legacyFieldDeprecationNotice } from '../pipeline/leg
 // (sca/sigstore-verify.js's SLSA/Sigstore build attestation). Three unrelated
 // things, three distinct keys — do not collapse them.
 import { redactFindingProvenance, sanitizeForTerminal } from '../posture/provenance/schema.js';
+// X-206: the one projection of the verification record. This report, the MCP tools and the autopilot response all call it.
+import { verificationFields, verificationCoverage } from '../posture/verification/projection.js';
+// X-207: a hunt hypothesis is advisory and is never a finding in any gating output; promotion is the only way across.
+import { isAdvisoryHypothesis } from '../posture/verification/advisory-state.js';
 // Re-exported: FR-PROV-026. Lives in provenance/schema.js (shared with
 // posture/auditor-walkthrough.js, a second CLI renderer of the same
 // untrusted fields — see that module's header for why it lives there
@@ -222,7 +226,11 @@ export function normalizeFindings(scan){
     });
     return true;
   };
+  const advisoryExcluded = [];
   for (const f of (scan.findings||[])) {
+    // X-207.AC01: an unpromoted hunt hypothesis cannot gate. It is excluded here, the one place every output format and every
+    // exit code derives from, and the exclusion is recorded (never silent) as `advisoryExcluded`.
+    if (isAdvisoryHypothesis(f)) { advisoryExcluded.push({ id: f.id ?? null, stableId: f.stableId ?? null, reason: 'advisory hunt hypothesis: not a finding until promoted by a verifier receipt and policy' }); continue; }
     if (suppress(f.vuln || f.type, f.file, f.line || f.source?.line || 0, f.snippet)) continue;
     out.push({
       id: f.id || fingerprint(f),
@@ -328,6 +336,11 @@ export function normalizeFindings(scan){
       // a finding with no proof backing simply omits these fields.
       ...(f.proofTier !== undefined ? { proofTier: f.proofTier } : {}),
       ...(f.proofEvidence !== undefined ? { proofEvidence: f.proofEvidence } : {}),
+      // X-206: the version-1 verification record and its shared projection, ADDITIVE and present only when the finding carries
+      // a record (a plain scan output is byte-identical). `verificationReplay` is the typed prerequisite list of a replay attempt.
+      ...(f.verificationRecord && typeof f.verificationRecord === 'object'
+        ? { verificationRecord: f.verificationRecord, ...(f.verificationReplay ? { verificationReplay: f.verificationReplay } : {}), ...verificationFields(f.verificationRecord, { replay: f.verificationReplay }) }
+        : {}),
       // 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.
@@ -587,6 +600,7 @@ export function normalizeFindings(scan){
   // all derive from this one function) — one place, covers every output
   // format, matches this function's own role as "the canonical shape".
   for (const f of out) applyLegacyCompat(f);
+  if (advisoryExcluded.length) scan.advisoryExcluded = advisoryExcluded; else delete scan.advisoryExcluded;
 
   // Sort by severity tier, then within a tier by EPSS percentile (desc) so that
   // CVEs with active in-the-wild abuse float above theoretical CVEs.
@@ -734,6 +748,11 @@ export function toJSON(scan, meta={}, opts={}){
     // hand-built `scan` object in a test), same convention as the S7 fields
     // above; a real scan always computes it.
     scanHealth: scan.scanHealth || null,
+    // X-207: advisory hypotheses a caller put in the finding list; excluded from `findings`, listed here so it is never silent.
+    ...(Array.isArray(scan.advisoryExcluded) && scan.advisoryExcluded.length ? { advisoryExcluded: scan.advisoryExcluded } : {}),
+    // X-206: trusted-negative accounting over the findings that carry a verification record. Absent when none does, so a plain
+    // scan's output is unchanged.
+    ...(findings.some(f => f.verificationRecord) ? { verificationCoverage: verificationCoverage(findings.map(f => f.verificationRecord).filter(Boolean)) } : {}),
   };
   if (opts.includeSuppressed) out.suppressed = scan.suppressions||[];
   return out;
@@ -903,6 +922,16 @@ function _mdFenceLen(text) {
   return Math.max(3, ...runs.map(r => r.length + 1));
 }
 
+/**
+ * X-206: the human-readable verification block for a normalized finding, from the SAME projection the JSON and MCP surfaces
+ * carry (`finding.verification.text`). Null when the finding has no verification record. Terminal control characters are stripped.
+ */
+export function verificationBlock(f) {
+  const text = f?.verificationView?.text;
+  // sanitizeForTerminal trims, so the line's own indentation is restored after it strips control characters.
+  return Array.isArray(text) && text.length ? text.map((l) => String(l).match(/^ */)[0] + sanitizeForTerminal(String(l))) : null;
+}
+
 export function toMarkdown(scan, meta={}){
   const findings = normalizeFindings(scan);
   const lines = ['# Agentic Security — Scan Report', ''];
@@ -935,6 +964,23 @@ export function toMarkdown(scan, meta={}){
         lines.push(`| \`${f.file}:${f.line}\` | ${f.vuln} | ${f.cwe||'—'} | ${epss} | ${fix.replace(/\|/g,'\\|').slice(0,140)} |`);
       }
     }
+    // X-206: verification blocks come from the shared projection, never a second renderer.
+    const withVerification = bySev[sev].filter(f => verificationBlock(f));
+    if (withVerification.length) {
+      lines.push('');
+      lines.push('<details><summary>Verification</summary>');
+      lines.push('');
+      for (const f of withVerification) {
+        const block = verificationBlock(f).join('\n');
+        lines.push(`**\`${f.file}:${f.line}\`**: ${f.vuln}`);
+        const fence = '`'.repeat(_mdFenceLen(block));
+        lines.push(fence);
+        lines.push(block);
+        lines.push(fence);
+        lines.push('');
+      }
+      lines.push('</details>');
+    }
     // FR-PROV-018: one provenance block per finding that has one, reusing
     // explainProvenance's content — never a second, divergent renderer.
     const withProvenance = bySev[sev].filter(f => f.findingProvenance);
@@ -1432,6 +1478,8 @@ export function toCLI(scan, { verbose=false, color=true, provenance=false }={}){
     if (ex.how) lines.push(`        ${c('how:', DIM)} ${ex.how}`);
     if (ex.fix) lines.push(`        ${c('fix:', DIM)} ${ex.fix}`);
     if (ex.fixCode) for (const ln of ex.fixCode.split('\n').slice(0, 6)) lines.push(`           ${c(ln, DIM)}`);
+    const vblock = verificationBlock(f);
+    if (vblock) for (const ln of vblock) lines.push(`        ${c(ln, DIM)}`);
     if (provenance) {
       // `f` here is already normalized, so its findingProvenance has been
       // through redactFindingProvenance — the email is gone before it can
@@ -1443,6 +1491,7 @@ export function toCLI(scan, { verbose=false, color=true, provenance=false }={}){
   lines.push('');
   const counts = { critical: 0, high: 0, medium: 0, low: 0, info: 0 };
   for (const f of findings) counts[f.severity] = (counts[f.severity]||0) + 1;
+  if (findings.some(f => f.verificationRecord)) lines.push(verificationCoverage(findings.map(f => f.verificationRecord).filter(Boolean)).lines[0]);
   lines.push(`${c('Critical:', SEV_COLOR.critical)} ${counts.critical}    ${c('High:', SEV_COLOR.high)} ${counts.high}    ${c('Medium:', SEV_COLOR.medium)} ${counts.medium}    ${c('Low:', SEV_COLOR.low)} ${counts.low}    ${c('Info:', SEV_COLOR.info)} ${counts.info}`);
   return lines.join('\n');
 }

package/src/sandbox/CLAUDE.md

@@ -347,6 +347,47 @@ 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.
 
+## Trust boundary (CORE-003)
+
+Four trust domains (target, worker, verifier/custodian, signer) are defined in
+`trust-domains.js` as a default-deny policy plus pure helpers (protected host
+paths, secret-env detection, verification-status formation). The ENFORCEMENT is
+`trust-boundary.js` `runInBoundary()`, the one function verifier-side code uses
+to run untrusted code. It: refuses secret-looking env for the target; refuses a
+workspace overlapping a protected path; probes the backend's controls
+(`control-probes.js`) and returns `status:'blocked'` (target never executed,
+`verificationStatus:'not-run'`) when any required control is not `proved`;
+then runs supervised with protected paths read-denied.
+
+- **Read denial** is the new control `denyReadPaths` (userspace backend: SBPL
+  deny rules after the blanket read allow, paths passed as parameters). The
+  default protected set is the key directory, common credential directories
+  under the home directory, plus caller-supplied sealed-label and evidence
+  directories. A denylist is a floor, not a claim of host-wide read isolation.
+  The namespace backend does NOT implement it and returns `status:'error'`
+  without executing when asked, so on Linux the boundary is `blocked`.
+- **Process trees** (`supervise.js`): own process group, periodic descendant
+  sweep, SIGTERM, grace, SIGKILL, then a poll that confirms no survivors; the
+  same cleanup runs on a clean exit. Cancel is an `AbortSignal` (status
+  `cancelled`). Output is capped. Known gap: a double-fork plus setsid between
+  two sweeps escapes; only a PID namespace or cgroup closes it. Supervised
+  execution exists ONLY for the userspace backend; `namespace` is refused
+  because tree termination has not been implemented and executed there.
+- **Active probes**: write confinement, read denial, env scrub, network, tree
+  termination and the file-size limit each run an attack plus a positive
+  control through the real backend. `process-cap` is reported `unverified` on
+  every backend and must not be claimed enforced (per-uid and system-wide on
+  macOS, and it did not refuse on the hosted Linux runner in the last release).
+  `capabilityReport()` carries the standing note that Linux enforcement is
+  evidenced only where the `sandbox-linux` CI job ran the same probes.
+- **Status**: target output is returned labelled `untrusted` and is never parsed
+  for a status. `classifyRun` can yield at most `inconclusive`; `confirmed`
+  and `refuted` come only from `settleVerification` given evidence with
+  `observedBy: 'verifier'`. Oracle adapters (X-202) must consume this.
+- **Consumer**: the oracle adapters (`posture/oracles/oracle.js`, X-202) run every target through `runInBoundary` and nowhere else, and replay (`posture/replay/replay.js`, X-203) goes through them. A `blocked` boundary is reported by the oracle runner as `unsupported` (an unmet isolation prerequisite), never as a pass or a failure of the hypothesis.
+- Tests: `test/trust-boundary.test.js` (attack fixture, tree kill with `ps`
+  orphan checks, blocked-never-pass), in `test:lifecycle`.
+
 ## Extending this module
 
 - Both real backends (`backend-userspace.js`, `backend-namespace.js`) must

package/src/sandbox/backend-namespace.js

@@ -244,8 +244,15 @@ export function runNamespace(argv, {
   limits = {},
   env = {},
   maxBuffer = 8 * 1024 * 1024,
+  denyReadPaths = [],
 } = {}) {
   // Documented shape, never a throw — see the same note in backend-userspace.
+  // Read denial is NOT implemented on this backend (its mount tree is rebound
+  // read-only, not detached). A caller that asks for it must get a refusal,
+  // never a run that silently leaves the path readable.
+  if (Array.isArray(denyReadPaths) && denyReadPaths.length) {
+    return errorResult('namespace', 'read denial of host paths is not implemented on this backend; refusing to execute');
+  }
   if (!root) return errorResult('namespace', 'runNamespace requires a sandbox root');
 
   const bin = resolveNamespaceBin();

package/src/sandbox/backend-userspace.js

@@ -13,75 +13,114 @@
 // running. Callers that need a hard tree kill must supply it themselves.
 import { spawnSync } from 'node:child_process';
 import fs from 'node:fs';
+import path from 'node:path';
 import { resolveUserspaceBin } from './capabilities.js';
 import { buildLimitPrelude, ambientRelativeMaxProcs } from './limits.js';
 import { buildResult, errorResult, buildConfinedEnv } from './result.js';
 
-function _profile({ allowNetwork }) {
+function _profile({ allowNetwork, denyRead = [] }) {
   return [
     '(version 1)',
     '(deny default)',
     '(allow process-exec process-fork)',
     '(allow sysctl-read)',
     '(allow file-read*)',
+    // Read denial (CORE-003). SBPL is last-match-wins, so these deny rules MUST
+    // come after the blanket read allow. Each path is a parameter, never
+    // spliced into the profile text, so a path cannot inject policy.
+    ...denyRead.map((_, i) => `(deny file-read* (subpath (param "DENY${i}")))`),
     '(allow file-write* (subpath (param "ROOT")))',
     allowNetwork ? '(allow network*)' : '',
   ].filter(Boolean).join('\n');
 }
 
-export function runUserspace(argv, {
+/**
+ * Build the exact spawn invocation for a userspace-confined command, without
+ * running it. Shared by the synchronous runner below and the supervised
+ * (process-tree-killing) runner, so both are confined by the SAME profile.
+ * Returns `{ error }` in the documented error shape instead of throwing.
+ */
+export function buildUserspaceInvocation(argv, {
   root,
-  timeoutMs = 10000,
   allowNetwork = false,
   limits = {},
   env = {},
-  maxBuffer = 8 * 1024 * 1024,
+  denyReadPaths = [],
 } = {}) {
-  // 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');
+  if (!root) return { error: errorResult('userspace', 'runUserspace requires a sandbox root') };
 
   const bin = resolveUserspaceBin();
-  if (!bin) return errorResult('userspace', 'no userspace confinement binary found on this host');
+  if (!bin) return { error: 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}`);
+    return { error: errorResult('userspace', `sandbox root is not usable: ${e.message}`) };
+  }
+
+  // Resolve each denied path as far as it exists (a symlink would otherwise
+  // let the same file be reached by a path the profile does not name). A path
+  // that does not exist yet is denied by its literal text.
+  const denyRead = [];
+  for (const p of denyReadPaths || []) {
+    if (typeof p !== 'string' || !p) continue;
+    let real = path.resolve(p);
+    try { real = fs.realpathSync(real); } catch { /* not present: deny the literal path */ }
+    if (!denyRead.includes(real)) denyRead.push(real);
   }
 
   const effectiveLimits = {
     ...limits,
     maxProcs: limits.maxProcs ?? ambientRelativeMaxProcs(),
   };
-
   let prelude, unsupported;
   try {
     ({ prelude, unsupported } = buildLimitPrelude(effectiveLimits));
   } catch (e) {
-    return errorResult('userspace', `invalid resource limit: ${e.message}`);
+    return { error: errorResult('userspace', `invalid resource limit: ${e.message}`) };
   }
   const inner = `${prelude}exec "$@"`;
 
-  const r = spawnSync(
+  return {
     bin,
-    ['-p', _profile({ allowNetwork }), '-D', `ROOT=${resolvedRoot}`,
-     '/bin/sh', '-c', inner, '_sbx', ...argv],
-    {
-      encoding: 'utf8',
-      timeout: timeoutMs,
-      // Match the namespace backend: SIGKILL cannot be ignored, SIGTERM can.
-      // A payload that installs a SIGTERM handler would otherwise outlive its
-      // own budget while the caller is told it timed out.
-      killSignal: 'SIGKILL',
-      maxBuffer,
-      cwd: resolvedRoot,
-      env: buildConfinedEnv({ root: resolvedRoot, env }),
-    },
-  );
+    args: [
+      '-p', _profile({ allowNetwork, denyRead }),
+      '-D', `ROOT=${resolvedRoot}`,
+      ...denyRead.flatMap((p, i) => ['-D', `DENY${i}=${p}`]),
+      '/bin/sh', '-c', inner, '_sbx', ...argv,
+    ],
+    cwd: resolvedRoot,
+    env: buildConfinedEnv({ root: resolvedRoot, env }),
+    unsupported,
+  };
+}
+
+export function runUserspace(argv, {
+  root,
+  timeoutMs = 10000,
+  allowNetwork = false,
+  limits = {},
+  env = {},
+  maxBuffer = 8 * 1024 * 1024,
+  denyReadPaths = [],
+} = {}) {
+  // Documented shape, never a throw: a caller that wraps this in try/catch and
+  // "falls back" is a classic route to unconfined execution.
+  const inv = buildUserspaceInvocation(argv, { root, allowNetwork, limits, env, denyReadPaths });
+  if (inv.error) return inv.error;
+
+  const r = spawnSync(inv.bin, inv.args, {
+    encoding: 'utf8',
+    timeout: timeoutMs,
+    // Match the namespace backend: SIGKILL cannot be ignored, SIGTERM can.
+    // A payload that installs a SIGTERM handler would otherwise outlive its
+    // own budget while the caller is told it timed out.
+    killSignal: 'SIGKILL',
+    maxBuffer,
+    cwd: inv.cwd,
+    env: inv.env,
+  });
 
-  return buildResult({ backend: 'userspace', spawnResult: r, unsupported });
+  return buildResult({ backend: 'userspace', spawnResult: r, unsupported: inv.unsupported });
 }

package/src/sandbox/control-probes.js

@@ -0,0 +1,215 @@
+// Active probes for every control the boundary relies on (CORE-003.AC02).
+//
+// A control is "proved" only when a probe ATTACKED it through the real
+// backend and the attack observably failed, AND a paired positive control
+// showed the same probe succeeds when the control is off (so a probe that can
+// never succeed cannot pass for a working control). An executable existing, a
+// flag being passed or an earlier run succeeding proves nothing here.
+//
+// States:
+//   proved       attack failed, positive control succeeded, both observed
+//   not-proved   the probe ran and the control did not hold, or the probe could
+//                not establish its own positive control
+//   unsupported  this backend does not implement the control at all
+//   unavailable  no confinement backend works on this host
+//   unverified   deliberately not probed; the reason says why (never a pass)
+//
+// The probes are generic, so on a Linux host they run against the namespace
+// backend for real. Nothing in this file asserts a Linux outcome in advance.
+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 { detectBackend } from './capabilities.js';
+import { runConfined } from './index.js';
+import { runConfinedSupervised } from './supervise.js';
+
+export const CONTROLS = Object.freeze([
+  'write-confinement', 'read-denial', 'env-scrub', 'network',
+  'tree-termination', 'file-size-limit', 'process-cap',
+]);
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+const alive = (pid) => { try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; } };
+const NODE = process.execPath;
+
+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 proved = (evidence) => ({ state: 'proved', evidence });
+const notProved = (reason) => ({ state: 'not-proved', reason });
+
+function probeWrite() {
+  const root = mk('agsec-probe-w-'); const outside = mk('agsec-probe-wo-');
+  try {
+    const good = runConfined(['/bin/sh', '-c', 'echo x > "$ROOT/in.txt"'], { root });
+    const inOk = fs.existsSync(path.join(root, 'in.txt'));
+    runConfined(['/bin/sh', '-c', `echo x > '${outside}/escape.txt'; true`], { root });
+    const escaped = fs.existsSync(path.join(outside, 'escape.txt'));
+    if (!inOk) return notProved(`positive control failed: in-root write did not happen (${good.status})`);
+    if (escaped) return notProved('an out-of-root write succeeded');
+    return proved('in-root write succeeded; out-of-root write created no file');
+  } finally { rm(root); rm(outside); }
+}
+
+function probeReadDenial(backend) {
+  if (backend !== 'userspace') 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');
+    const token = `SEALED-${crypto.randomBytes(8).toString('hex')}`;
+    fs.writeFileSync(secret, token);
+    const cmd = ['/bin/sh', '-c', `cat '${secret}' 2>&1; true`];
+    const open = runConfined(cmd, { root });
+    if (!open.stdout.includes(token)) return notProved('positive control failed: the probe could not read the canary even without denial');
+    const closed = runConfined(cmd, { root, denyReadPaths: [secretDir] });
+    if (closed.stdout.includes(token)) return notProved('a denied path was still readable');
+    return proved('canary readable without denial, unreadable with denyReadPaths');
+  } finally { rm(root); rm(secretDir); }
+}
+
+function probeEnv() {
+  const root = mk('agsec-probe-e-');
+  const name = 'AGSEC_PROBE_PARENT_CANARY';
+  const prev = process.env[name];
+  process.env[name] = 'parent-env-canary-value';
+  try {
+    const r = runConfined(['/usr/bin/env'], { root, env: { AGSEC_PROBE_EXPLICIT: 'explicit-ok' } });
+    if (!r.stdout.includes('AGSEC_PROBE_EXPLICIT=explicit-ok')) return notProved(`positive control failed: explicit env not visible (${r.status})`);
+    if (r.stdout.includes(name) || r.stdout.includes('parent-env-canary-value')) return notProved('the parent environment leaked into the target');
+    return proved('explicit variable visible, parent canary variable absent');
+  } finally {
+    if (prev === undefined) delete process.env[name]; else process.env[name] = prev;
+    rm(root);
+  }
+}
+
+async function probeNetwork() {
+  const root = mk('agsec-probe-n-');
+  let hits = 0;
+  const server = net.createServer((s) => { hits++; 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)`;
+    runConfined([NODE, '-e', script], { root, timeoutMs: 6000, allowNetwork: true });
+    await sleep(200);
+    const open = hits;
+    if (open < 1) return notProved('positive control failed: loopback listener saw no connection with network allowed');
+    runConfined([NODE, '-e', script], { root, timeoutMs: 6000, allowNetwork: false });
+    await sleep(200);
+    if (hits > open) return notProved('a connection reached a loopback listener with network denied');
+    return proved('connection seen with network allowed, none with network denied');
+  } finally { server.close(); rm(root); }
+}
+
+async function probeTree() {
+  const root = mk('agsec-probe-t-');
+  try {
+    // Three tree shapes: a plain background child, a grandchild, and one that
+    // ignores SIGTERM and so needs the SIGKILL escalation.
+    const script = [
+      'sleep 300 & echo $! > "$ROOT/p1"',
+      '(sleep 300 & echo $! > "$ROOT/p2"; wait) &',
+      `(trap '' TERM; sleep 300 & echo $! > "$ROOT/p3"; while :; do sleep 1; done) &`,
+      'wait',
+    ].join('\n');
+    const r = await runConfinedSupervised(['/bin/sh', '-c', script], { root, timeoutMs: 1500, graceMs: 300 });
+    if (r.backend !== 'userspace' || !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; } });
+    if (pids.some((p) => !Number.isFinite(p))) return notProved('positive control failed: the probe tree did not start');
+    await sleep(100);
+    const live = pids.filter(alive);
+    for (const p of live) { try { process.kill(p, 'SIGKILL'); } catch { /* probe cleanup */ } }
+    if (live.length) return notProved(`processes survived the timeout: ${live.join(',')}`);
+    return proved('timeout ended a three-process tree including a SIGTERM-ignoring member');
+  } finally { rm(root); }
+}
+
+function probeFileSize() {
+  const root = mk('agsec-probe-f-');
+  try {
+    const cmd = ['/bin/sh', '-c', 'dd if=/dev/zero of="$ROOT/big" bs=1024 count=400 2>&1; true'];
+    runConfined(cmd, { root, limits: { maxFileSizeKb: 65536 } });
+    const full = fs.existsSync(path.join(root, 'big')) ? fs.statSync(path.join(root, 'big')).size : 0;
+    if (full < 400 * 1024) return notProved('positive control failed: the unrestricted write did not complete');
+    fs.rmSync(path.join(root, 'big'));
+    runConfined(cmd, { root, limits: { maxFileSizeKb: 16 } });
+    const capped = fs.existsSync(path.join(root, 'big')) ? fs.statSync(path.join(root, 'big')).size : 0;
+    if (capped >= 400 * 1024) return notProved('the file size limit did not stop a large write');
+    return proved(`400 KiB write completed unrestricted and stopped at ${capped} bytes under a 16 KiB limit`);
+  } finally { rm(root); }
+}
+
+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',
+};
+
+const _cache = new Map();
+export function resetProbeCache() { _cache.clear(); }
+
+/**
+ * Probe every control on the active backend.
+ * @param {object} [o]
+ * @param {string} [o.force]   backend override (same meaning as runConfined's)
+ * @param {object} [o.probes]  per-control probe overrides (test seam). A probe
+ *                             may only make the report MORE restrictive in
+ *                             practice, since the boundary consults the report
+ *                             before any run; it cannot make a run unconfined.
+ */
+export async function probeControls({ force, probes = {} } = {}) {
+  const backend = detectBackend({ force });
+  const key = `${backend}:${Object.keys(probes).sort().join(',')}`;
+  if (!Object.keys(probes).length && _cache.has(backend)) return _cache.get(backend);
+
+  const controls = {};
+  if (backend === 'disabled') {
+    for (const c of CONTROLS) controls[c] = { state: 'unavailable', reason: 'no confinement backend works on this host' };
+  } else {
+    const run = async (name, fn) => {
+      if (probes[name]) { controls[name] = await probes[name](); return; }
+      try { controls[name] = await fn(); } catch (e) { controls[name] = notProved(`probe threw: ${e.message}`); }
+    };
+    await run('write-confinement', probeWrite);
+    await run('read-denial', () => probeReadDenial(backend));
+    await run('env-scrub', probeEnv);
+    await run('network', probeNetwork);
+    await run('tree-termination', probeTree);
+    await run('file-size-limit', probeFileSize);
+    controls['process-cap'] = probes['process-cap'] ? await probes['process-cap']() : UNPROBED_PROCESS_CAP;
+  }
+  const report = { platform: process.platform, backend, controls };
+  if (!Object.keys(probes).length) _cache.set(backend, report);
+  void key;
+  return report;
+}
+
+/** Controls from `required` that are not proved, with the reason for each. */
+export function unmetControls(report, required) {
+  const out = [];
+  for (const c of required) {
+    const v = report?.controls?.[c];
+    if (!v || v.state !== 'proved') out.push({ control: c, state: v?.state ?? 'not-probed', reason: v?.reason ?? 'no probe result' });
+  }
+  return out;
+}
+
+/**
+ * Human-readable capability matrix. States what each control is on this host
+ * and carries the standing disclosure that Linux enforcement is only evidenced
+ * where the hosted `sandbox-linux` job actually ran.
+ */
+export function capabilityReport(report) {
+  return {
+    ...report,
+    advertisedIsolationBackends: ['userspace (macOS family)', 'namespace (Linux family)'],
+    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.',
+    ],
+  };
+}