@clear-capabilities/agentic-security-scanner 0.133.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

@@ -142,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.
@@ -2293,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.
@@ -7894,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.
@@ -7995,6 +8082,7 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null,
   // 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(); }
@@ -8372,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) {
@@ -8465,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.
@@ -8762,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,executionProof:_executionProofSummary,vulnHistory:_vulnHistory,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/index.js

@@ -73,6 +73,7 @@ import { signLastScan } from '../posture/integrity.js';
 // doesn't have to reach through the `_internal` underscore-prefixed export.
 import { createCostLedger, parseCapUsd, renderCostCeiling } from './cost-ceiling.js';
 import { localEndpointConfig } from './local-endpoint.js';
+import { resolveProvider, buildProviderRequest, providerMatrix } from './providers.js';
 
 // The output cap we request. Shared with the cost estimate so the ceiling
 // charges exactly what we permit the model to produce.
@@ -124,49 +125,36 @@ Snippet (single line, trusted from scanner output): {{snippet}}
 Reply now with the JSON object on the last line of your response. Nothing else after it.
 `;
 
+// Delegates to the provider seam (PRD Epic 3). Kept as a thin adapter rather
+// than deleted: every call site, test and cost-ceiling path already speaks this
+// shape, and changing a seam and all its consumers at once is how a refactor
+// becomes a regression. `_localPresetRefusal` still carries a REFUSAL
+// distinctly from "nothing configured" — the local preset declining a remote
+// endpoint must not read as an absent config.
 function endpointConfig() {
-  // R11 — the local path is checked FIRST, ahead of the BYO endpoint, because
-  // it is the only mode that makes a promise about where data goes. If the
-  // operator asked for `local`, a stray AGENTIC_SECURITY_LLM_ENDPOINT pointing
-  // at a remote host must not quietly win: it is refused, and the tier stays
-  // off. Silently honouring it would break the one guarantee the preset exists
-  // to provide.
-  if ((process.env.AGENTIC_SECURITY_LLM_PRESET || '').toLowerCase() === 'local') {
-    const r = localEndpointConfig();
-    if (!r.ok) {
-      _localPresetRefusal = r.reason;
-      return null;
-    }
-    _localPresetRefusal = null;
-    return r.config;
-  }
-  // Explicit BYO endpoint always wins (unchanged behaviour).
-  const endpoint = process.env.AGENTIC_SECURITY_LLM_ENDPOINT;
-  if (endpoint) {
-    return { endpoint, apiKey: process.env.AGENTIC_SECURITY_LLM_API_KEY, model: process.env.AGENTIC_SECURITY_LLM_MODEL || 'unknown', preset: null };
-  }
-  // #18 — first-class Anthropic preset. Opt-in via AGENTIC_SECURITY_LLM_PRESET=anthropic
-  // + a key (AGENTIC_SECURITY_LLM_API_KEY or ANTHROPIC_API_KEY): makes the FP-suppression
-  // validator reachable with just a key — no BYO endpoint URL or request-shape wrangling.
-  // Offline-degrading: no key → null (validator no-ops; no runtime cloud call by default).
-  if ((process.env.AGENTIC_SECURITY_LLM_PRESET || '').toLowerCase() === 'anthropic') {
-    const apiKey = process.env.AGENTIC_SECURITY_LLM_API_KEY || process.env.ANTHROPIC_API_KEY;
-    if (!apiKey) return null;
-    return {
-      endpoint: 'https://api.anthropic.com/v1/messages',
-      apiKey,
-      model: process.env.AGENTIC_SECURITY_LLM_MODEL || 'claude-haiku-4-5',
-      preset: 'anthropic',
-    };
-  }
-  return null;
+  const r = resolveProvider({ role: 'validate' });
+  if (!r.ok) { _localPresetRefusal = r.reason || null; return null; }
+  _localPresetRefusal = null;
+  const c = r.config;
+  return {
+    endpoint: c.endpoint,
+    apiKey: c.apiKey,
+    model: c.model,
+    preset: c.provider === 'anthropic' ? 'anthropic' : (c.provider === 'local' ? 'local' : null),
+    provider: c.provider,
+    egress: c.egress,
+    _shape: c.shape,
+  };
 }
 
 // Shape the request for the target: the Anthropic Messages API needs an
 // x-api-key header (added by the caller), an anthropic-version header, and a
 // {model, max_tokens, messages:[…]} body with the reply in content[].text. The
 // generic path posts {prompt, model} with a Bearer header. Pure — no I/O.
-function buildRequest(model, prompt, preset) {
+function buildRequest(model, prompt, preset, shape) {
+  // A resolved provider carries its own wire shape; use it. The hand-written
+  // branches below remain for callers that pass only a preset string.
+  if (shape) return buildProviderRequest({ shape, model, apiKey: null }, prompt, MAX_OUTPUT_TOKENS);
   if (preset === 'anthropic') {
     return {
       headers: { 'Content-Type': 'application/json', 'anthropic-version': '2023-06-01' },
@@ -347,8 +335,8 @@ function renderPrompt(finding, fileContents, challenge, nonce) {
     .replace('{{context}}', sterileContext || '(no surrounding code available)');
 }
 
-async function callEndpoint(endpoint, apiKey, model, prompt, preset = null) {
-  const { headers, body, extractText, extractUsage } = buildRequest(model, prompt, preset);
+async function callEndpoint(endpoint, apiKey, model, prompt, preset = null, shape = null) {
+  const { headers, body, extractText, extractUsage } = buildRequest(model, prompt, preset, shape);
   if (apiKey) {
     if (preset === 'anthropic') headers['x-api-key'] = apiKey;
     else headers['Authorization'] = `Bearer ${apiKey}`;
@@ -520,7 +508,7 @@ export async function validateOne(finding, fileContents, scanRoot, ledger = null
     }
   }
 
-  const resp = await callEndpoint(cfg.endpoint, cfg.apiKey, cfg.model, prompt, cfg.preset);
+  const resp = await callEndpoint(cfg.endpoint, cfg.apiKey, cfg.model, prompt, cfg.preset, cfg._shape);
   // Record actual usage when the endpoint reports it, else the estimate. An
   // unreported call is never free — but the two are recorded DISTINCTLY, so
   // the reported spend can say which it is. Presenting an upper bound as a
@@ -629,6 +617,8 @@ export async function validateMany(findings, { fileContents, scanRoot, concurren
     findings.costCeiling = ledger.state();
     findings.costCeilingSummary = renderCostCeiling(ledger.state());
   }
+  // Which provider each role would use. No keys, ever — this is reported.
+  findings.providerMatrix = providerMatrix();
   const _cs = cacheStats();
   findings.validatorCache = _cs;
   if (_cs.unverified > 0) {