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

package/src/posture/evaluation/score.js

@@ -0,0 +1,174 @@
+// End-to-end scoring of an evaluation run (QA-003.AC03).
+//
+// The rule that makes this a measurement and not a flattering one: a known
+// positive that sat behind a timeout, an error, an unavailable tree or a
+// quarantine is a MISS. The end-to-end metrics keep every such case in the
+// denominator. A second set, "conditional on completion", is reported beside
+// them and is labelled as such; it never replaces them.
+//
+// What is NOT scored, and is counted with its reason instead of vanishing:
+//   - targets with no adjudicated label            (unlabeled-target)
+//   - labels that are only candidates / disputed   (label-not-adjudicated)
+//   - findings no adjudicated label accounts for   (no-adjudicated-label), which
+//     go to a review queue: they may be genuine, so they are never auto-FPs.
+//
+// False positives are counted ONLY on adjudicated negatives (patched code, safe
+// real code, near-misses), one per ROOT CAUSE: repeated alerts for the same flaw
+// (`clusterAlerts`) score once and are reported in `alertsCollapsed`; the operational
+// alert burden is report.js's job and is never hidden by this. The score also carries
+// `perTarget` tallies, which is what the grouped bootstrap resamples. Pure: no fs, no clock.
+
+import { SCHEMA_VERSION } from '../assurance/schema-kit.js';
+import { digestOf } from '../assurance/identity.js';
+import { isScoreable, matchFinding, matchNegative, reviewQueue, populationCounts } from './labels.js';
+
+const SCORE_SCHEMA = 'agentic-security/evaluation-score';
+
+const rate = (n, d) => (d > 0 ? n / d : null);
+
+function countsOf(tp, fn, fp, tn) {
+  const precision = rate(tp, tp + fp);
+  const recall = rate(tp, tp + fn);
+  const f1 = tp + fp + fn === 0 ? null : (2 * tp) / (2 * tp + fp + fn);
+  return { tp, fn, fp, tn, precision, recall, f1 };
+}
+
+function bump(map, key, field) {
+  if (!map[key]) map[key] = { tp: 0, fn: 0, fp: 0, tn: 0 };
+  map[key][field]++;
+}
+
+const finalize = (m) => Object.fromEntries(Object.keys(m).sort().map((k) => [k, countsOf(m[k].tp, m[k].fn, m[k].fp, m[k].tn)]));
+
+/** Micro (pooled counts) and macro (mean of per-group F1 over groups where F1 is defined). */
+export function aggregate(byGroup) {
+  const rows = Object.values(byGroup);
+  const sum = rows.reduce((s, r) => ({ tp: s.tp + r.tp, fn: s.fn + r.fn, fp: s.fp + r.fp, tn: s.tn + r.tn }), { tp: 0, fn: 0, fp: 0, tn: 0 });
+  const defined = rows.filter((r) => r.f1 !== null);
+  return { micro: countsOf(sum.tp, sum.fn, sum.fp, sum.tn), macroF1: defined.length ? defined.reduce((s, r) => s + r.f1, 0) / defined.length : null, groups: rows.length };
+}
+
+const findingKey = (f) => `${f.file}|${f.line}|${f.family}|${f.cwe}`;
+
+/**
+ * Collapse repeated alerts to root causes (QA-004.AC02). Findings in the same file and family whose lines chain within
+ * `lineWindow` of one another are one root cause: the same sink reported by two detectors, or a single flaw reported on its
+ * source line and its sink line, is one defect, not several. A finding with no line cannot be placed and stays alone. Returns
+ * clusters in a stable order; each carries every member so the operational alert count is still available.
+ */
+export function clusterAlerts(findings, lineWindow = 3) {
+  const sorted = [...findings].sort((a, b) => String(a.file).localeCompare(String(b.file)) || String(a.family).localeCompare(String(b.family)) || (a.line ?? -1) - (b.line ?? -1));
+  const clusters = [];
+  for (const f of sorted) {
+    const last = clusters[clusters.length - 1];
+    const prev = last && last.members[last.members.length - 1];
+    const joins = prev && prev.file === f.file && prev.family === f.family && Number.isInteger(prev.line) && Number.isInteger(f.line) && f.line - prev.line <= lineWindow;
+    if (joins) last.members.push(f); else clusters.push({ file: f.file, family: f.family, line: f.line, members: [f] });
+  }
+  return clusters;
+}
+
+/**
+ * @param {object} o
+ * @param {object} o.run         a run record (runner.js)
+ * @param {object} o.protocol    the protocol the run is bound to (matching policy comes from it)
+ * @param {object[]} o.defects   defect labels
+ * @param {object[]} o.negatives negative labels
+ */
+export function scoreRun({ run, protocol, defects = [], negatives = [] }) {
+  const policy = protocol.matching;
+  const outcomeOf = new Map(run.outcomes.map((o) => [`${o.targetId}|${o.variant}`, o]));
+  const inRun = new Set(run.outcomes.map((o) => o.targetId));
+
+  const e2e = { lang: {}, family: {} }; const cond = { lang: {}, family: {} };
+  const misses = []; const falsePositives = []; const negativeFailures = []; const matchedFinding = new Set();
+  const unscored = { unlabeledTargets: [], nonAdjudicatedLabels: 0, unlabeledFindings: { count: 0, byReason: {} }, positivesOutsideRun: 0 };
+  const queue = [];
+
+  const labelledTargets = new Set();
+  // Per-target tallies (end to end), so an interval can resample whole targets/groups instead of pretending cases are independent.
+  const perTarget = {};
+  const tally = (targetId, language, field, n = 1) => {
+    if (!perTarget[targetId]) perTarget[targetId] = { language, tp: 0, fn: 0, fp: 0, tn: 0 };
+    perTarget[targetId][field] += n;
+  };
+  const scoreable = (l) => {
+    if (isScoreable(l)) return true;
+    unscored.nonAdjudicatedLabels++;
+    return false;
+  };
+
+  for (const l of defects.filter(scoreable)) {
+    if (!inRun.has(l.targetId)) { unscored.positivesOutsideRun++; continue; }
+    labelledTargets.add(l.targetId);
+    const o = outcomeOf.get(`${l.targetId}|pre`);
+    const completed = o?.status === 'completed';
+    const hit = completed ? o.findings.find((f) => matchFinding(f, l, policy).matched) : null;
+    if (hit) {
+      matchedFinding.add(`${l.targetId}|pre|${findingKey(hit)}`);
+      for (const [m, k] of [[e2e.lang, l.language], [e2e.family, l.family], [cond.lang, l.language], [cond.family, l.family]]) bump(m, k, 'tp');
+      tally(l.targetId, l.language, 'tp');
+    } else {
+      const reason = !o ? 'no-outcome' : completed ? 'not-detected' : o.status;
+      misses.push({ labelId: l.id, targetId: l.targetId, reason, detail: o?.failureReason || null });
+      for (const [m, k] of [[e2e.lang, l.language], [e2e.family, l.family]]) bump(m, k, 'fn');
+      tally(l.targetId, l.language, 'fn');
+      if (completed) for (const [m, k] of [[cond.lang, l.language], [cond.family, l.family]]) bump(m, k, 'fn');
+    }
+  }
+
+  for (const n of negatives.filter(scoreable)) {
+    if (!inRun.has(n.targetId)) continue;
+    labelledTargets.add(n.targetId);
+    const o = outcomeOf.get(`${n.targetId}|${n.variant}`);
+    if (o?.status !== 'completed') {
+      negativeFailures.push({ labelId: n.id, targetId: n.targetId, variant: n.variant, reason: o?.status || 'no-outcome', detail: o?.failureReason || null });
+      continue;
+    }
+    const hits = new Map();
+    for (const f of o.findings) {
+      if (matchNegative(f, n).matched) hits.set(findingKey(f), f);
+      else if ((n.scope.files || []).includes(f.file)) queue.push({ targetId: n.targetId, variant: n.variant, finding: f, reason: 'finding-in-negative-scope-other-family' });
+    }
+    for (const f of hits.values()) matchedFinding.add(`${n.targetId}|${n.variant}|${findingKey(f)}`);
+    if (hits.size) {
+      // One false positive per ROOT CAUSE, not per alert: repeated alerts for the same flaw are reported in `alertsCollapsed` and
+      // in the operational burden, never silently hidden and never multiplied into the precision denominator.
+      const clusters = clusterAlerts([...hits.values()], policy.lineWindow);
+      for (const c of clusters) falsePositives.push({ labelId: n.id, targetId: n.targetId, kind: n.kind, finding: { file: c.members[0].file, line: c.members[0].line, family: c.family }, alertsCollapsed: c.members.length });
+      for (const [m, k] of [[e2e.lang, n.language], [e2e.family, n.family], [cond.lang, n.language], [cond.family, n.family]]) { for (let i = 0; i < clusters.length; i++) bump(m, k, 'fp'); }
+      tally(n.targetId, n.language, 'fp', clusters.length);
+    } else {
+      for (const [m, k] of [[e2e.lang, n.language], [e2e.family, n.family], [cond.lang, n.language], [cond.family, n.family]]) bump(m, k, 'tn');
+      tally(n.targetId, n.language, 'tn');
+    }
+  }
+
+  // Findings no adjudicated label accounts for: unscored, queued for review, never auto-FP.
+  for (const o of run.outcomes) {
+    if (o.status !== 'completed') continue;
+    for (const f of o.findings) {
+      if (matchedFinding.has(`${o.targetId}|${o.variant}|${findingKey(f)}`)) continue;
+      if (queue.some((q) => q.targetId === o.targetId && q.variant === o.variant && q.finding === f)) continue;
+      unscored.unlabeledFindings.count++;
+      unscored.unlabeledFindings.byReason['no-adjudicated-label'] = (unscored.unlabeledFindings.byReason['no-adjudicated-label'] || 0) + 1;
+      queue.push({ targetId: o.targetId, variant: o.variant, finding: f, reason: 'no-adjudicated-label' });
+    }
+  }
+  for (const id of [...inRun].sort()) if (!labelledTargets.has(id)) unscored.unlabeledTargets.push({ targetId: id, reason: 'unlabeled-target' });
+
+  const endToEnd = { byLanguage: finalize(e2e.lang), byFamily: finalize(e2e.family) };
+  const conditional = { byLanguage: finalize(cond.lang), byFamily: finalize(cond.family) };
+  const completed = run.outcomes.filter((o) => o.status === 'completed').length;
+  const score = {
+    schema: SCORE_SCHEMA, schemaVersion: SCHEMA_VERSION, runId: run.runId, protocolHash: run.protocolHash, split: run.split,
+    endToEnd: { ...endToEnd, ...aggregate(endToEnd.byLanguage), label: 'end-to-end: failures on known positives are misses' },
+    conditional: { ...conditional, ...aggregate(conditional.byLanguage), label: 'conditional on completion: additional, never a replacement' },
+    completion: { outcomes: run.outcomes.length, completed, rate: rate(completed, run.outcomes.length), totals: run.totals },
+    misses, falsePositives, negativeFailures, unscored, perTarget,
+    reviewQueue: reviewQueue(queue),
+    population: populationCounts(defects, negatives),
+  };
+  score.scoreHash = digestOf({ ...score, reviewQueue: undefined });
+  return score;
+}

package/src/posture/evaluation/synthetic.js

@@ -0,0 +1,90 @@
+// A SYNTHETIC evaluation suite, for exercising the machinery only.
+//
+// Everything here is authored by the tooling's developers: the code under
+// `test/fixtures/evaluation-synthetic/`, the "reviewers", the commits and the
+// licence. Every protocol and label it produces carries `synthetic: true`, and
+// gates.js refuses to let a synthetic population satisfy any real-code gate. Do
+// not read a score computed from this suite as an accuracy figure for the
+// engine: three tiny files cannot support one.
+
+import * as path from 'node:path';
+import { digestOf } from '../assurance/identity.js';
+import { digestTree, targetDigestOf } from './runner.js';
+import { freezeProtocol, CORE_LANGUAGES, PREREGISTERED_THRESHOLDS, DEFAULT_MATCHING } from './protocol.js';
+import { buildDefectLabel, buildNegativeLabel } from './labels.js';
+
+const SYNTHETIC_LICENSE = 'synthetic-test-fixture';
+const SHA = (c) => c.repeat(40);
+
+const TARGETS = [
+  { id: 'syn-sqli-js', language: 'javascript', upstream: 'example.invalid/synthetic/sqli-js', preCommit: SHA('1'), postCommit: SHA('2'), split: 'dev' },
+  { id: 'syn-cmd-py', language: 'python', upstream: 'example.invalid/synthetic/cmd-py', preCommit: SHA('3'), postCommit: SHA('4'), split: 'dev' },
+  { id: 'syn-nearmiss-js', language: 'javascript', upstream: 'example.invalid/synthetic/nearmiss-js', preCommit: SHA('5'), postCommit: null, split: 'sealed' },
+];
+
+const reviewers = (tag) => [
+  { reviewerId: `synthetic-reviewer-a-${tag}`, verdict: 'confirmed' },
+  { reviewerId: `synthetic-reviewer-b-${tag}`, verdict: 'confirmed' },
+];
+const adjudication = (tag) => ({ status: 'adjudicated', independent: true, reviewers: reviewers(tag) });
+
+/** Directory for one variant of a synthetic target. */
+const syntheticTargetDir = (fixturesDir, id, variant) => path.join(fixturesDir, id, variant);
+
+export function buildSyntheticSuite({ fixturesDir, thresholds = { ...PREREGISTERED_THRESHOLDS }, limits } = {}) {
+  const targets = TARGETS.map((t) => {
+    const pre = digestTree(syntheticTargetDir(fixturesDir, t.id, 'pre'));
+    const post = t.postCommit ? digestTree(syntheticTargetDir(fixturesDir, t.id, 'post')) : null;
+    const { split, ...rest } = t;
+    return { ...rest, pairId: `pair-${t.id}`, advisoryIds: [], license: SYNTHETIC_LICENSE, digest: targetDigestOf({ pre, post }) };
+  });
+  const splits = { dev: TARGETS.filter((t) => t.split === 'dev').map((t) => t.id).sort(), sealed: TARGETS.filter((t) => t.split === 'sealed').map((t) => t.id).sort() };
+  const draft = {
+    synthetic: true,
+    engine: { version: '0.0.0-synthetic', bundleDigest: digestOf('synthetic-engine') },
+    measurement: { commit: SHA('b'), cleanTree: true },
+    tools: { node: 'synthetic' },
+    models: [],
+    datasetLicenses: { [SYNTHETIC_LICENSE]: 'authored for tooling tests; not real-world code' },
+    scope: { languages: [...CORE_LANGUAGES], families: ['sql-injection', 'command-injection'] },
+    matching: { ...DEFAULT_MATCHING },
+    limits: { perTargetTimeoutMs: 120000, spendCeilingUsd: 0, replicates: 3, ...(limits || {}) },
+    thresholds,
+    targets,
+    splits,
+    grouping: { method: 'union-find', keys: ['pair', 'upstream', 'advisory', 'commit', 'template'], salt: 'synthetic' },
+  };
+  const frozen = freezeProtocol(draft);
+
+  const base = (tag) => ({ synthetic: true, adjudication: adjudication(tag), proposedBy: { role: 'worker', id: 'synthetic-proposer' } });
+  const defects = [
+    buildDefectLabel({
+      ...base('d1'), targetId: 'syn-sqli-js', rootCauseId: 'synthetic-root-cause-sqli-js', affected: { commit: SHA('1') },
+      language: 'javascript', family: 'sql-injection', cwe: 'CWE-89', location: { file: 'app.js', startLine: 8, endLine: 8 },
+      evidence: [{ ref: 'synthetic-review-note-sqli', producer: 'human' }],
+    }),
+    buildDefectLabel({
+      ...base('d2'), targetId: 'syn-cmd-py', rootCauseId: 'synthetic-root-cause-cmd-py', affected: { commit: SHA('3') },
+      language: 'python', family: 'command-injection', cwe: 'CWE-78', location: { file: 'tool.py', startLine: 11, endLine: 11 },
+      evidence: [{ ref: 'synthetic-review-note-cmd', producer: 'human' }],
+    }),
+  ];
+  const negatives = [
+    buildNegativeLabel({
+      ...base('n1'), targetId: 'syn-sqli-js', variant: 'post', kind: 'patched', language: 'javascript', family: 'sql-injection',
+      scope: { files: ['app.js'] }, pairedDefectId: defects[0].id, rationale: 'synthetic: parameterised query, reviewed as not injectable',
+    }),
+    buildNegativeLabel({
+      ...base('n2'), targetId: 'syn-cmd-py', variant: 'post', kind: 'patched', language: 'python', family: 'command-injection',
+      scope: { files: ['tool.py'] }, pairedDefectId: defects[1].id, rationale: 'synthetic: argument list and allow-list check, reviewed as not injectable',
+    }),
+    buildNegativeLabel({
+      ...base('n3'), targetId: 'syn-nearmiss-js', variant: 'pre', kind: 'near-miss', language: 'javascript', family: 'sql-injection',
+      scope: { files: ['report.js'] }, rationale: 'synthetic: query assembled from constants only, reviewed as not injectable',
+    }),
+  ];
+  return { protocol: frozen.ok ? frozen.protocol : null, freezeErrors: frozen.errors, draft, defects, negatives, fixturesDir };
+}
+
+/** resolveTarget for the runner over the synthetic fixtures. */
+export const syntheticResolver = (fixturesDir) => (target, variant) => ({ dir: syntheticTargetDir(fixturesDir, target.id, variant) });

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

@@ -0,0 +1,219 @@
+// Why-missed instrumentation across the analysis pipeline (QA-005.AC01, QA-005.AC03).
+//
+// For a labelled DEVELOPMENT miss, name the EARLIEST stage that lost the defect, or say `unknown` and why. The stages, in the
+// order a defect travels through the engine:
+//
+//   scan-execution   the scan never completed (timeout, error, unavailable, quarantined): nothing downstream ran
+//   parser-ir        the file did not lower to an IR function, or the parser failed on it
+//   source-modelling no untrusted source was recognised anywhere the flow could start
+//   propagation      a source and a sink were both recognised near the defect, and no flow joined them
+//   sink-modelling   no sink (or, for non-flow families, no detector rule) was recognised at the defect
+//   filters          a candidate existed and a precision filter (guard recognition, safe-shape, sanitized) dropped it
+//   suppression      a candidate existed and policy dropped it (ignore pragma, custom rule, learned feedback, validator)
+//   deduplication    a candidate existed and was collapsed into a finding that carries a different location
+//   attribution      a finding for this defect was REPORTED, at a location or under a family that does not match the label
+//
+// The order of DETERMINATION differs from the order of travel, deliberately: a candidate observed downstream (a dropped finding,
+// a deduplicated loser, a mislocated report) PROVES every earlier stage worked, so those are checked first and name the stage that
+// lost it. Only when no candidate was observed anywhere do the early stages explain the miss, and among them the first failed
+// stage wins. Sources are checked before sinks, and propagation is blamed only when BOTH endpoints were recognised.
+//
+// Honesty rules: evidence is the engine's own diagnostics (a suppression ledger entry carries file, line, id, cwe and family), not
+// a guess from the label; when there is no diagnostic evidence the answer is `unknown`, never a plausible-sounding stage. The
+// instrument only runs over the DEVELOPMENT split: the sealed split's per-case outcomes are not available to detector work.
+
+import { stageWorkspace, engineEnvironment } from './custody.js';
+import { defaultScanFn } from './runner.js';
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+export const STAGES = Object.freeze(['scan-execution', 'parser-ir', 'source-modelling', 'propagation', 'sink-modelling', 'filters', 'suppression', 'deduplication', 'attribution']);
+export const UNKNOWN = 'unknown';
+
+// Families whose detection is a source-to-sink flow; the rest (weak crypto, hardcoded secrets, misconfiguration) are pattern rules.
+const FLOW_FAMILIES = new Set([
+  'sql-injection', 'nosql-injection', 'command-injection', 'path-traversal', 'xss', 'ssrf', 'deserialization', 'insecure-deserialization',
+  'open-redirect', 'code-injection', 'xxe', 'ldap-injection', 'xpath-injection', 'ssti', 'prototype-pollution', 'response-splitting', 'log-injection',
+]);
+const IR_EXT = /\.(?:js|jsx|mjs|cjs|ts|tsx|py|java|cs|kt|kts|go|php|rb|rs|c|cc|cpp|cxx|h|hpp)$/i;
+
+// A ledger reason names its mechanism by prefix. Filters judge a candidate not to be a real flow; suppressions are policy.
+const FILTER_REASON = /^(?:guard-recognized:|sanitized:|universal-|bench-safe-shape|bench-category|primary-cwe|safe-sink-shape|sanitizer-gate)/;
+const SUPPRESSION_REASON = /^(?:inline[- ]pragma|custom-rule|llm-validator|learned|rules-disable|no-vuln-name)/;
+
+const norm = (p) => String(p || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
+
+function windowOf(label, policy) {
+  const w = Number.isInteger(policy?.lineWindow) ? policy.lineWindow : 3;
+  return { lo: label.location.startLine - w, hi: label.location.endLine + w };
+}
+const inWindow = (line, win) => Number.isInteger(line) && line >= win.lo && line <= win.hi;
+
+function familyOf(entry) { return entry.family ?? null; }
+function sameKind(entry, label) {
+  // A ledger entry or finding agrees with the label by family or CWE. With neither recorded the identity is location-only.
+  if (familyOf(entry) && familyOf(entry) === label.family) return 'family';
+  if (entry.cwe && label.cwe && String(entry.cwe).toUpperCase() === String(label.cwe).toUpperCase()) return 'cwe';
+  if (!familyOf(entry) && !entry.cwe) return 'location-only';
+  return null;
+}
+
+/**
+ * Classify ONE labelled miss.
+ * @param {object} o
+ * @param {object} o.label       an adjudicated defect label
+ * @param {object|null} o.outcome the run outcome for the label's target (variant 'pre')
+ * @param {object|null} o.diagnostics the scan child's diagnostics block for that target, or null
+ * @param {object} [o.policy]    the protocol's matching policy
+ * @param {string} [o.layer]     the configuration that produced the outcome
+ */
+export function classifyMiss({ label, outcome, diagnostics, policy, layer = 'deep-taint' }) {
+  const base = { labelId: label.id, targetId: label.targetId, language: label.language, family: label.family, location: label.location };
+  const done = (stage, reason, evidence = {}) => ({ ...base, stage, reason, evidence, deterministic: true });
+  if (!outcome) return done('scan-execution', 'no-outcome-recorded');
+  if (outcome.status !== 'completed') return done('scan-execution', `scan-${outcome.status}`, { failureReason: outcome.failureReason || null });
+  if (!diagnostics) return done(UNKNOWN, 'no-diagnostic-evidence', { note: 'the target was not re-scanned with diagnostics, so no stage can be named' });
+
+  const win = windowOf(label, policy);
+  const file = norm(label.location.file);
+  const here = (e) => norm(e.file) === file;
+
+  // ---- a candidate was REPORTED but does not match: attribution
+  const reported = (outcome.findings || []).filter(here);
+  let best = null;
+  for (const f of reported) {
+    const kind = sameKind(f, label);
+    if (!kind || kind === 'location-only') continue;
+    const inRange = inWindow(f.line, win);
+    if (inRange) continue; // would have matched; not a miss caused by attribution
+    if (!Number.isInteger(f.line)) { best = best || { f, distance: Infinity, why: 'finding-has-no-line' }; continue; }
+    const distance = f.line < win.lo ? win.lo - f.line : f.line - win.hi;
+    if (!best || distance < best.distance) best = { f, distance, why: 'right-file-and-family-wrong-line' };
+  }
+  if (best) return done('attribution', best.why, { reported: { id: best.f.id ?? null, line: best.f.line ?? null, family: best.f.family ?? null, cwe: best.f.cwe ?? null }, distanceLines: Number.isFinite(best.distance) ? best.distance : null });
+
+  // ---- a candidate was COLLAPSED into a winner elsewhere: deduplication
+  // Only the FINAL winner of a bucket counts: a winner that was itself collapsed into a later one is not where the candidate ended up.
+  const allDedupes = diagnostics.stageEvidence?.dedupe || [];
+  const laterLosers = new Set(allDedupes.map((d) => d.loser?.id).filter(Boolean));
+  const dedupes = allDedupes.filter((d) => !laterLosers.has(d.winner?.id) && norm(d.loser?.file || d.file) === file && inWindow(d.loser?.line, win) && (d.family === label.family || !d.family));
+  const dedupeHit = dedupes.find((d) => !(norm(d.winner?.file) === file && inWindow(d.winner?.line, win)));
+  if (dedupeHit) return done('deduplication', 'collapsed-into-winner-at-other-location', { loser: dedupeHit.loser, winner: dedupeHit.winner });
+
+  // ---- 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))
+    .sort((a, b) => String(a.reason).localeCompare(String(b.reason)) || (a.line ?? 0) - (b.line ?? 0));
+  if (dropped.length) {
+    const d = dropped[0];
+    const stage = SUPPRESSION_REASON.test(d.reason) ? 'suppression' : FILTER_REASON.test(d.reason) ? 'filters' : 'filters';
+    return done(stage, d.reason.split(':').slice(0, 2).join(':'), { ledger: { id: d.id ?? null, line: d.line, family: d.family ?? null, cwe: d.cwe ?? null, reason: d.reason, identity: sameKind(d, label) }, alsoDropped: dropped.length - 1 });
+  }
+
+  // ---- a finding of ANOTHER family sits at the defect's location and no candidate of this family was observed anywhere: it was reported under the wrong family
+  const wrongFamily = reported.find((f) => inWindow(f.line, win) && !sameKind(f, label));
+  if (wrongFamily) return done('attribution', 'right-location-wrong-family', { reported: { id: wrongFamily.id ?? null, line: wrongFamily.line, family: wrongFamily.family ?? null, cwe: wrongFamily.cwe ?? null } });
+
+  // ---- nothing observed anywhere: the early stages explain it
+  const flow = FLOW_FAMILIES.has(label.family) && layer !== 'deterministic-only';
+  if (!flow) {
+    return done('sink-modelling', layer === 'deterministic-only' && FLOW_FAMILIES.has(label.family) ? 'no-pattern-rule-fired-and-taint-layer-not-run' : 'no-detector-rule-fired', { family: label.family });
+  }
+  const ir = diagnostics.ir || {};
+  const entry = ir.files ? ir.files[label.location.file] ?? ir.files[file] : undefined;
+  const ext = (/\.[A-Za-z0-9]+$/.exec(file) || [''])[0].replace('.', '').toLowerCase();
+  if (IR_EXT.test(file)) {
+    if (ir.parseFailures?.byLanguage && ir.parseFailures.byLanguage[ext] > 0) return done('parser-ir', 'ir-parse-failure', { parseFailures: ir.parseFailures.byLanguage[ext], firstError: ir.parseFailures.firstError ?? null });
+    if (entry && (!entry.lowered || (entry.functions || []).length === 0)) return done('parser-ir', 'no-function-lowered', { file: label.location.file });
+  }
+  const sources = (diagnostics.sources || []);
+  const sinks = (diagnostics.sinks || []);
+  const sourcesInFile = sources.filter(here);
+  if (sourcesInFile.length === 0 && sources.length === 0) return done('source-modelling', 'no-source-recognized', { sourcesRecognized: 0 });
+  if (sourcesInFile.length === 0) return done('source-modelling', 'no-source-in-defect-file', { sourcesRecognizedElsewhere: sources.length });
+  const wide = { lo: win.lo - 10, hi: win.hi + 10 };
+  const sinkNear = sinks.some((s) => here(s) && inWindow(s.line, wide));
+  if (!sinkNear) return done('sink-modelling', 'no-sink-recognized-near-defect', { sourcesInFile: sourcesInFile.length });
+  return done('propagation', 'source-and-sink-recognized-no-flow', { sourcesInFile: sourcesInFile.length });
+}
+
+/** Classify every miss in a score. `diagnosticsFor(targetId)` returns that target's diagnostics or null. */
+export function classifyMisses({ score, defects, run, diagnosticsFor, policy, layer }) {
+  const byId = new Map(defects.map((d) => [d.id, d]));
+  const outcomeOf = new Map((run?.outcomes || []).map((o) => [`${o.targetId}|${o.variant}`, o]));
+  const classified = [];
+  for (const miss of score.misses || []) {
+    const label = byId.get(miss.labelId);
+    if (!label) { classified.push({ labelId: miss.labelId, targetId: miss.targetId, stage: UNKNOWN, reason: 'label-not-supplied', evidence: {}, deterministic: true }); continue; }
+    classified.push(classifyMiss({ label, outcome: outcomeOf.get(`${miss.targetId}|pre`) || null, diagnostics: diagnosticsFor ? diagnosticsFor(miss.targetId) : null, policy, layer }));
+  }
+  classified.sort((a, b) => String(a.labelId).localeCompare(String(b.labelId)));
+  return classified;
+}
+
+export function stageCounts(classified) {
+  const byStage = Object.fromEntries([...STAGES, UNKNOWN].map((s) => [s, 0]));
+  const byReason = {};
+  for (const c of classified) {
+    byStage[c.stage] = (byStage[c.stage] || 0) + 1;
+    byReason[`${c.stage}:${c.reason}`] = (byReason[`${c.stage}:${c.reason}`] || 0) + 1;
+  }
+  return { total: classified.length, byStage, byReason };
+}
+
+/**
+ * Before/after view of a fix (QA-005.AC03). Recovered defects are labels that were misses before and are not after; each is
+ * listed with the stage that lost it and the finding that now matches. New false positives are named, never netted away.
+ */
+export function compareMisses({ before, after, scoreBefore, scoreAfter }) {
+  const afterMissed = new Set(after.map((c) => c.labelId));
+  const recovered = before.filter((c) => !afterMissed.has(c.labelId));
+  const fpKey = (x) => `${x.targetId}|${x.finding?.file}|${x.finding?.family}|${x.finding?.line}`;
+  const fpBefore = new Set((scoreBefore.falsePositives || []).map(fpKey));
+  const newFalsePositives = (scoreAfter.falsePositives || []).filter((x) => !fpBefore.has(fpKey(x)));
+  const verdict = recovered.length === 0 ? 'no-recovery' : newFalsePositives.length ? 'recovered-with-new-false-positives' : 'recovered-without-new-false-positives';
+  return {
+    verdict,
+    stageCounts: { before: stageCounts(before), after: stageCounts(after) },
+    recovered: recovered.map((c) => ({ labelId: c.labelId, targetId: c.targetId, lostAtStage: c.stage, reason: c.reason })),
+    falsePositives: { before: (scoreBefore.falsePositives || []).length, after: (scoreAfter.falsePositives || []).length, newFalsePositives },
+    precisionNote: 'a recovery that adds a false positive is reported as such and does not count as a clean improvement',
+  };
+}
+
+/**
+ * Re-scan the DEVELOPMENT targets that have a miss, with diagnostics on, and return `Map(targetId -> diagnostics)`.
+ * The sealed split is refused outright: its per-case outcomes are not material for detector work.
+ */
+export async function collectDiagnostics({ protocol, score, defects, resolveTarget, protectedTerms = [], scanFn = defaultScanFn, layer = 'deep-taint', timeoutMs }) {
+  const sealed = new Set(protocol.splits.sealed);
+  const missTargets = [...new Set((score.misses || []).map((m) => m.targetId))];
+  const refused = missTargets.filter((t) => sealed.has(t));
+  if (refused.length) return { ok: false, errors: [{ code: 'SEALED_ACCESS', path: 'score.misses', message: `why-missed analysis is for development misses; ${refused.length} sealed target(s) refused` }], diagnostics: new Map() };
+  const byTarget = new Map();
+  for (const d of defects) { if (!byTarget.has(d.targetId)) byTarget.set(d.targetId, []); byTarget.get(d.targetId).push(d); }
+  const out = new Map();
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'eval-diag-'));
+  try {
+    for (const targetId of missTargets.sort()) {
+      const target = protocol.targets.find((t) => t.id === targetId);
+      if (!target) continue;
+      const r = await resolveTarget(target, 'pre');
+      if (!r?.dir) continue;
+      const staged = stageWorkspace({ srcDir: r.dir, destDir: path.join(root, targetId.replace(/[^\w.-]/g, '_')), terms: protectedTerms });
+      if (!staged.ok) continue;
+      try {
+        const files = [...new Set((byTarget.get(targetId) || []).map((d) => d.location.file))];
+        const env = engineEnvironment({ PATH: process.env.PATH, LANG: 'C', HOME: root, AGENTIC_SECURITY_DIAG_FILES: JSON.stringify(files) });
+        const res = await scanFn(staged.destDir, { layer, timeoutMs: timeoutMs || protocol.limits.perTargetTimeoutMs, env, diagnose: true });
+        if (res?.diagnostics) out.set(targetId, res.diagnostics);
+      } catch { /* a target that cannot be diagnosed stays `unknown`, which is the honest answer */ } finally {
+        fs.rmSync(staged.destDir, { recursive: true, force: true });
+      }
+    }
+  } finally {
+    fs.rmSync(root, { recursive: true, force: true });
+  }
+  return { ok: true, errors: [], diagnostics: out };
+}

package/src/posture/evidence-bundle.js

@@ -47,6 +47,61 @@ import * as crypto from 'node:crypto';
 
 export const BUNDLE_SCHEMA = 'agentic-security/finding-evidence@1';
 
+// ---- issuer and trust basis (CORE-003.AC03) --------------------------------
+//
+// A signature says WHO signed and nothing about whether anyone independent
+// vouches for them. This install generates its own key, so every bundle it
+// signs is SELF-ISSUED. The `issuance` block says so inside the signed bytes,
+// so a summariser cannot drop it, and the verifier reports it back. The only
+// trust basis this build can verify is the local one; a third-party basis needs
+// a trust-root policy that does not exist here, so an unknown basis is
+// REJECTED rather than being displayed as if it were certification.
+//
+// Backward compatible: `issuance` is absent from bundles signed before this
+// field existed. Those still verify exactly as before and are reported as
+// having NO DECLARED trust basis (not as trusted, not as invalid).
+export const TRUST_BASES = Object.freeze({
+  'self-issued-local-key': Object.freeze({
+    independentlyCertified: false,
+    statement:
+      'Signed by a key this install generated for itself. It proves the bundle is unmodified since ' +
+      'this key signed it. It is NOT independent third-party certification: whoever controls this ' +
+      'install controls the key.',
+  }),
+});
+
+/** SHA-256 of the SPKI DER of a public key: the stable identity of an issuer. */
+export function keyFingerprint(publicKeyPem) {
+  const der = crypto.createPublicKey(publicKeyPem).export({ type: 'spki', format: 'der' });
+  return crypto.createHash('sha256').update(der).digest('hex');
+}
+
+/** Issuance block for a locally generated key. */
+function buildLocalIssuance(publicKeyPem) {
+  const fp = keyFingerprint(publicKeyPem);
+  return {
+    issuer: { id: `local-install:${fp.slice(0, 16)}`, kind: 'local-install', keyFingerprint: fp },
+    trustBasis: 'self-issued-local-key',
+    independentlyCertified: false,
+    statement: TRUST_BASES['self-issued-local-key'].statement,
+  };
+}
+
+/** Group/world access to key material is a defect, reported by path. */
+export function keyPermissionIssues(dir = keyDir()) {
+  const p = keyPaths(dir);
+  const issues = [];
+  try {
+    const d = fs.statSync(dir).mode & 0o077;
+    if (d) issues.push(`${dir} is accessible to group/other (mode ${(fs.statSync(dir).mode & 0o777).toString(8)})`);
+  } catch { /* absent: nothing to report */ }
+  try {
+    const m = fs.statSync(p.privateKey).mode & 0o777;
+    if (m & 0o077) issues.push(`${p.privateKey} is accessible to group/other (mode ${m.toString(8)})`);
+  } catch { /* absent */ }
+  return issues;
+}
+
 /** Where the Ed25519 signing key lives. Mirrors integrity.js's key handling. */
 function keyDir() {
   const xdg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config');
@@ -142,6 +197,9 @@ export function canonicalBytes(bundle) {
     engine: bundle.engine,
     proves: bundle.proves,
     doesNotProve: bundle.doesNotProve,
+    // Only when present, so the canonical bytes (and signatures) of every
+    // bundle signed before this field existed are unchanged.
+    ...(bundle.issuance !== undefined ? { issuance: bundle.issuance } : {}),
   };
   return Buffer.from(canonicalJson(signed), 'utf8');
 }
@@ -226,11 +284,17 @@ export function buildEvidenceBundle(finding, { engineVersion, rulesetVersion, bu
   };
 }
 
-/** Sign a bundle. Returns a new object; the input is not mutated. */
+/**
+ * Sign a bundle. Returns a new object; the input is not mutated. The issuer and
+ * trust basis are derived from the signing key and signed with the bundle; a
+ * caller cannot supply a stronger basis than the one this build can verify.
+ */
 export function signEvidenceBundle(bundle, privateKeyPem) {
-  const sig = crypto.sign(null, canonicalBytes(bundle), privateKeyPem);
+  const publicKeyPem = crypto.createPublicKey(privateKeyPem).export({ type: 'spki', format: 'pem' });
+  const withIssuance = { ...bundle, issuance: buildLocalIssuance(publicKeyPem) };
+  const sig = crypto.sign(null, canonicalBytes(withIssuance), privateKeyPem);
   return {
-    ...bundle,
+    ...withIssuance,
     signature: {
       algorithm: 'ed25519',
       canonicalisation: BUNDLE_SCHEMA,
@@ -256,7 +320,7 @@ export function signEvidenceBundle(bundle, privateKeyPem) {
 // what buildEvidenceBundle+signEvidenceBundle actually produce, or a
 // legitimate bundle would start failing verification.
 const BUNDLE_TOP_LEVEL_KEYS = new Set([
-  'schema', 'finding', 'evidence', 'engine', 'proves', 'doesNotProve', 'signature',
+  'schema', 'finding', 'evidence', 'engine', 'proves', 'doesNotProve', 'issuance', 'signature',
 ]);
 
 export function verifyEvidenceBundle(bundle, publicKeyPem) {
@@ -276,7 +340,29 @@ export function verifyEvidenceBundle(bundle, publicKeyPem) {
   } catch (e) {
     return { ok: false, reason: `verification error: ${e.message}` };
   }
-  return ok
-    ? { ok: true, reason: null }
-    : { ok: false, reason: 'signature does not match the bundle contents — it was modified after signing' };
+  if (!ok) return { ok: false, reason: 'signature does not match the bundle contents — it was modified after signing' };
+
+  // Trust basis. Checked AFTER the signature so the issuance block is already
+  // known to be unmodified.
+  if (bundle.issuance === undefined) {
+    return {
+      ok: true, reason: null, trustBasis: 'none-declared', independentlyCertified: false, issuer: null,
+      trustNote: 'This bundle predates issuer declarations: no trust basis is declared. Treat it as unattested provenance, not as certification.',
+    };
+  }
+  const iss = bundle.issuance;
+  const basis = iss && typeof iss === 'object' ? TRUST_BASES[iss.trustBasis] : undefined;
+  if (!basis) return { ok: false, reason: `unsupported trust basis: ${JSON.stringify(iss?.trustBasis ?? null)}` };
+  if (iss.independentlyCertified !== false) {
+    return { ok: false, reason: 'a self-issued bundle may not claim independent certification' };
+  }
+  let fp;
+  try { fp = keyFingerprint(publicKeyPem); } catch (e) { return { ok: false, reason: `verification error: ${e.message}` }; }
+  if (iss.issuer?.keyFingerprint !== fp) {
+    return { ok: false, reason: 'the declared issuer key does not match the key that verified the signature' };
+  }
+  return {
+    ok: true, reason: null, trustBasis: iss.trustBasis, independentlyCertified: false,
+    issuer: iss.issuer, trustNote: basis.statement,
+  };
 }

package/src/posture/execution-proof.js

@@ -8,6 +8,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { runConfined, sandboxAvailable, detectBackend } from '../sandbox/index.js';
 import { attachProofTier, proofTierOf } from './proof-tier.js';
+import { emitVerification } from './verification/emit.js';
 
 const PROOF_MARKER = 'PROVEN';
 
@@ -75,7 +76,16 @@ export const DEFAULT_PROOF_TIMEOUT_MS =
     ? Number(process.env.AGENTIC_SECURITY_PROOF_TIMEOUT_MS)
     : 45000;
 
-export async function proveFinding(finding, { timeoutMs = DEFAULT_PROOF_TIMEOUT_MS, force, files } = {}) {
+// X-201: the proof result also carries the one verification record, ADDITIVELY (`proofTier` and `proofEvidence` are
+// unchanged). A PoC run under this older sandbox path is not a trusted runner, so the record says `inconclusive` for a
+// run that demonstrated the effect and for one that did not; `confirmed` takes a trusted oracle adapter.
+export async function proveFinding(finding, opts = {}) {
+  const proved = await _proveFinding(finding, opts);
+  const emitted = emitVerification('execution-proof', proved, { finding: proved, commit: opts.commit ?? null });
+  return emitted.ok ? { ...proved, verificationRecord: emitted.record } : proved;
+}
+
+async function _proveFinding(finding, { timeoutMs = DEFAULT_PROOF_TIMEOUT_MS, force, files } = {}) {
   const poc = finding?.poc;
   if (!poc?.code) {
     return attachProofTier(finding, _evidence({ tier: proofTierOf(finding), reason: 'no proof-of-concept attached' }));