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

package/src/llm-validator/index.js

@@ -33,6 +33,26 @@
 //      file:line mismatch → verdict='escalate' (KEEP the finding). The
 //      validator can NEVER silently reject a finding it didn't successfully
 //      verify.
+//   8. A `reject` cannot DELETE a strongly-provenanced finding (IR-TAINT,
+//      MULTI-SINK, execution-proven) — it is demoted to `escalate` and the
+//      refusal is recorded. See `applyValidatorVerdicts`.
+//   9. The response cache is HMAC-signed and verified on read; an unsigned,
+//      tampered or foreign-keyed entry is a MISS, never a verdict.
+//
+// WHAT ITEMS 1-6 DO AND DO NOT BUY, stated precisely because an earlier version
+// of this header overstated it. The delimiters, challenge and file:line echo
+// defend against a FORGED or REPLAYED response — they prove the reply came from
+// a model that saw this prompt and judged this finding. They do NOT prevent the
+// model being PERSUADED by instructions inside the code it legitimately read:
+// such a reply echoes the challenge correctly because the model really did see
+// it. Item 4 asks the model to self-report injection attempts, and the
+// `/prompt-injection/i` check in `validateResponse` acts on that — but it only
+// fires when the model volunteers the phrase, so "reject, and don't mention
+// injection" walks past it.
+//
+// That is why items 8 and 9 exist. The property "an attacker cannot cause a
+// finding to be deleted" is now enforced structurally for findings real
+// analysis produced, rather than inferred from prompt hardening.
 //   6. The reasoning string is sanitized before storing/rendering — stops
 //      secondary markdown/HTML injection into reports.
 //   7. Concurrent worker pool replaced with deterministic sorted iteration
@@ -46,10 +66,23 @@ import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { statePath, ensureStateDir, safeWriteState } from '../posture/state-dir.js';
 import { redactSecrets } from './redact.js';
+import { signLastScan } from '../posture/integrity.js';
 
 // Bump on every prompt change so the cache invalidates. Exported as a
 // stable public symbol (premortem 4R-15) so the validator-cache GC subcommand
 // 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.
+const MAX_OUTPUT_TOKENS = 512;
+
+// Why the local preset declined, if it did. Surfaced on the batch so a refusal
+// reads as a refusal rather than as "no endpoint configured".
+let _localPresetRefusal = null;
+
 export const PROMPT_VERSION = 'v2.0-hardened';
 const CACHE_DIR = '.agentic-security/llm-cache';
 
@@ -92,45 +125,63 @@ 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() {
-  // 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' },
-      body: { model, max_tokens: 512, messages: [{ role: 'user', content: prompt }] },
+      body: { model, max_tokens: MAX_OUTPUT_TOKENS, messages: [{ role: 'user', content: prompt }] },
       extractText: (j) => (Array.isArray(j?.content) ? j.content.filter(b => b?.type === 'text').map(b => b.text || '').join('') : ''),
+      // R12 — real token usage, so the cost ledger books what was actually
+      // spent instead of the worst case it had to assume beforehand.
+      extractUsage: (j) => (j?.usage && Number.isFinite(j.usage.input_tokens)
+        ? { inputTokens: j.usage.input_tokens, outputTokens: j.usage.output_tokens || 0 }
+        : null),
     };
   }
   return {
     headers: { 'Content-Type': 'application/json' },
     body: { prompt, model },
     extractText: (j) => (j && (j.response || j.text || j.content || j.output || j.choices?.[0]?.message?.content || j.message?.content)) || '',
+    // OpenAI-compatible servers (and most local ones) report usage in this
+    // shape. A server that reports nothing yields null, and the ledger then
+    // records an ESTIMATE and says so — it never silently presents one as the
+    // other.
+    extractUsage: (j) => {
+      const u = j?.usage;
+      if (!u) return null;
+      const inputTokens = u.prompt_tokens ?? u.input_tokens;
+      const outputTokens = u.completion_tokens ?? u.output_tokens ?? 0;
+      return Number.isFinite(inputTokens) ? { inputTokens, outputTokens } : null;
+    },
   };
 }
 
@@ -150,15 +201,78 @@ function cacheKey(finding, fileHash, modelId) {
   return crypto.createHash('sha256').update(material).digest('hex');
 }
 
+// The cache is INTEGRITY-PROTECTED, and it has to be: a cache hit assigns a
+// verdict directly, and a `reject` verdict DELETES a finding. That made the
+// cache a deletion primitive — planting one JSON file under
+// `.agentic-security/llm-cache/` removed a critical finding with no model call
+// and no network, deterministically. The key is derivable by anyone with repo
+// access (file hash, path, prompt version, model id are all knowable), and the
+// realistic delivery vector is not a repo write at all: CI restores cache
+// directories between runs.
+//
+// `last-scan.json` has been HMAC-signed for exactly this reason. The cache that
+// can delete findings had nothing. Same mechanism, same key handling — no
+// second crypto path is introduced.
+//
+// AN UNVERIFIABLE ENTRY IS A MISS, NEVER A VERDICT. That includes the entry
+// being unsigned, signed under a different install key, or structurally
+// malformed. The cost of a miss is one model call; the cost of trusting a
+// planted entry is a silently deleted vulnerability.
+function _cacheSignable(value) {
+  // Sign the fields that carry meaning. Signing the serialised object would
+  // make the signature depend on key order and on any field added later.
+  return [
+    String(value?.verdict ?? ''),
+    String(value?.confidence ?? ''),
+    String(value?.reasoning ?? ''),
+    String(value?.model ?? ''),
+    String(value?.prompt_version ?? ''),
+  ].join('\u0000');
+}
+
+// A cache entry that EXISTS but does not verify is a different event from an
+// ordinary miss, and it must be countable. In CI the per-install key is
+// regenerated every run (nothing persists `$XDG_CONFIG_HOME`), so a restored
+// cache directory verifies against nothing and the hit rate is silently zero —
+// the operator pays for every call twice over and sees no signal. Fail-closed is
+// right; failing closed invisibly is not.
+const _cacheStats = { hits: 0, misses: 0, unverified: 0 };
+function cacheStats() { return { ..._cacheStats }; }
+function _resetCacheStatsForTests() { _cacheStats.hits = 0; _cacheStats.misses = 0; _cacheStats.unverified = 0; }
+
 function readCache(scanRoot, key) {
   const fp = statePath(scanRoot, 'llm-cache', key + '.json');
-  if (!fs.existsSync(fp)) return null;
-  try { return JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { return null; }
+  if (!fs.existsSync(fp)) { _cacheStats.misses++; return null; }
+  let raw;
+  try { raw = JSON.parse(fs.readFileSync(fp, 'utf8')); } catch { _cacheStats.unverified++; return null; }
+  if (!raw || typeof raw !== 'object') { _cacheStats.unverified++; return null; }
+
+  // Verdict allowlist on READ, mirroring validateResponse. A cached verdict is
+  // as much untrusted input as a model response is.
+  if (!['accept', 'reject', 'escalate'].includes(raw.verdict)) { _cacheStats.unverified++; return null; }
+
+  const sig = typeof raw.sig === 'string' ? raw.sig : null;
+  if (!sig) { _cacheStats.unverified++; return null; }
+  let expected;
+  try { expected = signLastScan(_cacheSignable(raw)); } catch { _cacheStats.unverified++; return null; }
+  // Constant-time compare; length mismatch short-circuits before timingSafeEqual
+  // (which throws on unequal lengths).
+  if (sig.length !== expected.length) { _cacheStats.unverified++; return null; }
+  try {
+    if (!crypto.timingSafeEqual(Buffer.from(sig, 'utf8'), Buffer.from(expected, 'utf8'))) {
+      _cacheStats.unverified++; return null;
+    }
+  } catch { _cacheStats.unverified++; return null; }
+  _cacheStats.hits++;
+  return raw;
 }
 
 function writeCache(scanRoot, key, value) {
   const fp = statePath(scanRoot, 'llm-cache', key + '.json');
-  safeWriteState(fp, JSON.stringify(value, null, 2));
+  let signed = value;
+  try { signed = { ...value, sig: signLastScan(_cacheSignable(value)) }; }
+  catch { return; } // cannot sign -> do not cache; an unsignable entry would never be read back
+  safeWriteState(fp, JSON.stringify(signed, null, 2));
 }
 
 function fileHashOf(fileContents, file) {
@@ -221,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 } = 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}`;
@@ -231,7 +345,7 @@ async function callEndpoint(endpoint, apiKey, model, prompt, preset = null) {
     const r = await fetch(endpoint, { method: 'POST', headers, body: JSON.stringify(body) });
     if (!r.ok) return { ok: false, error: `HTTP ${r.status}` };
     const j = await r.json().catch(() => null);
-    return { ok: true, text: String(extractText(j) || '') };
+    return { ok: true, text: String(extractText(j) || ''), usage: extractUsage ? extractUsage(j) : null };
   } catch (e) {
     return { ok: false, error: e.message };
   }
@@ -322,7 +436,7 @@ export function validateResponse(obj, { challenge, file, line }) {
 // Pre-flight (premortem 2R2.2): findings WITHOUT a precise file:line cannot
 // be cross-checked against the LLM response (the model can trivially echo
 // empty/zero values). Such findings are marked unvalidated and KEPT.
-export async function validateOne(finding, fileContents, scanRoot) {
+export async function validateOne(finding, fileContents, scanRoot, ledger = null) {
   const cfg = endpointConfig();
   if (!cfg) {
     finding.validator_verdict = 'unvalidated';
@@ -371,7 +485,40 @@ export async function validateOne(finding, fileContents, scanRoot) {
   const challenge = crypto.randomBytes(8).toString('hex');
   const nonce     = crypto.randomBytes(8).toString('hex');
   const prompt = renderPrompt(finding, fileContents, challenge, nonce);
-  const resp = await callEndpoint(cfg.endpoint, cfg.apiKey, cfg.model, prompt, cfg.preset);
+
+  // R12 — the hard ceiling. Checked BEFORE the call, against a conservative
+  // estimate: input from the prompt we are about to send, output at the full
+  // max_tokens we allow. Charging the worst case is the only direction that
+  // cannot overshoot, and checking afterwards would let a call blow the cap
+  // and report the overrun as already spent.
+  const _est = {
+    inputTokens: Math.ceil(prompt.length / 4),
+    outputTokens: MAX_OUTPUT_TOKENS,
+  };
+  if (ledger) {
+    const afford = ledger.canAfford(_est);
+    if (!afford.ok) {
+      // Explicitly unvalidated, with the reason. NOT downgraded to a cheaper
+      // model and NOT treated as accepted — a finding nobody checked must not
+      // read like one that passed.
+      finding.validator_verdict = 'unvalidated';
+      finding.unvalidated = true;
+      finding.validator_skipped_reason = afford.reason;
+      return { verdict: 'unvalidated', error: 'cost-ceiling' };
+    }
+  }
+
+  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
+  // measurement is the defect this distinction exists to prevent: the estimate
+  // charges the full max_tokens for output, which most replies never reach.
+  if (ledger) {
+    const u = resp?.usage;
+    if (u) ledger.record(u, { measured: true });
+    else ledger.record(_est, { measured: false });
+  }
   if (!resp.ok) {
     finding.validator_verdict = 'unvalidated';
     finding.unvalidated = true;
@@ -420,7 +567,9 @@ export async function validateMany(findings, { fileContents, scanRoot, concurren
     for (const f of findings) {
       f.validator_verdict = 'unvalidated';
       f.unvalidated = true;
+      if (_localPresetRefusal) f.validator_skipped_reason = _localPresetRefusal;
     }
+    if (_localPresetRefusal) findings.localPathRefusal = _localPresetRefusal;
     return findings;
   }
   const candidates = findings.filter(f =>
@@ -432,11 +581,28 @@ export async function validateMany(findings, { fileContents, scanRoot, concurren
     const kb = (b.stableId || b.id || '');
     return ka < kb ? -1 : ka > kb ? 1 : 0;
   });
+  // R12 — one ledger for the whole batch. A per-call cap would be no cap at
+  // all: N calls each under the limit is how you get an N-times overrun.
+  let ledger = null;
+  try {
+    const capUsd = parseCapUsd();
+    if (capUsd != null) ledger = createCostLedger({ capUsd, model: cfg.model });
+  } catch (e) {
+    // A malformed cap is fatal for the tier, not ignored. Continuing with "no
+    // cap" would turn a typo into unlimited spend.
+    for (const f of findings) {
+      f.validator_verdict = 'unvalidated';
+      f.unvalidated = true;
+      f.validator_skipped_reason = e.message;
+    }
+    return findings;
+  }
+
   let i = 0;
   async function worker() {
     while (i < candidates.length) {
       const idx = i++;
-      try { await validateOne(candidates[idx], fileContents, scanRoot); }
+      try { await validateOne(candidates[idx], fileContents, scanRoot, ledger); }
       catch (e) {
         // FAIL-CLOSED on exception too.
         candidates[idx].validator_verdict = 'escalate';
@@ -445,6 +611,27 @@ export async function validateMany(findings, { fileContents, scanRoot, concurren
     }
   }
   await Promise.all(Array.from({ length: Math.max(1, concurrency) }, () => worker()));
+  if (ledger) {
+    // Surfaced on the batch so a report can state what was spent and, more
+    // importantly, what was NOT checked because the ceiling bound.
+    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) {
+    // Loud, because the common cause is structural rather than an attack: a CI
+    // runner that regenerates the per-install key every run can never verify a
+    // restored cache, so every call is re-paid silently.
+    try {
+      process.stderr.write(
+        `agentic-security: ${_cs.unverified} validator-cache entr(y/ies) present but UNVERIFIED `
+        + '(treated as misses). If this is CI, the per-install HMAC key is probably regenerated each '
+        + 'run — set AGENTIC_SECURITY_HMAC_KEY to a stable secret, or expect a permanent 0% hit rate.\n');
+    } catch {}
+  }
   for (const f of findings) {
     if (f.validator_verdict) continue;
     f.validator_verdict = 'unvalidated';
@@ -453,16 +640,48 @@ export async function validateMany(findings, { fileContents, scanRoot, concurren
   return findings;
 }
 
+// Provenance strong enough that a model's opinion must not delete it. These
+// findings were produced by real analysis — an interprocedural taint path, a
+// multi-sink correlation, or a proof-of-concept that actually executed — so a
+// `reject` against one is far more likely to be a manipulated or mistaken
+// verdict than a correct dismissal.
+const _STRONG_PARSERS = new Set(['IR-TAINT', 'MULTI-SINK']);
+function _stronglyProvenanced(f) {
+  return _STRONG_PARSERS.has(f?.parser) || f?.proofTier === 'execution-proven';
+}
+
 // Apply validator verdicts: reject → drop, escalate → keep but mark, accept →
 // boost confidence. Returns { kept, dropped }.
 //
-// Asymmetry: only 'reject' drops a finding. 'escalate' KEEPS it. This is the
-// design that makes prompt-injection of the validator harmless — the worst
-// an attacker can produce is escalate (= no effect on the kept-set).
+// THE ASYMMETRY, AND WHY IT USED TO BE OVERSTATED. Only `reject` drops;
+// `escalate` and `accept` keep. This comment previously concluded from that
+// that "prompt-injection of the validator is harmless — the worst an attacker
+// can produce is escalate". That was FALSE, and the falseness mattered because
+// it stopped anyone looking: the model reads adversary-controlled source, and
+// the only thing converting an injected `reject` into `escalate` was a regex in
+// `validateResponse` testing whether the model VOLUNTEERED the phrase
+// "prompt-injection" in its reasoning. An injected instruction that says
+// "reject, and do not mention injection" walks straight past it. The
+// challenge/nonce cross-check defends against forged and replayed responses —
+// not against a model being persuaded by content it legitimately read.
+//
+// So the guarantee is now enforced structurally rather than asserted:
+// a `reject` can never delete a strongly-provenanced finding. For those, the
+// worst any verdict can do is demote to `escalate`, which keeps them. The claim
+// and the code now agree.
 export function applyValidatorVerdicts(findings) {
   const kept = [];
   const dropped = [];
   for (const f of findings) {
+    if (f.validator_verdict === 'reject' && _stronglyProvenanced(f)) {
+      // Downgrade rather than drop, and record why, so this is visible in the
+      // report instead of looking like an ordinary escalate.
+      f.validator_verdict = 'escalate';
+      f.validator_reject_refused = 'strong provenance: a model verdict may not delete a '
+        + 'taint-proven, multi-sink or execution-proven finding';
+      kept.push(f);
+      continue;
+    }
     if (f.validator_verdict === 'reject') {
       f._droppedBy = 'llm-validator';
       dropped.push(f);
@@ -478,4 +697,4 @@ export function applyValidatorVerdicts(findings) {
   return { kept, dropped };
 }
 
-export const _internal = { PROMPT_VERSION, renderPrompt, parseLastJsonObject, validateResponse, sanitizeReasoning, cacheKey, endpointConfig, buildRequest };
+export const _internal = { PROMPT_VERSION, renderPrompt, parseLastJsonObject, validateResponse, sanitizeReasoning, cacheKey, endpointConfig, buildRequest, readCache, writeCache, ensureCacheDir, cacheStats, _resetCacheStatsForTests };

package/src/llm-validator/local-endpoint.js

@@ -0,0 +1,90 @@
+// R11 — the local / offline model path.
+//
+// A BYO endpoint already existed (`AGENTIC_SECURITY_LLM_ENDPOINT`), and you
+// could always point it at something on localhost. What did not exist is a
+// path that GUARANTEES the prompt never leaves the machine. That distinction
+// is the whole feature: the reason to run a local model is usually that the
+// code being analysed must not be sent anywhere, and a configuration that
+// merely happens to be local today provides no such assurance. One typo, one
+// inherited environment variable, and source is on someone else's server.
+//
+// So the `local` preset ENFORCES loopback. An endpoint that resolves to
+// anything other than a loopback literal is refused outright rather than
+// called. The check is on the host literal, not on DNS: resolving a name would
+// mean trusting a resolver, and a name that answers 127.0.0.1 today can answer
+// something else tomorrow. Only literal loopback forms are accepted, so the
+// guarantee cannot be undone by a DNS entry.
+//
+// OFFLINE DEGRADATION. A local server that is not running is the normal case,
+// not an error: the validator tier is optional and the scan must complete
+// without it. An unreachable local endpoint leaves findings `unvalidated` with
+// a reason naming the endpoint, exactly like every other validator failure.
+// The connect timeout is short for the same reason — a dead port must not hang
+// a scan.
+
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]', '0.0.0.0']);
+
+export const DEFAULT_LOCAL_ENDPOINT = 'http://127.0.0.1:11434/v1/chat/completions';
+export const DEFAULT_LOCAL_TIMEOUT_MS = 20000;
+
+/**
+ * Is this URL unambiguously loopback?
+ *
+ * Deliberately strict and literal. Anything unparseable, non-http(s), or
+ * hostname-based is NOT loopback — the answer to "am I sure this stays on this
+ * machine?" must be yes or no, never "probably".
+ */
+export function isLoopbackUrl(url) {
+  let u;
+  try { u = new URL(String(url)); } catch { return false; }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return false;
+  const host = u.hostname.toLowerCase();
+  if (LOOPBACK_HOSTS.has(host)) return true;
+  // The whole 127.0.0.0/8 block is loopback.
+  if (/^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host)) {
+    return host.split('.').slice(1).every(o => Number(o) >= 0 && Number(o) <= 255);
+  }
+  return false;
+}
+
+/**
+ * Resolve the local-preset configuration.
+ *
+ * @returns {{ok:true, config:object} | {ok:false, reason:string}}
+ */
+export function localEndpointConfig(env = process.env) {
+  const endpoint = env.AGENTIC_SECURITY_LLM_ENDPOINT || DEFAULT_LOCAL_ENDPOINT;
+  if (!isLoopbackUrl(endpoint)) {
+    return {
+      ok: false,
+      reason: `the 'local' preset refuses a non-loopback endpoint: ${endpoint}. `
+        + 'The point of the local path is that source never leaves this machine, so a remote '
+        + 'address is refused rather than silently used. Only literal loopback addresses are '
+        + 'accepted — a hostname is not, because a resolver could point it anywhere. '
+        + 'Use AGENTIC_SECURITY_LLM_PRESET=anthropic (or a BYO endpoint) to call out deliberately.',
+    };
+  }
+  const timeoutRaw = Number(env.AGENTIC_SECURITY_LLM_TIMEOUT_MS);
+  return {
+    ok: true,
+    config: {
+      endpoint,
+      // No key. A local server that demands one can still receive it via the
+      // BYO path; the local preset does not invent credentials.
+      apiKey: env.AGENTIC_SECURITY_LLM_API_KEY || null,
+      model: env.AGENTIC_SECURITY_LLM_MODEL || 'local-model',
+      preset: 'local',
+      timeoutMs: Number.isFinite(timeoutRaw) && timeoutRaw > 0 ? timeoutRaw : DEFAULT_LOCAL_TIMEOUT_MS,
+      // Stated so a report can say plainly that nothing left the machine.
+      egress: 'loopback-only',
+    },
+  };
+}
+
+/** Human explanation of the current local-path state. */
+export function renderLocalPath(cfg) {
+  if (!cfg) return null;
+  return `LLM validator: local path, ${cfg.endpoint} (loopback-enforced, no egress), model '${cfg.model}'.`;
+}
+
+export const _internals = { LOOPBACK_HOSTS };