@clear-capabilities/agentic-security-scanner 0.172.1 → 0.173.0

package/src/posture/assurance/waiver.js

@@ -0,0 +1,200 @@
+// Approvals, waivers and tenant isolation (E7-05).
+//
+// A WAIVER is a decision by named people to leave a finding (or a class of them) open for a stated time, for a stated reason, under a stated policy. Three
+// things make it safe to honour and all three are enforced here, not left to convention:
+//   1. It can never suppress silently. A waiver that is honoured puts the finding in `waived` with the waiver attached; one that is not honoured (expired, for
+//      another tenant or environment, signed under a superseded policy, short of approvers, badly signed) is listed in `refused` with the reason, and the finding
+//      stays open. `summary` counts both, so a gate can fail on an expired waiver instead of a person finding out later.
+//   2. It is bound: to a tenant, an environment, a scope, an expiry and a policy version. None of those can be widened by editing another field.
+//   3. It identifies people by opaque id only. An id that looks like an e-mail address is refused, justification text is scanned for secrets and personal data,
+//      and the audit log records ids and reason codes, never free text.
+//
+// The AUDIT LOG is append-only and hash-chained: each entry commits to the one before it, so removing or editing an entry is detected. Erasure of a tenant's
+// evidence leaves a tombstone entry (who asked, when, which tenant), never the content, and is refused while a legal hold covers the tenant.
+//
+// TENANT ISOLATION. Evidence lives under one directory per tenant. A request names the tenant it acts for and the tenant whose evidence it wants; they must be
+// the same, the names are validated so neither can walk out of the store, symlinks are refused, and every denial is written to the audit log.
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { canonicalJson, keyFingerprint } from '../evidence-bundle.js';
+import { secretCanaryHit, canaryHit } from '../runtime-trace-ingest.js';
+import { isUnderHold } from '../legal-hold.js';
+import { digestOf } from './identity.js';
+import { SCHEMA_VERSION, checkFields, checkHeader, checkString, guardObject, isPlainObject, makeCtx, result } from './schema-kit.js';
+
+const WAIVER_SCHEMA = 'agentic-security/waiver';
+const SCOPE_KINDS = Object.freeze(['finding', 'rule', 'path']);
+const ALLOWED = ['schema', 'schemaVersion', 'id', 'tenant', 'environment', 'scope', 'actor', 'approvals', 'justification', 'compensatingControl', 'createdAt', 'expiresAt', 'policyVersion', 'signature'];
+const REQUIRED = ['schema', 'schemaVersion', 'id', 'tenant', 'environment', 'scope', 'actor', 'approvals', 'justification', 'createdAt', 'expiresAt', 'policyVersion'];
+const ID = /^[a-z0-9][a-z0-9._:-]{1,62}$/i;
+const ACTOR_ID = /^[a-z0-9][a-z0-9._:-]{2,63}$/i;
+const ISO = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d+)?Z$/;
+export const DEFAULT_POLICY = Object.freeze({ version: 1, minPolicyVersion: 1, maxLifetimeDays: 90, requiredApprovals: 1, requireSignature: false, minJustificationChars: 20, requireCompensatingControl: true });
+
+export const waiverId = (w) => `wvr:${digestOf({ tenant: w.tenant, environment: w.environment, scope: w.scope, actor: w.actor && w.actor.id, createdAt: w.createdAt, expiresAt: w.expiresAt, policyVersion: w.policyVersion }).slice(7, 7 + 16)}`;
+
+function actorOk(ctx, p, a) {
+  if (!isPlainObject(a)) { ctx.err('BAD_TYPE', p, 'must be an object {id, role}'); return; }
+  for (const k of Object.keys(a)) if (!['id', 'role'].includes(k)) ctx.err('UNKNOWN_FIELD', `${p}.${k}`, 'only an opaque id and a role are recorded for a person; no name or contact detail');
+  if (typeof a.id !== 'string' || !ACTOR_ID.test(a.id)) ctx.err('BAD_ID', `${p}.id`, 'must be an opaque identifier (letters, digits, . _ : -), 3 to 64 characters');
+  else if (a.id.includes('@')) ctx.err('BAD_ID', `${p}.id`, 'an e-mail address is personal data and is not accepted as an identifier; use an opaque id');
+  checkString(ctx, `${p}.role`, a.role);
+}
+
+/** Closed-world validation of one waiver. Never throws. */
+export function validateWaiver(w, policy = DEFAULT_POLICY) {
+  const g = guardObject(w); const ctx = g.ctx;
+  if (!g.ok) return result(ctx);
+  if (!checkHeader(ctx, w, WAIVER_SCHEMA)) return result(ctx);
+  checkFields(ctx, w, ALLOWED, REQUIRED);
+  for (const k of ['tenant', 'environment']) if (typeof w[k] !== 'string' || !ID.test(w[k])) ctx.err('BAD_ID', k, 'must be a plain identifier (letters, digits, . _ : -)');
+  if (!isPlainObject(w.scope) || !SCOPE_KINDS.includes(w.scope.kind) || typeof w.scope.value !== 'string' || !w.scope.value) ctx.err('BAD_TYPE', 'scope', `must be {kind: ${SCOPE_KINDS.join('|')}, value}`);
+  else if (w.scope.kind === 'path' && (w.scope.value === '**' || w.scope.value === '*')) ctx.err('RULE_VIOLATION', 'scope.value', 'a waiver for every path is not a scoped waiver');
+  actorOk(ctx, 'actor', w.actor);
+  if (!Array.isArray(w.approvals)) ctx.err('BAD_TYPE', 'approvals', 'must be a list');
+  else {
+    const seen = new Set();
+    w.approvals.forEach((a, i) => { actorOk(ctx, `approvals[${i}]`, a); if (a && a.id) { if (a.id === (w.actor && w.actor.id)) ctx.err('RULE_VIOLATION', `approvals[${i}]`, 'a person cannot approve their own waiver'); if (seen.has(a.id)) ctx.err('DUPLICATE_ID', `approvals[${i}]`, 'the same approver twice counts once'); seen.add(a.id); } });
+    if (seen.size < policy.requiredApprovals) ctx.err('RULE_VIOLATION', 'approvals', `${policy.requiredApprovals} distinct approver(s) required, ${seen.size} given`);
+  }
+  if (typeof w.justification !== 'string' || w.justification.trim().length < policy.minJustificationChars) ctx.err('RULE_VIOLATION', 'justification', `a justification of at least ${policy.minJustificationChars} characters is required`);
+  else { const hit = secretCanaryHit(w.justification) || canaryHit(w.justification); if (hit) ctx.err('RULE_VIOLATION', 'justification', `the justification contains something that looks like ${hit.replace(/-/g, ' ')}; waivers are stored and shown, so it is refused`); }
+  if (policy.requireCompensatingControl && (typeof w.compensatingControl !== 'string' || w.compensatingControl.trim().length < 10)) ctx.err('RULE_VIOLATION', 'compensatingControl', 'a compensating control is required: a reason to wait is not one');
+  for (const k of ['createdAt', 'expiresAt']) if (typeof w[k] !== 'string' || !ISO.test(w[k]) || !Number.isFinite(Date.parse(w[k]))) ctx.err('BAD_TYPE', k, 'must be a UTC ISO timestamp');
+  if (ISO.test(w.createdAt || '') && ISO.test(w.expiresAt || '')) {
+    const life = (Date.parse(w.expiresAt) - Date.parse(w.createdAt)) / 86400000;
+    if (life <= 0) ctx.err('RULE_VIOLATION', 'expiresAt', 'must be after createdAt');
+    if (life > policy.maxLifetimeDays) ctx.err('RULE_VIOLATION', 'expiresAt', `a waiver may last at most ${policy.maxLifetimeDays} days`);
+  }
+  if (!Number.isInteger(w.policyVersion) || w.policyVersion < 1) ctx.err('BAD_TYPE', 'policyVersion', 'must be a positive integer');
+  if (w.id && w.id !== waiverId(w)) ctx.err('ID_MISMATCH', 'id', 'the id does not match the waiver it names');
+  return result(ctx);
+}
+
+export function buildWaiver(f) {
+  const w = { schema: WAIVER_SCHEMA, schemaVersion: SCHEMA_VERSION, tenant: f.tenant, environment: f.environment, scope: f.scope, actor: f.actor, approvals: f.approvals || [], justification: f.justification, ...(f.compensatingControl ? { compensatingControl: f.compensatingControl } : {}), createdAt: f.createdAt, expiresAt: f.expiresAt, policyVersion: f.policyVersion };
+  w.id = waiverId(w);
+  return w;
+}
+
+const bytesOf = (w) => Buffer.from(canonicalJson((({ signature, ...rest }) => rest)(w)), 'utf8');
+export function signWaiver(w, privateKeyPem) {
+  const pub = crypto.createPublicKey(privateKeyPem).export({ type: 'spki', format: 'pem' });
+  return { ...w, signature: { algorithm: 'ed25519', keyFingerprint: keyFingerprint(pub), value: crypto.sign(null, bytesOf(w), privateKeyPem).toString('base64') } };
+}
+function signatureState(w, trustedKeys) {
+  if (!w.signature) return 'unsigned';
+  const pem = trustedKeys && trustedKeys[w.signature.keyFingerprint];
+  if (!pem) return 'untrusted-key';
+  try { return crypto.verify(null, bytesOf(w), pem, Buffer.from(w.signature.value, 'base64')) ? 'valid' : 'invalid'; } catch { return 'invalid'; }
+}
+
+// ---- evaluation ----------------------------------------------------------------------------------------------------------------
+
+/**
+ * Can this waiver be honoured here and now?
+ * @param {{now:number, tenant:string, environment:string, policy?:object, trustedKeys?:Object<string,string>}} ctx
+ * @returns {{honoured:boolean, reasons:string[]}} `reasons` are stable codes: invalid, expired, tenant-mismatch, environment-mismatch, policy-version-superseded, unsigned, untrusted-key, bad-signature
+ */
+export function evaluateWaiver(w, ctx) {
+  const policy = { ...DEFAULT_POLICY, ...(ctx.policy || {}) };
+  const reasons = [];
+  // judged against the policy in force NOW: a waiver made under looser rules (a longer lifetime, fewer approvers) stops being honoured when the rules tighten
+  const v = validateWaiver(w, policy);
+  if (!v.ok) return { honoured: false, reasons: ['invalid'], errors: v.errors.map((e) => `${e.path}: ${e.message}`) };
+  if (Date.parse(w.expiresAt) <= ctx.now) reasons.push('expired');
+  if (Date.parse(w.createdAt) > ctx.now) reasons.push('not-yet-valid');
+  if (w.tenant !== ctx.tenant) reasons.push('tenant-mismatch');
+  if (w.environment !== ctx.environment) reasons.push('environment-mismatch');
+  if (w.policyVersion < policy.minPolicyVersion) reasons.push('policy-version-superseded');
+  const sig = signatureState(w, ctx.trustedKeys);
+  if (sig === 'invalid') reasons.push('bad-signature'); else if (sig === 'untrusted-key') reasons.push('untrusted-key'); else if (sig === 'unsigned' && policy.requireSignature) reasons.push('unsigned');
+  return { honoured: reasons.length === 0, reasons };
+}
+
+const globToRe = (g) => new RegExp('^' + g.split('**').map((p) => p.split('*').map((x) => x.replace(/[.+?^${}()|[\]\\]/g, '\\$&')).join('[^/]*')).join('.*') + '$');
+function matches(w, f) {
+  if (w.scope.kind === 'finding') return w.scope.value === f.stableId || w.scope.value === f.id;
+  if (w.scope.kind === 'rule') return w.scope.value === f.vuln || w.scope.value === f.family || w.scope.value === f.cwe || w.scope.value === f.id;
+  return typeof f.file === 'string' && globToRe(w.scope.value).test(f.file);
+}
+
+/**
+ * Apply waivers to findings. A finding is removed from `open` only by a waiver that is honoured; everything else is reported.
+ * @returns {{open:object[], waived:{finding:object, waiverId:string}[], refused:{waiverId:string, findingId:string, reasons:string[]}[], summary:object}}
+ */
+export function applyWaivers(findings, waivers, ctx, auditLog = null) {
+  const open = []; const waived = []; const refused = [];
+  const evals = new Map((waivers || []).map((w) => [w.id, evaluateWaiver(w, ctx)]));
+  for (const f of findings || []) {
+    const cand = (waivers || []).filter((w) => isPlainObject(w) && isPlainObject(w.scope) && typeof w.scope.value === 'string' && matches(w, f));
+    const ok = cand.find((w) => evals.get(w.id).honoured);
+    if (ok) { waived.push({ finding: f, waiverId: ok.id }); if (auditLog) auditLog.append({ event: 'waiver.applied', tenant: ctx.tenant, waiver: ok.id, finding: f.stableId || f.id }); continue; }
+    open.push(f);
+    for (const w of cand) { const e = evals.get(w.id); refused.push({ waiverId: w.id, findingId: f.stableId || f.id, reasons: e.reasons }); if (auditLog) auditLog.append({ event: 'waiver.refused', tenant: ctx.tenant, waiver: w.id, finding: f.stableId || f.id, reasons: e.reasons }); }
+  }
+  const expired = [...new Set(refused.filter((r) => r.reasons.includes('expired')).map((r) => r.waiverId))];
+  const unusedExpired = (waivers || []).filter((w) => evals.get(w.id) && evals.get(w.id).reasons.includes('expired') && !expired.includes(w.id)).map((w) => w.id);
+  return { open, waived, refused, summary: { findings: (findings || []).length, open: open.length, waived: waived.length, refusedMatches: refused.length, expiredWaivers: [...expired, ...unusedExpired].length, reopenedByExpiry: refused.filter((r) => r.reasons.includes('expired')).length } };
+}
+
+// ---- audit log -----------------------------------------------------------------------------------------------------------------
+
+const AUDIT_FIELDS = new Set(['event', 'tenant', 'actor', 'waiver', 'finding', 'reasons', 'target', 'name', 'code']);
+export function createAuditLog({ file = null, now = () => Date.now() } = {}) {
+  const entries = []; let prev = 'sha256:' + '0'.repeat(64);
+  const log = {
+    entries,
+    append(e) {
+      const body = {};
+      for (const [k, v] of Object.entries(e)) {
+        if (!AUDIT_FIELDS.has(k)) throw new Error(`the audit log does not record "${k}": ids and reason codes only`);
+        if (typeof v === 'string' && (canaryHit(v) || secretCanaryHit(v))) throw new Error(`the audit log refuses a value that looks like personal data or a secret (${k})`);
+        body[k] = v;
+      }
+      const entry = { seq: entries.length + 1, at: new Date(now()).toISOString(), ...body, prev };
+      entry.hash = digestOf(entry); prev = entry.hash; entries.push(entry);
+      if (file) fs.appendFileSync(file, JSON.stringify(entry) + '\n');
+      return entry;
+    },
+  };
+  return log;
+}
+
+/** Re-derive the chain. A removed, edited or reordered entry breaks it. @returns {{ok:boolean, brokenAt:number|null}} */
+export function verifyAuditLog(entries) {
+  let prev = 'sha256:' + '0'.repeat(64);
+  for (const [i, e] of (entries || []).entries()) {
+    const { hash, ...rest } = e;
+    if (e.seq !== i + 1 || e.prev !== prev || hash !== digestOf(rest)) return { ok: false, brokenAt: i + 1 };
+    prev = hash;
+  }
+  return { ok: true, brokenAt: null };
+}
+
+// ---- tenant-isolated evidence store -------------------------------------------------------------------------------------------
+
+export class AccessDenied extends Error { constructor(m) { super(m); this.code = 'ACCESS_DENIED'; } }
+const NAME = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+
+export function createTenantStore(root, { auditLog, holds = () => [], now = () => Date.now() } = {}) {
+  const dirOf = (tenant) => { if (typeof tenant !== 'string' || !ID.test(tenant)) throw new AccessDenied('invalid tenant identifier'); return path.join(root, 'tenants', tenant); };
+  const deny = (requester, target, why) => { if (auditLog) auditLog.append({ event: 'access.denied', tenant: typeof requester === 'string' ? requester.slice(0, 64) : 'invalid', target: typeof target === 'string' ? target.slice(0, 64) : 'invalid', code: why }); throw new AccessDenied(`access denied: ${why}`); };
+  const guard = (requester, tenant) => { if (typeof requester !== 'string' || !ID.test(requester)) deny(requester, tenant, 'invalid-requester'); if (requester !== tenant) deny(requester, tenant, 'other-tenant'); };
+  const fileOf = (tenant, name, requester) => { if (typeof name !== 'string' || !NAME.test(name) || name.includes('..')) deny(requester, tenant, 'invalid-name'); return path.join(dirOf(tenant), name); };
+  return {
+    put(requester, tenant, name, bytes) { guard(requester, tenant); const f = fileOf(tenant, name, requester); fs.mkdirSync(dirOf(tenant), { recursive: true }); try { if (fs.lstatSync(f).isSymbolicLink()) deny(requester, tenant, 'symlink'); } catch (e) { if (e instanceof AccessDenied) throw e; } fs.writeFileSync(f, bytes); if (auditLog) auditLog.append({ event: 'evidence.put', tenant, name }); },
+    get(requester, tenant, name) { guard(requester, tenant); const f = fileOf(tenant, name, requester); let st; try { st = fs.lstatSync(f); } catch { return null; } if (st.isSymbolicLink()) deny(requester, tenant, 'symlink'); if (auditLog) auditLog.append({ event: 'evidence.get', tenant, name }); return fs.readFileSync(f); },
+    list(requester, tenant) { guard(requester, tenant); try { return fs.readdirSync(dirOf(tenant)).sort(); } catch { return []; } },
+    /** Erase a tenant's evidence on request. Refused while a legal hold covers the tenant. Leaves a tombstone, not the content. */
+    erase(requester, tenant, { reason } = {}) {
+      guard(requester, tenant);
+      if (isUnderHold(`tenant:${tenant}`, holds(), now())) { if (auditLog) auditLog.append({ event: 'erasure.refused', tenant, code: 'legal-hold' }); return { erased: false, reason: 'legal-hold' }; }
+      let n = 0; try { n = fs.readdirSync(dirOf(tenant)).length; } catch { /* nothing stored */ }
+      fs.rmSync(dirOf(tenant), { recursive: true, force: true });
+      if (auditLog) auditLog.append({ event: 'erasure.done', tenant, code: typeof reason === 'string' && /^[a-z-]{3,32}$/.test(reason) ? reason : 'requested' });
+      return { erased: true, files: n };
+    },
+  };
+}

package/src/posture/compliance-truth.js

@@ -0,0 +1,100 @@
+// The compliance truth model (E7-04): what can honestly be said about each control of a framework, in six states, with the denominators beside them.
+//
+// The framework evaluators (`auditor-walkthrough.js#evaluateFramework` and the privacy one) already refuse to call an unexamined bucket evidence, and the OSCAL
+// export already refuses to invent a verdict for a control nobody decided. This module states the rules once, for any evaluator's rows, so that a report cannot
+// say more than the evidence allows and a reader can see how much of the framework was actually looked at.
+//
+//   assessed_satisfied      every automated signal the control needs ran, cleared, on a complete scan, and the control is one the scanner can decide alone
+//   assessed_not_satisfied  at least one signal found an open problem the finding list attributes to this control. A failure is conclusive even when the rest of
+//                           the scan was incomplete
+//   not_assessed            nothing looked: the control is rated checkable by its publisher but this tool has no check for it, or the evaluator reported a status
+//                           this module does not recognise
+//   not_applicable          someone with the authority declared it so, with a reason; the tool never infers this
+//   requires_human_review   the control needs a person: no automated mapping and not code-testable, or the automated signals cleared but the control also needs
+//                           organisational evidence, or a single scanner signal stands for an obligation wider than one check
+//   insufficient_evidence   signals exist but cannot carry a verdict: the scan was incomplete or examined nothing, a mapping is unverifiable, or the evidence is weak
+//
+// NEVER claimed: that the system complies with the framework. `frameworkClaim.established` is false unless every applicable control is assessed_satisfied, and
+// even then the statement is about the automated signals, not about compliance. One SAST family clearing never satisfies a control the publisher rates only
+// partly or not at all checkable by code.
+export const TRUTH_STATES = Object.freeze(['assessed_satisfied', 'assessed_not_satisfied', 'not_assessed', 'not_applicable', 'requires_human_review', 'insufficient_evidence']);
+
+/**
+ * @param {{control:object, status:string, observations?:string[], controlRefs?:any[], evidence?:{tier?:string}, partiallyEvidenced?:boolean}} row one row of an evaluator
+ * @param {{scanStatus?:string, scanExaminedFiles?:boolean, notApplicable?:Object<string,{reason:string, declaredBy:string}>}} ctx
+ * @returns {{state:string, reasons:string[]}}
+ */
+export function classifyControl(row, ctx = {}) {
+  const c = (row && row.control) || {};
+  const id = c.id;
+  const reasons = [];
+  const na = ctx.notApplicable && id !== undefined ? ctx.notApplicable[id] : null;
+  if (na) {
+    if (!na.reason || !na.declaredBy) return { state: 'insufficient_evidence', reasons: ['a not-applicable declaration needs a reason and a person who declared it; this one has neither, so it is not honoured'] };
+    return { state: 'not_applicable', reasons: [`declared not applicable by ${na.declaredBy}: ${na.reason}`] };
+  }
+  const testable = c.codeTestable;                 // 'yes' | 'partial' | 'no' | undefined
+  const status = row && row.status;
+  const maps = Array.isArray(c.mapsTo) ? c.mapsTo : [];
+  const scanComplete = ctx.scanStatus === 'complete';
+
+  if (status === 'manual') {
+    if (testable === 'yes' || testable === 'partial') return { state: 'not_assessed', reasons: ['the publisher rates this control as checkable by code (at least in part) but this tool implements no check for it: a gap in the tool, not a finding about the system'] };
+    return { state: 'requires_human_review', reasons: ['no automated mapping, and the control is not code-testable: it needs a person'] };
+  }
+  if (!['present', 'partial', 'absent'].includes(status)) return { state: 'not_assessed', reasons: [`the evaluator reported status ${JSON.stringify(status)}, which this model does not recognise, so no verdict is made`] };
+
+  const attributable = Array.isArray(row.controlRefs) && row.controlRefs.length > 0;
+  if (status === 'absent' || (status === 'partial' && attributable)) {
+    return { state: 'assessed_not_satisfied', reasons: [attributable ? `${row.controlRefs.length} open finding(s) are attributed to this control` : 'signals exist for this control and none cleared'] };
+  }
+  if (status === 'partial') return { state: 'insufficient_evidence', reasons: ['no open finding is attributed to this control, but a mapped signal could not be verified, so a clean result is not evidence'] };
+
+  // status === 'present': every mapped signal cleared. What else has to be true before that is a verdict?
+  if (ctx.scanExaminedFiles === false) return { state: 'insufficient_evidence', reasons: ['the scan examined no files, so an empty finding list is not evidence'] };
+  if (!scanComplete) return { state: 'insufficient_evidence', reasons: [`the scan was ${JSON.stringify(ctx.scanStatus ?? 'unknown')}, not complete: a signal that cleared may not have looked everywhere`] };
+  if (row.partiallyEvidenced || (row.evidence && ['weak', 'unmeasured'].includes(row.evidence.tier))) return { state: 'insufficient_evidence', reasons: [`the evidence behind the signals is rated ${JSON.stringify(row.evidence && row.evidence.tier)}`] };
+  if (testable === 'no') return { state: 'requires_human_review', reasons: ['the automated signals cleared, but the publisher rates this control as not code-testable: they cannot decide it'] };
+  if (testable === 'partial') return { state: 'requires_human_review', reasons: ['the automated signals cleared, but the publisher rates this control as only partly code-testable: the rest needs organisational evidence'] };
+  if (maps.length === 1 && testable !== 'yes') return { state: 'requires_human_review', reasons: ['a single scanner signal stands for this obligation and the control is not rated fully code-testable'] };
+  reasons.push(`${Math.max(maps.length, 1)} automated signal(s) cleared on a complete scan, and the control is rated code-testable`);
+  return { state: 'assessed_satisfied', reasons };
+}
+
+/**
+ * Classify every control of a framework and state the denominators.
+ * @returns {{frameworkId:string|null, controls:object[], denominators:object, frameworkClaim:object}}
+ */
+export function assessFrameworkTruth(framework, rows, ctx = {}) {
+  const controls = (rows || []).map((r) => {
+    const t = classifyControl(r, ctx);
+    return { id: r && r.control ? r.control.id : null, title: r && r.control ? (r.control.summary || r.control.title || '') : '', state: t.state, reasons: t.reasons, codeTestable: r && r.control ? r.control.codeTestable ?? null : null, evaluatorStatus: r ? r.status : null, observations: (r && r.observations) || [] };
+  });
+  const by = Object.fromEntries(TRUTH_STATES.map((s) => [s, controls.filter((c) => c.state === s).length]));
+  const total = controls.length;
+  const applicable = total - by.not_applicable;
+  const assessed = by.assessed_satisfied + by.assessed_not_satisfied;
+  const declared = framework && Number.isInteger(framework.controlCount) ? framework.controlCount : null;
+  const denominators = {
+    declaredControls: declared, evaluatedControls: total, unevaluatedControls: declared === null ? null : Math.max(0, declared - total),
+    applicable, byState: by,
+    assessed, assessedOfApplicable: applicable === 0 ? null : Number((assessed / applicable).toFixed(4)),
+    satisfied: by.assessed_satisfied, satisfiedOfApplicable: applicable === 0 ? null : Number((by.assessed_satisfied / applicable).toFixed(4)),
+    needAPersonOrMoreEvidence: by.requires_human_review + by.insufficient_evidence + by.not_assessed,
+  };
+  const everyApplicableSatisfied = applicable > 0 && by.assessed_satisfied === applicable;
+  const frameworkClaim = {
+    established: false,
+    statement: everyApplicableSatisfied
+      ? 'Every applicable control this tool can decide was satisfied by its automated signals. That is a statement about those signals; it is not a statement that the system complies with the framework.'
+      : `This tool assessed ${assessed} of ${applicable} applicable controls from automated signals (${by.assessed_satisfied} satisfied, ${by.assessed_not_satisfied} not satisfied); ${denominators.needAPersonOrMoreEvidence} need a person or more evidence. It does not establish compliance with the framework.`,
+    reasons: [
+      ...(by.assessed_not_satisfied ? [`${by.assessed_not_satisfied} control(s) are not satisfied`] : []),
+      ...(by.requires_human_review ? [`${by.requires_human_review} control(s) require human review`] : []),
+      ...(by.insufficient_evidence ? [`${by.insufficient_evidence} control(s) have insufficient evidence`] : []),
+      ...(by.not_assessed ? [`${by.not_assessed} control(s) were not assessed`] : []),
+      ...(denominators.unevaluatedControls ? [`${denominators.unevaluatedControls} control(s) of the framework were not evaluated at all`] : []),
+    ],
+  };
+  return { frameworkId: framework && framework.id ? framework.id : null, controls, denominators, frameworkClaim };
+}

package/src/posture/evaluation/scan-child.js

@@ -71,7 +71,9 @@ async function main() {
   }));
   const result = { findings };
   if (mode === 'diagnose') result.diagnostics = await diagnosticsOf(scan);
-  process.stdout.write(`${RESULT_BEGIN}${JSON.stringify(result)}${RESULT_END}\n`);
+  // The parent reads this through a pipe. A pipe holds about 64 KB, and `process.exit()` right after a larger write drops what has not been read, so the
+  // parent saw "no result block" for any scan with a big diagnostics payload (62 of 272 forensics re-scans). Wait until the write has been handed over.
+  await new Promise((resolve, reject) => process.stdout.write(`${RESULT_BEGIN}${JSON.stringify(result)}${RESULT_END}\n`, (err) => (err ? reject(err) : resolve())));
 }
 
 // Only when run as a script: runner.js imports the markers and must not start a scan.

package/src/posture/evaluation/why-missed.js

@@ -103,7 +103,9 @@ export function classifyMiss({ label, outcome, diagnostics, policy, layer = 'dee
 
   // ---- a candidate was DROPPED with a recorded reason: filters or suppression
   const dropped = (diagnostics.suppressions || [])
-    .filter((s) => here(s) && inWindow(s.line, win) && sameKind(s, label))
+    // A drop that records neither a family nor a CWE says only that SOMETHING near the defect was dropped. Blaming the miss on it is a coincidence of location
+    // (a too-short secret candidate beside an authorization bug), so it is not a cause; it is counted in the evidence of whatever stage does explain the miss.
+    .filter((s) => here(s) && inWindow(s.line, win) && sameKind(s, label) && sameKind(s, label) !== 'location-only')
     .sort((a, b) => String(a.reason).localeCompare(String(b.reason)) || (a.line ?? 0) - (b.line ?? 0));
   if (dropped.length) {
     const d = dropped[0];

package/src/posture/exploitability-evidence.js

@@ -0,0 +1,141 @@
+// Multi-level exploitability evidence (E5-05).
+//
+// "Is this exploitable?" is several independent questions, each answered from different evidence, and each can be unanswered. Collapsing them into
+// one number hides which are known. This module states them separately:
+//
+//   presentInDependency            the vulnerable code arrives through a dependency
+//   includedInArtifact             that code is in the built artifact that ships
+//   staticallyReachable            the analysis found a path to it
+//   runtimeObserved                a matched-build trace saw the path or the function used
+//   externallyReachable            the path starts at something an outside party can call
+//   proofOfExecution               a proof of concept RAN and showed the effect
+//   blockedByCompensatingControl   a cited control stops it
+//
+// Each is { value, basis, source }. value is one of `yes`, `no`, `unknown`, `not_applicable`, plus two that are deliberately NOT `no`:
+//   not_observed     runtimeObserved only: nothing was seen in the window. Says nothing about whether the code is reachable or safe.
+//   not_demonstrated proofOfExecution only: a proof ran and did not show the effect. A triage signal, not a verdict.
+// `unknown` is a value like any other and is listed in `unknownLevels`. Nothing is inferred from another level.
+//
+// PRIORITIZATION. Context may move a finding's PRIORITY (never its severity, never its existence) under a pre-registered policy:
+//   * the policy is frozen data with a digest over its rules; a policy whose digest does not match is refused and nothing moves
+//   * every rule names the levels it needs and the adjustment it makes, and every adjustment records the evidence it cites
+//   * a rule that LOWERS priority may only rest on positive evidence (`no` for static reachability from an analysis that ran, or `yes` for a cited
+//     control); a rule that lowers on `not_observed`, `unknown` or `not_demonstrated` is invalid and rejected when the policy is validated
+//   * raising rests on `yes` levels
+// The finding is returned with an `exploitabilityEvidence` block added and every other field untouched.
+import { createHash } from 'node:crypto';
+import { proofTierOf } from './proof-tier.js';
+
+export const LEVELS = Object.freeze(['presentInDependency', 'includedInArtifact', 'staticallyReachable', 'runtimeObserved', 'externallyReachable', 'proofOfExecution', 'blockedByCompensatingControl']);
+export const LEVEL_VALUES = Object.freeze(['yes', 'no', 'unknown', 'not_applicable', 'not_observed', 'not_demonstrated']);
+const lv = (value, basis, source) => ({ value, basis, source });
+const UNKNOWN = (basis) => lv('unknown', basis, 'none');
+
+/**
+ * @param {object} finding
+ * @param {{artifact?:{included?:boolean|null, basis?:string}, controlsEvaluated?:boolean}} ctx evidence the caller has that the finding does not carry
+ */
+export function buildEvidenceLevels(finding, ctx = {}) {
+  const f = finding || {};
+  const isDep = f.type === 'vulnerable_dep' || (!!f.package && !!f.reachabilityTier);
+  const levels = {};
+  levels.presentInDependency = isDep ? lv('yes', `finding is a vulnerable dependency (${f.package || 'package'})`, 'sca') : lv('not_applicable', 'the finding is in first-party code', 'finding');
+
+  const art = ctx.artifact;
+  levels.includedInArtifact = art && typeof art.included === 'boolean' ? lv(art.included ? 'yes' : 'no', art.basis || 'artifact analysis', 'artifact') : UNKNOWN('no artifact analysis was supplied');
+
+  const tier = f.reachabilityTier;
+  if (isDep && (tier === 'route-reachable-via-function' || tier === 'function-reachable')) levels.staticallyReachable = lv('yes', `function-level reachability: ${tier}`, 'sca-reachability');
+  else if (isDep && tier === 'unreachable') levels.staticallyReachable = lv('no', 'function-level analysis found no call to the vulnerable function', 'sca-reachability');
+  else if (!isDep && f.unreachable === true) levels.staticallyReachable = lv('no', 'the finding was demoted as unreachable by the reachability pass', 'reachability');
+  else if (!isDep && (f.parser === 'IR-TAINT' || f.routeRooted === true)) levels.staticallyReachable = lv('yes', f.routeRooted ? 'rooted in a route handler' : 'a taint path from a source reaches the sink', 'dataflow');
+  else levels.staticallyReachable = UNKNOWN(isDep ? `reachability tier "${tier || 'unrecorded'}" does not settle it` : 'no path analysis backs this finding');
+
+  const rt = f.runtimeEvidence;
+  if (rt && rt.state === 'observed') levels.runtimeObserved = lv('yes', rt.corroboration === 'corroborated' ? 'observed by a build matched to this snapshot' : 'observed, but the build is not tied to this snapshot', 'runtime');
+  else if (rt && rt.state === 'not_observed_in_window') levels.runtimeObserved = lv('not_observed', 'nothing on the path appeared in the window. This does not mean the code is unreachable or safe', 'runtime');
+  else levels.runtimeObserved = UNKNOWN(rt ? rt.basis || 'the trace cannot say' : 'no runtime trace');
+  if (levels.runtimeObserved.value === 'yes') levels.runtimeObserved.corroboration = rt.corroboration === 'corroborated' ? 'corroborated' : 'unattested';
+
+  if (f.routeRooted === true || (f._inRoute && f._inRoute.path)) levels.externallyReachable = lv('yes', `rooted in a route handler${f._inRoute && f._inRoute.path ? ` (${f._inRoute.path})` : ''}. Whether the route is exposed beyond the service is not verified here`, 'route-rooting');
+  else if (isDep && tier === 'route-reachable-via-function') levels.externallyReachable = lv('yes', 'the vulnerable function is called from a route handler', 'sca-reachability');
+  else levels.externallyReachable = UNKNOWN('no route handler roots this path');
+
+  const pt = proofTierOf(f);
+  levels.proofOfExecution = pt === 'execution-proven' ? lv('yes', 'a proof of concept ran in the sandbox and produced the predicted effect', 'execution-proof')
+    : pt === 'proof-failed' ? lv('not_demonstrated', 'a proof ran and did not show the effect. Absence of proof is not proof of absence', 'execution-proof') : UNKNOWN('no proof of concept has run');
+
+  if (f.sanitized === true) levels.blockedByCompensatingControl = lv('yes', 'a sanitizer applicable to this vulnerability family sits on the path', 'dataflow');
+  else if (f.compensatingControl && typeof f.compensatingControl === 'string') levels.blockedByCompensatingControl = lv('yes', `declared control: ${f.compensatingControl}`, 'suppression');
+  else if (ctx.controlsEvaluated === true) levels.blockedByCompensatingControl = lv('no', 'controls were evaluated and none applies', 'controls');
+  else levels.blockedByCompensatingControl = UNKNOWN('compensating controls were not evaluated');
+
+  return { levels, unknownLevels: LEVELS.filter((k) => levels[k].value === 'unknown') };
+}
+
+// ---- policy ------------------------------------------------------------------------------------------------------------------
+
+const TIERS = Object.freeze(['info', 'low', 'medium', 'high', 'critical']);
+const digestOf = (rules) => createHash('sha256').update(JSON.stringify(rules)).digest('hex');
+const LOWERING_FORBIDS = Object.freeze({ runtimeObserved: ['not_observed', 'unknown'], proofOfExecution: ['not_demonstrated', 'unknown'], staticallyReachable: ['unknown'], blockedByCompensatingControl: ['unknown', 'no'], externallyReachable: ['unknown'], includedInArtifact: ['unknown'] });
+
+/** Freeze a policy and stamp the digest over its rules. */
+export function registerPolicy({ id, version, rules }) {
+  const frozen = Object.freeze({ id, version, rules: Object.freeze(rules.map((r) => Object.freeze({ ...r, when: Object.freeze({ ...r.when }) }))) });
+  return Object.freeze({ ...frozen, digest: digestOf(frozen.rules) });
+}
+
+/** @returns {{ok:boolean, errors:string[]}} */
+export function validatePolicy(policy) {
+  const errors = [];
+  if (!policy || typeof policy !== 'object' || !policy.id || !policy.version || !Array.isArray(policy.rules)) return { ok: false, errors: ['policy needs id, version and rules'] };
+  if (policy.digest !== digestOf(policy.rules)) errors.push('policy digest does not match its rules: the policy was edited after it was registered');
+  for (const r of policy.rules) {
+    if (!r.id || !r.when || typeof r.when !== 'object' || ![-1, 1].includes(r.adjust)) { errors.push(`rule ${r.id || '?'}: needs id, when and adjust of 1 or -1`); continue; }
+    for (const [k, v] of Object.entries(r.when)) {
+      if (!LEVELS.includes(k)) errors.push(`rule ${r.id}: unknown level ${k}`);
+      else if (!LEVEL_VALUES.includes(v)) errors.push(`rule ${r.id}: unknown value ${v}`);
+      else if (r.adjust === -1 && (LOWERING_FORBIDS[k] || []).includes(v)) errors.push(`rule ${r.id}: lowering priority may not rest on ${k}=${v}`);
+    }
+    if (r.adjust === -1 && !Object.entries(r.when).some(([k, v]) => (k === 'staticallyReachable' && v === 'no') || (k === 'blockedByCompensatingControl' && v === 'yes') || (k === 'includedInArtifact' && v === 'no'))) errors.push(`rule ${r.id}: a lowering rule needs positive evidence (staticallyReachable=no, includedInArtifact=no or blockedByCompensatingControl=yes)`);
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/** The default policy: raise on executed proof, or on corroborated runtime evidence of an externally reachable path; lower only on positive evidence. */
+export const DEFAULT_POLICY = registerPolicy({
+  id: 'default-exploitability', version: '1.0.0',
+  rules: [
+    { id: 'raise-execution-proven', when: { proofOfExecution: 'yes' }, adjust: 1 },
+    { id: 'raise-corroborated-runtime-external', when: { runtimeObserved: 'yes', staticallyReachable: 'yes', externallyReachable: 'yes' }, adjust: 1, requireCorroborated: true },
+    { id: 'lower-statically-unreachable', when: { staticallyReachable: 'no' }, adjust: -1 },
+    { id: 'lower-compensating-control', when: { blockedByCompensatingControl: 'yes' }, adjust: -1 },
+    { id: 'lower-not-in-artifact', when: { includedInArtifact: 'no' }, adjust: -1 },
+  ],
+});
+
+/**
+ * Attach the levels and the policy-driven priority. Severity is never changed and the finding is never removed.
+ * @returns {object} a copy of the finding with `exploitabilityEvidence`
+ */
+export function withExploitabilityEvidence(finding, ctx = {}, policy = DEFAULT_POLICY) {
+  const { levels, unknownLevels } = buildEvidenceLevels(finding, ctx);
+  const valid = validatePolicy(policy);
+  const original = TIERS.includes(finding.severity) ? finding.severity : null;
+  const block = { schema: 'agentic-security/exploitability-evidence@1', levels, unknownLevels, priority: { original, adjusted: original, adjustments: [], policy: { id: policy && policy.id, version: policy && policy.version, digest: policy && policy.digest, valid: valid.ok } } };
+  if (!valid.ok) block.priority.refused = valid.errors;
+  else if (original) {
+    let idx = TIERS.indexOf(original);
+    for (const r of policy.rules) {
+      const hit = Object.entries(r.when).every(([k, v]) => levels[k] && levels[k].value === v);
+      if (!hit) continue;
+      if (r.requireCorroborated && levels.runtimeObserved.corroboration !== 'corroborated') continue;
+      const next = Math.max(0, Math.min(TIERS.length - 1, idx + r.adjust));
+      if (next === idx) continue;
+      idx = next;
+      block.priority.adjustments.push({ rule: r.id, direction: r.adjust > 0 ? 'raise' : 'lower', cited: Object.keys(r.when).map((k) => ({ level: k, value: levels[k].value, basis: levels[k].basis, source: levels[k].source })) });
+    }
+    block.priority.adjusted = TIERS[idx];
+  }
+  return { ...finding, exploitabilityEvidence: block };
+}

package/src/posture/fix-verify.js

@@ -186,6 +186,7 @@ export async function verifyFix({
   depFileContents,
   fixMeta,
   testTimeoutMs,
+  runTests,
   recordMetrics = true,
   poc,
   patchNegative,
@@ -203,12 +204,13 @@ export async function verifyFix({
   _lap('rescan');
   const lint = runProjectLinter(scanRoot, Object.keys(files || {}));
   _lap('lint');
-  const tests = runProjectTests(scanRoot, testTimeoutMs != null ? { timeoutMs: testTimeoutMs } : {});
+  // `runTests` lets a caller supply a runner that tests the PATCHED tree (fix/test-commands.js); the default runs the tree as it is on disk.
+  const tests = runTests ? runTests() : runProjectTests(scanRoot, testTimeoutMs != null ? { timeoutMs: testTimeoutMs } : {});
   _lap('tests');
   // True when a candidate patch was supplied but has not been written, so the
   // suite necessarily ran against the pre-patch tree. Surfaced in the summary
   // and on the result so a caller cannot mistake it for a verified patch.
-  const _testedPrePatch = !tests.skipped && _candidateDiffersFromDisk(scanRoot, files);
+  const _testedPrePatch = !runTests && !tests.skipped && _candidateDiffersFromDisk(scanRoot, files);
   const testsOk = tests.skipped ? true : tests.passed === true;
   // R5 — the PoC leg. Re-run the finding's proof-of-concept against the
   // CANDIDATE patch inside R1's sandbox. A patch that still lets the PoC