@clear-capabilities/agentic-security-scanner 0.132.0 → 0.134.0

package/src/discovery/lenses.js

@@ -0,0 +1,69 @@
+//
+// The seven hunting lenses. Each hunter run is one (focus area × lens) pair.
+//
+// WHY DIVERSE LENSES RATHER THAN N IDENTICAL HUNTERS: redundancy raises
+// confidence in what was already found and adds nothing to coverage. A lens
+// that is told to look only at authorization asks different questions of the
+// same code than one told to look at crypto, so the union covers failure modes
+// no single prompt reaches. `wildcard` exists because a fixed taxonomy is a
+// ceiling, and the classes worth finding are the ones not on the list.
+export const LENSES = Object.freeze([
+  { key: 'injection', title: 'Injection', family: 'injection', cwe: 'CWE-74',
+    brief: 'Untrusted input reaching an interpreter: SQL, shell, template, XPath, LDAP, or deserialization. Follow the value, not the function name.' },
+  { key: 'authz', title: 'Authorization', family: 'access-control', cwe: 'CWE-285',
+    brief: 'Missing, partial, or bypassable authorization: object references not scoped to the caller, tier checks applied on one path but not another, checks performed after the effect.' },
+  { key: 'crypto', title: 'Cryptography', family: 'crypto', cwe: 'CWE-327',
+    brief: 'Misuse rather than choice of primitive: reused nonces, unauthenticated ciphertext, comparisons that are not constant time, keys derived from guessable material.' },
+  { key: 'business-logic', title: 'Business logic', family: 'business-logic', cwe: 'CWE-840',
+    brief: 'The code does what it says and what it says is wrong: state machines that accept out-of-order transitions, quantities that may be negative, refunds that exceed charges, limits enforced client side.' },
+  { key: 'feature-abuse', title: 'Feature abuse', family: 'abuse', cwe: 'CWE-799',
+    brief: 'A working feature used as a weapon: unbounded fan-out, expensive endpoints with no cost to the caller, invitations or exports that leak across tenants.' },
+  { key: 'chained', title: 'Chained', family: 'attack-chain', cwe: 'CWE-1173',
+    brief: 'Two behaviours that are each acceptable alone and unacceptable together. State the chain as an ordered sequence of steps with the attacker capability required at each.' },
+  { key: 'wildcard', title: 'Wildcard', family: 'other', cwe: 'CWE-710',
+    brief: 'Anything the other lenses do not cover. Prefer the surprising and specific over the generic; report nothing rather than something already obvious.' },
+]);
+
+export function lensByKey(key) {
+  if (typeof key !== 'string') return null;
+  return LENSES.find(l => l.key === key) || null;
+}
+
+const DEFAULT_MAX_CHARS = 60_000;
+
+export function buildHunterPrompt(focusArea, lens, ctx = {}) {
+  const maxChars = Number.isInteger(ctx.maxChars) && ctx.maxChars > 0 ? ctx.maxChars : DEFAULT_MAX_CHARS;
+  const contents = ctx.fileContents || {};
+  const files = (focusArea?.files || []).filter(f => typeof contents[f] === 'string');
+
+  let budget = maxChars;
+  const blocks = [];
+  for (const f of files) {
+    const src = contents[f];
+    const slice = src.length > budget ? src.slice(0, Math.max(0, budget)) : src;
+    const truncated = slice.length < src.length;
+    blocks.push(`--- ${f}${truncated ? ' (truncated)' : ''} ---\n${slice}`);
+    budget -= slice.length;
+    if (budget <= 0) break;
+  }
+  const omitted = files.length - blocks.length;
+
+  return [
+    `You are hunting for security vulnerabilities in one area of a codebase.`,
+    `Area: ${focusArea?.label ?? 'unknown'} (${files.length} files)`,
+    ``,
+    `Your lens is ${lens.title}. ${lens.brief}`,
+    `Report ONLY through this lens. Another hunter covers the others.`,
+    ``,
+    `Rules:`,
+    `- Report a candidate only if you can name the entry point an attacker controls and the effect they achieve.`,
+    `- Do not report defence-in-depth gaps, style, or "could be hardened". Those are not candidates.`,
+    `- Cite a real file and line from the source below. A candidate with no location is discarded.`,
+    ``,
+    `Return JSON: {"candidates":[{"title","file","line","rationale","entryPoint","sink"}]}`,
+    `Return {"candidates":[]} if you find nothing. An empty result is a valid and useful answer.`,
+    ``,
+    omitted > 0 ? `NOTE: ${omitted} file(s) omitted, prompt budget exhausted (truncated context).\n` : ``,
+    ...blocks,
+  ].join('\n');
+}

package/src/discovery/llm-invoke.js

@@ -0,0 +1,31 @@
+//
+// Shared LLM endpoint caller. Both the hunter and the refutation panel need
+// the same default endpoint caller when tests don't inject a mock. Two copies
+// of a network call is one copy too many — if one path gets fixed and the
+// other does not, the bug stays buried in one direction.
+//
+
+const DEFAULT_TIMEOUT_MS = 60000;
+
+export async function defaultLlmInvoke(prompt, opts = {}) {
+  const timeoutMs = Number.isFinite(opts.timeoutMs) ? opts.timeoutMs : DEFAULT_TIMEOUT_MS;
+  // The URL is the operator's own configured endpoint, read from an environment
+  // variable they set. Reaching it is this module's entire purpose; no
+  // request-controlled input exists anywhere on this path, and an operator who
+  // can set this variable can already run code.
+  const res = await fetch(process.env.AGENTIC_SECURITY_LLM_ENDPOINT, { // agentic-security-ignore: CWE-918
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ prompt }),
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!res.ok) throw new Error(`llm endpoint returned ${res.status}`);
+  const body = await res.json();
+  return typeof body === 'string' ? body : (body?.text ?? JSON.stringify(body));
+}
+
+export function resolveLlmInvoke(opts = {}) {
+  if (opts.llmInvoke) return opts.llmInvoke;
+  if (!process.env.AGENTIC_SECURITY_LLM_ENDPOINT) return null;
+  return (prompt) => defaultLlmInvoke(prompt, { timeoutMs: opts.timeoutMs });
+}

package/src/discovery/partition.js

@@ -0,0 +1,92 @@
+//
+// Split the codebase into disjoint focus areas so parallel hunters cannot
+// converge on the same code.
+//
+// WHY THE CALL GRAPH AND NOT DIRECTORIES: a directory split hands one
+// subsystem to several hunters whenever a feature spans folders, and hands
+// unrelated code to one hunter whenever a folder is a grab bag. Weakly-
+// connected components over call edges group code that actually talks to
+// itself, which is the unit a hunter can reason about end to end.
+//
+// FILES, NOT FUNCTIONS, ARE THE ATOM. A hunter reads whole files. If two
+// components share a file they are merged, otherwise the same source lands in
+// two hunters' context and the convergence this module exists to prevent
+// comes straight back.
+import * as crypto from 'node:crypto';
+
+export function focusAreaId(files) {
+  const canon = [...new Set(files || [])].sort().join('\n');
+  return crypto.createHash('sha256').update(canon).digest('hex').slice(0, 12);
+}
+
+// Union-find over file paths.
+function makeDSU() {
+  const parent = new Map();
+  const find = (x) => {
+    if (!parent.has(x)) parent.set(x, x);
+    let r = x;
+    while (parent.get(r) !== r) r = parent.get(r);
+    while (parent.get(x) !== r) { const n = parent.get(x); parent.set(x, r); x = n; }
+    return r;
+  };
+  const union = (a, b) => { const ra = find(a), rb = find(b); if (ra !== rb) parent.set(ra, rb); };
+  return { find, union };
+}
+
+function labelFor(files) {
+  if (files.length === 1) return files[0];
+  const parts = files[0].split('/');
+  for (let i = parts.length - 1; i > 0; i--) {
+    const prefix = parts.slice(0, i).join('/') + '/';
+    if (files.every(f => f.startsWith(prefix))) return prefix;
+  }
+  return files[0] + ` (+${files.length - 1})`;
+}
+
+export function partitionCallGraph(callGraph, opts = {}) {
+  const fns = callGraph?.functions;
+  if (!fns || typeof fns.get !== 'function' || fns.size === 0) return [];
+  const maxAreas = Number.isInteger(opts.maxAreas) && opts.maxAreas > 0 ? opts.maxAreas : 8;
+
+  const dsu = makeDSU();
+  for (const fn of fns.values()) if (fn?.file) dsu.find(fn.file);
+  for (const e of callGraph.edges || []) {
+    const a = fns.get(e?.caller)?.file;
+    const b = fns.get(e?.callee)?.file;
+    if (a && b) dsu.union(a, b);
+  }
+
+  const filesByRoot = new Map();
+  for (const fn of fns.values()) {
+    if (!fn?.file) continue;
+    const root = dsu.find(fn.file);
+    if (!filesByRoot.has(root)) filesByRoot.set(root, new Set());
+    filesByRoot.get(root).add(fn.file);
+  }
+
+  const fnsByFile = new Map();
+  for (const fn of fns.values()) {
+    if (!fn?.file) continue;
+    if (!fnsByFile.has(fn.file)) fnsByFile.set(fn.file, []);
+    fnsByFile.get(fn.file).push(fn.qid);
+  }
+
+  const build = (files, label) => {
+    const sorted = [...files].sort();
+    const functions = sorted.flatMap(f => (fnsByFile.get(f) || [])).sort();
+    return { id: focusAreaId(sorted), label: label ?? labelFor(sorted), files: sorted, functions, size: functions.length };
+  };
+
+  let areas = [...filesByRoot.values()].map(s => build(s));
+  // Deterministic ranking: biggest first, ties broken by id so two runs on the
+  // same graph produce the same order.
+  areas.sort((a, b) => b.size - a.size || (a.id < b.id ? -1 : 1));
+
+  if (areas.length > maxAreas) {
+    const kept = areas.slice(0, maxAreas - 1);
+    const tail = areas.slice(maxAreas - 1);
+    kept.push(build(tail.flatMap(a => a.files), 'misc'));
+    areas = kept;
+  }
+  return areas;
+}

package/src/engine.js

@@ -90,6 +90,7 @@ import { scanOpenRedirect } from './sast/open-redirect.js';
 import { scanWrongContextSanitizer, scanSanitizerContextMismatch } from './sast/wrong-context-sanitizer.js';
 import { scanFrontendHygiene } from './sast/frontend-hygiene.js';
 import { scanCsvInjection } from './sast/csv-injection.js';
+import { scanCryptoSpecialist } from './sast/crypto-specialist.js';
 import { scanStoredTaint } from './sast/stored-taint.js';
 import { scanTreeSitterSinks } from './sast/tree-sitter-sinks.js';
 import { scanJavaStructural } from './sast/java-structural.js';
@@ -121,6 +122,8 @@ import { classifySecretCandidate as _entropyClassifySecret } from './sast/_secre
 import { annotateConfidence } from './posture/confidence.js';
 import { backfillFindingDefaults } from './posture/finding-defaults.js';
 import { annotatePocs } from './posture/poc-generator.js';
+import { annotateExecutionProofs } from './posture/prove-findings.js';
+import { mineVulnHistory, annotateHistoricalRisk } from './posture/vuln-archaeology.js';
 import { annotateVerifierVerdicts } from './posture/verifier.js';
 import { annotateRegressionTests } from './posture/regression-test-gen.js';
 import { annotateCalibratedConfidence } from './posture/calibration.js';
@@ -139,6 +142,7 @@ import { scanIacReachability } from './posture/iac-reachability.js';
 import { scanIamPolicies } from './posture/iam-policy.js';
 import { scanContainerRuntime } from './posture/container-runtime.js';
 import { scanBusinessLogic as scanBusinessLogicV2 } from './posture/business-logic.js';
+import { ingestLogicClaims } from './posture/logic-claims.js';
 import { annotateNarration } from './posture/flow-narration.js';
 import { applyPathConstraints } from './posture/path-predicates.js';
 // Phase 3 (Sentinel-parity Layer 1 + 2) — IR + interprocedural taint engine.
@@ -2290,6 +2294,80 @@ function _resetSuppressions(){ _suppressionLog.length = 0; }
 function _pfrMetaOnly(ta){ if(!ta||typeof ta!=='object')return {}; const o={}; for(const k of Object.keys(ta)){ if(k==='findings'||k==='sources'||k==='sinks'||k==='sanitizers')continue; o[k]=ta[k]; } return o; }
 function _getSuppressions(){ return [..._suppressionLog]; }
 
+// ── inline suppression pragma ───────────────────────────────────────────────
+//
+// `// agentic-security-ignore: <rule-id>` on the offending line. This is
+// documented in the root CLAUDE.md and `pr-comment.js` tells every reviewer to
+// use it — and until now NOTHING implemented it. A suppression mechanism that
+// silently does nothing is worse than not having one: a developer writes the
+// pragma, sees the finding again, and concludes the scanner is noisy rather
+// than that the pragma is dead.
+//
+// MATCHED ON THE LINE, AND ON THE RULE. A bare pragma with no rule id
+// suppresses every finding on that line; with an id it suppresses only findings
+// whose id, vuln or CWE contains it. Line-scoped rather than file-scoped on
+// purpose — a file-wide opt-out is how a whole module quietly leaves coverage.
+//
+// EVERY SUPPRESSION IS LOGGED to the same ledger custom rules use, so
+// `--include-suppressed` and the suppression summary show them. A suppression
+// nobody can see is indistinguishable from a finding that never fired.
+const _IGNORE_PRAGMA_RE = /(?:\/\/|#|\/\*|<!--)\s*agentic-security-ignore\s*:?\s*([^\n*]*?)\s*(?:\*\/|-->)?\s*$/;
+
+function _pragmaOnLine(content, line){
+  if (typeof content !== 'string' || !Number.isInteger(line) || line < 1) return null;
+  const lines = content.split('\n');
+  if (line > lines.length) return null;
+  const m = lines[line - 1].match(_IGNORE_PRAGMA_RE);
+  if (!m) return null;
+  return { rule: (m[1] || '').trim() };
+}
+
+function _pragmaSuppresses(pragma, f){
+  if (!pragma) return false;
+  if (!pragma.rule) return true;              // bare pragma: this line, any rule
+  const want = pragma.rule.toLowerCase();
+  const hay = `${f.id || ''} ${f.vuln || ''} ${f.cwe || ''} ${f.family || ''}`.toLowerCase();
+  return hay.includes(want);
+}
+
+// Filter one findings array in place. Returns the number removed.
+// Filter one findings array in place against inline pragmas. Returns the count.
+//
+// CALLED TWICE per scan, deliberately: once after the cross-file passes and
+// again after deep-mode IR findings are appended. See both call sites.
+//
+// KNOWN LIMITATION — a finding with no integer `line` can never be suppressed.
+// The guard below skips it, because a line-scoped pragma has nothing to match
+// against. This is not hypothetical: `struct:` detectors emit findings with no
+// `line` property at all (the line survives only inside the id string, e.g.
+// `struct:app.js:22:Mass_Assignment`), so a false positive from one of those
+// cannot be silenced by a pragma and has to be fixed at the source instead.
+//
+// A file-scoped fallback was considered and REJECTED. Widening a line pragma to
+// a whole file would silently suppress findings the author never looked at, and
+// silent over-suppression in a security tool is worse than the gap it closes.
+// The real fix is for struct detectors to carry a `line`; that changes finding
+// output repo-wide, moves the self-scan baseline, and belongs in its own change.
+function _applyIgnorePragmas(arr, fc){
+  if (!Array.isArray(arr)) return 0;
+  let removed = 0;
+  for (let i = arr.length - 1; i >= 0; i--) {
+    const f = arr[i];
+    const file = f && (f.file || f.sink?.file);
+    const line = f && Number(f.line ?? f.sink?.line);
+    if (!file || !Number.isInteger(line)) continue;
+    const pragma = _pragmaOnLine(fc[file], line);
+    if (!_pragmaSuppresses(pragma, f)) continue;
+    _suppressionLog.push({
+      vuln: f.vuln, file, line, snippet: f.snippet || '',
+      reason: `inline pragma: agentic-security-ignore${pragma.rule ? ': ' + pragma.rule : ''}`,
+    });
+    arr.splice(i, 1);
+    removed++;
+  }
+  return removed;
+}
+
 // FP-9 / Feat-4: custom rules loaded from .agentic-security/rules.{yml,yaml,json}
 // at scan root. Mutates SOURCE/SINK/SANITIZER pattern arrays in place when active;
 // snapshot lengths from the first call so subsequent scans can restore baseline.
@@ -7566,6 +7644,11 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
       aF.push(...scanSanitizerContextMismatch(p,c));
       aF.push(...scanFrontendHygiene(p,c));
       aF.push(...scanCsvInjection(p,c));
+      // R16 — specialist crypto-hygiene classes (constant-time comparison,
+      // secret zeroization). Narrow by design: keyed on the secret-ness of the
+      // identifier, and silent whenever the correct constant-time or
+      // guaranteed-wipe API is already present.
+      aF.push(...scanCryptoSpecialist(p,c));
       aF.push(...scanStoredTaint(p,c));
       aF.push(...scanJavaStructural(p,c));
       aF.push(...scanCsharpStructural(p,c));
@@ -7886,6 +7969,18 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
   // AGENTIC_SECURITY_TREE_SITTER=1; degrades to no-op without the optional dep).
   if(process.env.AGENTIC_SECURITY_TREE_SITTER==='1'){try{aF.push(...await scanTreeSitterSinks(fc));}catch(_){}}
   let finalFindings;try{finalFindings=dedupeFindingsWithEvidence(aF);}catch(_){finalFindings=dd(aF,f=>f.id);}
+  // Inline `agentic-security-ignore` pragmas, pass 1 of 2. This covers every
+  // finding that exists BY THIS POINT — the pattern detectors, the cross-file
+  // passes, and the logic and secrets buckets, which are the ones a developer
+  // is most likely to want silenced on a specific line.
+  //
+  // It does NOT cover deep-mode IR findings: those are appended much further
+  // down (search `finalFindings.push(...irFindings)`), so a second pass runs
+  // there. For years this call carried a comment claiming it ran "after every
+  // cross-file pass has appended", which was false for the deep path — a
+  // correctly-formed pragma on the exact line of an ir-taint finding did
+  // nothing, silently, in the mode the CLI actually uses.
+  try{ _applyIgnorePragmas(finalFindings, fc); _applyIgnorePragmas(aLogic, fc); _applyIgnorePragmas(aSecrets, fc); }catch(_){}
   // #1 — centralized SSRF/path guard recognition: drop CWE-918/CWE-22 findings
   // on code hardened by a host allow/deny check or a path containment guard,
   // regardless of which detector emitted them. Opt out: AGENTIC_SECURITY_NO_GUARD_RECOGNITION=1.
@@ -7986,6 +8081,8 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
   // Every catch in this block writes into _annotatorErrors so the operator
   // can tell "didn't run" from "ran cleanly." The array is surfaced as
   // scan.annotatorErrors in the report; an empty array means clean.
+  let _executionProofSummary = null, _vulnHistory = null;
+  let _logicClaims = null;
   const _annotatorErrors = [];
   const _runAnnotator = (phase, fn) => {
     try { return fn(); }
@@ -8195,6 +8292,28 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
   _runAnnotator("annotatePocs", () => { annotatePocs(finalFindings, { routes: aR, fileContents: fc }); });
   // FR-VER-3: regression-test generator (builds on the PoC artifact).
   _runAnnotator("annotateRegressionTests", () => { annotateRegressionTests(finalFindings); });
+  // R2 — execution proof. Synthesizes a SANDBOX-RUNNABLE PoC (the HTTP PoCs
+  // above need a live server, so they can never be executed by the prover)
+  // and lets R1's sandbox decide the tier. Opt-in via AGENTIC_SECURITY_PROVE=1
+  // because it executes code derived from the scanned project; with the flag
+  // unset, or with no confinement backend, nothing runs and no tier moves.
+  // Awaited rather than fire-and-forget: a proof that lands after the report
+  // is emitted is not evidence anyone sees.
+  // R14 — vulnerability archaeology. Mines git history for where this team has
+  // introduced security bugs before and attaches an ADVISORY per-file prior.
+  // Never a finding and never a severity change: those bugs are fixed, and a
+  // historical fix is not evidence of a present defect. Opt-in because it
+  // shells out to git over up to 500 commits.
+  _runAnnotator('annotateHistoricalRisk', () => {
+    if (process.env.AGENTIC_SECURITY_ARCHAEOLOGY !== '1' || !scanRoot) return;
+    _vulnHistory = mineVulnHistory(scanRoot);
+    annotateHistoricalRisk(finalFindings, _vulnHistory);
+  });
+  try {
+    _executionProofSummary = await annotateExecutionProofs(finalFindings, { fileContents: fc });
+  } catch (e) {
+    _annotatorErrors.push({ phase: 'annotateExecutionProofs', err: String((e && e.message) || e) });
+  }
   // Phase-1 next-gen P1.2 (FR-VER-3, FR-VER-6, FR-VER-7): per-finding
   // verifier verdict — verified-exploit (live PoC ran), verified-by-llm,
   // verified-sanitizer-absence, unverified-by-design, or cannot-verify.
@@ -8341,6 +8460,18 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
         f.validator_verdict = 'unvalidated';
       }
       finalFindings.push(...irFindings);
+      // Pragma pass 2 of 2 — see the pass-1 comment far above. Deep-mode IR
+      // findings land here, long after pass 1 ran, so without this an
+      // `agentic-security-ignore` on an ir-taint finding is inert. Deep mode is
+      // what the CLI uses outside CI and taint findings are the ones users most
+      // want to silence, so the documented feature did nothing in the case that
+      // mattered most.
+      //
+      // Re-running over the already-filtered array is safe and does not
+      // double-log: pass 1's removals are gone from `finalFindings`, so only the
+      // newly-appended IR findings can match here, and each suppression reaches
+      // the ledger exactly once.
+      try{ _applyIgnorePragmas(finalFindings, fc); }catch(_){}
       // Java SCA enrichment: use deep-mode IR call graph to improve Java function reachability
       try {
         for (const sc of supplyChain) {
@@ -8434,6 +8565,25 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
   catch (e) { _annotatorErrors.push({ phase: '_enrichWithScorecard', err: String((e && e.message) || e) }); }
   // 0.8.0 Feat-10: license policy
   try{const lp=loadLicensePolicy(scanRoot);if(lp){const lv=evaluateLicensePolicy(annotatedComponents,lp);aLogic.push(...lv);}}catch(_){}
+  // PRD Epic 6: business-logic claims from a reviewing agent, put through the
+  // deterministic refutation lenses before they are allowed anywhere near the
+  // report. A claim citing a file that was never scanned, misquoting the code,
+  // or contradicted by the handler it names comes back quarantined. Refuted
+  // claims are KEPT — the tier's contract is recall-preserving, same as
+  // falsification's — so the reader can see what the reviewer said and why no
+  // second party could corroborate it.
+  try {
+    if (scanRoot) {
+      const raw = fs.readFileSync(path.join(scanRoot, '.agentic-security', 'logic-claims.json'), 'utf8');
+      const parsed = JSON.parse(raw);
+      const incoming = Array.isArray(parsed) ? parsed : (parsed && parsed.claims) || [];
+      if (incoming.length) {
+        const r = ingestLogicClaims(incoming, { fileContents: fc });
+        _logicClaims = r.summary;
+        aLogic.push(...r.claims);
+      }
+    }
+  } catch(_) { /* absent or unreadable → the tier simply contributes nothing */ }
   // Phase 4 / Item 7 of the SCA improvement plan: load sca-policy.yml and
   // apply accept-risk / SLA / major-version-freeze rules. supplyChain
   // findings get suppressed/tagged in place.
@@ -8731,7 +8881,7 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
   // Addition #3 — root-cause sweep: from confirmed findings, find sibling instances
   // detectors missed, with total-count accounting. Confirmed-only (cheap by default).
   let _rootCauseSweep = null; try { _rootCauseSweep = sweepRootCauses(finalFindings, fc); } catch { _rootCauseSweep = null; }
-  return{entrypointInventory:_entrypointInventory,rootCauseSweep:_rootCauseSweep,routes:dd(aR,r=>`${r.method}:${r.path}:${r.file}:${r.line}`),findings:finalFindings,sources:aSrc,sinks:aSink,sanitizers:aSan,filesScanned:files.length,crossFileCount:cf.length,logicVulns:aLogic,supplyChain,components:annotatedComponents,secrets:aSecrets,ciphers:{atRest:aCiphersRest,inTransit:aCiphersTransit},pfr,fc,suppressions:_getSuppressions(),_v3,_scanMeta,_engineErrors:{cppDataflowParseErrors:_cppDataflowParseErrors.value},annotatorErrors:_annotatorErrors,threatModel:_threatModel,sbomDiff:_sbomDiff,complianceReport:_complianceReport,exploitBundles:_exploitBundles,pqcPlan:_pqcPlan,licenseGraph:_licenseGraph,attributions:_attributions,attackTaxonomy:_taxonomySummary};}
+  return{entrypointInventory:_entrypointInventory,rootCauseSweep:_rootCauseSweep,routes:dd(aR,r=>`${r.method}:${r.path}:${r.file}:${r.line}`),findings:finalFindings,sources:aSrc,sinks:aSink,sanitizers:aSan,filesScanned:files.length,crossFileCount:cf.length,logicVulns:aLogic,supplyChain,components:annotatedComponents,secrets:aSecrets,ciphers:{atRest:aCiphersRest,inTransit:aCiphersTransit},pfr,fc,suppressions:_getSuppressions(),_v3,_scanMeta,_engineErrors:{cppDataflowParseErrors:_cppDataflowParseErrors.value},annotatorErrors:_annotatorErrors,executionProof:_executionProofSummary,logicClaims:_logicClaims,vulnHistory:_vulnHistory,threatModel:_threatModel,sbomDiff:_sbomDiff,complianceReport:_complianceReport,exploitBundles:_exploitBundles,pqcPlan:_pqcPlan,licenseGraph:_licenseGraph,attributions:_attributions,attackTaxonomy:_taxonomySummary};}
 
 // Post-aggregation classification: every source becomes "unsafe"|"safe"; every sink becomes "confirmed"|"safe".
 // Orphans (no finding linkage) are bucketed by file-local heuristic so the UI shows binary states only.

package/src/llm-validator/cost-ceiling.js

@@ -0,0 +1,199 @@
+// R12 — a hard cost ceiling for the LLM validator tier.
+//
+// A cost *advisor* already exists (`hooks/model-cost-advisor.js`): it biases a
+// quality/cost dial and warns as spend approaches a soft budget. What did not
+// exist is a CAP — something that refuses to spend rather than advising about
+// it. A soft budget you can sail past is not a ceiling, and "it warned you" is
+// no comfort on an invoice.
+//
+// THE DISTINCTION THAT MATTERS: this never degrades quality to fit a budget.
+// It stops. Silently switching to a cheaper model or a shorter prompt to stay
+// under a cap would change what the scan MEANS while reporting the same shape,
+// and a finding validated by a model the operator did not choose is a
+// different claim than the one they asked for. When the cap binds, remaining
+// findings are left explicitly `unvalidated` with a reason naming the cap.
+//
+// FAIL CLOSED ON UNKNOWN PRICING. A ceiling that cannot price a call cannot
+// enforce anything. Rather than spending unmetered and reporting a $0.00
+// ledger, an unpriceable model refuses every call. Operators override with
+// `AGENTIC_SECURITY_LLM_PRICE_USD_PER_MTOK="<in>,<out>"`.
+//
+// PRICES ARE OPERATOR-SUPPLIED FACTS, NOT ENGINE FACTS. The built-in table is a
+// convenience for the shipped preset, and list prices change. It is deliberately
+// small, it is stamped with the date it was last checked, and anything not in it
+// must be priced explicitly. Do not grow this table casually — a stale price
+// here silently mis-enforces every ceiling built on it.
+
+// USD per 1,000,000 tokens, {input, output}. Last checked: 2026-08-07.
+const PRICES = Object.freeze({
+  'claude-haiku-4-5': { input: 1.00, output: 5.00 },
+});
+
+export class CapExceeded extends Error {
+  constructor(msg) { super(msg); this.name = 'CapExceeded'; }
+}
+
+/** Parse the configured cap. Returns null when no cap is set (feature off). */
+export function parseCapUsd(env = process.env) {
+  const raw = env.AGENTIC_SECURITY_LLM_MAX_USD;
+  if (raw == null || raw === '') return null;
+  const n = Number(raw);
+  // A malformed cap is refused rather than ignored: treating "abc" or a
+  // negative as "no cap" turns a typo into unlimited spend.
+  if (!Number.isFinite(n) || n < 0) {
+    throw new CapExceeded(`AGENTIC_SECURITY_LLM_MAX_USD is not a non-negative number: ${JSON.stringify(raw)}`);
+  }
+  return n;
+}
+
+/** Resolve {input, output} USD per 1M tokens for a model, or null if unknown. */
+export function priceFor(model, env = process.env) {
+  const override = env.AGENTIC_SECURITY_LLM_PRICE_USD_PER_MTOK;
+  if (override) {
+    const parts = String(override).split(',').map(s => Number(s.trim()));
+    if (parts.length === 2 && parts.every(n => Number.isFinite(n) && n >= 0)) {
+      return { input: parts[0], output: parts[1], source: 'override' };
+    }
+    return null; // malformed override -> unpriceable, so fail closed
+  }
+  const p = PRICES[model];
+  return p ? { ...p, source: 'built-in' } : null;
+}
+
+export function costOf({ inputTokens = 0, outputTokens = 0 }, price) {
+  if (!price) return null;
+  return (inputTokens / 1e6) * price.input + (outputTokens / 1e6) * price.output;
+}
+
+/**
+ * A ledger enforcing a hard ceiling.
+ *
+ * `capUsd === null` means no ceiling was configured: `canAfford` always allows
+ * and nothing is enforced. That is the default, and it is the ONLY state in
+ * which unpriceable models are permitted — without a cap there is nothing to
+ * enforce, so refusing would break existing behaviour for no benefit.
+ */
+export function createCostLedger({ capUsd = null, model = 'unknown', env = process.env } = {}) {
+  const price = priceFor(model, env);
+  let spentUsd = 0, calls = 0, refusals = 0;
+  // How much of `spentUsd` came from ESTIMATES rather than reported usage.
+  // Tracked separately because the two are not the same kind of number: the
+  // estimate charges the full permitted output length, which most replies
+  // never reach, so a ledger fed only estimates reports an upper bound. That
+  // is fine for ENFORCEMENT (it can only stop early, never late) and wrong for
+  // REPORTING. Callers get told which they are looking at.
+  let estimatedUsd = 0, estimatedCalls = 0;
+
+  const enforcing = capUsd != null;
+
+  return {
+    enforcing,
+    capUsd,
+    model,
+    price,
+    spentUsd: () => spentUsd,
+    calls: () => calls,
+    refusals: () => refusals,
+    remainingUsd: () => (enforcing ? Math.max(0, capUsd - spentUsd) : Infinity),
+
+    /**
+     * May a call costing at most `estimate` tokens proceed?
+     * @returns {{ok:boolean, reason?:string}}
+     */
+    canAfford({ inputTokens = 0, outputTokens = 0 } = {}) {
+      if (!enforcing) return { ok: true };
+      if (!price) {
+        refusals++;
+        return {
+          ok: false,
+          reason: `no price is known for model '${model}', so a spend ceiling cannot be enforced. `
+            + 'Set AGENTIC_SECURITY_LLM_PRICE_USD_PER_MTOK="<input>,<output>" (USD per 1M tokens) '
+            + 'or remove AGENTIC_SECURITY_LLM_MAX_USD. Refusing rather than spending unmetered.',
+        };
+      }
+      // Charge the ESTIMATE before the call, not the actual after it. Checking
+      // afterwards would let a single call blow through the cap and report the
+      // overrun as a fait accompli.
+      const projected = spentUsd + (costOf({ inputTokens, outputTokens }, price) || 0);
+      if (projected > capUsd) {
+        refusals++;
+        return {
+          ok: false,
+          reason: `cost ceiling reached: this call would bring spend to $${projected.toFixed(4)}, `
+            + `over the $${capUsd.toFixed(4)} cap (AGENTIC_SECURITY_LLM_MAX_USD). `
+            + 'Remaining findings are left unvalidated rather than validated by a cheaper substitute.',
+        };
+      }
+      return { ok: true };
+    },
+
+    /**
+     * Record usage after a call.
+     * @param {object} usage {inputTokens, outputTokens}
+     * @param {object} [opts]
+     * @param {boolean} [opts.measured] true when the figures came from the
+     *   provider's own usage report; false when they are our pre-call
+     *   estimate. Defaults to false — the conservative reading, so a caller
+     *   that forgets to say cannot accidentally upgrade an estimate into a
+     *   measurement.
+     */
+    record({ inputTokens = 0, outputTokens = 0 } = {}, { measured = false } = {}) {
+      calls++;
+      const c = costOf({ inputTokens, outputTokens }, price);
+      // Unpriceable usage is not free. With no cap it is simply not tracked;
+      // with a cap, `canAfford` already refused, so this branch cannot spend.
+      if (c != null) spentUsd += c;
+      if (!measured) {
+        estimatedCalls++;
+        if (c != null) estimatedUsd += c;
+      }
+      return spentUsd;
+    },
+
+    /** Reportable state. Always carries the cap so a figure cannot be read alone. */
+    state() {
+      return {
+        enforcing,
+        capUsd,
+        model,
+        priceSource: price?.source || null,
+        priceable: !!price,
+        spentUsd: Number(spentUsd.toFixed(6)),
+        remainingUsd: enforcing ? Number(Math.max(0, capUsd - spentUsd).toFixed(6)) : null,
+        calls,
+        refusals,
+        // Disclosure, not decoration. `spentUsd` is an UPPER BOUND to the
+        // extent these are non-zero, and a reader has no way to know that
+        // without being told.
+        estimatedCalls,
+        estimatedUsd: Number(estimatedUsd.toFixed(6)),
+        fullyMeasured: estimatedCalls === 0,
+      };
+    },
+  };
+}
+
+/** One-line summary; null when no ceiling is configured. */
+export function renderCostCeiling(s) {
+  if (!s || !s.enforcing) return null;
+  if (!s.priceable) {
+    return `LLM cost ceiling: ENFORCED but model '${s.model}' is unpriceable — ${s.refusals} call(s) refused, nothing spent.`;
+  }
+  // Say "at most" whenever any part of the figure is an estimate. The word is
+  // the whole point: without it an upper bound reads as a measurement.
+  const qualifier = s.fullyMeasured ? '' : 'at most ';
+  const base = `LLM spend ${qualifier}$${s.spentUsd.toFixed(4)} of $${s.capUsd.toFixed(4)} cap across ${s.calls} call(s)`;
+  const parts = [base];
+  if (!s.fullyMeasured) {
+    parts.push(
+      `${s.estimatedCalls} of those call(s) reported no token usage, so their cost is ESTIMATED at the `
+      + 'full permitted output length — the true spend is lower',
+    );
+  }
+  if (s.refusals) {
+    parts.push(`${s.refusals} call(s) REFUSED at the ceiling — those findings are unvalidated, not validated`);
+  }
+  return parts.join('; ') + '.';
+}
+
+export const _internals = { PRICES };