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

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/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`.
 

package/src/sast/api-authz.js

@@ -34,6 +34,23 @@ function mk(r, kind, api, cwe, why) {
   };
 }
 
+// #9 — CWE-306 missing authentication for a state-changing route.
+function mk306(r) {
+  return {
+    id: `api-authz:missing-auth:${r.file}:${r.line}`,
+    severity: 'high',
+    file: r.file,
+    line: r.line || 0,
+    vuln: `Missing authentication for a state-changing route (${r.method} ${r.path})`,
+    cwe: '306',
+    family: 'broken-access-control',
+    parser: 'API-AUTHZ',
+    subfamily: 'missing-auth',
+    description: `${r.method} ${r.path} performs a destructive/state-changing operation with no authentication, while other routes in this app DO enforce it — so auth-detection demonstrably works here. An unauthenticated ${r.method} lets anyone invoke it (delete/modify another user's data).`,
+    remediation: 'Require authentication on this route (the same middleware/guard the app uses elsewhere) and, for object routes, verify the caller owns the target object.',
+  };
+}
+
 /**
  * Cross-route analysis over the aggregated route inventory (aR).
  * Pure: takes routes[], returns Finding[].
@@ -67,5 +84,24 @@ export function scanApiBrokenAuthz(routes) {
       }
     }
   }
+
+  // #9 — CWE-306 app-level pass. If the app authenticates SOME route (so our
+  // auth-detection works for it), a destructive route left unauthenticated is a
+  // missing-auth bug even when its file-local siblings are also public (the
+  // in-file inconsistency rule above cannot see that case). Scoped to DELETE and
+  // id-taking PUT/PATCH — the least-ambiguous "should never be public" shapes —
+  // so intentionally-public POSTs (login / signup / webhooks) don't false-fire.
+  // `push` dedupes by file:line, so a route already flagged BFLA/BOLA above is
+  // not double-reported here.
+  const appHasAuth = routes.some((r) => r && r.hasAuth);
+  if (appHasAuth) {
+    for (const r of routes) {
+      if (!r || r.hasAuth || !r.file || r.path === '(file-based)') continue;
+      const destructive = r.method === 'DELETE'
+        || ((r.method === 'PUT' || r.method === 'PATCH') && ID_PARAM.test(r.path || ''));
+      if (destructive) push(mk306(r));
+    }
+  }
+
   return findings;
 }

package/src/sast/file-upload.js

@@ -0,0 +1,118 @@
+// CWE-434 — Unrestricted file upload (#6). A whole CWE that had NO detector.
+//
+// Bread-and-butter for the vibecoder stacks (Next.js / Express / Supabase /
+// Firebase / FastAPI / Flask): an upload endpoint that writes an attacker-
+// supplied file without restricting its type/extension/size, or that uses the
+// client-supplied filename as the on-disk destination (also CWE-22 path
+// traversal — `../../x` in the filename escapes the upload dir).
+//
+// Precision is the whole game here (uploads are everywhere). Each rule fires
+// only on a clear unrestricted shape and is suppressed by the standard guard:
+//   - Multer configured with NEITHER fileFilter NOR limits → unrestricted.
+//   - A write whose destination is built from the CLIENT filename
+//     (file.originalname / req.files.*.name / UploadFile.filename) with no
+//     sanitizer (basename / uuid / randomUUID / sanitize / whitelist) nearby.
+// A validated upload (fileFilter+limits, or a generated/sanitized name) does
+// NOT match.
+import { blankComments } from './_comment-strip.js';
+
+const JS_EXT = /\.(?:js|jsx|ts|tsx|mjs|cjs)$/i;
+const PY_EXT = /\.py$/i;
+
+const _lineOf = (raw, idx) => raw.substring(0, idx).split('\n').length;
+const _snip = (raw, line) => (raw.split('\n')[line - 1] || '').trim().slice(0, 200);
+// A sanitizer for the destination filename anywhere in the ±6-line window.
+const NAME_SANITIZER = /\b(?:basename|randomUUID|uuidv4|uuid4|uuid\.v4|nanoid|sanitize[-_]?filename|sanitizeFilename|slugify|crypto\.random|secure_filename|werkzeug)\b/i;
+
+function _window(raw, line, half = 6) {
+  const lines = raw.split('\n');
+  const start = Math.max(0, line - 1 - half);
+  const end = Math.min(lines.length, line - 1 + half);
+  return lines.slice(start, end).join('\n');
+}
+
+function mk(file, raw, line, sub, severity, vuln, description, remediation) {
+  return {
+    id: `file-upload:${sub}:${file}:${line}`,
+    severity, file, line,
+    vuln, cwe: 'CWE-434',
+    family: 'unrestricted-file-upload',
+    parser: 'FILE-UPLOAD',
+    subfamily: sub,
+    snippet: _snip(raw, line),
+    description,
+    remediation,
+  };
+}
+
+function scanJs(file, raw, code, out, seen) {
+  const push = (line, mkr) => { const k = `${line}`; if (seen.has(k)) return; seen.add(k); out.push(mkr); };
+
+  // 1) Multer with neither fileFilter nor limits → unrestricted upload config.
+  //    Matches `multer()` and `multer({ ... })` whose options lack both guards.
+  const multerRe = /\bmulter\s*\(\s*(?:\)|\{([\s\S]*?)\}\s*\))/g;
+  let m;
+  while ((m = multerRe.exec(code))) {
+    const opts = m[1] || '';
+    if (/\bfileFilter\b/.test(opts) || /\blimits\b/.test(opts)) continue; // guarded
+    const line = _lineOf(raw, m.index);
+    push(line, mk(file, raw, line, 'multer-unrestricted', 'medium',
+      'Unrestricted file upload — Multer configured with no fileFilter and no limits',
+      'This Multer instance accepts any file of any size. An attacker can upload an executable, oversized, or malicious file (web shell, zip bomb).',
+      'Add a `fileFilter` that allow-lists MIME types / extensions and a `limits: { fileSize }` cap. Store uploads outside the web root and never serve them with their uploaded name.'));
+  }
+
+  // 2) Write whose destination is built from the CLIENT-supplied filename.
+  //    e.g. path.join(dir, file.originalname) / req.files.x.mv('...'+req.files.x.name)
+  //    Also CWE-22: `../../` in the filename escapes the upload dir.
+  const clientName = /\b(?:\w+\.originalname|req\.files(?:\.\w+|\[[^\]]+\])?\.name)\b/;
+  const writeSinks = [
+    /\.mv\s*\(/,                         // express-fileupload
+    /\b(?:fs\.)?(?:writeFile|writeFileSync|createWriteStream)\s*\(/,
+    /\bpath\.join\s*\(/,                 // building the dest path
+  ];
+  const lines = code.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (!clientName.test(lines[i])) continue;
+    if (!writeSinks.some(re => re.test(lines[i]))) continue;
+    const line = i + 1;
+    if (NAME_SANITIZER.test(_window(raw, line))) continue; // sanitized/generated name → safe
+    push(line, mk(file, raw, line, 'client-filename-dest', 'high',
+      'Unrestricted file upload — client-supplied filename used as the write destination',
+      'The uploaded file is written using its client-controlled name. An attacker can choose the extension (upload `shell.php`) or embed path traversal (`../../etc/x`) to escape the upload directory.',
+      'Never trust the uploaded filename. Generate a server-side name (uuid/nanoid) and validate the extension against an allow-list; write with path.basename() into a fixed directory outside the web root.'));
+  }
+}
+
+function scanPy(file, raw, code, out, seen) {
+  const push = (line, mkr) => { const k = `${line}`; if (seen.has(k)) return; seen.add(k); out.push(mkr); };
+  // Flask: request.files['x'].save(os.path.join(dir, file.filename))
+  // FastAPI: open(file.filename, ...) / shutil.copyfileobj(upload.file, open(upload.filename))
+  const clientName = /\b\w+\.filename\b/;
+  const writeSinks = [/\.save\s*\(/, /\bopen\s*\(/, /\bos\.path\.join\s*\(/, /\bcopyfileobj\s*\(/];
+  const lines = code.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    if (!clientName.test(lines[i])) continue;
+    if (!writeSinks.some(re => re.test(lines[i]))) continue;
+    const line = i + 1;
+    if (NAME_SANITIZER.test(_window(raw, line))) continue; // secure_filename / uuid → safe
+    push(line, mk(file, raw, line, 'client-filename-dest', 'high',
+      'Unrestricted file upload — client-supplied filename used as the write destination',
+      'The uploaded file is saved under its client-controlled name. An attacker can choose the extension or embed path traversal to escape the upload directory.',
+      'Use werkzeug secure_filename() (Flask) or generate a uuid name; validate the extension against an allow-list and write into a fixed directory outside the web root.'));
+  }
+}
+
+export function scanFileUpload(fp, raw) {
+  if (!raw || raw.length > 500_000) return [];
+  const isJs = JS_EXT.test(fp), isPy = PY_EXT.test(fp);
+  if (!isJs && !isPy) return [];
+  // Cheap relevance gate — skip files with no upload surface.
+  if (!/\b(?:multer|originalname|req\.files|UploadFile|\.filename|createWriteStream|\.mv\s*\()/i.test(raw)) return [];
+  const code = blankComments(raw, isPy ? 'py' : null);
+  const out = [];
+  const seen = new Set();
+  try { if (isJs) scanJs(fp, raw, code, out, seen); } catch { /* per-file best-effort */ }
+  try { if (isPy) scanPy(fp, raw, code, out, seen); } catch { /* per-file best-effort */ }
+  return out;
+}

package/src/sast/llm-cost-advisor.js

@@ -0,0 +1,88 @@
+// LLM cost + prompt-cache advisor (PRD CACHE_ECONOMICS_V2 — F1 cache-hygiene +
+// P3 per-provider model/depth recommendation), as a SAST detector over the
+// user's own LLM-calling code.
+//
+// Two rules, both gated on detecting an LLM provider in the file (low FP), both
+// emitted at ADVISORY severity so they never inflate security counts:
+//
+//   1. cache-killer: a non-deterministic value (Date.now / uuid / datetime.now)
+//      interpolated into a prompt/system string — defeats prompt caching for the
+//      whole prefix after it (every provider).
+//   2. over-provisioned: a flagship model used at a high reasoning depth — the
+//      catalog suggests a cheaper model + lower depth WITHIN the same provider.
+//
+// Provider/model/cache facts come from posture/provider-catalog.js (P1/P2).
+import { blankComments } from './_comment-strip.js';
+import { detectProvider, PROVIDERS, modelEntry, cheaperModel, depthAxis, cacheModel, SOURCED_AT } from '../posture/provider-catalog.js';
+
+// How this provider's cache behaves — shapes the cache-killer remediation.
+const CACHE_HINT = {
+  explicit: "Claude's prompt cache (set on a stable prefix via cache_control)",
+  automatic: 'the provider\'s automatic prompt cache (matches a ≥1024-token static prefix)',
+  'implicit-explicit': "Gemini's implicit/explicit context cache",
+};
+
+const NONDET = /\b(?:Date\.now|new\s+Date|datetime\.now|datetime\.utcnow|time\.time|uuid4|uuidv4|crypto\.randomUUID|uuid\.uuid4|secrets\.token_hex|os\.urandom)\s*\(/;
+const PROMPT_CTX = /\b(?:system|instructions?|developer|messages|prompt)\b|["']role["']\s*:\s*["'](?:system|developer)["']/i;
+const EXPENSIVE_DEPTH = /(?:reasoning_effort|["']?effort["']?)\s*[:=]\s*["']?(?:high|xhigh|max)["']?|thinking[_]?budget\s*[:=]\s*\(?\s*(?:[1-9]\d{4,})/i;
+
+const lineOf = (raw, idx) => raw.substring(0, idx).split('\n').length;
+const snippetAt = (raw, line) => (raw.split('\n')[line - 1] || '').trim().slice(0, 200);
+
+export function scanLlmCost(fp, raw) {
+  if (!/\.(?:js|jsx|ts|tsx|mjs|cjs|py|rb)$/i.test(fp)) return [];
+  if (!raw || raw.length > 500_000) return [];
+  const provider = detectProvider(raw);
+  if (!provider) return [];
+  const code = blankComments(raw);
+  const lines = code.split('\n');
+  const findings = [];
+  const seen = new Set();
+  const push = (f) => { if (!seen.has(f.id)) { seen.add(f.id); findings.push(f); } };
+  const pLabel = PROVIDERS[provider].label;
+
+  // ── Rule 1: non-deterministic content in a prompt-building string ──────────
+  for (let i = 0; i < lines.length; i++) {
+    if (!NONDET.test(lines[i])) continue;
+    // Require a prompt-context marker on the SAME line — the volatile value is
+    // being built into a system/prompt/messages string. (Same-line keeps FP low:
+    // a `datetime.now()` in a nearby log line must not trip on a `SYSTEM =` const
+    // three lines up.)
+    if (!PROMPT_CTX.test(lines[i])) continue;
+    const line = i + 1;
+    push({
+      id: `llm-cache-nondeterminism:${fp}:${line}`,
+      file: fp, line,
+      vuln: `Prompt-cache killer (cost advisory) — non-deterministic value in a ${pLabel} prompt prefix`,
+      severity: 'low', cwe: 'CWE-400', family: 'llm-cache', parser: 'LLM-COST', confidence: 0.6,
+      snippet: snippetAt(raw, line),
+      remediation: `A timestamp / UUID / random value in the cached prefix changes its bytes every request, so ${CACHE_HINT[cacheModel(provider)?.kind] || 'the prompt cache'} never hits and you pay full input price every call. Move the volatile value AFTER the stable prefix (or out of the prompt entirely) so the long shared prefix stays byte-identical and cacheable.`,
+    });
+  }
+
+  // ── Rule 2: flagship model at high depth → recommend a cheaper option ──────
+  const expensiveModels = PROVIDERS[provider].models.filter(m => m.tier >= 2);
+  const dax = depthAxis(provider);
+  for (let i = 0; i < lines.length; i++) {
+    const m = expensiveModels.find(em => em.match.test(lines[i]));
+    if (!m) continue;
+    // Look for an expensive depth setting in the same call window (±6 lines).
+    const win = lines.slice(Math.max(0, i - 6), i + 7).join('\n');
+    if (!EXPENSIVE_DEPTH.test(win)) continue;
+    const line = i + 1;
+    const cheaper = cheaperModel(provider, m.id);
+    const alt = cheaper
+      ? `${cheaper.id} at ${dax?.knob}=${dax?.cheap}`
+      : `a lower ${dax?.knob || 'reasoning depth'}`;
+    push({
+      id: `llm-overprovisioned:${fp}:${line}`,
+      file: fp, line,
+      vuln: `Over-provisioned model (cost advisory) — ${pLabel} flagship at high depth`,
+      severity: 'info', cwe: 'CWE-400', family: 'llm-cost', parser: 'LLM-COST', confidence: 0.5,
+      snippet: snippetAt(raw, line),
+      remediation: `This call pairs a flagship model (${m.id}) with a high ${dax?.knob || 'reasoning'} setting — the most expensive combination in ${pLabel}. If the task isn't intelligence-critical, try ${alt} first and measure: it can cut cost several-fold with little quality loss. Keep the flagship+high only where correctness clearly needs it. (Catalog pricing as of ${SOURCED_AT}.)`,
+    });
+  }
+
+  return findings;
+}