@clear-capabilities/agentic-security-scanner 0.74.0

package/src/posture/calibration.js

@@ -0,0 +1,204 @@
+// Brier-calibrated confidence (P1.3 / FR-UX-1, FR-UX-2).
+//
+// Today's `confidence` field is an ordinal score: combinations of severity,
+// parser type, route-rooting, and a few heuristic adjustments. It correlates
+// with true-positive rate but isn't calibrated — a "0.8" today doesn't mean
+// "80% likely TP," it means "above-the-fold finding."
+//
+// This module turns the ordinal score into a calibrated probability via a
+// per-family bucket map of historical TP rates from `validator-metrics.json`.
+// It also computes:
+//
+//   - 95% Wilson-score confidence intervals (small-sample-safe; never reports
+//     a CI of [0.95, 1.00] from a single observation).
+//   - The running Brier score on the labeled history, so the operator can
+//     see how well the calibration tracks reality.
+//
+// HONESTY: when a family has fewer than `MIN_SAMPLES_FOR_CALIBRATION` labels
+// (default 30), we refuse to ship a calibrated number and instead emit
+// `null` with a reason. Pillar-6 of the parent PRD calls this out: "When the
+// verifier cannot rule a finding in or out, surface 'cannot verify' rather
+// than pick a confidence number out of a hat."
+//
+// Seed corpus: the v1 calibration table is seeded from per-family TP/FP
+// counts collected by the bench-realworld runner against OWASP Benchmark
+// v1.2 and the curated Juliet subsets. Customers' own `validator-metrics.json`
+// extends and overrides per-family.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const MIN_SAMPLES_FOR_CALIBRATION = 30;
+
+// ─── Wilson-score interval ──────────────────────────────────────────────────
+//
+// Returns [lower, upper] for proportion p with n observations at 95% conf.
+// Source: https://en.wikipedia.org/wiki/Binomial_proportion_confidence_interval
+
+const Z_95 = 1.959963984540054;
+
+export function wilsonInterval(tp, n) {
+  if (n <= 0) return [0, 1];
+  const p = tp / n;
+  const z = Z_95;
+  const denom = 1 + (z * z) / n;
+  const centre = p + (z * z) / (2 * n);
+  const margin = z * Math.sqrt((p * (1 - p)) / n + (z * z) / (4 * n * n));
+  const lower = Math.max(0, (centre - margin) / denom);
+  const upper = Math.min(1, (centre + margin) / denom);
+  return [lower, upper];
+}
+
+// ─── Brier score ─────────────────────────────────────────────────────────────
+//
+// brier = mean( (prediction - actual)^2 )
+// 0 = perfect; 0.25 = worse than coin flip; 1 = always wrong.
+// PRD success criterion: ≤ 0.10.
+
+export function brierScore(samples) {
+  if (!Array.isArray(samples) || samples.length === 0) return null;
+  let sum = 0, n = 0;
+  for (const s of samples) {
+    if (!s || typeof s.prediction !== 'number' || typeof s.actual !== 'number') continue;
+    const p = Math.max(0, Math.min(1, s.prediction));
+    const a = Math.max(0, Math.min(1, s.actual));
+    sum += (p - a) * (p - a);
+    n++;
+  }
+  return n > 0 ? sum / n : null;
+}
+
+// ─── Per-family calibration table ────────────────────────────────────────────
+//
+// Map<family, { tp, fp, n, calibrated, ci95 }>
+//   tp           — labeled true positives in this family
+//   fp           — labeled false positives in this family
+//   n            — tp + fp
+//   calibrated   — tp / n  (only set when n >= MIN_SAMPLES_FOR_CALIBRATION)
+//   ci95         — [lower, upper]
+
+export function buildCalibrationTable(history) {
+  if (!history || typeof history !== 'object') return {};
+  const out = {};
+  const families = history.families || history.perFamily || {};
+  for (const [fam, raw] of Object.entries(families)) {
+    if (!raw || typeof raw !== 'object') continue;
+    const tp = Number(raw.tp) || 0;
+    const fp = Number(raw.fp) || 0;
+    const n = tp + fp;
+    if (n === 0) continue;
+    const calibrated = n >= MIN_SAMPLES_FOR_CALIBRATION ? tp / n : null;
+    const ci95 = wilsonInterval(tp, n);
+    out[fam] = { tp, fp, n, calibrated, ci95 };
+  }
+  return out;
+}
+
+function _readJsonMaybe(fp) {
+  try { return JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { return null; }
+}
+
+// Load history from .agentic-security/validator-metrics.json + the bundled
+// seed file. The bundled seed ships with this release; the customer file
+// overrides per-family when N is higher there.
+export function loadCalibrationHistory(scanRoot) {
+  const customer = _readJsonMaybe(path.join(scanRoot || process.cwd(), '.agentic-security', 'validator-metrics.json')) || {};
+  const seedPath = new URL('./calibration-seed.json', import.meta.url);
+  let seed = null;
+  try { seed = JSON.parse(fs.readFileSync(seedPath, 'utf8')); } catch { seed = null; }
+  // Merge: customer takes precedence when its sample count is higher.
+  const families = {};
+  const merge = (src) => {
+    const fams = src?.families || src?.perFamily || {};
+    for (const [k, v] of Object.entries(fams)) {
+      if (!v || typeof v !== 'object') continue;
+      const tp = Number(v.tp) || 0, fp = Number(v.fp) || 0;
+      const n = tp + fp;
+      const cur = families[k];
+      if (!cur || n > cur.tp + cur.fp) families[k] = { tp, fp };
+    }
+  };
+  if (seed) merge(seed);
+  if (customer) merge(customer);
+  return { families };
+}
+
+// ─── Annotation ──────────────────────────────────────────────────────────────
+//
+// For each finding, set:
+//   f.calibrated_confidence       — number in [0,1] or null
+//   f.calibrated_confidence_ci    — [lower, upper] or null
+//   f.calibrated_n                — sample size used
+//   f.calibration_reason          — when null, why ("insufficient-samples" | "no-family")
+
+export function annotateCalibratedConfidence(findings, opts = {}) {
+  if (!Array.isArray(findings)) return;
+  const table = opts.table || buildCalibrationTable(opts.history || loadCalibrationHistory(opts.scanRoot));
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    const fam = f.family || null;
+    if (!fam) {
+      f.calibrated_confidence = null;
+      f.calibrated_confidence_ci = null;
+      f.calibrated_n = 0;
+      f.calibration_reason = 'no-family';
+      continue;
+    }
+    const row = table[fam];
+    if (!row || typeof row.calibrated !== 'number') {
+      f.calibrated_confidence = null;
+      f.calibrated_confidence_ci = null;
+      f.calibrated_n = row ? row.n : 0;
+      f.calibration_reason = row ? 'insufficient-samples' : 'no-history';
+      continue;
+    }
+    f.calibrated_confidence = round3(row.calibrated);
+    f.calibrated_confidence_ci = [round3(row.ci95[0]), round3(row.ci95[1])];
+    f.calibrated_n = row.n;
+    f.calibration_reason = null;
+  }
+}
+
+function round3(x) { return Math.round(x * 1000) / 1000; }
+
+// ─── Brier on held-out labels ───────────────────────────────────────────────
+//
+// Premortem #9: the previous `computeBrierFromHistory` was tautological — it
+// fed (prediction = row.calibrated, actual = row.calibrated) into brierScore
+// and always returned 0. That number is unsafe to surface anywhere because
+// readers will interpret it as "calibration is perfect," when it actually
+// measures nothing.
+//
+// The honest computation needs *held-out labels* — verdicts the engine did
+// NOT use to fit the calibration table. We accept those as an array of
+// { family, predicted, actual } where `predicted` is the calibrated rate
+// the model gave (e.g. f.calibrated_confidence) and `actual ∈ {0,1}` is
+// the human/system-confirmed truth.
+//
+// Callers must supply held-out data. There is no fallback that produces
+// a number from the seed corpus alone — that path is what produced the
+// tautology, and it should fail loudly instead.
+export function computeBrierOnHeldOut(samples) {
+  if (!Array.isArray(samples) || samples.length === 0) {
+    return { brier: null, reason: 'no-held-out-samples' };
+  }
+  const cleaned = [];
+  for (const s of samples) {
+    if (!s || typeof s !== 'object') continue;
+    const p = typeof s.predicted === 'number' ? Math.max(0, Math.min(1, s.predicted)) : null;
+    const a = typeof s.actual === 'number'
+      ? (s.actual >= 0.5 ? 1 : 0)
+      : (s.actual === true ? 1 : s.actual === false ? 0 : null);
+    if (p === null || a === null) continue;
+    cleaned.push({ prediction: p, actual: a });
+  }
+  if (!cleaned.length) return { brier: null, reason: 'no-valid-samples' };
+  const brier = brierScore(cleaned);
+  return { brier, n: cleaned.length };
+}
+
+// Removed: computeBrierFromHistory. Anyone relying on it for a dashboard
+// number should switch to computeBrierOnHeldOut(samples) with real labels.
+
+// For tests / introspection.
+export const _internals = { MIN_SAMPLES_FOR_CALIBRATION, Z_95, round3 };

package/src/posture/clustering.js

@@ -0,0 +1,75 @@
+// Root-cause clustering (FR-PREC-6).
+//
+// When a single missing sanitizer produces N flow paths converging on the
+// same sink expression, the engine emits N findings. This module collapses
+// them into one finding with `clusterSize` = N and `exampleFlows` containing
+// up to 5 representative paths. Downstream `/fix` operates on the cluster,
+// not on each leaf — one patch fixes all flows.
+//
+// Distinct from the existing `dedupeFindingsWithEvidence`, which clusters by
+// (file, sink-line, family). Root-cause clustering goes further: it clusters
+// across files when the sink shape and rule are identical, surfacing the
+// "one bug, N expressions of it" view.
+
+function sinkKey(f) {
+  // Cluster by the detector that fired + rule + file + a normalized form of
+  // the sink expression. We INTENTIONALLY do not cluster across files — the
+  // existing fix-bundling pipeline does that (one buggy helper called from N
+  // routes → one bundle of N findings). Clustering here is for the narrower
+  // case where a single sink has multiple flows feeding it within the same
+  // file.
+  //
+  // The parser tag MUST be in the key (bench-regression May 2026). Without it,
+  // two distinct detectors that happen to share a CWE and target the same
+  // sink line (e.g. structural Open Redirect + host-header redirect detector
+  // both flag CWE-601 on the same res.redirect line) collapse into one,
+  // hiding real findings. Each parser asks its own question; their findings
+  // are not redundant flows of the same vuln.
+  const parser = f.parser || '';
+  const rule = f.cwe || f.family || (f.vuln || '').slice(0, 40);
+  const file = f.file || f.sink?.file || '';
+  const sinkExpr = (f.sink?.label || f.sink?.snippet || f.snippet || '')
+    .replace(/['"`][^'"`]*['"`]/g, '_S_')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, 120);
+  // Empty sinkExpr keys cluster too eagerly (rate-limit findings that don't
+  // carry a snippet all land in the same bucket). Skip clustering entirely
+  // when we have no sink expression to compare.
+  if (!sinkExpr) return null;
+  return `${parser}::${rule}::${file}::${sinkExpr}`;
+}
+
+export function clusterByRootCause(findings) {
+  if (!Array.isArray(findings) || findings.length === 0) return findings;
+  const buckets = new Map();
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    const k = sinkKey(f);
+    if (!k) continue;
+    if (!buckets.has(k)) buckets.set(k, []);
+    buckets.get(k).push(f);
+  }
+  const drop = new Set();
+  for (const [, group] of buckets) {
+    if (group.length < 2) continue;
+    // Sort by severity (highest first), then by triageScore — keep the strongest.
+    const SEV = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+    group.sort((a, b) =>
+      (SEV[a.severity] ?? 9) - (SEV[b.severity] ?? 9) ||
+      (b.triageScore || 0) - (a.triageScore || 0)
+    );
+    const keeper = group[0];
+    keeper.clusterSize = group.length;
+    keeper.exampleFlows = group.slice(1, 6).map(f => ({
+      file: f.file || f.sink?.file,
+      line: f.line || f.sink?.line,
+      source: f.source ? { file: f.source.file, line: f.source.line, label: f.source.label } : null,
+      sink: f.sink ? { file: f.sink.file, line: f.sink.line, label: f.sink.label } : null,
+      snippet: f.snippet,
+    }));
+    for (let i = 1; i < group.length; i++) drop.add(group[i]);
+  }
+  if (!drop.size) return findings;
+  return findings.filter(f => !drop.has(f));
+}

package/src/posture/concurrency-checker.js

@@ -0,0 +1,265 @@
+// FR-SEM-9 — Bounded concurrency heuristic checker.
+//
+// A real model checker is research; this module ships the high-leverage
+// subset: regex-level detectors for the four most common concurrency bugs
+// commercial SAST misses.
+//
+//   1. Missed-unlock — `mutex.Lock()` / `lock.acquire()` / `synchronized` /
+//      `pthread_mutex_lock` without a matching unlock on every exit path
+//      within the same function body (early returns, exceptions).
+//   2. Data race — a shared variable (file-scope or struct field) written
+//      from a goroutine / async task / Worker without protection from a
+//      detected mutex/Lock/atomic primitive.
+//   3. Deadlock cycle — two functions where one acquires A then B and
+//      another acquires B then A. Bounded to ≤ 50 functions per scan.
+//   4. Fire-and-forget — async function that mutates shared state called
+//      without `await` (Node), `wait()` (Python), `.get()` (futures).
+//
+// Languages: Go, Java, JS/TS, Python. Each pattern is conservative — we
+// only emit when the surface evidence is unambiguous. Severity is medium
+// by default; family `concurrency-bug`.
+
+const PATTERNS = {
+  go: {
+    lockAcquire: /\b(\w+)\.Lock\(\)/g,
+    lockRelease: /\b(\w+)\.Unlock\(\)/g,
+    asyncStart: /\bgo\s+\w/g,
+    syncOnce: /\bsync\.Once\b/g,
+    shared: /^var\s+(\w+)\s+\w/gm,
+  },
+  java: {
+    lockAcquire: /\b(\w+)\.lock\(\)/g,
+    lockRelease: /\b(\w+)\.unlock\(\)/g,
+    synchronized: /\bsynchronized\s*\(/g,
+    asyncStart: /\bnew\s+Thread\(|\.start\(\)|@Async\b|CompletableFuture\.runAsync/g,
+  },
+  js: {
+    asyncFn: /\basync\s+function\s+\w+|async\s+\(/g,
+    asyncCallNoAwait: /^(?!.*\bawait\b).*\b\w+\s*\([^)]*\)\.then\(/gm,
+    workerPost: /\bworker\.postMessage\b/g,
+    sharedAt: /^(?:const|let|var)\s+(\w+)\s*=/gm,
+  },
+  py: {
+    lockAcquire: /\b(\w+)\.acquire\(\)/g,
+    lockRelease: /\b(\w+)\.release\(\)/g,
+    asyncDef: /\basync\s+def\s+\w+/g,
+    asyncCallNoAwait: /^(?!.*\bawait\b).*\basyncio\.create_task\(/gm,
+  },
+};
+
+function inferLang(fp) {
+  if (/\.go$/i.test(fp)) return 'go';
+  if (/\.(java|kt)$/i.test(fp)) return 'java';
+  if (/\.(js|jsx|ts|tsx|mjs|cjs)$/i.test(fp)) return 'js';
+  if (/\.py$/i.test(fp)) return 'py';
+  return null;
+}
+
+// Walk a function body and collect lock acquire/release pairs.
+// Naive: assume single-block functions. Good enough for the common case.
+function extractFunctions(text, lang) {
+  const out = [];
+  let m;
+  if (lang === 'go') {
+    const re = /func(?:\s+\(\w+\s+\*?\w+\))?\s+(\w+)\s*\([^)]*\)[^{]*\{/g;
+    while ((m = re.exec(text))) {
+      const body = grabBody(text, m.index + m[0].length - 1);
+      if (body) out.push({ name: m[1], body, startLine: text.slice(0, m.index).split('\n').length });
+    }
+  } else if (lang === 'java') {
+    const re = /(?:public|private|protected|static|final|synchronized)\s+[\w<>,\s\[\]]+\s+(\w+)\s*\([^)]*\)\s*(?:throws\s+[\w,\s]+)?\s*\{/g;
+    while ((m = re.exec(text))) {
+      const body = grabBody(text, m.index + m[0].length - 1);
+      if (body) out.push({ name: m[1], body, startLine: text.slice(0, m.index).split('\n').length });
+    }
+  } else if (lang === 'js') {
+    const re = /(?:function\s+(\w+)\s*\(|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?\([^)]*\)\s*=>)/g;
+    while ((m = re.exec(text))) {
+      const braceIdx = text.indexOf('{', m.index);
+      if (braceIdx < 0) continue;
+      const body = grabBody(text, braceIdx);
+      if (body) out.push({ name: m[1] || m[2], body, startLine: text.slice(0, m.index).split('\n').length });
+    }
+  } else if (lang === 'py') {
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+      const m2 = /^def\s+(\w+)\s*\(|^async\s+def\s+(\w+)\s*\(/.exec(lines[i]);
+      if (!m2) continue;
+      const name = m2[1] || m2[2];
+      const body = lines.slice(i, Math.min(i + 80, lines.length)).join('\n');
+      out.push({ name, body, startLine: i + 1 });
+    }
+  }
+  return out;
+}
+
+function grabBody(text, openBraceIdx) {
+  if (text[openBraceIdx] !== '{') return null;
+  let depth = 0;
+  for (let i = openBraceIdx; i < Math.min(openBraceIdx + 8000, text.length); i++) {
+    if (text[i] === '{') depth++;
+    else if (text[i] === '}') {
+      depth--;
+      if (depth === 0) return text.slice(openBraceIdx, i + 1);
+    }
+  }
+  return null;
+}
+
+function findMissedUnlocks(fn, lang) {
+  const out = [];
+  const p = PATTERNS[lang];
+  if (!p || !p.lockAcquire || !p.lockRelease) return out;
+  const acquires = [...fn.body.matchAll(p.lockAcquire)];
+  const releases = [...fn.body.matchAll(p.lockRelease)];
+  if (!acquires.length) return out;
+  // For each acquired lock name, check at least one release in the body.
+  const acquiredNames = new Set(acquires.map(m => m[1]));
+  const releasedNames = new Set(releases.map(m => m[1]));
+  for (const name of acquiredNames) {
+    if (!releasedNames.has(name)) {
+      out.push({
+        kind: 'missed-unlock',
+        lock: name,
+        functionName: fn.name,
+        startLine: fn.startLine,
+      });
+    } else {
+      // Lock+unlock both present, but check that the function has a defer/
+      // try-finally guarantee. Go: `defer`; Java/Py: try/finally; otherwise
+      // early-return-before-unlock is a risk.
+      const guarded =
+        (lang === 'go' && /defer\s+\w+\.Unlock\(\)/.test(fn.body)) ||
+        (lang === 'java' && /try\s*\{[\s\S]*finally\s*\{[\s\S]*\.unlock\(\)/m.test(fn.body)) ||
+        (lang === 'py' && (/with\s+\w+:/.test(fn.body) || /try\s*:[\s\S]*finally\s*:[\s\S]*\.release\(\)/m.test(fn.body)));
+      if (!guarded && /\breturn\b/.test(fn.body)) {
+        out.push({
+          kind: 'unguarded-lock',
+          lock: name,
+          functionName: fn.name,
+          startLine: fn.startLine,
+          remediation: lang === 'go' ? 'use `defer mu.Unlock()`' :
+                       lang === 'java' ? 'wrap in try/finally with unlock in finally' :
+                       lang === 'py' ? 'use `with lock:` context manager' :
+                       'guarantee release on every exit path',
+        });
+      }
+    }
+  }
+  return out;
+}
+
+function findFireAndForget(fn, lang) {
+  const out = [];
+  const p = PATTERNS[lang];
+  if (!p || !p.asyncCallNoAwait) return out;
+  let m;
+  p.asyncCallNoAwait.lastIndex = 0;
+  while ((m = p.asyncCallNoAwait.exec(fn.body))) {
+    if (/\bvoid\s/.test(m[0])) continue;        // explicit void = intentional
+    out.push({
+      kind: 'fire-and-forget',
+      functionName: fn.name,
+      startLine: fn.startLine,
+      snippet: m[0].slice(0, 80),
+    });
+  }
+  return out;
+}
+
+function findDeadlockCycles(fns) {
+  // Build a graph: function → list of lock pairs acquired in order.
+  // Cycle if A acquires (x,y) and B acquires (y,x) somewhere — even when
+  // distinct calls are interleaved at runtime.
+  const lockOrders = [];
+  for (const fn of fns) {
+    const acquires = [...fn.body.matchAll(/\b(\w+)\.(?:Lock|lock|acquire)\(\)/g)].map(m => m[1]);
+    const distinct = [...new Set(acquires)];
+    if (distinct.length >= 2) {
+      lockOrders.push({ fn: fn.name, startLine: fn.startLine, pairs: pairsOf(distinct) });
+    }
+    if (lockOrders.length > 50) break;          // bounded
+  }
+  const out = [];
+  for (let i = 0; i < lockOrders.length; i++) {
+    for (let j = i + 1; j < lockOrders.length; j++) {
+      const a = lockOrders[i], b = lockOrders[j];
+      for (const [x, y] of a.pairs) {
+        for (const [bx, by] of b.pairs) {
+          if (x === by && y === bx) {
+            out.push({
+              kind: 'deadlock-cycle',
+              functionA: a.fn,
+              functionB: b.fn,
+              order: `${a.fn} locks (${x}, ${y}); ${b.fn} locks (${bx}, ${by})`,
+              startLineA: a.startLine,
+              startLineB: b.startLine,
+            });
+          }
+        }
+      }
+    }
+  }
+  return out;
+}
+
+function pairsOf(arr) {
+  const p = [];
+  for (let i = 0; i < arr.length; i++)
+    for (let j = i + 1; j < arr.length; j++) p.push([arr[i], arr[j]]);
+  return p;
+}
+
+export function scanConcurrency(fileContents) {
+  const findings = [];
+  if (!fileContents) return findings;
+  for (const [fp, text] of Object.entries(fileContents)) {
+    const lang = inferLang(fp);
+    if (!lang || !text) continue;
+    const fns = extractFunctions(text, lang);
+    if (!fns.length) continue;
+
+    for (const fn of fns) {
+      for (const bug of findMissedUnlocks(fn, lang)) {
+        findings.push({
+          id: `concurrency:${bug.kind}:${fp}:${bug.startLine}:${bug.lock}`,
+          file: fp,
+          line: bug.startLine,
+          vuln: bug.kind === 'missed-unlock'
+            ? `Concurrency: ${fn.name}() acquires ${bug.lock} but no matching unlock`
+            : `Concurrency: ${fn.name}() can return without releasing ${bug.lock}`,
+          severity: 'medium',
+          family: 'concurrency-bug',
+          confidence: 0.5,
+          remediation: bug.remediation || 'Release the lock on every exit path (defer / try-finally / context manager).',
+        });
+      }
+      for (const bug of findFireAndForget(fn, lang)) {
+        findings.push({
+          id: `concurrency:fire-forget:${fp}:${bug.startLine}`,
+          file: fp,
+          line: bug.startLine,
+          vuln: `Concurrency: fire-and-forget async call in ${fn.name}() — result not awaited`,
+          severity: 'low',
+          family: 'concurrency-bug',
+          confidence: 0.4,
+          remediation: 'Await the promise / call .get() on the future / use asyncio.gather.',
+        });
+      }
+    }
+
+    for (const bug of findDeadlockCycles(fns)) {
+      findings.push({
+        id: `concurrency:deadlock:${fp}:${bug.startLineA}-${bug.startLineB}`,
+        file: fp,
+        line: bug.startLineA,
+        vuln: `Concurrency: potential deadlock — ${bug.order}`,
+        severity: 'high',
+        family: 'concurrency-bug',
+        confidence: 0.4,
+        remediation: 'Acquire locks in a consistent global order across all call sites.',
+      });
+    }
+  }
+  return findings;
+}

package/src/posture/confidence.js

@@ -0,0 +1,65 @@
+// Calibrated confidence score (0.0–1.0) per finding.
+//
+// Layered on top of the existing triage score, evidence count, parser type,
+// and sanitizer signals. Maps the engine's various internal trust signals
+// into a single normalized field that downstream consumers (Claude Code UX,
+// SARIF emit, validator pipelines) can rely on.
+//
+// Output:
+//   f.confidence ∈ [0,1]   — combined confidence the finding is real
+//   f.confidenceTier       — 'high' | 'medium' | 'low' | 'very-low'
+//
+// Existing fields preserved (triageScore/triageLabel are unchanged).
+
+const PARSER_PRIOR = {
+  AST: 0.10,        // AST detectors are precise
+  CHAIN: 0.12,      // attack chains are confirmed by multiple findings
+  CONFIRMED: 0.20,  // explicitly confirmed by cross-file taint
+  VALIDATOR: 0.25,  // LLM validator accepted
+};
+
+const SEVERITY_PRIOR = {
+  critical: 0.85,
+  high: 0.75,
+  medium: 0.55,
+  low: 0.35,
+  info: 0.20,
+};
+
+export function annotateConfidence(findings) {
+  if (!Array.isArray(findings)) return;
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    // If the finding already shipped with a hand-tuned confidence (e.g. jwt-exp
+    // emits 0.85/0.95), keep that but still normalize the tier label.
+    let conf = typeof f.confidence === 'number' ? f.confidence : null;
+    if (conf == null) {
+      conf = SEVERITY_PRIOR[f.severity] ?? 0.40;
+      // Triage score in [0,100] is the strongest signal we have today; weight it.
+      if (typeof f.triageScore === 'number') {
+        conf = 0.5 * conf + 0.5 * (f.triageScore / 100);
+      }
+      const parserBoost = PARSER_PRIOR[f.parser] || 0;
+      conf = Math.min(1, conf + parserBoost);
+      if (f.evidence && f.evidence.length > 1) conf = Math.min(1, conf + 0.05 * (f.evidence.length - 1));
+      if (f.sanitizerMismatch) conf = Math.min(1, conf + 0.05);
+      if (f.isSanitized) conf *= 0.10;
+      if (f.routeRooted) conf = Math.min(1, conf + 0.05);
+      if (f.guards && f.guards.length) conf *= 0.80;
+      if (f.reachable === false) conf *= 0.55;
+      if (f.unvalidated) conf *= 0.85;   // LLM validator unavailable
+      if (f.llmOnly) conf *= 0.70;       // LLM-only finding, no Layer-2 path
+    }
+    conf = Math.max(0, Math.min(1, conf));
+    f.confidence = Math.round(conf * 1000) / 1000;
+    // Premortem 3R-15: derive tier from the 2-decimal display value so a
+    // finding reported as "0.75" never lands in two tiers depending on the
+    // viewer's rounding. Add a +0.005 epsilon to anchor cutoffs to the
+    // displayed rounded value (3-decimal raw 0.745 → 2-decimal 0.75 → high).
+    const display = Math.round(f.confidence * 100) / 100;
+    if (display >= 0.75) f.confidenceTier = 'high';
+    else if (display >= 0.50) f.confidenceTier = 'medium';
+    else if (display >= 0.25) f.confidenceTier = 'low';
+    else f.confidenceTier = 'very-low';
+  }
+}