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

package/src/posture/verification/repair-records.js

@@ -0,0 +1,124 @@
+// Separate records for patch application, rejection and rollback (X-204.AC03).
+//
+// The CORE-002 verification record carries ONE repair status (`none`, `proposed`, `applied`, `replay-verified`,
+// `rolled-back`). That field answers "where is this repair now"; it cannot also be the history, and it has no value for a
+// rejection. So the history is kept here as an append-only ledger of small records, one per event, each with its own id and
+// a link to the record before it. A rollback is therefore a NEW record after an application, not an edit that erases it, and
+// a rejection is a record of its own, not a status that vanishes when the patch is dropped.
+//
+// Rules the ledger enforces, each with a test (the state is per hypothesis and exact diff):
+//   proposed   first event for a diff.
+//   rejected   from proposed or promoted. Needs a reason; carries the incomplete step when verification caused it. Terminal.
+//   promoted   from proposed, and ONLY through `recordPromotion`, which accepts nothing but a result `promotePatch` itself
+//              returned `ok: true` for. The generic append refuses this kind, so a caller cannot write a promotion by hand.
+//   applied    from promoted only: nothing is applied that was not promoted for that exact diff.
+//   rolled-back from applied or promoted (a partial application that was undone). Terminal.
+// `verificationRepairFor` maps the ledger onto the CORE-002 repair field; a rejection has no value there, so the record keeps
+// `proposed` and the ledger holds the rejection (the enum is a foundation contract this change does not widen).
+import { semanticId } from '../assurance/identity.js';
+import { buildVerificationRecord, validateVerificationRecord } from '../assurance/verification-record.js';
+import { isCommit, isDigest, isPlainObject } from '../assurance/schema-kit.js';
+import { isIssuedPromotion } from './patch-promotion.js';
+
+const REPAIR_RECORD_SCHEMA = 'agentic-security/repair-record';
+const REPAIR_RECORD_VERSION = '1.0.0';
+const REPAIR_KINDS = Object.freeze(['proposed', 'rejected', 'promoted', 'applied', 'rolled-back']);
+
+const ID_FIELDS = ['kind', 'hypothesisId', 'revision', 'diffDigest', 'reason', 'step', 'receiptDigests', 'verificationRecordId', 'previous'];
+const TRANSITIONS = Object.freeze({
+  proposed: [null],
+  rejected: ['proposed', 'promoted'],
+  promoted: ['proposed'],
+  applied: ['promoted'],
+  'rolled-back': ['applied', 'promoted'],
+});
+
+function build(fields) {
+  const rec = {
+    schema: REPAIR_RECORD_SCHEMA, schemaVersion: REPAIR_RECORD_VERSION,
+    kind: fields.kind, hypothesisId: fields.hypothesisId, revision: fields.revision ?? null, diffDigest: fields.diffDigest,
+    reason: fields.reason ?? null, step: fields.step ?? null, receiptDigests: fields.receiptDigests ?? null,
+    verificationRecordId: fields.verificationRecordId ?? null, previous: fields.previous ?? null,
+  };
+  rec.id = semanticId('rrec', rec, ID_FIELDS);
+  return Object.freeze(rec);
+}
+
+/** The latest event kind recorded for a hypothesis and exact diff, or null. */
+function stateOf(records, hypothesisId, diffDigest) {
+  for (let i = records.length - 1; i >= 0; i--) {
+    if (records[i].hypothesisId === hypothesisId && records[i].diffDigest === diffDigest) return records[i];
+  }
+  return null;
+}
+
+function check(records, fields) {
+  const errs = [];
+  if (!REPAIR_KINDS.includes(fields.kind)) errs.push(`unknown repair kind '${fields.kind}'`);
+  if (typeof fields.hypothesisId !== 'string' || !fields.hypothesisId) errs.push('hypothesisId is required');
+  if (!isDigest(fields.diffDigest)) errs.push('diffDigest must be sha256:<64 hex>');
+  if (fields.revision !== undefined && fields.revision !== null && !isCommit(fields.revision)) errs.push('revision must be an exact commit or null');
+  if (['rejected', 'rolled-back'].includes(fields.kind) && !(typeof fields.reason === 'string' && fields.reason.trim())) errs.push(`a '${fields.kind}' record needs a reason`);
+  if (errs.length) return errs;
+  const last = stateOf(records, fields.hypothesisId, fields.diffDigest);
+  const from = last ? last.kind : null;
+  if (!TRANSITIONS[fields.kind].includes(from)) errs.push(`'${fields.kind}' cannot follow ${from ? `'${from}'` : 'no earlier record'} for this diff`);
+  return errs;
+}
+
+/**
+ * Append one event. Returns a NEW list (the input is never changed) and the record. `promoted` is refused here: use
+ * `recordPromotion`. Never throws.
+ * @returns {{ ok: boolean, records: object[], record: object|null, errors: string[] }}
+ */
+export function appendRepairRecord(records, fields) {
+  const list = Array.isArray(records) ? records : [];
+  if (!isPlainObject(fields)) return { ok: false, records: list, record: null, errors: ['fields must be an object'] };
+  if (fields.kind === 'promoted') return { ok: false, records: list, record: null, errors: ['a promotion is recorded only through recordPromotion, from a promotePatch result'] };
+  const errors = check(list, fields);
+  if (errors.length) return { ok: false, records: list, record: null, errors };
+  const last = stateOf(list, fields.hypothesisId, fields.diffDigest);
+  const record = build({ ...fields, previous: last ? last.id : null });
+  return { ok: true, records: [...list, record], record, errors: [] };
+}
+
+/** Record a promotion. Accepts only a result `promotePatch` returned with `ok: true`. */
+export function recordPromotion(records, promotion, { verificationRecordId = null } = {}) {
+  const list = Array.isArray(records) ? records : [];
+  if (!isIssuedPromotion(promotion)) return { ok: false, records: list, record: null, errors: ['not a promotion issued by promotePatch'] };
+  const fields = {
+    kind: 'promoted', hypothesisId: promotion.hypothesisId, revision: promotion.revision, diffDigest: promotion.diffDigest,
+    reason: 'independent verifier receipts match the exact proposed diff and revision', receiptDigests: promotion.receiptDigests, verificationRecordId,
+  };
+  const errors = check(list, fields);
+  if (errors.length) return { ok: false, records: list, record: null, errors };
+  const last = stateOf(list, fields.hypothesisId, fields.diffDigest);
+  const record = build({ ...fields, previous: last ? last.id : null });
+  return { ok: true, records: [...list, record], record, errors: [] };
+}
+
+/** The current CORE-002 `repair` object for a diff, derived from the ledger. */
+export function verificationRepairFor(records, hypothesisId, diffDigest, patchedRecordId = null) {
+  const last = stateOf(Array.isArray(records) ? records : [], hypothesisId, diffDigest);
+  if (!last) return { status: 'none' };
+  if (last.kind === 'applied') return { status: 'applied', patchDigest: diffDigest };
+  if (last.kind === 'rolled-back') return { status: 'rolled-back', patchDigest: diffDigest };
+  if (last.kind === 'promoted' && typeof patchedRecordId === 'string' && patchedRecordId.startsWith('vrec:')) {
+    return { status: 'replay-verified', patchDigest: diffDigest, replayRecordId: patchedRecordId };
+  }
+  return { status: 'proposed', patchDigest: diffDigest };
+}
+
+/**
+ * A copy of a verification record with its repair status replaced, rebuilt and re-validated (the id is recomputed, the
+ * confirmation level stays what its evidence supports). Returns null if the result is not a valid record.
+ */
+export function withRepairStatus(record, repair) {
+  if (!isPlainObject(record)) return null;
+  const rebuilt = buildVerificationRecord({
+    hypothesisId: record.hypothesisId, commit: record.commit, detectorOrigin: record.detectorOrigin, oracle: record.oracle,
+    attempt: record.attempt, outcome: record.outcome, reason: record.reason, evidence: record.evidence, evidenceRefs: record.evidenceRefs,
+    scope: record.scope, preconditions: record.preconditions, repair,
+  });
+  return validateVerificationRecord(rebuilt).ok ? rebuilt : null;
+}

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

@@ -4,6 +4,7 @@ import { _isCustomSuppressed } from '../engine.js';
 import { alertFace, approveFace } from './mascot.js';
 import { SCANNER_VERSION } from '../posture/version.js';
 import { proofBlock } from '../posture/proof-artifact.js';
+import { portfolioAssuranceEnabled, scanVerdictWording, NOT_A_GUARANTEE } from '../posture/portfolio/wording.js';
 import { applyLegacyCompat, legacyFieldDeprecationNotice } from '../pipeline/legacy-compat.js';
 // Finding Provenance (M0/M1). NOTE the name: `findingProvenance` is the
 // git-origin record from posture/provenance/. It is NOT `finding.provenance`
@@ -12,6 +13,13 @@ 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';
+import { invariantCoverageFields } from '../posture/invariants/coverage.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';
+// X-307: the one projection of the deployment boundary context. Additive and present only when a finding carries a context.
+import { boundaryFields, boundaryCoverage } from '../lineage/deployment/projection.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 +230,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 +340,16 @@ 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 }) }
+        : {}),
+      // X-307: the deployment boundary context and its projection, ADDITIVE and present only when a producer (the
+      // `deployment-boundaries` feature) attached one. A plain scan output is byte-identical.
+      ...(f.boundaryContext && typeof f.boundaryContext === 'object'
+        ? boundaryFields(f.boundaryContext)
+        : {}),
       // 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 +609,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 +757,15 @@ 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)) } : {}),
+    // X-307: boundary accounting over the findings that carry a context; absent when none does.
+    ...(findings.some(f => f.boundaryContext) ? { boundaryCoverage: boundaryCoverage(findings.map(f => f.boundaryContext).filter(Boolean)) } : {}),
+    // X-407: bounded business-logic coverage, when a caller attached one AND the invariant-scenarios feature is on (off by default).
+    ...invariantCoverageFields(scan.invariantCoverage),
   };
   if (opts.includeSuppressed) out.suppressed = scan.suppressions||[];
   return out;
@@ -903,6 +935,25 @@ 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;
+}
+
+/**
+ * X-307: the human-readable boundary block for a normalized finding, from the SAME projection the JSON and MCP surfaces carry.
+ * Null when the finding has no boundary context. Terminal control characters are stripped.
+ */
+export function boundaryBlock(f) {
+  const text = f?.boundaryView?.text;
+  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 +986,40 @@ 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>');
+    }
+    // X-307: boundary blocks come from the shared projection, never a second renderer.
+    const withBoundary = bySev[sev].filter(f => boundaryBlock(f));
+    if (withBoundary.length) {
+      lines.push('');
+      lines.push('<details><summary>Deployment boundaries</summary>');
+      lines.push('');
+      for (const f of withBoundary) {
+        const block = boundaryBlock(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 +1517,10 @@ 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)}`);
+    const bblock = boundaryBlock(f);
+    if (bblock) for (const ln of bblock) 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 +1532,9 @@ 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]);
+  if (findings.some(f => f.boundaryContext)) lines.push(boundaryCoverage(findings.map(f => f.boundaryContext).filter(Boolean)).lines[0]);
+  { const ic = invariantCoverageFields(scan.invariantCoverage); if (ic.invariantCoverage) lines.push(...ic.invariantCoverage.lines); }
   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');
 }
@@ -1567,7 +1659,14 @@ export function toShipVerdict(scan, options = {}) {
   const clean = actionable.length === 0 && !scanIncomplete;
   lines.push(clean ? approveFace({ color }) : alertFace({ color }));
   lines.push(bar);
-  if (clean) {
+  // X-703.AC03: with the `portfolio-assurance` feature on, the headline is the bounded claim followed by scope and gaps. Off
+  // (the default) the wording below is unchanged, because existing output and documentation pin it.
+  const _bounded = portfolioAssuranceEnabled({ option: options.portfolioAssurance, scanRoot: options.scanRoot });
+  if (_bounded) {
+    const w = scanVerdictWording({ clean, scanIncomplete: !!scanIncomplete, actionableCount: actionable.length });
+    lines.push(c(`  ${w.icon}  ${w.headline}`, w.tier === 'ok' ? SEV_COLOR.low + BOLD : w.tier === 'incomplete' ? SEV_COLOR.high + BOLD : SEV_COLOR.critical + BOLD));
+    lines.push(c(`  Scope: completed supported checks only${scanIncomplete ? '; gaps listed below' : '; no gaps recorded by scan health'}. ${NOT_A_GUARANTEE}`, DIM));
+  } else if (clean) {
     lines.push(c('  ✅  Safe to deploy', SEV_COLOR.low + BOLD));
   } else if (actionable.length === 0) {
     lines.push(c('  ⚠️  Scan incomplete — cannot confirm safe to deploy', SEV_COLOR.high + BOLD));

package/src/sandbox/CLAUDE.md

@@ -347,6 +347,57 @@ 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`.
+
+## Capability mode (X-502, X-504)
+
+`backend-userspace.js` has an opt-in mode used by `capabilities/runner.js`; every pre-existing caller passes none of these options and gets the profile it always had.
+
+- `readRoots` (array): reads are confined to a fixed baseline of system paths (loader, libraries, locale, timezone, device nodes), the sandbox root, the write roots and these roots. File metadata is granted only for the ancestors of those roots, so a path outside them cannot be probed for existence. `denyReadPaths` still apply last.
+- `writeRoots`: further writable subtrees (readable too). `cwd`: working directory, which must exist.
+- `networkProxyPort`: opens exactly one loopback port (`(remote ip "localhost:PORT")`); DNS, every other port and every other address stay denied.
+
+Verified by execution on macOS only (`test/capabilities/`, probes in `capabilities/probes.js`). The namespace backend implements none of these options; asked for them it ignores them, which is why the capability runner never asks it: its probes report these controls `unsupported` there and the run is blocked.
+
 ## 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,192 @@
 // 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 }) {
-  return [
+// Host paths every confined process needs just to start (dynamic loader, system
+// libraries, locale and timezone data, device nodes). Used ONLY when reads are
+// confined; the default profile below still allows reads globally. Metadata
+// (stat) is granted on the ancestors of each readable root and nowhere else, so
+// a path outside the readable set cannot even be probed for existence.
+const BASELINE_READ_SUBPATHS = Object.freeze([
+  '/usr', '/bin', '/sbin', '/System', '/Library/Preferences', '/private/etc', '/dev',
+  '/private/var/db/dyld', '/private/var/db/timezone', '/private/var/select',
+]);
+const BASELINE_META_LITERALS = Object.freeze([
+  '/', '/private', '/private/var', '/private/var/db', '/var', '/etc', '/tmp', '/Library', '/private/tmp',
+]);
+
+function _profile({ allowNetwork, proxyPort = null, denyRead = [], confineReads = false, readRoots = [], writeRoots = [], metaLiterals = [] }) {
+  const lines = [
     '(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');
+  ];
+  if (!confineReads) {
+    lines.push('(allow file-read*)');
+  } else {
+    // Reads are confined to the baseline above, the declared readable roots and
+    // the writable roots. Every path is a parameter or a fixed literal, never
+    // spliced text, so a path cannot inject policy.
+    lines.push(`(allow file-read* (literal "/") ${BASELINE_READ_SUBPATHS.map((p) => `(subpath "${p}")`).join(' ')})`);
+    lines.push(`(allow file-read-metadata ${BASELINE_META_LITERALS.map((p) => `(literal "${p}")`).join(' ')})`);
+    lines.push('(allow file-read* (subpath (param "ROOT")))');
+    readRoots.forEach((_, i) => lines.push(`(allow file-read* (subpath (param "RD${i}")))`));
+    writeRoots.forEach((_, i) => lines.push(`(allow file-read* (subpath (param "WR${i}")))`));
+    metaLiterals.forEach((_, i) => lines.push(`(allow file-read-metadata (literal (param "META${i}")))`));
+    lines.push('(allow file-write* (literal "/dev/null"))');
+  }
+  // Read denial (CORE-003). SBPL is last-match-wins, so these deny rules MUST
+  // come after every read allow.
+  denyRead.forEach((_, i) => lines.push(`(deny file-read* (subpath (param "DENY${i}")))`));
+  lines.push('(allow file-write* (subpath (param "ROOT")))');
+  writeRoots.forEach((_, i) => lines.push(`(allow file-write* (subpath (param "WR${i}")))`));
+  if (allowNetwork) lines.push('(allow network*)');
+  // Mediated network (X-504): the only reachable endpoint is the runner's own
+  // loopback proxy port; everything else, including every other loopback port
+  // and DNS, stays denied by the default rule.
+  else if (Number.isInteger(proxyPort) && proxyPort > 0 && proxyPort < 65536) {
+    lines.push(`(allow network-outbound (remote ip "localhost:${proxyPort}"))`);
+  }
+  return lines.join('\n');
 }
 
-export function runUserspace(argv, {
+function _realOrResolved(p) {
+  let real = path.resolve(p);
+  try { real = fs.realpathSync(real); } catch { /* not present: use the literal path */ }
+  return real;
+}
+
+function _ancestors(p) {
+  const out = [];
+  let cur = path.dirname(p);
+  while (cur && cur !== path.dirname(cur)) { out.push(cur); cur = path.dirname(cur); }
+  return out;
+}
+
+/**
+ * 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 = [],
+  readRoots = null,
+  writeRoots = [],
+  networkProxyPort = null,
+  cwd = null,
 } = {}) {
-  // 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);
+  }
+
+  // Capability mode (X-502/X-504). `readRoots` non-null confines reads to the
+  // baseline plus those roots; `writeRoots` adds writable subtrees beyond
+  // `root`; `networkProxyPort` opens exactly one loopback port. All of them are
+  // absent for every pre-existing caller, whose profile is unchanged.
+  const confineReads = Array.isArray(readRoots);
+  const rd = confineReads ? [...new Set(readRoots.filter((p) => typeof p === 'string' && p).map(_realOrResolved))] : [];
+  const wr = [...new Set((writeRoots || []).filter((p) => typeof p === 'string' && p).map(_realOrResolved))];
+  let resolvedCwd = resolvedRoot;
+  if (cwd) {
+    resolvedCwd = _realOrResolved(cwd);
+    try { if (!fs.statSync(resolvedCwd).isDirectory()) throw new Error('not a directory'); } catch (e) {
+      return { error: errorResult('userspace', `working directory is not usable: ${e.message}`) };
+    }
   }
+  const metaSet = new Set();
+  if (confineReads) {
+    for (const p of [resolvedRoot, resolvedCwd, ...rd, ...wr]) for (const a of _ancestors(p)) metaSet.add(a);
+    for (const b of BASELINE_META_LITERALS) metaSet.delete(b);
+  }
+  const metaLiterals = [...metaSet].sort();
 
   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, proxyPort: networkProxyPort, denyRead, confineReads, readRoots: rd, writeRoots: wr, metaLiterals }),
+      '-D', `ROOT=${resolvedRoot}`,
+      ...denyRead.flatMap((p, i) => ['-D', `DENY${i}=${p}`]),
+      ...rd.flatMap((p, i) => ['-D', `RD${i}=${p}`]),
+      ...wr.flatMap((p, i) => ['-D', `WR${i}=${p}`]),
+      ...metaLiterals.flatMap((p, i) => ['-D', `META${i}=${p}`]),
+      '/bin/sh', '-c', inner, '_sbx', ...argv,
+    ],
+    cwd: resolvedCwd,
+    env: buildConfinedEnv({ root: resolvedRoot, env }),
+    unsupported,
+  };
+}
+
+export function runUserspace(argv, {
+  root,
+  timeoutMs = 10000,
+  allowNetwork = false,
+  limits = {},
+  env = {},
+  maxBuffer = 8 * 1024 * 1024,
+  denyReadPaths = [],
+  readRoots = null,
+  writeRoots = [],
+  networkProxyPort = null,
+  cwd = null,
+} = {}) {
+  // 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, readRoots, writeRoots, networkProxyPort, cwd });
+  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 });
 }