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

package/src/posture/fleet/exposure-ranking.js

@@ -0,0 +1,115 @@
+// Fleet exposure ranking (E7-06): which findings matter most across many repositories and services, and WHY, without collapsing the reasons into one number.
+//
+// A single risk score hides what it is made of. This ranking keeps five things apart and shows each:
+//   impact          what is lost if it is exploited: severity, the classes of data on the path (card numbers, health data), how many services the path crosses
+//   exposure        who can reach it: a route of a public service, a route of an internal service, a path from nothing, or unknown
+//   exploitability  how likely and how well shown: an execution proof, a known-exploited listing, a taint path, a pattern match; runtime evidence counts only while it is FRESH
+//   confidence      how sure we are of the path itself: whether the chain is made of named, declared links or inferred ones
+//   coverage        how complete the picture is: scan health of the repositories on the path, and repositories of the fleet that were not scanned at all
+// Coverage is reported beside the rest and never folded into them: an incomplete picture is a caveat on the ranking, not a reason to rank something lower.
+//
+// PRIORITY is read from a fixed table of those tiers (`PRIORITY_RULES`), top to bottom, first match wins, so any finding's priority can be traced to the rule that
+// gave it. Ties are broken by the tiers in a fixed order, then by id, so the order is deterministic.
+//
+// NEGATIVE CONTROLS built in: runtime evidence older than the freshness window does not raise exploitability and is listed as stale; a finding that arrives through
+// a library only counts for a path whose library step is marked vulnerable for that very package (a dependency on a version outside the advisory range, or on a
+// different package, excludes it and says so); a path is followed only along links that exist in the service graph, so a same-named route in another service is
+// never reached.
+const TIER = Object.freeze({ none: 0, unknown: 0, low: 1, medium: 2, high: 3, critical: 4 });
+const SENSITIVE = new Set(['payment-card', 'health', 'phi', 'pii', 'credentials', 'financial']);
+const SEVERITY = Object.freeze({ info: 'low', low: 'low', medium: 'medium', high: 'high', critical: 'critical' });
+
+/** The pre-registered priority table. First matching rule wins; each names the tiers it needs. */
+export const PRIORITY_RULES = Object.freeze([
+  { id: 'P0-proven-public-sensitive', priority: 'P0', when: (t) => t.impact >= TIER.high && t.exposure === 'public' && t.exploitability >= TIER.high && t.confidence >= TIER.medium },
+  { id: 'P0-critical-public', priority: 'P0', when: (t) => t.impact >= TIER.critical && t.exposure === 'public' && t.exploitability >= TIER.medium && t.confidence >= TIER.medium },
+  { id: 'P1-high-public', priority: 'P1', when: (t) => t.impact >= TIER.high && t.exposure === 'public' && t.exploitability >= TIER.medium },
+  { id: 'P1-proven-internal', priority: 'P1', when: (t) => t.impact >= TIER.high && t.exposure === 'internal' && t.exploitability >= TIER.high },
+  { id: 'P2-reachable', priority: 'P2', when: (t) => (t.exposure === 'public' || t.exposure === 'internal') && t.impact >= TIER.medium },
+  { id: 'P3-exposure-unknown', priority: 'P3', when: (t) => t.exposure === 'unknown' && t.impact >= TIER.high },
+  { id: 'P4-not-reached', priority: 'P4', when: () => true },
+]);
+const PRIORITY_ORDER = ['P0', 'P1', 'P2', 'P3', 'P4'];
+const tierName = (n) => Object.keys(TIER).find((k) => TIER[k] === n && k !== 'unknown') || 'none';
+const daysBetween = (a, b) => (a - b) / 86400000;
+
+/**
+ * @param {object} o
+ * @param {{nodes:object[], edges:object[]}} o.graph from buildServiceChainGraph
+ * @param {{route:string, service:string, repo:string, sink:string, steps:object[], confidence:number, repos:string[], dataClassifications:string[], crossesServices:boolean, throughLibrary:object[]}[]} o.chains from findChains
+ * @param {object[]} o.findings { id, repo, sinkRef:{repo, qid, kind}, severity, proofTier, kev, epss, viaLibrary:{package}, runtime:{observedAt, corroboration}, scanHealth:'complete'|'partial'|... }
+ * @param {Object<string,{exposure:'public'|'internal'}>} o.services keyed by service name
+ * @param {string[]} [o.fleet] every repository of the fleet, so unscanned ones are counted
+ * @param {string[]} [o.scanned] the repositories that were scanned
+ * @param {number} o.now
+ * @param {number} [o.freshnessDays] runtime evidence older than this is stale (default 14)
+ */
+export function rankFleetExposure({ graph, chains, findings, services = {}, fleet = [], scanned = null, now, freshnessDays = 14 }) {
+  const byRepoSink = new Map();
+  for (const c of chains || []) {
+    const sinkStep = c.steps[c.steps.length - 1];
+    const node = (graph.nodes || []).find((n) => n.id === (sinkStep && sinkStep.to));
+    if (!node) continue;
+    const key = `${node.repo}|${node.id.split(':sink:')[1] || ''}`;
+    (byRepoSink.get(key) || byRepoSink.set(key, []).get(key)).push(c);
+  }
+  // a repository counts as scanned when the caller says so, or, failing that, when some finding of it carries a scan health
+  const scannedRepos = new Set(scanned || (findings || []).filter((f) => f.scanHealth).map((f) => f.repo));
+  const ranked = []; const excluded = [];
+  for (const f of findings || []) {
+    const ref = f.sinkRef || {};
+    const key = `${ref.repo}|${ref.qid}#${ref.kind}`;
+    let cands = byRepoSink.get(key) || [];
+    const dropped = [];
+    if (f.viaLibrary) {
+      const keep = cands.filter((c) => c.throughLibrary.some((l) => l.package === f.viaLibrary.package && l.vulnerable === true));
+      for (const c of cands) if (!keep.includes(c)) dropped.push({ route: c.route, reason: c.throughLibrary.some((l) => l.package === f.viaLibrary.package) ? `the dependency on ${f.viaLibrary.package} is outside the advisory range` : `the path does not use ${f.viaLibrary.package}` });
+      cands = keep;
+      if (!keep.length && dropped.length) { excluded.push({ id: f.id, reason: dropped[0].reason, paths: dropped.length }); continue; }
+    }
+    const factors = [];
+    // ---- exposure
+    let exposure = 'none'; let entry = null;
+    if (cands.length) {
+      const exposures = cands.map((c) => (services[c.service] ? services[c.service].exposure : 'unknown'));
+      exposure = exposures.includes('public') ? 'public' : exposures.includes('internal') ? 'internal' : 'unknown';
+      // the entry that explains the exposure: the most certain path among those that give it
+      entry = cands.filter((c) => (services[c.service] ? services[c.service].exposure : 'unknown') === exposure).sort((a, b) => b.confidence - a.confidence)[0] || cands[0];
+      factors.push({ dimension: 'exposure', value: exposure, because: `${cands.length} path(s) reach it from a route; the entry service${cands.length > 1 ? 's are' : ' is'} ${[...new Set(cands.map((c) => c.service))].join(', ')} (${exposure})` });
+    } else factors.push({ dimension: 'exposure', value: ref.repo ? 'none' : 'unknown', because: ref.repo ? 'no path from any route in the service graph reaches this sink' : 'the finding does not say which sink it is, so no path can be looked for' });
+    if (!cands.length && !ref.repo) exposure = 'unknown'; else if (!cands.length) exposure = 'none';
+    // ---- impact
+    const classes = [...new Set(cands.flatMap((c) => c.dataClassifications))].sort();
+    const sev = SEVERITY[f.severity] || 'low';
+    let impact = TIER[sev];
+    if (classes.some((c) => SENSITIVE.has(c))) { impact = Math.min(TIER.critical, impact + 1); factors.push({ dimension: 'impact', value: tierName(impact), because: `severity ${f.severity}; the path carries ${classes.filter((c) => SENSITIVE.has(c)).join(', ')}, which raises it one tier` }); }
+    else factors.push({ dimension: 'impact', value: tierName(impact), because: `severity ${f.severity}${classes.length ? `; data on the path: ${classes.join(', ')} (not rated sensitive)` : '; no data classification on the path'}` });
+    if (cands.some((c) => c.crossesServices)) factors.push({ dimension: 'impact', value: 'info', because: 'the path crosses services, so a compromise is not contained to the entry service' });
+    // ---- exploitability
+    let exploit = f.proofTier === 'execution-proven' ? TIER.high : f.kev ? TIER.high : (typeof f.epss === 'number' && f.epss >= 0.5) ? TIER.high : f.proofTier === 'taint-proven' ? TIER.medium : TIER.low;
+    factors.push({ dimension: 'exploitability', value: tierName(exploit), because: f.proofTier === 'execution-proven' ? 'a proof of concept ran and showed the effect' : f.kev ? 'listed as known exploited' : (typeof f.epss === 'number' && f.epss >= 0.5) ? `EPSS ${f.epss}` : f.proofTier === 'taint-proven' ? 'a taint path was found by static analysis; nothing was executed' : 'a pattern match; no path or proof' });
+    if (f.runtime && f.runtime.observedAt) {
+      const age = daysBetween(now, Date.parse(f.runtime.observedAt));
+      if (!(age >= 0)) factors.push({ dimension: 'exploitability', value: 'info', because: 'runtime evidence is dated in the future and is ignored' });
+      else if (age > freshnessDays) factors.push({ dimension: 'exploitability', value: 'info', stale: true, because: `runtime evidence is ${Math.floor(age)} days old, past the ${freshnessDays}-day window: stale, so it does not raise anything` });
+      else if (f.runtime.corroboration === 'corroborated') { exploit = Math.min(TIER.critical, exploit + 1); factors.push({ dimension: 'exploitability', value: tierName(exploit), because: `observed by a matched build ${Math.floor(age)} day(s) ago: raises it one tier` }); }
+      else factors.push({ dimension: 'exploitability', value: 'info', because: 'seen at runtime but not tied to this build: noted, not counted' });
+    }
+    // ---- confidence
+    const conf = entry ? entry.confidence : 0;
+    const confidence = !entry ? TIER.unknown : conf >= 0.7 ? TIER.high : conf >= 0.5 ? TIER.medium : TIER.low;
+    factors.push({ dimension: 'confidence', value: entry ? tierName(confidence) : 'unknown', because: entry ? `the best path has confidence ${entry.confidence} (product of its links; named links 0.9, inferred 0.7 and below)` : 'there is no path to judge' });
+    // ---- coverage (reported, never merged)
+    const reposOnPath = new Set(cands.flatMap((c) => c.repos));
+    const unscanned = [...reposOnPath].filter((r) => fleet.length && !scannedRepos.has(r));
+    const coverage = { scanHealth: f.scanHealth || 'unknown', reposOnPath: [...reposOnPath].sort(), unscannedReposOnPath: unscanned.sort(), complete: (f.scanHealth === 'complete') && unscanned.length === 0 };
+    factors.push({ dimension: 'coverage', value: coverage.complete ? 'complete' : 'incomplete', because: coverage.complete ? 'the scan of this repository was complete and every repository on the path was scanned' : `scan health ${coverage.scanHealth}${unscanned.length ? `; not scanned: ${unscanned.join(', ')}` : ''}` });
+    const tiers = { impact, exposure, exploitability: exploit, confidence };
+    const rule = PRIORITY_RULES.find((r) => r.when(tiers));
+    ranked.push({ id: f.id, repo: ref.repo || f.repo || null, priority: rule.priority, rule: rule.id, tiers: { impact: tierName(impact), exposure, exploitability: tierName(exploit), confidence: entry ? tierName(confidence) : 'unknown' }, coverage, entryRoute: entry ? entry.route : null, paths: cands.length, droppedPaths: dropped, factors, _sort: [PRIORITY_ORDER.indexOf(rule.priority), -impact, -(exposure === 'public' ? 2 : exposure === 'internal' ? 1 : 0), -exploit, -confidence, String(f.id)] });
+  }
+  ranked.sort((a, b) => { for (let i = 0; i < a._sort.length; i++) { if (a._sort[i] < b._sort[i]) return -1; if (a._sort[i] > b._sort[i]) return 1; } return 0; });
+  for (const r of ranked) delete r._sort;
+  const byPriority = Object.fromEntries(PRIORITY_ORDER.map((p) => [p, ranked.filter((r) => r.priority === p).length]));
+  return { ranked, excluded, summary: { findings: (findings || []).length, ranked: ranked.length, excluded: excluded.length, byPriority, incompleteCoverage: ranked.filter((r) => !r.coverage.complete).length } };
+}

package/src/posture/fleet/service-chain-graph.js

@@ -0,0 +1,150 @@
+// Multi-repo, multi-service chain graph (E5-06).
+//
+// fleet-graph.js knows which repos depend on which packages. That says a defect in a shared library can reach its dependants, but not whether any route
+// of any service reaches the defect. This module adds the layers that answer that, over the same fleet:
+//
+//   call      inside one repo: function A calls function B (taken from the semantic graph's resolved call edges, supplied as facts)
+//   library   a function in repo A uses a symbol that a package published by repo L exports; the edge is made only when A's manifest depends on L
+//             (the existing dependency graph), and it is marked `vulnerable` when A's declared version is in L's advisory list
+//   api       a function in repo A calls an HTTP route of ANOTHER service; the edge goes to the route that service exposes
+//   topic     a function publishes an event topic and a function in another repo consumes it
+//
+// A CHAIN is route -> ... -> sink, found by walking those edges. Each step carries the evidence that made it and a confidence; a chain's confidence is
+// the product of its steps'.
+//
+// WRONG-SERVICE EDGES ARE THE FAILURE TO AVOID. Two services often expose the same path (`/health`, `/charge`). An outbound call that names its target
+// service links ONLY to that service's route. A call that names no service links to a route only when exactly ONE service in the tenant exposes it;
+// when several do, no edge is made and the call is listed under `ambiguous` with the candidates, never resolved by guessing.
+//
+// BUDGETS. `maxRepos`, `maxNodes`, `maxEdges`, `maxDepth`, `maxChains` bound the work. Hitting one stops that step and sets `truncated` with the name of
+// the budget; a result that was cut short never looks complete.
+//
+// TENANT ISOLATION. Every repo belongs to one tenant, every node id is prefixed with it, and a graph is built for one tenant. A repo from another tenant
+// is not read at all (counted in `refusedOtherTenant`), and a link that would cross tenants is refused. Nothing here reads outside the facts passed in.
+import { buildFleetDependencyGraph } from './fleet-graph.js';
+
+export const DEFAULT_BUDGETS = Object.freeze({ maxRepos: 200, maxNodes: 20000, maxEdges: 60000, maxDepth: 12, maxChains: 200 });
+
+const nid = (tenant, repo, kind, key) => `${tenant}:${repo}:${kind}:${key}`;
+const routeKey = (r) => `${(r.method || 'ANY').toUpperCase()} ${r.path}`;
+const ver = (v) => String(v || '').replace(/^[^\d]*/, '').split('.').map((n) => parseInt(n, 10) || 0);
+const cmp = (a, b) => { for (let i = 0; i < 3; i++) { const d = (a[i] || 0) - (b[i] || 0); if (d) return d; } return 0; };
+function isVulnerable(version, advisories) {
+  if (!version || !Array.isArray(advisories)) return false;
+  const v = ver(version);
+  return advisories.some((a) => (a.exact && cmp(v, ver(a.exact)) === 0) || (a.lt && cmp(v, ver(a.lt)) < 0 && (!a.gte || cmp(v, ver(a.gte)) >= 0)));
+}
+
+/**
+ * @param {object[]} repos RepoFacts:
+ *   { id, path, tenant, service?: string, environment?: string,
+ *     routes?: [{method?, path, handler, classification?}], calls?: [{from, to}],
+ *     outboundCalls?: [{from, service?, method?, path}],
+ *     topics?: { publishes?: [{topic, from}], consumes?: [{topic, handler}] },
+ *     libraryUses?: [{package, symbol, from}], exports?: [{package, symbol, qid}],
+ *     functions?: [{qid, sinks?: [{kind, cwe?}]}], advisories?: [{exact?|lt?, gte?}], dependencyVersions?: {pkg: version},
+ *   }  `path` is the repo directory: its manifests (package.json, go.mod, ...) are read by fleet-graph.js to decide who publishes and who depends on what
+ * @param {{tenant:string, budgets?:object}} opts
+ */
+export function buildServiceChainGraph(repos, opts = {}) {
+  const tenant = opts.tenant;
+  if (typeof tenant !== 'string' || !tenant) throw new Error('tenant is required: a fleet graph is built for exactly one tenant');
+  const B = { ...DEFAULT_BUDGETS, ...(opts.budgets || {}) };
+  const truncated = []; const trunc = (name) => { if (!truncated.includes(name)) truncated.push(name); };
+  const refusedOtherTenant = []; const ambiguous = []; const unresolved = [];
+  let mine = [];
+  for (const r of repos || []) { if (r.tenant !== tenant) refusedOtherTenant.push(r.id); else mine.push(r); }
+  if (mine.length > B.maxRepos) { trunc('maxRepos'); mine = mine.slice(0, B.maxRepos); }
+
+  const nodes = new Map(); const edges = []; const edgeSet = new Set();
+  const addNode = (id, n) => { if (nodes.has(id)) return true; if (nodes.size >= B.maxNodes) { trunc('maxNodes'); return false; } nodes.set(id, { id, ...n }); return true; };
+  const addEdge = (from, to, e) => {
+    const key = `${e.kind}|${from}|${to}`; if (edgeSet.has(key)) return;
+    if (edges.length >= B.maxEdges) { trunc('maxEdges'); return; }
+    if (!addNode(from, {}) || !addNode(to, {})) return;
+    edgeSet.add(key); edges.push({ from, to, ...e });
+  };
+
+  // the existing manifest-based dependency graph decides which library edges are allowed at all
+  const dep = buildFleetDependencyGraph(mine.map((r) => ({ id: r.id, path: r.path || '' })));
+  const dependsOn = new Set(dep.edges.map((e) => `${e.from}>${e.to}`));
+  const publishedBy = new Map();
+  for (const r of mine) { const n = (dep.nodes.find((x) => x.id === r.id) || {}).declaredName; if (n) publishedBy.set(n, r); }
+
+  for (const r of mine) {
+    for (const fn of r.functions || []) { addNode(nid(tenant, r.id, 'fn', fn.qid), { kind: 'function', repo: r.id, qid: fn.qid, sinks: (fn.sinks || []).map((s) => s.kind) }); }
+    for (const rt of r.routes || []) {
+      const rid = nid(tenant, r.id, 'route', routeKey(rt));
+      addNode(rid, { kind: 'route', repo: r.id, service: r.service || r.id, route: routeKey(rt), classification: rt.classification || null });
+      addEdge(rid, nid(tenant, r.id, 'fn', rt.handler), { kind: 'handler', confidence: 0.95, evidence: `route ${routeKey(rt)} is handled by ${rt.handler}`, repo: r.id });
+    }
+    for (const c of r.calls || []) addEdge(nid(tenant, r.id, 'fn', c.from), nid(tenant, r.id, 'fn', c.to), { kind: 'call', confidence: 0.9, evidence: 'resolved call edge in the semantic graph', repo: r.id });
+    for (const fn of r.functions || []) for (const s of fn.sinks || []) {
+      const sid = nid(tenant, r.id, 'sink', `${fn.qid}#${s.kind}`);
+      addNode(sid, { kind: 'sink', repo: r.id, sink: s.kind, cwe: s.cwe || null });
+      addEdge(nid(tenant, r.id, 'fn', fn.qid), sid, { kind: 'sink', confidence: 0.9, evidence: `${fn.qid} reaches a ${s.kind} sink`, repo: r.id });
+    }
+  }
+
+  // library edges: only along a declared dependency, and only for a symbol the library publishes
+  for (const r of mine) for (const u of r.libraryUses || []) {
+    const lib = publishedBy.get(u.package);
+    if (!lib) { unresolved.push({ repo: r.id, kind: 'library', package: u.package, reason: 'no repo in this tenant publishes this package' }); continue; }
+    if (lib.id === r.id) continue;
+    if (!dependsOn.has(`${r.id}>${lib.id}`)) { unresolved.push({ repo: r.id, kind: 'library', package: u.package, reason: 'the repo does not declare a dependency on the publishing repo' }); continue; }
+    const exp = (lib.exports || []).find((x) => x.symbol === u.symbol && (!x.package || x.package === u.package));
+    if (!exp) { unresolved.push({ repo: r.id, kind: 'library', package: u.package, symbol: u.symbol, reason: 'the publishing repo does not export this symbol' }); continue; }
+    const v = (r.dependencyVersions || {})[u.package];
+    const vulnerable = isVulnerable(v, lib.advisories);
+    addEdge(nid(tenant, r.id, 'fn', u.from), nid(tenant, lib.id, 'fn', exp.qid), { kind: 'library', confidence: 0.85, evidence: `${r.id} depends on ${lib.id} and uses ${u.package}.${u.symbol}`, repo: r.id, toRepo: lib.id, package: u.package, version: v || null, vulnerable });
+  }
+
+  // api edges: named service links only to that service; unnamed links only when exactly one service exposes the route
+  const exposers = (path, method) => mine.filter((x) => (x.routes || []).some((rt) => rt.path === path && (!method || !rt.method || rt.method.toUpperCase() === method.toUpperCase())));
+  for (const r of mine) for (const c of r.outboundCalls || []) {
+    const cands = exposers(c.path, c.method).filter((x) => x.id !== r.id);
+    let target = null;
+    if (c.service) {
+      target = cands.find((x) => (x.service || x.id) === c.service) || null;
+      if (!target) { unresolved.push({ repo: r.id, kind: 'api', path: c.path, service: c.service, reason: 'the named service does not expose this route' }); continue; }
+    } else if (cands.length === 1) target = cands[0];
+    else if (cands.length > 1) { ambiguous.push({ repo: r.id, from: c.from, path: c.path, candidates: cands.map((x) => x.service || x.id).sort() }); continue; }
+    else { unresolved.push({ repo: r.id, kind: 'api', path: c.path, reason: 'no service in this tenant exposes this route' }); continue; }
+    const rt = (target.routes || []).find((x) => x.path === c.path && (!c.method || !x.method || x.method.toUpperCase() === c.method.toUpperCase()));
+    addEdge(nid(tenant, r.id, 'fn', c.from), nid(tenant, target.id, 'route', routeKey(rt)), { kind: 'api', confidence: c.service ? 0.9 : 0.7, evidence: c.service ? `call names service ${c.service}` : `only service exposing ${c.path}`, repo: r.id, toRepo: target.id, classification: rt.classification || null });
+  }
+
+  // topic edges
+  for (const r of mine) for (const p of (r.topics && r.topics.publishes) || []) for (const o of mine) {
+    if (o.id === r.id) continue;
+    for (const cn of (o.topics && o.topics.consumes) || []) if (cn.topic === p.topic) addEdge(nid(tenant, r.id, 'fn', p.from), nid(tenant, o.id, 'fn', cn.handler), { kind: 'topic', confidence: 0.75, evidence: `topic ${p.topic}`, repo: r.id, toRepo: o.id, topic: p.topic });
+  }
+  return { tenant, nodes: [...nodes.values()], edges, ambiguous, unresolved, refusedOtherTenant, truncated, budgets: B, dependencyEdges: dep.edges.length };
+}
+
+/** Walk route -> ... -> sink. Cycles are not followed; depth and chain count are budgeted and reported. */
+export function findChains(graph, { sinkKind = null, fromRepo = null } = {}) {
+  const B = graph.budgets; const out = new Map();
+  for (const e of graph.edges) { (out.get(e.from) || out.set(e.from, []).get(e.from)).push(e); }
+  const byId = new Map(graph.nodes.map((n) => [n.id, n]));
+  const chains = []; const truncated = [];
+  for (const start of graph.nodes.filter((n) => n.kind === 'route' && (!fromRepo || n.repo === fromRepo))) {
+    const stack = [{ at: start.id, steps: [], seen: new Set([start.id]) }];
+    while (stack.length) {
+      const { at, steps, seen } = stack.pop();
+      const node = byId.get(at);
+      if (node && node.kind === 'sink' && (!sinkKind || node.sink === sinkKind)) {
+        if (chains.length >= B.maxChains) { if (!truncated.includes('maxChains')) truncated.push('maxChains'); break; }
+        chains.push({ route: start.route, service: start.service, repo: start.repo, sink: node.sink, steps, confidence: Math.round(steps.reduce((p, s) => p * s.confidence, 1) * 1000) / 1000, crossesServices: steps.some((s) => s.kind === 'api' || s.kind === 'topic'), throughLibrary: steps.filter((s) => s.kind === 'library').map((s) => ({ package: s.package, version: s.version, vulnerable: s.vulnerable })), repos: [...new Set([start.repo, ...steps.map((s) => s.toRepo || s.repo)])], dataClassifications: [...new Set([start.classification, ...steps.map((s) => s.classification)].filter(Boolean))].sort() });
+        continue;
+      }
+      if (steps.length >= B.maxDepth) { if (!truncated.includes('maxDepth')) truncated.push('maxDepth'); continue; }
+      for (const e of out.get(at) || []) {
+        if (seen.has(e.to)) continue;
+        stack.push({ at: e.to, steps: [...steps, { kind: e.kind, from: e.from, to: e.to, confidence: e.confidence, evidence: e.evidence, ...(e.package ? { package: e.package, version: e.version, vulnerable: e.vulnerable } : {}), ...(e.toRepo ? { toRepo: e.toRepo } : {}), ...(e.repo ? { repo: e.repo } : {}), ...(e.classification ? { classification: e.classification } : {}) }], seen: new Set([...seen, e.to]) });
+      }
+    }
+  }
+  chains.sort((a, b) => b.confidence - a.confidence || (a.route < b.route ? -1 : 1));
+  return { chains, truncated };
+}

package/src/posture/graph-reconciliation.js

@@ -0,0 +1,154 @@
+// Static / runtime graph reconciliation (E5-04).
+//
+// The static graph says which calls, routes and service edges the CODE contains. A runtime trace says which ones a RUNNING BUILD exercised. This
+// module lines the two up edge by edge and states, for each edge, what is actually known:
+//
+//   statically_inferred  the static graph has the edge; no usable runtime evidence about it
+//   runtime_observed     a runtime record shows the edge; the static graph does not contain it (a gap in the static graph, or dynamic dispatch)
+//   both                 the static graph has it AND a record from a build matched to this snapshot shows it
+//   conflicted           the two disagree: the same route reached a different handler, or the same call site's caller reached a callee the static
+//                        graph never resolved it to while a matched build was running
+//   unknown              evidence exists but cannot be tied to this snapshot (runtime records with no comparable build identity), so the edge is
+//                        neither confirmed nor refuted
+//
+// `both` REQUIRES a matched build (deployment-identity.js). A record from a different build never confirms an edge: it is counted against the edge
+// as `mismatchedRecords` and decays its confidence. Records with no build identity make the edge `unknown`, not `both`.
+//
+// CONFIDENCE is a number in [0,1] with the factors listed in `factors`, so a reader can see why it is what it is:
+//   base           static edge 0.6; resolved call 0.7; runtime-only 0.5; both 0.95; conflicted 0.3; unknown 0.4
+//   x0.5           for each edge that also has records from a mismatched build (the evidence is about different code), once
+//   x0.85          when the trace's coverage is partial: sampled below 1 or sampling undeclared
+// Matching is by NORMALIZED KEY: symbols lose a trailing @line and, per `opts.normalize`, a configured prefix and case; routes become their path
+// with every `:param` and id-like segment collapsed to `:id`.
+//
+// NOT USED: spans. Static symbols carry a start line and no end line, so line-range matching is not attempted; matching is by qualified symbol.
+import * as fs from 'node:fs';
+import * as readline from 'node:readline';
+import { linkObservationToSnapshot, normalizeIdentity } from '../lineage/deployment-identity.js';
+import { normalizeRoute } from './runtime-trace-ingest.js';
+
+export const EDGE_STATES = Object.freeze(['statically_inferred', 'runtime_observed', 'both', 'conflicted', 'unknown']);
+const BASE = Object.freeze({ statically_inferred: 0.6, runtime_observed: 0.5, both: 0.95, conflicted: 0.3, unknown: 0.4 });
+
+/** Normalise a symbol per the configurable rules. */
+export function normalizeSymbol(q, norm = {}) {
+  if (typeof q !== 'string') return null;
+  let s = q.replace(/@\d+$/, '').replace(/\(\)$/, '');
+  // `rewrite` is [[pattern, replacement], ...]: how this project's collector spells a symbol versus how the IR does (the IR writes `app.js::<module>::run`)
+  for (const [pat, rep] of norm.rewrite || []) s = s.replace(new RegExp(pat), rep);
+  for (const pre of norm.stripPrefixes || []) if (s.startsWith(pre)) { s = s.slice(pre.length); break; }
+  if (norm.caseInsensitive) s = s.toLowerCase();
+  return s || null;
+}
+/** Normalise a route path: query dropped, ids and `:param` collapsed to `:id`. */
+export function normalizeRouteKey(r) {
+  const n = normalizeRoute(typeof r === 'string' ? r.replace(/\{[^}/]+\}/g, ':id') : r);
+  return n ? n.split('/').map((seg) => (seg.startsWith(':') ? ':id' : seg)).join('/') : null;
+}
+
+const keyOf = (kind, a, b) => `${kind}|${a}|${b}`;
+
+/**
+ * Static edges from a SemanticGraph.
+ * @param {object} graph a SemanticGraph v1
+ * @param {{routes?:{path:string, handler:string}[]}} extra route -> handler pairs the caller knows (the IR has no route entity)
+ */
+export function staticEdgesFromGraph(graph, extra = {}, norm = {}) {
+  const byId = new Map((graph.symbols || []).map((s) => [s.id, s]));
+  const edges = new Map();
+  const add = (kind, a, b, over = {}) => { if (a && b) edges.set(keyOf(kind, a, b), { kind, from: a, to: b, resolved: true, ...over }); };
+  for (const c of graph.callSites || []) {
+    if (c.resolution !== 'resolved') continue;
+    add('call', normalizeSymbol(byId.get(c.caller)?.qid, norm), normalizeSymbol(byId.get(c.callee)?.qid, norm), { file: c.file ?? null, line: c.line ?? null });
+  }
+  for (const r of extra.routes || []) add('route', normalizeRouteKey(r.path), normalizeSymbol(r.handler, norm));
+  for (const b of graph.serviceBoundaries || []) if (b.from && b.to && b.from.service && b.to.service) add('service', b.from.service, b.to.service);
+  return edges;
+}
+
+/** Read the trace file and collect runtime edges with their build links. Never throws on a bad line. */
+export async function readRuntimeEdges(tracePath, opts = {}) {
+  const snap = opts.snapshotIdentity ? normalizeIdentity(opts.snapshotIdentity) : null;
+  const norm = opts.normalize || {};
+  const windowMs = (opts.windowDays || 30) * 86400_000; const now = opts.now ?? Date.now();
+  const edges = new Map(); let records = 0;
+  const touch = (key, kind, from, to, link) => {
+    const e = edges.get(key) || { kind, from, to, matched: 0, unattested: 0, mismatched: 0 };
+    e[link === 'matched' ? 'matched' : link === 'mismatched' ? 'mismatched' : 'unattested']++;
+    edges.set(key, e);
+  };
+  const rl = readline.createInterface({ input: fs.createReadStream(tracePath, { encoding: 'utf8' }), crlfDelay: Infinity });
+  for await (const line of rl) {
+    let r; try { r = JSON.parse(line); } catch { continue; }
+    if (!r || typeof r !== 'object') continue;
+    const t = r.ts ? Date.parse(r.ts) : NaN;
+    if (Number.isFinite(t) && now - t > windowMs) continue;
+    records++;
+    const link = snap ? linkObservationToSnapshot({ commit: r.commit, buildHash: r.buildHash, imageDigest: r.imageDigest, sbomRef: r.sbomRef, environment: r.environment }, snap).state : 'unknown';
+    if (r.kind === 'function-call' && r.caller && r.qid) { const a = normalizeSymbol(r.caller, norm); const b = normalizeSymbol(r.qid, norm); if (a && b) touch(keyOf('call', a, b), 'call', a, b, link); }
+    else if (r.kind === 'route-hit' && r.route && r.qid) { const a = normalizeRouteKey(r.route); const b = normalizeSymbol(r.qid, norm); if (a && b) touch(keyOf('route', a, b), 'route', a, b, link); }
+    else if (r.kind === 'service-call' && r.service && r.peer) touch(keyOf('service', r.service, r.peer), 'service', r.service, r.peer, link);
+  }
+  return { edges, records };
+}
+
+/**
+ * @param {Map} staticEdges  from staticEdgesFromGraph
+ * @param {{edges:Map, records:number}} runtime from readRuntimeEdges
+ * @param {{sampling?:{state:string}}} opts sampling from runtime-correlation.js samplingOf(trace)
+ * @returns {{edges:object[], counts:Object<string,number>, limitations:string[]}}
+ */
+export function reconcileGraphs(staticEdges, runtime, opts = {}) {
+  const partial = !opts.sampling || opts.sampling.state !== 'complete';
+  const out = new Map();
+  const finish = (key, state, base, extra) => {
+    const factors = [{ name: 'base', value: BASE[state] ?? base }];
+    let c = BASE[state] ?? base;
+    if (base !== undefined && state === 'statically_inferred') { c = base; factors[0].value = base; }
+    if (extra.mismatchedRecords > 0) { c *= 0.5; factors.push({ name: 'records-from-a-different-build', value: 0.5 }); }
+    if (partial) { c *= 0.85; factors.push({ name: 'partial-or-undeclared-coverage', value: 0.85 }); }
+    out.set(key, { key, state, confidence: Math.round(c * 1000) / 1000, factors, ...extra });
+  };
+  const rt = runtime ? runtime.edges : new Map();
+  for (const [key, s] of staticEdges) {
+    const r = rt.get(key);
+    const base = s.kind === 'call' ? 0.7 : 0.6;
+    const common = { kind: s.kind, from: s.from, to: s.to, mismatchedRecords: r ? r.mismatched : 0, matchedRecords: r ? r.matched : 0, unattestedRecords: r ? r.unattested : 0 };
+    if (r && r.matched > 0) finish(key, 'both', base, common);
+    else if (r && r.unattested > 0) finish(key, 'unknown', base, { ...common, reason: 'runtime records show this edge but carry no build identity comparable to the snapshot' });
+    else finish(key, 'statically_inferred', base, { ...common, ...(r && r.mismatched ? { reason: 'only a different build was observed using this edge' } : {}) });
+  }
+  // runtime-only edges, and conflicts
+  const staticByFrom = new Map();
+  for (const s of staticEdges.values()) { const k = `${s.kind}|${s.from}`; (staticByFrom.get(k) || staticByFrom.set(k, []).get(k)).push(s); }
+  for (const [key, r] of rt) {
+    if (out.has(key)) continue;
+    const common = { kind: r.kind, from: r.from, to: r.to, mismatchedRecords: r.mismatched, matchedRecords: r.matched, unattestedRecords: r.unattested };
+    if (r.matched === 0 && r.unattested === 0) { finish(key, 'unknown', undefined, { ...common, reason: 'seen only in a different build: not evidence about this snapshot' }); continue; }
+    const rivals = (r.kind === 'route' || r.kind === 'call') ? (staticByFrom.get(`${r.kind}|${r.from}`) || []) : [];
+    const conflicting = r.matched > 0 && r.kind === 'route' && rivals.length > 0;
+    if (conflicting) {
+      finish(key, 'conflicted', undefined, { ...common, conflictsWith: rivals.map((x) => keyOf(x.kind, x.from, x.to)), reason: 'the same route reached a different handler than the static graph names' });
+      for (const x of rivals) { const k = keyOf(x.kind, x.from, x.to); const cur = out.get(k); if (cur && cur.state !== 'both') finish(k, 'conflicted', undefined, { kind: cur.kind, from: cur.from, to: cur.to, mismatchedRecords: cur.mismatchedRecords, matchedRecords: cur.matchedRecords, unattestedRecords: cur.unattestedRecords, conflictsWith: [key], reason: 'a matched build routed this path to a different handler' }); }
+    } else finish(key, 'runtime_observed', undefined, { ...common, ...(r.matched === 0 ? { reason: 'build identity not comparable: observed, not corroborating' } : {}) });
+  }
+  const edges = [...out.values()].sort((a, b) => (a.key < b.key ? -1 : 1));
+  const counts = Object.fromEntries(EDGE_STATES.map((s) => [s, edges.filter((e) => e.state === s).length]));
+  return { edges, counts, partialCoverage: partial, limitations: ['Spans are not used: static symbols carry no end line, so matching is by qualified symbol.', 'Route-to-handler static edges exist only when the caller supplies them; the IR has no route entity.', 'Conflicts are detected for routes only; a call edge to a callee the static graph did not resolve is runtime_observed.'] };
+}
+
+/**
+ * Can an exploit path be called runtime-corroborated? Only when EVERY edge of it is `both`. A conflicted edge makes the path conflicted; an edge
+ * the reconciliation has no entry for counts as uncorroborated.
+ * @param {string[]} pathKeys edge keys along the path
+ */
+export function pathCorroboration(reconciled, pathKeys) {
+  const byKey = new Map(reconciled.edges.map((e) => [e.key, e]));
+  const states = pathKeys.map((k) => (byKey.get(k) || { state: 'statically_inferred' }).state);
+  if (!states.length) return { state: 'uncorroborated', reason: 'the path has no edges' };
+  if (states.includes('conflicted')) return { state: 'conflicted' };
+  if (states.every((s) => s === 'both')) return { state: 'corroborated' };
+  return { state: states.some((s) => s === 'both') ? 'partial' : 'uncorroborated', missing: pathKeys.filter((k, i) => states[i] !== 'both') };
+}
+
+export { keyOf as edgeKey };

package/src/posture/provenance/coverage.js

@@ -0,0 +1,103 @@
+// How much of the work of attributing findings to commits was actually possible, and how much of that was done (E7-02).
+//
+// A single "attributed / total" rate mixes two different things: findings the pipeline could have attributed and did not (a gap in the pipeline), and findings no
+// pipeline could attribute (a file git ignores, generated code, a file git does not track, a checkout with no history). Counting the second kind as failures
+// punishes the tool for the repository, and hiding them inflates the rate. This module keeps them apart and states both denominators:
+//
+//   attributed             complete: a commit introduced it. uncommitted: it is in the working tree and in no commit yet (resolved, but not to a commit)
+//   ineligible             ignored, generated, untracked, or history-unavailable (no repository, git failed, or a shallow clone cut the history short)
+//   eligible, unattributed the pipeline could have and did not, with its reason: budget_exhausted, project-wide (a whole-project analysis that a
+//                          single-file replay cannot reproduce), unconfirmed (the finding's condition was not confirmed in the history it could see),
+//                          not_available, or error
+//
+// `eligibleRate` = attributed / (attributed + eligible unattributed). It is a rate over what attribution could reach, and it is reported next to `overallRate`
+// (attributed / all) so neither can stand in for the other. The target of 95% is aspirational: `targetStatus` says `met`, `not_met`, or
+// `insufficient_eligible` when there are too few eligible findings (under 30) for a rate to mean anything. Nothing here invents an author or a date.
+import * as cp from 'node:child_process';
+import * as path from 'node:path';
+import { hardenGitArgs, hardenGitEnv } from '../../util/git-hardening.js';
+
+export const ATTRIBUTION_TARGET = 0.95;
+export const MIN_ELIGIBLE_FOR_RATE = 30;
+export const ATTRIBUTION_CATEGORIES = Object.freeze([
+  'attributed', 'uncommitted',
+  'ineligible:ignored', 'ineligible:generated', 'ineligible:untracked', 'ineligible:history-unavailable',
+  'eligible:budget_exhausted', 'eligible:project-wide', 'eligible:unconfirmed', 'eligible:not_available', 'eligible:error',
+]);
+
+// Findings made by a pass over the WHOLE project (a declared set of states found in one file and violated in another, a race between two files, a prompt
+// stored in one file and used in another, a call between services). Replaying a single file at an old commit cannot reproduce them, so the origin walk ends
+// "never confirmed" for every one. They are reported under their own name because the remedy (a project-scoped replay) is different from the remedy for
+// an ordinary unconfirmed finding.
+const PROJECT_WIDE_PARSERS = new Set(['STATE-MACHINE', 'CONCURRENCY', 'LLM-STORED-PROMPT-XFILE', 'CROSS-SERVICE', 'CROSS-REPO']);
+const PROJECT_WIDE_FAMILIES = new Set(['spec-drift', 'state-machine-bypass', 'concurrency-bug']);
+
+const GENERATED_PATH = /(?:^|\/)(?:generated|gen|__generated__|dist|build|vendor|node_modules)\/|\.min\.(?:js|css)$|\.pb\.(?:go|js|ts|py)$|_pb2(?:_grpc)?\.py$|\.g\.dart$|\.generated\.\w+$/i;
+const GENERATED_HEADER = /@generated\b|\bDO NOT EDIT\b|\bCode generated by\b|\bauto-?generated\b.*\bdo not (?:edit|modify)\b/i;
+
+const git = (root, args, input) => {
+  try { return { ok: true, out: cp.execFileSync('git', hardenGitArgs(args), { cwd: root, encoding: 'utf8', input, timeout: 30000, stdio: [input === undefined ? 'ignore' : 'pipe', 'pipe', 'ignore'], maxBuffer: 64 * 1024 * 1024, env: hardenGitEnv() }) }; }
+  catch (e) { return { ok: false, out: '', error: e }; }
+};
+
+/** What git says about a set of files: tracked, ignored, and whether there is usable history. @param {string[]} files paths relative to `root` */
+export function inspectRepository(root, files) {
+  const inside = git(root, ['rev-parse', '--is-inside-work-tree']);
+  if (!inside.ok || inside.out.trim() !== 'true') return { repo: false, shallow: false, tracked: new Set(), ignored: new Set() };
+  const shallow = git(root, ['rev-parse', '--is-shallow-repository']).out.trim() === 'true';
+  const head = git(root, ['rev-parse', '--verify', 'HEAD']);
+  const prefix = git(root, ['rev-parse', '--show-prefix']).out.trim();
+  const tracked = new Set(git(root, ['ls-files', '-z']).out.split('\0').filter(Boolean).map((p) => (prefix && p.startsWith(prefix) ? p.slice(prefix.length) : p)));
+  const ignored = new Set();
+  const list = [...new Set(files)].filter((f) => !tracked.has(f));
+  if (list.length) {
+    const r = git(root, ['check-ignore', '--stdin', '-z'], list.join('\0') + '\0');
+    for (const p of r.out.split('\0').filter(Boolean)) ignored.add(p);
+  }
+  return { repo: true, shallow, hasHead: head.ok, tracked, ignored };
+}
+
+const normalise = (root, f) => { const rel = path.isAbsolute(f) ? path.relative(root, f) : f; return rel.split(path.sep).join('/'); };
+
+/**
+ * @param {object[]} findings findings carrying `file` and `findingProvenance`
+ * @param {{root:string, readHeader?:(file:string)=>string|null, repo?:object}} ctx `readHeader` returns the first lines of a file (for generated-code markers)
+ * @returns {{categories:Object<string,number>, total:number, attributed:number, ineligible:number, eligible:number, eligibleUnattributed:number, overallRate:number|null,
+ *            eligibleRate:number|null, target:number, targetStatus:string, perFinding:{id:string, file:string|null, category:string, reason:string|null}[]}}
+ */
+export function attributionCoverage(findings, { root, readHeader = null, repo = null } = {}) {
+  const list = Array.isArray(findings) ? findings : [];
+  const files = list.map((f) => (f && typeof f.file === 'string' ? normalise(root || '.', f.file) : null)).filter(Boolean);
+  const info = repo || inspectRepository(root || '.', files);
+  const categories = Object.fromEntries(ATTRIBUTION_CATEGORIES.map((c) => [c, 0]));
+  const perFinding = [];
+  for (const f of list) {
+    const file = f && typeof f.file === 'string' ? normalise(root || '.', f.file) : null;
+    const fp = f && f.findingProvenance;
+    const status = fp && fp.status;
+    let category; let reason = null;
+    if (status === 'complete') category = 'attributed';
+    else if (status === 'uncommitted') category = 'uncommitted';
+    else if (!info.repo) { category = 'ineligible:history-unavailable'; reason = 'the directory is not inside a git work tree'; }
+    else if (file && info.ignored.has(file)) { category = 'ineligible:ignored'; reason = 'git ignores this file'; }
+    else if (file && (GENERATED_PATH.test(file) || (readHeader && GENERATED_HEADER.test(readHeader(file) || '')))) { category = 'ineligible:generated'; reason = 'the file is generated code, not authored'; }
+    else if (file && !info.tracked.has(file)) { category = 'ineligible:untracked'; reason = 'git does not track this file'; }
+    else if (info.hasHead === false) { category = 'ineligible:history-unavailable'; reason = 'the repository has no commits'; }
+    else if (info.shallow && (status === 'partial' || status === 'not_available') && fp && fp.historyCoverage && fp.historyCoverage.shallow === true) { category = 'ineligible:history-unavailable'; reason = 'a shallow clone cut the history short'; }
+    else if (status === 'budget_exhausted') { category = 'eligible:budget_exhausted'; reason = (fp.limitations || [])[0] || 'the analysis budget ran out'; }
+    else if (status === 'partial' && (PROJECT_WIDE_PARSERS.has(f.parser) || PROJECT_WIDE_FAMILIES.has(f.family))) { category = 'eligible:project-wide'; reason = 'the finding comes from a whole-project analysis; replaying one file at an old commit cannot reproduce it'; }
+    else if (status === 'partial') { category = 'eligible:unconfirmed'; reason = (fp.limitations || [])[0] || 'the finding was not confirmed in the history that could be seen'; }
+    else if (status === 'error') { category = 'eligible:error'; reason = (fp.limitations || [])[0] || 'resolution failed'; }
+    else { category = 'eligible:not_available'; reason = (fp && (fp.limitations || [])[0]) || 'no provenance was recorded for this finding'; }
+    categories[category]++;
+    perFinding.push({ id: String((f && (f.stableId || f.id)) ?? ''), file, category, reason });
+  }
+  const total = list.length;
+  const attributed = categories.attributed + categories.uncommitted;
+  const ineligible = Object.entries(categories).filter(([k]) => k.startsWith('ineligible:')).reduce((a, [, n]) => a + n, 0);
+  const eligibleUnattributed = Object.entries(categories).filter(([k]) => k.startsWith('eligible:')).reduce((a, [, n]) => a + n, 0);
+  const eligible = attributed + eligibleUnattributed;
+  const eligibleRate = eligible === 0 ? null : Number((attributed / eligible).toFixed(4));
+  const targetStatus = eligible < MIN_ELIGIBLE_FOR_RATE ? 'insufficient_eligible' : eligibleRate >= ATTRIBUTION_TARGET ? 'met' : 'not_met';
+  return { categories, total, attributed, ineligible, eligible, eligibleUnattributed, overallRate: total === 0 ? null : Number((attributed / total).toFixed(4)), eligibleRate, target: ATTRIBUTION_TARGET, targetStatus, perFinding };
+}