@clear-capabilities/agentic-security-scanner 0.124.1 → 0.128.1

package/src/posture/model-routing.js

@@ -0,0 +1,126 @@
+// Capability-based model routing for cost-sensitive subagent dispatch.
+//
+// A declarative CWE/severity → model policy. When the orchestrator is about to
+// dispatch a delegable, cost-sensitive subagent for a finding (fixer, triager,
+// PoC generator, attack-chain synthesizer), it can ask this module which model
+// tier the work actually warrants — spend Opus reasoning on the hard classes
+// (crypto, auth, deserialization, XXE, cross-file taint) and let Haiku handle
+// the mechanical hardening findings.
+//
+// Mirrors the model IDs + tier vocabulary of hooks/model-cost-advisor.js:
+//   strongest = claude-opus-4-8   (high effort)
+//   mid       = claude-sonnet-4-6 (medium effort)
+//   cheapest  = claude-haiku-4-5  (low effort)
+//
+// This is a *preference*, not a ceiling — a caller may always upgrade when the
+// specific task clearly needs more capability (same spirit as the
+// subagentOverride contract documented in the root CLAUDE.md).
+//
+// Pure + deterministic — no I/O, no network, never throws.
+
+// Model IDs (module-local; the public API is the routing functions below).
+const MODEL_STRONGEST = 'claude-opus-4-8';
+const MODEL_MID = 'claude-sonnet-4-6';
+const MODEL_CHEAPEST = 'claude-haiku-4-5';
+
+const LABEL = {
+  [MODEL_STRONGEST]: 'Opus 4.8',
+  [MODEL_MID]: 'Sonnet 4.6',
+  [MODEL_CHEAPEST]: 'Haiku 4.5',
+};
+
+// Hard classes — subtle, high-blast-radius bugs where a wrong fix is worse than
+// no fix: auth, TLS/cert validation, weak crypto/hashing/randomness, signature
+// verification, unsafe deserialization, XXE. Worth Opus when they land at high
+// or critical severity.
+const HARD_CWES = new Set([
+  'CWE-287', // improper authentication
+  'CWE-295', // improper certificate validation
+  'CWE-327', // broken / risky crypto algorithm
+  'CWE-328', // weak hash
+  'CWE-330', // use of insufficiently random values
+  'CWE-347', // improper verification of cryptographic signature
+  'CWE-502', // deserialization of untrusted data
+  'CWE-611', // XML external entity (XXE)
+]);
+
+// Mid classes — the common injection / traversal / CSRF / SSRF families.
+// Well-understood remediations; Sonnet handles them cost-effectively.
+const MID_CWES = new Set([
+  'CWE-22',  // path traversal
+  'CWE-78',  // OS command injection
+  'CWE-79',  // cross-site scripting
+  'CWE-89',  // SQL injection
+  'CWE-94',  // code injection
+  'CWE-352', // cross-site request forgery
+  'CWE-434', // unrestricted file upload
+  'CWE-601', // open redirect
+  'CWE-918', // server-side request forgery
+]);
+
+// Extract the canonical `CWE-<n>` token from a finding.cwe value that may be a
+// bare id ("CWE-89") or a descriptive string ("CWE-89: SQL Injection").
+// Returns the uppercased id, or null when nothing parseable is present.
+export function parseCwe(raw) {
+  if (typeof raw !== 'string') return null;
+  const m = raw.match(/CWE-\d+/i);
+  return m ? m[0].toUpperCase() : null;
+}
+
+// Route a single finding to a model tier. First match wins.
+// Returns { model, effort, reason }.
+export function routeModelForFinding(finding) {
+  const f = finding || {};
+  const severity = typeof f.severity === 'string' ? f.severity.toLowerCase() : '';
+  const cwe = parseCwe(f.cwe);
+  const multiFile = f.multiFile === true || f.isCrossFile === true;
+  const highOrCritical = severity === 'high' || severity === 'critical';
+
+  // ── Tier 1: strongest (Opus, high effort) ──
+  if (severity === 'critical') {
+    return { model: MODEL_STRONGEST, effort: 'high',
+      reason: `Critical severity — worth ${LABEL[MODEL_STRONGEST]} at high effort.` };
+  }
+  if (cwe && HARD_CWES.has(cwe) && highOrCritical) {
+    return { model: MODEL_STRONGEST, effort: 'high',
+      reason: `${cwe} at ${severity} severity is a hard class (crypto / auth / deserialization / XXE) — ${LABEL[MODEL_STRONGEST]} at high effort.` };
+  }
+  if (multiFile) {
+    return { model: MODEL_STRONGEST, effort: 'high',
+      reason: `Cross-file finding — needs ${LABEL[MODEL_STRONGEST]} at high effort to reason across files.` };
+  }
+
+  // ── Tier 2: mid (Sonnet, medium effort) ──
+  if (cwe && MID_CWES.has(cwe)) {
+    return { model: MODEL_MID, effort: 'medium',
+      reason: `${cwe} is a common injection / traversal class — ${LABEL[MODEL_MID]} at medium effort.` };
+  }
+  if (severity === 'high') {
+    return { model: MODEL_MID, effort: 'medium',
+      reason: `High severity — ${LABEL[MODEL_MID]} at medium effort.` };
+  }
+
+  // ── Tier 3: cheapest (Haiku, low effort) ──
+  return { model: MODEL_CHEAPEST, effort: 'low',
+    reason: `${cwe ? `${cwe} at ` : ''}${severity || 'low'} severity is a simple / hardening class — ${LABEL[MODEL_CHEAPEST]} at low effort.` };
+}
+
+// Route a list of findings. Returns [{ finding, model, effort, reason }, …].
+export function routeModelForFindings(findings) {
+  const list = Array.isArray(findings) ? findings : [];
+  return list.map((finding) => ({ finding, ...routeModelForFinding(finding) }));
+}
+
+// Tally how many findings land on each model tier.
+// Returns { 'claude-opus-4-8': n, 'claude-sonnet-4-6': n, 'claude-haiku-4-5': n }.
+export function summarizeRouting(findings) {
+  const counts = {
+    [MODEL_STRONGEST]: 0,
+    [MODEL_MID]: 0,
+    [MODEL_CHEAPEST]: 0,
+  };
+  for (const { model } of routeModelForFindings(findings)) {
+    if (model in counts) counts[model] += 1;
+  }
+  return counts;
+}

package/src/posture/mttr.js

@@ -63,6 +63,31 @@ export function findingsExceedingSLA(findings, slaDays = null) {
   });
 }
 
+// Median age (days) of the currently-open findings — a single-scan proxy for
+// "how long has this debt been sitting". True MTTR (computeMTTR) needs the set
+// of findings that were FIXED; this reports the open backlog's median age so a
+// scan can show whether debt is getting older. Returns null on empty input.
+// Local — surfaced only through renderSlaSummary (its sole consumer).
+function medianOpenAgeDays(findings) {
+  const ages = (findings || []).map(f => f.ageDays || 0).sort((a, b) => a - b);
+  if (!ages.length) return null;
+  return ages[Math.floor(ages.length / 2)];
+}
+
+// One-line SLA-breach summary for surfacing after a scan (#10). Returns null
+// when nothing is past its per-severity SLA. Pairs with medianOpenAgeDays for a
+// "is my security debt aging" readout that the vibecoder can act on.
+export function renderSlaSummary(findings, slaDays = null) {
+  const breached = findingsExceedingSLA(findings || [], slaDays);
+  if (!breached.length) return null;
+  const bySev = {};
+  for (const f of breached) bySev[f.severity] = (bySev[f.severity] || 0) + 1;
+  const parts = ['critical', 'high', 'medium', 'low', 'info'].filter(s => bySev[s]).map(s => `${bySev[s]} ${s}`);
+  const median = medianOpenAgeDays(findings);
+  const ageNote = median != null ? ` (median open age ${median}d)` : '';
+  return `${breached.length} finding(s) past remediation SLA: ${parts.join(', ')}${ageNote}`;
+}
+
 // Compute MTTR statistics from a series of saved scans (each with firstSeen/lastSeen).
 // Useful for trend reporting.
 export function computeMTTR(removedFindings) {

package/src/posture/provider-catalog.js

@@ -0,0 +1,108 @@
+// Multi-provider model + pricing + cache catalog (PRD CACHE_ECONOMICS_V2, P2).
+//
+// One abstraction over four very different frameworks so the cost/cache advisor
+// (sast/llm-cost-advisor.js) and the economics modules work uniformly. Captures,
+// per provider: the model ladder (cheap→capable, with $/1M rates), the "depth"
+// knob (Anthropic effort / OpenAI+xAI reasoning_effort / Gemini thinkingBudget),
+// and the cache model (explicit vs automatic vs implicit; read/write economics).
+//
+// ⚠️ PRICES + MODEL NAMES DRIFT MONTHLY — this is a DATED snapshot, not truth.
+// Anything that needs a live number must read it here and treat `sourcedAt` as
+// the staleness signal; refresh from each provider's pricing/models API (or the
+// claude-api skill for Anthropic) at implementation time. No network at runtime.
+export const SOURCED_AT = '2026-07-05';
+
+// $/1M tokens. `cached` = effective cached-input rate (Anthropic = read multiplier
+// applied to `in`; others publish a cached-input price directly).
+export const PROVIDERS = {
+  anthropic: {
+    label: 'Anthropic (Claude)',
+    importMarkers: [/@anthropic-ai\b/, /\banthropic\b/, /\bClaude\b/],
+    modelMarkers: [/\bclaude-/i, /\bfable\b/i, /\bopus\b/i, /\bsonnet\b/i, /\bhaiku\b/i],
+    depth: { knob: 'effort', cheap: 'low', expensive: ['high', 'xhigh', 'max'], levels: ['low', 'medium', 'high', 'xhigh', 'max'] },
+    cache: { kind: 'explicit', readMult: 0.1, writeMult: 1.25, minPrefixTokens: 1024, modelScoped: true, manualControl: true },
+    // The /sonnet/i row prices both Sonnet 4.6 and Sonnet 5 ($3/$15). Fable 5 is
+    // the current flagship (above Opus) at $10/$50 — a distinct rate, so it gets
+    // its own top-tier row so the over-provisioned rule can suggest Opus/Sonnet.
+    models: [
+      { id: 'claude-haiku-4-5',  match: /haiku/i,        tier: 0, in: 1,  out: 5,  cached: 0.10 },
+      { id: 'claude-sonnet-4-6', match: /sonnet/i,       tier: 1, in: 3,  out: 15, cached: 0.30 },
+      { id: 'claude-opus-4-8',   match: /opus/i,         tier: 2, in: 5,  out: 25, cached: 0.50 },
+      { id: 'claude-fable-5',    match: /fable|mythos/i, tier: 3, in: 10, out: 50, cached: 1.00 },
+    ],
+  },
+  openai: {
+    label: 'OpenAI',
+    importMarkers: [/\bfrom openai\b/, /\bimport openai\b/, /@?openai\b/, /\bAzureOpenAI\b/],
+    modelMarkers: [/\bgpt-/i, /\bo[34]-?mini\b/i, /\bo3\b/i],
+    depth: { knob: 'reasoning_effort', cheap: 'low', expensive: ['high'], levels: ['minimal', 'low', 'medium', 'high'] },
+    cache: { kind: 'automatic', cachedDiscount: 0.90, minPrefixTokens: 1024, modelScoped: true, manualControl: false },
+    models: [
+      { id: 'gpt-4.1-nano', match: /gpt-4\.1-nano/i, tier: 0, in: 0.10, out: 0.40, cached: 0.025 },
+      { id: 'gpt-5-mini',   match: /gpt-5[.\d]*-mini/i, tier: 1, in: 0.60, out: 2.40, cached: 0.06 },
+      { id: 'gpt-5.4',      match: /gpt-5\.4(?!-mini)/i, tier: 2, in: 2.50, out: 15, cached: 0.25 },
+      { id: 'gpt-5.5',      match: /gpt-5\.5/i, tier: 3, in: 5, out: 30, cached: 0.50 },
+    ],
+    reasoningModels: [/\bo3\b/i, /\bo4-?mini\b/i],
+  },
+  google: {
+    label: 'Google (Gemini)',
+    importMarkers: [/google\.generativeai/, /\bgenai\b/, /@google\/genai/, /\bGenerativeModel\b/],
+    modelMarkers: [/\bgemini-/i],
+    depth: { knob: 'thinkingBudget', cheap: 'low budget', expensive: ['high budget'], levels: ['0', 'low', 'high', 'dynamic'] },
+    cache: { kind: 'implicit-explicit', cachedDiscount: 0.90, minPrefixTokens: 1024, modelScoped: true, manualControl: 'optional', storagePriced: true },
+    models: [
+      { id: 'gemini-flash-lite',  match: /flash-lite/i, tier: 0, in: 0.10, out: 0.40, cached: 0.025 },
+      { id: 'gemini-3.5-flash',   match: /3\.5-flash|2\.5-flash(?!-lite)/i, tier: 1, in: 1.50, out: 9, cached: 0.15 },
+      { id: 'gemini-3.1-pro',     match: /3\.1-pro|2\.5-pro/i, tier: 2, in: 2, out: 12, cached: 0.30 },
+    ],
+  },
+  xai: {
+    label: 'xAI (Grok)',
+    importMarkers: [/\bxai\b/i, /api\.x\.ai/, /\bGROK\b/i],
+    modelMarkers: [/\bgrok-/i],
+    depth: { knob: 'reasoning_effort', cheap: 'low', expensive: ['high'], levels: ['none', 'low', 'medium', 'high'] },
+    cache: { kind: 'automatic', cachedDiscount: 0.85, minPrefixTokens: 1024, modelScoped: true, manualControl: false },
+    models: [
+      { id: 'grok-4.1-fast', match: /grok-4\.1-fast/i, tier: 0, in: 0.20, out: 0.50, cached: 0.05 },
+      { id: 'grok-4.3',      match: /grok-4\.(3|20)/i, tier: 1, in: 1.25, out: 2.50, cached: 0.20 },
+    ],
+  },
+};
+
+// Detect the provider a file targets, from SDK import markers (preferred) then
+// model-string markers. Returns a provider key or null.
+export function detectProvider(raw) {
+  if (typeof raw !== 'string' || !raw) return null;
+  for (const [key, p] of Object.entries(PROVIDERS)) {
+    if (p.importMarkers.some(re => re.test(raw))) return key;
+  }
+  for (const [key, p] of Object.entries(PROVIDERS)) {
+    if (p.modelMarkers.some(re => re.test(raw))) return key;
+  }
+  return null;
+}
+
+// Which model-ladder entry does a model string map to (within a provider)?
+export function modelEntry(provider, modelStr) {
+  const p = PROVIDERS[provider];
+  if (!p || typeof modelStr !== 'string') return null;
+  return p.models.find(m => m.match.test(modelStr)) || null;
+}
+
+// A cheaper model in the same provider's ladder (one tier down), or null if the
+// model is already the cheapest / unknown.
+export function cheaperModel(provider, modelStr) {
+  const p = PROVIDERS[provider];
+  const cur = modelEntry(provider, modelStr);
+  if (!p || !cur || cur.tier === 0) return null;
+  const below = p.models.filter(m => m.tier < cur.tier).sort((a, b) => b.tier - a.tier)[0];
+  return below || null;
+}
+
+export function depthAxis(provider) {
+  return PROVIDERS[provider]?.depth || null;
+}
+export function cacheModel(provider) {
+  return PROVIDERS[provider]?.cache || null;
+}

package/src/posture/root-cause-sweep.js

@@ -0,0 +1,262 @@
+// Addition #3 — Root-cause sweep with total-count accounting.
+//
+// A detector fires on the instance it can prove. But the same root cause is
+// usually copy-pasted across the codebase, and most of those siblings never
+// trip a rule (different variable names, an assignment wrapper, a file the
+// scanner didn't reach with taint). This module takes CONFIRMED findings and
+// sweeps every source line for structural siblings of the same sink, then
+// accounts for every match honestly:
+//
+//     found === candidates + mitigated        (per sweep, always)
+//
+// where `found` is every structural match across the repo EXCLUDING the
+// finding's own origin site, `mitigated` is the subset a detector already
+// covered (a finding exists at that file:line), and `candidates` is the
+// remainder — new instances nobody has looked at yet. Nothing is dropped.
+//
+// Matching reuses semantic-clone's normalized token-shape hashing (`shapeHash`)
+// so that `db.query(a)` and `db.query(b)` collapse to one shape. Pure shape is
+// too loose on its own (`db.query(x)` and `console.log(x)` both normalize to
+// `ID.ID(ID)`), so we anchor on the LITERAL callee (`db.query`) and use the
+// shape only to confirm the argument arity/structure. Anchor + shape = precise.
+//
+// Like semantic-clone this is a coarse structural approximation, not a proof of
+// semantic equivalence. It catches the common "same call, cloned around" case.
+
+import { shapeHash } from './semantic-clone.js';
+
+// shapeHash defaults to minTokens:8 (tuned to avoid trivial clone collisions on
+// whole functions). A single call expression is short — `foo(a)` is 4 tokens,
+// `db.query(a)` is 6 — so we lower the floor for call-granular matching.
+const MIN_SHAPE_TOKENS = 3;
+
+// A callee whose final segment is one of these is control flow, not a sink call.
+const CONTROL_KEYWORDS = new Set([
+  'if', 'for', 'while', 'switch', 'catch', 'return', 'function', 'with', 'do', 'await',
+]);
+
+function escapeRegex(s) {
+  return String(s).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// Accept both a Map and a plain { path: source } object.
+function toMap(fileContents) {
+  if (fileContents instanceof Map) return fileContents;
+  const m = new Map();
+  if (fileContents && typeof fileContents === 'object') {
+    for (const k of Object.keys(fileContents)) m.set(k, fileContents[k]);
+  }
+  return m;
+}
+
+// A finding qualifies for a sweep when it is confirmed. With confirmedOnly
+// disabled we sweep everything (the caller has opted out of the gate).
+function qualifies(finding, confirmedOnly) {
+  if (!confirmedOnly) return true;
+  return finding.confirmed === true || finding.confidenceTier === 'high';
+}
+
+// The origin site is the finding's own location; siblings must exclude it.
+function originSite(finding) {
+  if (finding.sink && finding.sink.file && finding.sink.line != null) {
+    return { file: finding.sink.file, line: finding.sink.line };
+  }
+  return { file: finding.file ?? null, line: finding.line ?? null };
+}
+
+// Every file:line that already carries a finding — used to classify a match as
+// 'mitigated-or-known' vs. a fresh 'candidate'.
+function buildKnownLocations(findings) {
+  const set = new Set();
+  for (const f of Array.isArray(findings) ? findings : []) {
+    if (!f || typeof f !== 'object') continue;
+    if (f.file != null && f.line != null) set.add(`${f.file}:${f.line}`);
+    if (f.sink && f.sink.file != null && f.sink.line != null) set.add(`${f.sink.file}:${f.sink.line}`);
+  }
+  return set;
+}
+
+// Pull the leading callee path out of a call snippet: `db.query(x)` → `db.query`.
+function extractCallee(snippet) {
+  if (!snippet || typeof snippet !== 'string') return null;
+  const m = snippet.match(/([A-Za-z_$][\w$]*(?:\.[A-Za-z_$][\w$]*)*)\s*\(/);
+  if (!m) return null;
+  const callee = m[1];
+  const last = callee.split('.').pop();
+  if (CONTROL_KEYWORDS.has(last)) return null;
+  return callee;
+}
+
+// Extract the full balanced call expression for `callee` from `text`:
+// `const r = db.query(f(1), g);` → `db.query(f(1), g)`. Null if absent/unbalanced.
+function extractCall(text, callee) {
+  if (!text || typeof text !== 'string') return null;
+  const re = new RegExp('(?:^|[^\\w$.])' + escapeRegex(callee) + '\\s*\\(');
+  const m = re.exec(text);
+  if (!m) return null;
+  const calleeStart = m.index + m[0].indexOf(callee); // callee offset within the match
+
+  const open = text.indexOf('(', calleeStart);
+  if (open < 0) return null;
+  let depth = 0;
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === '(') depth++;
+    else if (ch === ')') {
+      depth--;
+      if (depth === 0) return text.slice(calleeStart, i + 1);
+    }
+  }
+  return null; // unbalanced on this line
+}
+
+// Structural shape of a sink snippet: hash of the normalized call expression
+// (callee + args reduced to token kinds), reusing semantic-clone's hasher.
+function sinkShapeOf(snippet) {
+  if (!snippet || typeof snippet !== 'string') return null;
+  const callee = extractCallee(snippet);
+  const call = callee ? (extractCall(snippet, callee) || snippet) : snippet;
+  return shapeHash(call, { minTokens: MIN_SHAPE_TOKENS });
+}
+
+// Build a searchable pattern from a finding's sink (preferred) or fall back to
+// vuln/cwe keywords when no snippet is available.
+function deriveSinkPattern(finding) {
+  const snippet = finding?.sink?.snippet || finding?.snippet || '';
+  const callee = extractCallee(snippet);
+  if (callee) {
+    return {
+      kind: 'call',
+      callee,
+      shape: sinkShapeOf(snippet),
+      regex: new RegExp('(?:^|[^\\w$.])' + escapeRegex(callee) + '\\s*\\('),
+      display: `${callee}(…)`,
+    };
+  }
+  const kw = keywordFor(finding);
+  if (kw) {
+    return { kind: 'keyword', keyword: kw, shape: null, regex: new RegExp(escapeRegex(kw), 'i'), display: kw };
+  }
+  return null;
+}
+
+// Source pattern is reported for context; the sweep itself is sink-driven.
+function deriveSourcePattern(finding) {
+  const s = finding?.source?.snippet;
+  if (s && typeof s === 'string' && s.trim()) return { display: s.trim() };
+  const kw = keywordFor(finding);
+  if (kw) return { display: kw };
+  return null;
+}
+
+function keywordFor(finding) {
+  const v = (finding?.vuln ?? '').toString().trim();
+  if (v) return v;
+  const cwe = (finding?.cwe ?? '').toString().trim();
+  if (cwe) return cwe;
+  return null;
+}
+
+// Does a single source line structurally match the sink pattern?
+function matchLine(pattern, line) {
+  if (!pattern || typeof line !== 'string') return false;
+  if (pattern.kind === 'call') {
+    if (!pattern.regex.test(line)) return false;      // literal callee anchor
+    if (pattern.shape == null) return true;           // anchor-only (snippet too short to shape)
+    const call = extractCall(line, pattern.callee);
+    if (!call) return false;
+    return shapeHash(call, { minTokens: MIN_SHAPE_TOKENS }) === pattern.shape;
+  }
+  if (pattern.kind === 'keyword') {
+    return pattern.regex.test(line);
+  }
+  return false;
+}
+
+/**
+ * Sweep confirmed findings for sibling instances of the same root cause.
+ *
+ * @param {Array<object>} findings   scan findings (confirmed ones drive sweeps)
+ * @param {Map|object}    fileContents  { path: source } — Map or plain object
+ * @param {object}        opts       { confirmedOnly = true }
+ * @returns {{ sweeps: Array<object>, totals: {found,candidates,mitigated} }}
+ */
+export function sweepRootCauses(findings, fileContents, opts = {}) {
+  const confirmedOnly = opts?.confirmedOnly !== false;
+  const list = Array.isArray(findings) ? findings : [];
+  const files = toMap(fileContents);
+  const knownLocations = buildKnownLocations(list);
+
+  const sweeps = [];
+  const totals = { found: 0, candidates: 0, mitigated: 0 };
+
+  for (const finding of list) {
+    if (!finding || typeof finding !== 'object') continue;
+    if (!qualifies(finding, confirmedOnly)) continue;
+
+    const sinkPattern = deriveSinkPattern(finding);
+    if (!sinkPattern) continue; // nothing searchable — skip rather than fabricate
+    const sourcePattern = deriveSourcePattern(finding);
+    const origin = originSite(finding);
+
+    const instances = [];
+    for (const [path, source] of files) {
+      if (source == null) continue;
+      const lines = String(source).split(/\r?\n/);
+      for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (!matchLine(sinkPattern, line)) continue;
+        const lineNo = i + 1;
+        if (path === origin.file && lineNo === origin.line) continue; // exclude the finding's own site
+        const status = knownLocations.has(`${path}:${lineNo}`) ? 'mitigated-or-known' : 'candidate';
+        instances.push({ file: path, line: lineNo, snippet: line.trim(), status });
+      }
+    }
+
+    const candidates = instances.filter((x) => x.status === 'candidate').length;
+    const mitigated = instances.filter((x) => x.status === 'mitigated-or-known').length;
+    const found = instances.length; // every match is exactly one status → invariant holds by construction
+
+    sweeps.push({
+      fromFindingId: finding.id ?? finding.stableId ?? null,
+      sourcePattern: sourcePattern ? sourcePattern.display : null,
+      sinkPattern: sinkPattern.display,
+      found,
+      candidates,
+      mitigated,
+      remaining: candidates, // unaccounted instances that still need triage
+      instances,
+    });
+
+    totals.found += found;
+    totals.candidates += candidates;
+    totals.mitigated += mitigated;
+  }
+
+  return { sweeps, totals };
+}
+
+/**
+ * One short human line per sweep, e.g.:
+ *   "root-cause sweep: 20 found, 3 candidate, 17 mitigated"
+ */
+export function formatSweepLedger(result) {
+  if (!result || !Array.isArray(result.sweeps)) return '';
+  return result.sweeps
+    .map((s) => `root-cause sweep: ${s.found} found, ${s.candidates} candidate, ${s.mitigated} mitigated`)
+    .join('\n');
+}
+
+export const _internals = {
+  MIN_SHAPE_TOKENS,
+  sinkShapeOf,
+  deriveSinkPattern,
+  deriveSourcePattern,
+  extractCallee,
+  extractCall,
+  matchLine,
+  qualifies,
+  originSite,
+  buildKnownLocations,
+  toMap,
+};

package/src/posture/secret-live-check.js

@@ -0,0 +1,71 @@
+// Live-secret validation (#22) — label a detected secret live | dead | unknown.
+//
+// "This Stripe/GitHub key is LIVE and was committed 40 commits ago" is a P0 the
+// vibecoder must rotate now; "you have a high-entropy string" is noise. This
+// closes that gap for the providers with a cheap, read-only "whoami" check.
+//
+// STRICTLY opt-in (a --validate-secrets flag / AGENTIC_SECURITY_VALIDATE_SECRETS)
+// and OFFLINE-DEGRADING: any network error, timeout, or unrecognized provider
+// yields 'unknown' — never a false 'dead'. No runtime cloud calls by default,
+// per the scanner's no-network-by-default convention. The request builder is
+// pure (no I/O) so it's testable without hitting a provider.
+
+// Map a detected secret to a read-only validation request, or null when we have
+// no safe check for that provider. Only providers whose token is a self-
+// contained bearer/token credential (no signing, no extra params) are covered.
+function buildLiveCheckRequest(secret) {
+  const val = (secret && (secret.match || secret.value || secret.secret || secret.token)) || '';
+  if (typeof val !== 'string' || val.length < 8) return null;
+
+  // GitHub PAT / OAuth token → GET /user (200 = live, 401 = dead).
+  if (/^gh[posru]_[A-Za-z0-9]{20,}$/.test(val) || /^github_pat_[A-Za-z0-9_]{20,}$/.test(val)) {
+    return { provider: 'github', method: 'GET', url: 'https://api.github.com/user',
+      headers: { Authorization: `token ${val}`, 'User-Agent': 'agentic-security', Accept: 'application/vnd.github+json' } };
+  }
+  // Stripe secret key → GET /v1/account (200 = live, 401 = dead).
+  if (/^sk_live_[A-Za-z0-9]{16,}$/.test(val) || /^rk_live_[A-Za-z0-9]{16,}$/.test(val)) {
+    return { provider: 'stripe', method: 'GET', url: 'https://api.stripe.com/v1/account',
+      headers: { Authorization: `Bearer ${val}` } };
+  }
+  // OpenAI key → GET /v1/models.
+  if (/^sk-[A-Za-z0-9]{20,}$/.test(val) && !/^sk_live_/.test(val)) {
+    return { provider: 'openai', method: 'GET', url: 'https://api.openai.com/v1/models',
+      headers: { Authorization: `Bearer ${val}` } };
+  }
+  // SendGrid key → GET /v3/scopes.
+  if (/^SG\.[A-Za-z0-9_-]{16,}\.[A-Za-z0-9_-]{16,}$/.test(val)) {
+    return { provider: 'sendgrid', method: 'GET', url: 'https://api.sendgrid.com/v3/scopes',
+      headers: { Authorization: `Bearer ${val}` } };
+  }
+  return null;
+}
+
+// Classify an HTTP status into a liveness verdict. 200-2xx = live; 401/403 =
+// dead (rejected credential); anything else = unknown (rate-limit, 5xx, etc. —
+// we don't know, so don't claim dead).
+function classifyStatus(status) {
+  if (status >= 200 && status < 300) return 'live';
+  if (status === 401 || status === 403) return 'dead';
+  return 'unknown';
+}
+
+// Perform the validation. Returns { verdict: 'live'|'dead'|'unknown', provider }.
+// Offline-degrading: on any error/timeout, verdict is 'unknown'.
+export async function checkSecretLive(secret, { timeoutMs = 4000 } = {}) {
+  const req = buildLiveCheckRequest(secret);
+  if (!req) return { verdict: 'unknown', provider: null };
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), timeoutMs);
+  try {
+    const r = await fetch(req.url, { method: req.method, headers: req.headers, signal: ctrl.signal });
+    return { verdict: classifyStatus(r.status), provider: req.provider };
+  } catch {
+    return { verdict: 'unknown', provider: req.provider };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+// Pure surfaces exposed for tests (no network) — kept off the public API so the
+// dead-module guard doesn't flag them; `checkSecretLive` is the wired entry.
+export const _internal = { buildLiveCheckRequest, classifyStatus };

package/src/pr-comment.js

@@ -25,6 +25,8 @@
 // route through an LLM for richer prose when AGENTIC_SECURITY_LLM_ENDPOINT
 // is configured.
 
+import { escapeMarkdown } from './util/untrusted.js';
+
 const SEVERITY_GLYPH = {
   critical: '🟥',
   high:     '🟧',
@@ -136,7 +138,7 @@ export function renderPrComment(delta, { repoName, prNumber, prTitle } = {}) {
     const sev = SEVERITY_GLYPH[f.severity] || '⬜';
     const route = _route(f);
     const where = route ? `\`${route}\` (\`${f.file}:${f.line}\`)` : `\`${f.file}:${f.line}\``;
-    lines.push(`${sev} **${meta?.name || f.vuln}** — ${where}`);
+    lines.push(`${sev} **${meta?.name || escapeMarkdown(f.vuln)}** — ${where}`);
     if (meta) lines.push(`  > ${meta.why}`);
     if (f.remediation) {
       const onelineFix = String(f.remediation).split('\n')[0].slice(0, 240);

package/src/sast/CLAUDE.md

@@ -23,7 +23,7 @@ SAST detector modules. Each file exports one or more `scan*()` functions returni
 
 **Framework structural (taint-independent, JS/Py recall)** — `js-framework-structural.js` (Express/Koa/NestJS/TypeORM: SQLi via `.query`/`.execute` concat-template, koa-send path, `ctx.body` XSS, HttpService SSRF, deep-merge prototype pollution) `python-structural.js` (Flask `render_template_string` XSS/SSTI, Django `.raw`/`.extra` + `cursor.execute` SQLi — robust string-literal matching spans embedded quotes like `"… name = '" + x`; `open()`/`send_file` path traversal via concat/f-string, CWE-22 deferring to `dropGuardedFindings`), and `go-structural.js` (db query + `fmt.Sprintf`/concat SQLi, `os.Open` + concat/Sprintf path traversal). High precision: parameterized/escaped/`{{ }}`-Jinja/`%s`-placeholder forms do NOT match; SSRF/path findings defer to `engine.js dropGuardedFindings` (which also drops a reflected-XSS finding when the reflected value passed through a captured HTML escaper — a *discarded* `escapeHtml(s);` does not count — and skips already-`isSanitized` findings so the suppression pipeline keeps its bookkeeping).
 
-**Cross-cutting vuln classes** — `authz.js`, `csrf.js` (POST/PUT/PATCH/DELETE state-changing routes without CSRF defence; defence-aware suppression covers Express/Fastify/Flask/Django/FastAPI/Spring/Symfony **and Go (gin/echo/mux), Rails routes, ASP.NET MVC** — recognizes `gorilla/csrf`/`protect_from_forgery`/`[ValidateAntiForgeryToken]` defences and exempts token-auth (`[ApiController]`, Bearer scheme); bare ASP.NET `[Authorize]` still flags as cookie auth is CSRF-vulnerable), `code-injection-multilang.js` (CWE-94 for Java/C#/Go/Kotlin — dynamic code/expression evaluators on a NON-LITERAL argument: javax.script `eval`, GroovyShell, Spring SpEL `parseExpression`, MVEL/OGNL, Roslyn `CSharpScript`, `DataTable.Compute`, yaegi `interp.Eval`, `text/template` Parse of a user-controlled body; literal arguments don't match. JS/Python/Ruby eval stay with the flow engine + per-language modules), `csv-injection.js` (formula injection into spreadsheet cells, CWE-1236), `secret-concat.js` (language-agnostic hardcoded-secret SPLIT across concatenated literals — `'AKIA' + 'IOSF…'` / `'ghp' + '_…'` / `'sk' + '_live_…'` — reassembled and matched against provider prefixes; complements the contiguous-token secrets scanner and the C#-only split-concat rule), `host-header.js`, `jndi.js`, `jwt-exp.js`, `ldap-injection.js` (CWE-90 across JS/Java/Python **and** PHP/Go/C#/Ruby/Kotlin — filter built by concat/interpolation; an inline call-guard and a file-level escape-API guard suppress `ldap_escape`/`EscapeFilter`/`escape_filter_chars`/`Net::LDAP::Filter`/`EqualityFilter` forms), `xpath-injection.js` (CWE-643 across Java/Python/JS **and** PHP/Go/Ruby/C#/Kotlin — XPath expression built by concat/interpolation: `DOMXPath->query`, `SelectNodes`, Nokogiri `.xpath`, htmlquery/xmlpath, `XPath.compile`; embedded-quote-tolerant literal matching; parameterized/variable-bound APIs and static literals don't match), `mass-assignment.js`, `mutation-xss.js`, `nosql-injection.js`, `prototype-pollution.js`, `response-splitting.js` (CWE-113 CRLF/header injection across JS/Python/Java/PHP/Go/Ruby/C#/Kotlin — a response header value set from a request source without stripping CR/LF; recognizes CRLF-strip sanitizers — `.replace(/[\r\n]/)`, chained `.replace("\r")`, Ruby `gsub`/`delete`, Go `strings.NewReplacer`, PHP `str_replace` — and a request-scope param heuristic for the JVM/C# single-file shape), `ssrf-cloud-metadata.js`, `xss-reflected-multilang.js` (cross-language reflected XSS for Go/Ruby/PHP/C#/Kotlin/Java — user input written into an HTML response via concat/interpolation, e.g. Java servlet `response.getWriter().write("<…" + q)`, with a per-language escaper exclusion so `htmlspecialchars`/`HtmlEncode`/`template.HTMLEscapeString`/ERB `<%= %>`/OWASP `Encode.forHtml` forms don't match; JS/Python XSS stays with the flow engine + framework structural detectors), `stored-taint.js` (second-order / stored injection — **opt-in** via `AGENTIC_SECURITY_STORED_TAINT=1`), `toctou.js`, `wrong-context-sanitizer.js` (HTML-entity encoder used in a URL context — wrong-context output encoding, CWE-79), `zip-slip.js`.
+**Cross-cutting vuln classes** — `authz.js`, `csrf.js` (POST/PUT/PATCH/DELETE state-changing routes without CSRF defence; defence-aware suppression covers Express/Fastify/Flask/Django/FastAPI/Spring/Symfony **and Go (gin/echo/mux), Rails routes, ASP.NET MVC** — recognizes `gorilla/csrf`/`protect_from_forgery`/`[ValidateAntiForgeryToken]` defences and exempts token-auth (`[ApiController]`, Bearer scheme); bare ASP.NET `[Authorize]` still flags as cookie auth is CSRF-vulnerable), `code-injection-multilang.js` (CWE-94 for Java/C#/Go/Kotlin — dynamic code/expression evaluators on a NON-LITERAL argument: javax.script `eval`, GroovyShell, Spring SpEL `parseExpression`, MVEL/OGNL, Roslyn `CSharpScript`, `DataTable.Compute`, yaegi `interp.Eval`, `text/template` Parse of a user-controlled body; literal arguments don't match. JS/Python/Ruby eval stay with the flow engine + per-language modules), `csv-injection.js` (formula injection into spreadsheet cells, CWE-1236), `secret-concat.js` (language-agnostic hardcoded-secret SPLIT across concatenated literals — `'AKIA' + 'IOSF…'` / `'ghp' + '_…'` / `'sk' + '_live_…'` — reassembled and matched against provider prefixes; complements the contiguous-token secrets scanner and the C#-only split-concat rule), `host-header.js`, `jndi.js`, `jwt-exp.js`, `ldap-injection.js` (CWE-90 across JS/Java/Python **and** PHP/Go/C#/Ruby/Kotlin — filter built by concat/interpolation; an inline call-guard and a file-level escape-API guard suppress `ldap_escape`/`EscapeFilter`/`escape_filter_chars`/`Net::LDAP::Filter`/`EqualityFilter` forms), `xpath-injection.js` (CWE-643 across Java/Python/JS **and** PHP/Go/Ruby/C#/Kotlin — XPath expression built by concat/interpolation: `DOMXPath->query`, `SelectNodes`, Nokogiri `.xpath`, htmlquery/xmlpath, `XPath.compile`; embedded-quote-tolerant literal matching; parameterized/variable-bound APIs and static literals don't match), `mass-assignment.js`, `mutation-xss.js`, `nosql-injection.js`, `prototype-pollution.js`, `response-splitting.js` (CWE-113 CRLF/header injection across JS/Python/Java/PHP/Go/Ruby/C#/Kotlin — a response header value set from a request source without stripping CR/LF; recognizes CRLF-strip sanitizers — `.replace(/[\r\n]/)`, chained `.replace("\r")`, Ruby `gsub`/`delete`, Go `strings.NewReplacer`, PHP `str_replace` — and a request-scope param heuristic for the JVM/C# single-file shape), `ssrf-cloud-metadata.js`, `xss-reflected-multilang.js` (cross-language reflected XSS for Go/Ruby/PHP/C#/Kotlin/Java — user input written into an HTML response via concat/interpolation, e.g. Java servlet `response.getWriter().write("<…" + q)`, with a per-language escaper exclusion so `htmlspecialchars`/`HtmlEncode`/`template.HTMLEscapeString`/ERB `<%= %>`/OWASP `Encode.forHtml` forms don't match; JS/Python XSS stays with the flow engine + framework structural detectors), `stored-taint.js` (second-order / stored injection — **opt-in** via `AGENTIC_SECURITY_STORED_TAINT=1`), `toctou.js`, `wrong-context-sanitizer.js` (HTML-entity encoder used in a URL context — wrong-context output encoding, CWE-79), `zip-slip.js`, `file-upload.js` (CWE-434 unrestricted file upload for JS/Python — Multer configured with no `fileFilter`/`limits`, and a write whose destination is built from the client-supplied filename (`originalname`/`req.files.*.name`/`.filename`); suppressed by a `basename`/uuid/`secure_filename`/sanitizer in the window).
 
 **Cloud/infra** — `db-rls.js` (Supabase RLS), `env-hygiene.js` (NEXT_PUBLIC_ leaks, .env.example real values), `mobile-manifest.js`, `pipeline.js` (CI/CD integrity), `rate-limit.js`, `webhook.js`.