@clear-capabilities/agentic-security-scanner 0.74.0

package/src/posture/exploitability-probability.js

@@ -0,0 +1,212 @@
+// Probabilistic exploitability with Wilson 95% confidence intervals (v0.68).
+//
+// Replaces opaque severity strings with a calibrated number per finding:
+//   f.exploitProbability      ∈ [0,1]        — Bayesian point estimate
+//   f.exploitProbabilityCI95  [lo, hi]       — Wilson interval on point
+//   f.exploitProbabilityWhy   string[]       — feature names that fired
+//
+// This is the COMPLEMENT to `exploitability.js`, which is intentionally an
+// ordinal priority (sort key). This module is the calibrated probability
+// you'd put on a slide or stake a budget on.
+//
+// Inputs (per finding + context):
+//   - finding.cwe                     CWE family
+//   - finding.parser, finding.family  detector identity
+//   - taint signals (`trace`, `chain`, source provenance)
+//   - reachability tier from posture/reachability-filter.js (set externally)
+//   - project context: hasAuth / hasWAF / hasCSP / route_unauth
+//   - historical signal: .agentic-security/exploit-history.jsonl (operator-
+//     curated record of past confirmed exploits per CWE family).
+//
+// Method:
+//   1. Start with a CWE-family prior (CISA-KEV-aggregated base rate).
+//   2. Multiplicatively update with feature factors (reachability +,
+//      sanitizer-present −, auth/WAF/CSP −, source-from-network +).
+//   3. Wilson CI computed from operator's historical hit rate at finer
+//      grain (CWE × language × framework) when enough samples exist; falls
+//      back to wider CI from the global CWE-family prior otherwise.
+//
+// Important: this is NOT yet a calibrated statistical model. It's a
+// principled heuristic that EXPOSES its uncertainty via the CI rather than
+// hiding it behind a severity label. The CI width is the honest signal —
+// when n is small or factors conflict, the interval gets wide on purpose.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { wilsonInterval } from './calibration.js';
+
+// CISA KEV-derived base rate per CWE family. These are rough mid-2025
+// observations of "actually exploited in the wild" rates among findings
+// of the family, not academic numbers. Refresh annually.
+const CWE_BASE_RATE = {
+  'CWE-78':   0.50,   // command injection
+  'CWE-89':   0.55,   // SQLi
+  'CWE-79':   0.35,   // XSS
+  'CWE-22':   0.40,   // path traversal
+  'CWE-918':  0.40,   // SSRF
+  'CWE-502':  0.55,   // deserialization
+  'CWE-94':   0.55,   // code injection / SSTI
+  'CWE-611':  0.30,   // XXE
+  'CWE-1321': 0.45,   // prototype pollution
+  'CWE-352':  0.20,   // CSRF
+  'CWE-601':  0.20,   // open redirect (low impact alone, often a chain link)
+  'CWE-113':  0.30,   // response splitting
+  'CWE-798':  0.65,   // hardcoded secrets — when the secret leaks, exploit is immediate
+  'CWE-90':   0.40,   // LDAP injection
+  'CWE-643':  0.40,   // XPath injection
+  'CWE-1333': 0.25,   // ReDoS — exploitation often DoS only
+  'CWE-327':  0.25,   // weak crypto — usually requires chained access
+  'CWE-329':  0.30,   // static IV
+  'CWE-338':  0.30,   // weak RNG
+  'CWE-916':  0.40,   // weak password hash
+  'CWE-1336': 0.40,   // prompt injection
+  'CWE-269':  0.45,   // privilege escalation
+};
+
+const DEFAULT_BASE_RATE = 0.30;
+
+// Multiplicative factors. The point estimate is base * Π(factors), clamped
+// to (0, 1). Factor > 1 raises the probability; factor < 1 lowers it. We
+// also collect which factors fired into `why`.
+const FACTORS = [
+  // POSITIVE (raise probability)
+  {
+    name: 'reachable-from-public-route',
+    factor: 1.5,
+    test: (f) => f.reachabilityTier === 'reachable-public' || f.reachabilityTier === 'public-unauthed',
+  },
+  {
+    name: 'source-from-network',
+    factor: 1.3,
+    test: (f) => (f.trace || f.chain || []).some(t =>
+      /http-body|url-param|header|cookie/i.test(t.provenance || '')),
+  },
+  {
+    name: 'critical-severity-detector',
+    factor: 1.15,
+    test: (f) => f.severity === 'critical',
+  },
+  {
+    name: 'cwe-on-cisa-kev',
+    factor: 1.25,
+    test: (f) => !!f.kevReferenced,
+  },
+  // NEGATIVE (lower probability)
+  {
+    name: 'sanitizer-in-path',
+    factor: 0.5,
+    test: (f) => Array.isArray(f.sanitizerCallsInPath) && f.sanitizerCallsInPath.length > 0,
+  },
+  {
+    name: 'auth-middleware-on-route',
+    factor: 0.6,
+    test: (f) => f.routeAuth === true,
+  },
+  {
+    name: 'project-has-waf',
+    factor: 0.75,
+    test: (f, ctx) => ctx && ctx.hasWAF === true,
+  },
+  {
+    name: 'project-has-csp',
+    factor: 0.85,
+    test: (f, ctx) => ctx && ctx.hasCSP === true && /CWE-79|xss/i.test(f.cwe || f.family || ''),
+  },
+  {
+    name: 'low-severity-detector',
+    factor: 0.6,
+    test: (f) => f.severity === 'low' || f.severity === 'info',
+  },
+  {
+    name: 'unreachable',
+    factor: 0.1,
+    test: (f) => f.unreachable === true,
+  },
+];
+
+function _basePrior(cwe) {
+  if (!cwe) return DEFAULT_BASE_RATE;
+  return CWE_BASE_RATE[cwe] || DEFAULT_BASE_RATE;
+}
+
+function _clamp01(x) { return Math.max(0.001, Math.min(0.999, x)); }
+
+// Operator-curated exploit history. JSONL, one row per past confirmed
+// exploit:  {"cwe": "CWE-89", "language": "javascript", "framework": "express",
+//            "verdict": "true_positive_exploited" | "false_positive"}
+// Used to refine the Wilson CI when enough samples exist at the
+// (cwe × language × framework) grain.
+function _loadHistory(scanRoot) {
+  if (!scanRoot) return [];
+  const fp = path.join(scanRoot, '.agentic-security', 'exploit-history.jsonl');
+  if (!fs.existsSync(fp)) return [];
+  const out = [];
+  try {
+    for (const line of fs.readFileSync(fp, 'utf8').split('\n')) {
+      const t = line.trim();
+      if (!t) continue;
+      try {
+        const o = JSON.parse(t);
+        if (o && o.cwe && o.verdict) out.push(o);
+      } catch {}
+    }
+  } catch {}
+  return out;
+}
+
+function _historicalCi(history, cwe, language) {
+  if (!Array.isArray(history) || history.length === 0) return null;
+  // Tier the slice: prefer (cwe × language) when n ≥ 5, fall back to cwe
+  // alone when n ≥ 10, fall back to nothing when neither slice has volume.
+  const cl = history.filter(h => h.cwe === cwe && h.language === language);
+  const c  = history.filter(h => h.cwe === cwe);
+  let pool, sliceName;
+  if (cl.length >= 5) { pool = cl; sliceName = `${cwe}×${language}`; }
+  else if (c.length >= 10) { pool = c; sliceName = cwe; }
+  else return null;
+  const tp = pool.filter(h => h.verdict === 'true_positive_exploited').length;
+  const n = pool.length;
+  return { ci: wilsonInterval(tp, n), p: tp / n, n, slice: sliceName };
+}
+
+// Public entry. Annotates each finding in `findings` with
+// exploitProbability + exploitProbabilityCI95 + exploitProbabilityWhy.
+//
+// Pure function over findings — returns the same array.
+export function annotateExploitProbability(findings, ctx = {}) {
+  if (!Array.isArray(findings) || findings.length === 0) return findings;
+  const history = _loadHistory(ctx.scanRoot);
+  for (const f of findings) {
+    const cwe = f.cwe || null;
+    const why = [];
+    let p = _basePrior(cwe);
+    for (const F of FACTORS) {
+      try {
+        if (F.test(f, ctx)) { p *= F.factor; why.push(F.name); }
+      } catch {}
+    }
+    p = _clamp01(p);
+    // Wilson CI: prefer historical CI when we have one, otherwise derive
+    // a wider CI from the prior (n=10 implied sample at base rate).
+    const hist = _historicalCi(history, cwe, f.language || (f.file || '').split('.').pop());
+    if (hist) {
+      f.exploitProbability = hist.p;
+      f.exploitProbabilityCI95 = hist.ci;
+      f.exploitProbabilitySlice = hist.slice;
+      f.exploitProbabilityN = hist.n;
+    } else {
+      // Wilson with a synthetic n=10 "prior pseudo-observations" at the
+      // updated probability — gives a wide CI when we have no data.
+      const tp = Math.round(p * 10);
+      f.exploitProbability = p;
+      f.exploitProbabilityCI95 = wilsonInterval(tp, 10);
+      f.exploitProbabilitySlice = 'prior-only';
+      f.exploitProbabilityN = 10;
+    }
+    f.exploitProbabilityWhy = why;
+  }
+  return findings;
+}
+
+// Convenience for tests / diagnostics.
+export const _internal = { CWE_BASE_RATE, DEFAULT_BASE_RATE, FACTORS, _basePrior };

package/src/posture/exploitability.js

@@ -0,0 +1,121 @@
+// Exploitability scoring (FR-PREC-3) — ORDINAL PRIORITY, NOT A PROBABILITY.
+//
+// The output is a 0–1 ordinal priority score used to rank findings, NOT a
+// calibrated probability. The weights below are hand-picked heuristics and
+// have not been calibrated against a labeled outcome set. Treat the number
+// as "use this to sort, not to bet money on."
+//
+// In particular, do NOT:
+//   - render the score as a percentage in customer-facing UI ("95% likely
+//     to be exploited" implies a precision the score doesn't have)
+//   - feed the score into a downstream pricing / risk-acceptance decision
+//   - aggregate it across findings (average exploitability is meaningless)
+//
+// DO use it for:
+//   - ranking findings within a single scan ("show me the top 10")
+//   - tier labels (critical/high/medium/low) which intentionally collapse
+//     the score into coarse buckets
+//
+// To turn this into a calibrated probability, you need a labeled outcome
+// dataset (PRs merged with no incident vs. PRs that became incidents) and
+// isotonic regression. See PRD §10 / bench/README.md for the open work.
+//
+// Output:
+//   f.exploitability ∈ [0,1]          — ordinal priority score
+//   f.priorityScore = f.exploitability — explicit alias for new callers
+//   f.exploitabilityFactors: string[]  — which signals contributed
+//   f.exploitabilityTier: 'critical' | 'high' | 'medium' | 'low'
+
+const SEVERITY_BASE = {
+  critical: 0.80,
+  high: 0.65,
+  medium: 0.40,
+  low: 0.20,
+  info: 0.10,
+};
+
+// Detected from project signals — passed in via ctx.
+//   ctx.hasCSP        — Content-Security-Policy header configured
+//   ctx.hasHelmet     — helmet middleware present
+//   ctx.hasWAF        — WAF / Cloudflare rules ingested
+//   ctx.hasAuth       — auth middleware/guards detected somewhere
+//   ctx.unauthRoutes  — count of routes that lack auth on the project
+export function detectProjectContext(fc, routes) {
+  const ctx = {
+    hasCSP: false,
+    hasHelmet: false,
+    hasWAF: false,
+    hasAuth: false,
+    unauthRoutes: 0,
+  };
+  if (!fc) return ctx;
+  for (const [fp, c] of Object.entries(fc)) {
+    if (!c || typeof c !== 'string') continue;
+    if (!ctx.hasCSP && /content[-_]security[-_]policy|Content-Security-Policy/i.test(c)) ctx.hasCSP = true;
+    if (!ctx.hasHelmet && /\bhelmet\s*\(/.test(c)) ctx.hasHelmet = true;
+    if (!ctx.hasWAF && /(cloudflare|aws[-_]?waf|akamai[-_]?waf|fastly[-_]?waf)/i.test(c)) ctx.hasWAF = true;
+    if (!ctx.hasAuth && /(passport\.|express-jwt|requireAuth|requires?_login|@login_required|isAuthenticated|verifyJWT)/i.test(c)) ctx.hasAuth = true;
+    void fp;
+  }
+  if (Array.isArray(routes)) ctx.unauthRoutes = routes.filter(r => r && r.unauthed).length;
+  return ctx;
+}
+
+function scoreOne(f, ctx) {
+  const factors = [];
+  let s = SEVERITY_BASE[f.severity] ?? 0.30;
+  factors.push(`sev:${f.severity}`);
+
+  // Reachability from entry points raises exploitability sharply.
+  if (f.routeRooted) { s += 0.20; factors.push('route-rooted'); }
+  else if (f.reachable === true) { s += 0.10; factors.push('reachable'); }
+  else if (f.reachable === false) { s -= 0.20; factors.push('unreachable'); }
+
+  // Auth gating on the path lowers it.
+  if (f.guards && f.guards.length) { s -= 0.15; factors.push(`guards:${f.guards.length}`); }
+
+  // Sanitized paths are very low.
+  if (f.isSanitized) { s = Math.min(s, 0.10); factors.push('sanitized'); }
+  if (f.sanitizerMismatch) { s += 0.10; factors.push('sanitizer-mismatch'); }
+
+  // SCA enrichment: KEV-listed vulns are by definition actively exploited;
+  // EPSS percentile ≥ 0.95 puts the CVE in the "exploited now" cohort.
+  if (f.kev || f.kevListed) { s = Math.max(s, 0.92); factors.push('kev'); }
+  if (typeof f.epssPercentile === 'number' && f.epssPercentile >= 0.95) {
+    s = Math.max(s, 0.85); factors.push('epss>=p95');
+  }
+  if (f.exploitedNow) { s = Math.max(s, 0.85); factors.push('exploited-now'); }
+
+  // Project-wide mitigations reduce exploitability.
+  if (ctx) {
+    if (ctx.hasCSP && /xss/i.test(f.family || f.vuln || '')) { s -= 0.10; factors.push('csp-present'); }
+    if (ctx.hasHelmet) { s -= 0.05; factors.push('helmet'); }
+    if (ctx.hasWAF) { s -= 0.05; factors.push('waf'); }
+    if (!ctx.hasAuth && f.routeRooted) { s += 0.10; factors.push('no-auth-middleware'); }
+  }
+
+  s = Math.max(0, Math.min(1, s));
+  // Round to 2 decimals — the score is ordinal, not calibrated. Three
+  // decimals of precision suggested precision the model doesn't have.
+  return { score: Math.round(s * 100) / 100, factors };
+}
+
+export function annotateExploitability(findings, ctx) {
+  if (!Array.isArray(findings)) return;
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    try {
+      const { score, factors } = scoreOne(f, ctx);
+      f.exploitability = score;
+      f.priorityScore = score;  // ordinal-priority alias; new code should use this name
+      f.exploitabilityFactors = factors;
+      f._scoreIsOrdinal = true;  // marker so downstream code knows not to treat as probability
+      if (score >= 0.80) f.exploitabilityTier = 'critical';
+      else if (score >= 0.60) f.exploitabilityTier = 'high';
+      else if (score >= 0.35) f.exploitabilityTier = 'medium';
+      else f.exploitabilityTier = 'low';
+    } catch {
+      f.exploitability = null;
+    }
+  }
+}

package/src/posture/feature-flags.js

@@ -0,0 +1,110 @@
+// FR-PROD-6 — Feature-flag awareness.
+//
+// When a security finding lives behind a feature-flag check, its real-world
+// exposure depends on the flag's rollout state, not on the code itself.
+// A flag at 0% rollout is `info`; the same code at 100% is `critical`.
+//
+// This module recognizes flag-gated code regions for the major providers:
+//   - LaunchDarkly (`ldClient.variation`, `useFlag`)
+//   - Statsig (`Statsig.checkGate`, `useGate`)
+//   - ConfigCat (`configCatClient.getValue`)
+//   - Unleash (`unleash.isEnabled`)
+//   - OpenFeature (`client.getBooleanValue`)
+//   - Vercel Flags (`@vercel/flags`)
+//   - Custom env-var flags (`process.env.FEATURE_X === 'true'`)
+//
+// We tag findings with the gating flag name when detected. Rollout percentage
+// can be supplied via `.agentic-security/feature-flag-rollouts.json` (a map
+// of flag name → percentage 0..100); if absent, default to 100% (assume the
+// flag is on) — fail-open against the security side.
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+
+const FLAG_PATTERNS = [
+  // LaunchDarkly
+  [/\bldClient\.variation\s*\(\s*['"`]([^'"`]+)['"`]/g, 'launchdarkly'],
+  [/\buseFlag\s*\(\s*['"`]([^'"`]+)['"`]/g, 'launchdarkly'],
+  [/\bvariation\s*\(\s*['"`]([^'"`]+)['"`]/g, 'launchdarkly'],
+  // Statsig
+  [/\bStatsig\.(?:checkGate|getExperiment|getConfig)\s*\(\s*['"`]([^'"`]+)['"`]/g, 'statsig'],
+  [/\buseGate\s*\(\s*['"`]([^'"`]+)['"`]/g, 'statsig'],
+  // ConfigCat
+  [/\bconfigCatClient\.getValue\s*\(\s*['"`]([^'"`]+)['"`]/g, 'configcat'],
+  // Unleash
+  [/\bunleash\.isEnabled\s*\(\s*['"`]([^'"`]+)['"`]/g, 'unleash'],
+  // OpenFeature
+  [/\b(?:client|of)\.get(?:Boolean|String|Number)Value\s*\(\s*['"`]([^'"`]+)['"`]/g, 'openfeature'],
+  // Vercel
+  [/\b(?:flag|getFlag|flags)\s*\(\s*['"`]([^'"`]+)['"`]/g, 'vercel-or-generic'],
+  // env-var flags
+  [/process\.env\.(FEATURE_[A-Z0-9_]+)\s*===?\s*['"`]?(?:true|1)/g, 'env-var'],
+  [/process\.env\.(FF_[A-Z0-9_]+)\s*===?\s*['"`]?(?:true|1)/g, 'env-var'],
+];
+
+function loadRollouts(scanRoot) {
+  const candidates = [
+    '.agentic-security/feature-flag-rollouts.json',
+    '.agentic-security/feature-flags.json',
+  ];
+  for (const rel of candidates) {
+    const fp = path.join(scanRoot || process.cwd(), rel);
+    try {
+      if (fs.existsSync(fp)) {
+        const data = JSON.parse(fs.readFileSync(fp, 'utf8'));
+        if (data && typeof data === 'object') return data;
+      }
+    } catch {}
+  }
+  return null;
+}
+
+// Walk every file once and build a map: file → list of { flagName, line, vendor }.
+// Cheap regex scan, suitable to call per-scan.
+export function detectFlagSites(fileContents) {
+  const out = {};
+  if (!fileContents || typeof fileContents !== 'object') return out;
+  for (const [fp, text] of Object.entries(fileContents)) {
+    if (!text || typeof text !== 'string') continue;
+    const sample = text.length > 100_000 ? text.slice(0, 100_000) : text;
+    const hits = [];
+    for (const [re, vendor] of FLAG_PATTERNS) {
+      re.lastIndex = 0;
+      let m;
+      while ((m = re.exec(sample))) {
+        const flagName = m[1];
+        const line = sample.slice(0, m.index).split('\n').length;
+        hits.push({ flagName, vendor, line });
+      }
+    }
+    if (hits.length) out[fp] = hits;
+  }
+  return out;
+}
+
+// For each finding, search ±20 lines around the finding location in its file
+// for a flag site. If found, tag with the controlling flag and rollout %.
+export function annotateFeatureFlagGating(findings, fileContents, opts = {}) {
+  if (!Array.isArray(findings)) return findings;
+  const rollouts = opts.rollouts || loadRollouts(opts.scanRoot);
+  const sites = detectFlagSites(fileContents || {});
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    const fp = f.file;
+    const ln = f.line || 0;
+    if (!fp || !sites[fp]) continue;
+    const window = 20;
+    const nearby = sites[fp].find(s => Math.abs(s.line - ln) <= window);
+    if (!nearby) continue;
+    f.featureFlag = nearby.flagName;
+    f.featureFlagVendor = nearby.vendor;
+    const rollout = rollouts && Object.prototype.hasOwnProperty.call(rollouts, nearby.flagName)
+      ? Number(rollouts[nearby.flagName])
+      : 100;
+    f.featureFlagRollout = Number.isFinite(rollout) ? Math.max(0, Math.min(100, rollout)) : 100;
+    if (f.featureFlagRollout === 0) f.featureFlagState = 'gated-off';
+    else if (f.featureFlagRollout < 100) f.featureFlagState = 'partial-rollout';
+    else f.featureFlagState = 'fully-rolled-out';
+  }
+  return findings;
+}

package/src/posture/finding-defaults.js

@@ -0,0 +1,132 @@
+// Premortem #8: backfill the `parser` and `family` fields on every finding.
+//
+// Symptom this fixes: a smoke run on test/fixtures/vulnerable-js reported 31
+// findings, all with `parser: null` — which silenced the PARSER_PRIOR boost in
+// confidence.js, AND 20/31 had `family: null` — which silenced the entire
+// calibration table in calibration.js. The annotation pipeline downstream
+// expected these fields to be set by every detector, but most regex-style
+// detectors emit a plain Finding shape without them.
+//
+// We backfill, never overwrite. Detector-set values win.
+
+// Lightweight family inference. CWE-based first, then title/vuln keyword.
+const _CWE_FAMILY = {
+  'CWE-78':  'command-injection',
+  'CWE-79':  'xss',
+  'CWE-80':  'xss',
+  'CWE-87':  'xss',
+  'CWE-89':  'sql-injection',
+  'CWE-90':  'ldap-injection',
+  'CWE-91':  'xpath-injection',
+  'CWE-94':  'code-injection',
+  'CWE-22':  'path-traversal',
+  'CWE-23':  'path-traversal',
+  'CWE-36':  'path-traversal',
+  'CWE-200': 'info-disclosure',
+  'CWE-209': 'info-disclosure',
+  'CWE-256': 'hardcoded-secret',
+  'CWE-259': 'hardcoded-secret',
+  'CWE-287': 'broken-auth',
+  'CWE-295': 'cert-validation',
+  'CWE-306': 'broken-auth',
+  'CWE-307': 'rate-limit',
+  'CWE-326': 'weak-crypto',
+  'CWE-327': 'weak-crypto',
+  'CWE-328': 'weak-crypto',
+  'CWE-329': 'weak-crypto',
+  'CWE-330': 'weak-rng',
+  'CWE-338': 'weak-rng',
+  'CWE-345': 'integrity',
+  'CWE-352': 'csrf',
+  'CWE-384': 'session-fixation',
+  'CWE-434': 'unrestricted-upload',
+  'CWE-502': 'insecure-deserialization',
+  'CWE-601': 'open-redirect',
+  'CWE-611': 'xxe',
+  'CWE-639': 'idor',
+  'CWE-640': 'broken-auth',
+  'CWE-732': 'permissions',
+  'CWE-770': 'rate-limit',
+  'CWE-776': 'xxe',
+  'CWE-798': 'hardcoded-secret',
+  'CWE-829': 'supply-chain',
+  'CWE-862': 'broken-authz',
+  'CWE-863': 'broken-authz',
+  'CWE-915': 'mass-assignment',
+  'CWE-918': 'ssrf',
+  'CWE-1004': 'cookie-flag',
+  'CWE-1021': 'clickjacking',
+  'CWE-1287': 'idor',
+  'CWE-1321': 'prototype-pollution',
+  'CWE-1333': 'redos',
+};
+
+const _KEYWORD_FAMILY = [
+  [/sql\s*injection/i,       'sql-injection'],
+  [/command\s*injection/i,   'command-injection'],
+  [/code\s*injection|eval|insecure\s*eval/i, 'code-injection'],
+  [/cross[-\s]?site\s*scripting|\bxss\b/i,    'xss'],
+  [/path\s*traversal|directory\s*traversal/i, 'path-traversal'],
+  [/server[-\s]?side\s*request\s*forgery|\bssrf\b/i, 'ssrf'],
+  [/cross[-\s]?site\s*request\s*forgery|\bcsrf\b/i,  'csrf'],
+  [/open\s*redirect/i,       'open-redirect'],
+  [/\bxxe\b|external\s*entity/i, 'xxe'],
+  [/\bidor\b|insecure\s*direct\s*object/i, 'idor'],
+  [/mass[-\s]?assignment|over[-\s]?posting/i, 'mass-assignment'],
+  [/prototype\s*pollution/i, 'prototype-pollution'],
+  [/deserialization|deserialize/i, 'insecure-deserialization'],
+  [/weak\s*(?:crypto|hash|cipher)|\bmd5\b|\bsha1\b|\brc4\b/i, 'weak-crypto'],
+  [/weak\s*rng|insecure\s*random|math\.random/i, 'weak-rng'],
+  [/hardcoded\s*(?:secret|credential|key|password|token)|secret\s*in\s*code/i, 'hardcoded-secret'],
+  [/jwt|json\s*web\s*token/i, 'broken-auth'],
+  [/jndi/i,                  'jndi-injection'],
+  [/log\s*injection|log4shell/i, 'log-injection'],
+  [/insecure\s*http|http\s*without\s*tls|missing\s*https/i, 'insecure-http'],
+  [/host\s*header/i,         'host-header'],
+  [/rate[-\s]?limit/i,       'rate-limit'],
+  [/vulnerable\s*dependency|cve-\d{4}-\d+|known\s*vulnerable\s*component/i, 'vulnerable-dep'],
+  [/prompt\s*injection|llm\s*injection/i, 'prompt-injection'],
+  [/clickjacking|x-frame-options/i, 'clickjacking'],
+  [/zip[-\s]?slip/i,         'path-traversal'],
+];
+
+function _inferFamily(f) {
+  if (!f || typeof f !== 'object') return null;
+  if (typeof f.family === 'string' && f.family.length) return f.family;
+  if (typeof f.cwe === 'string' && _CWE_FAMILY[f.cwe]) return _CWE_FAMILY[f.cwe];
+  const hay = `${f.vuln || ''} ${f.title || ''} ${f.description || ''}`.slice(0, 600);
+  for (const [re, fam] of _KEYWORD_FAMILY) {
+    if (re.test(hay)) return fam;
+  }
+  return null;
+}
+
+function _inferParser(f) {
+  if (!f || typeof f !== 'object') return 'REGEX';
+  if (typeof f.parser === 'string' && f.parser.length) return f.parser;
+  // SCA findings carry pkg/component/purl; tag them so triage and validator
+  // can short-circuit (LLM validator already special-cases parser SCA).
+  if (f.parser === 'SCA' || f.kind === 'sca' ||
+      typeof f.pkg === 'string' || typeof f.component === 'string' ||
+      typeof f.purl === 'string') return 'SCA';
+  if (f.custom === true) return 'CUSTOM_RULE';
+  // Findings carrying a source/sink chain are layer-2 taint outputs.
+  if (Array.isArray(f.chain) && f.chain.length && f.source && f.sink) return 'IR-TAINT';
+  // AST-driven detectors mark themselves; fall back to REGEX otherwise.
+  return 'REGEX';
+}
+
+export function backfillFindingDefaults(findings) {
+  if (!Array.isArray(findings)) return;
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    if (!f.parser) f.parser = _inferParser(f);
+    if (!f.family) {
+      const fam = _inferFamily(f);
+      if (fam) f.family = fam;
+    }
+  }
+}
+
+// Exported for tests.
+export const _internals = { _CWE_FAMILY, _KEYWORD_FAMILY, _inferFamily, _inferParser };