@clear-capabilities/agentic-security-scanner 0.137.1 → 0.139.0

package/src/posture/accuracy-scorecard.js

@@ -65,6 +65,24 @@ function sliceBy(scored, key) {
   return [...map.values()].sort((a, b) => a.key.localeCompare(b.key));
 }
 
+/**
+ * Build the { byLanguage: [{language, taint:{n,d}}] } shape for one
+ * taintByLanguage/totalByLanguage pair. Sorted by language so the rendered
+ * document is stable run-to-run, matching every other byX array here.
+ *
+ * A language present in `total` but absent from `taint` reports n:0 — a real
+ * measured zero. A language absent from BOTH is simply not included in the
+ * output at all, so "measured zero" and "not measured on this subset" never
+ * collapse into the same row (see the deepTierOnly caller below).
+ */
+function taintRateByLanguage(taintByLanguage, totalByLanguage) {
+  const langs = Object.keys(totalByLanguage || {}).sort();
+  return langs.map(language => ({
+    language,
+    taint: { n: (taintByLanguage || {})[language] || 0, d: totalByLanguage[language] },
+  }));
+}
+
 /**
  * Aggregate the per-entry detail records emitted by the corpus runner.
  *
@@ -141,6 +159,24 @@ export function buildScorecard(inputs) {
       byTier: corpus.byTier,
     },
     selfScan: { measuredThisRun: true, targets, polyglot: selfScan.polyglot || { total: 0, byLanguage: {} } },
+    taintRecall: (() => {
+      const lr = inputs.layerRecall;
+      if (!lr) {
+        return { measuredThisRun: false, wholeCorpus: { entriesScored: 0, byLanguage: [] }, deepTierOnly: { entriesScored: 0, byLanguage: [] } };
+      }
+      const deep = lr.deepTier || { entriesScored: 0, taintByLanguage: {}, totalByLanguage: {} };
+      return {
+        measuredThisRun: true,
+        wholeCorpus: {
+          entriesScored: lr.entriesScored || 0,
+          byLanguage: taintRateByLanguage(lr.taintByLanguage, lr.totalByLanguage),
+        },
+        deepTierOnly: {
+          entriesScored: deep.entriesScored || 0,
+          byLanguage: taintRateByLanguage(deep.taintByLanguage, deep.totalByLanguage),
+        },
+      };
+    })(),
     committedInputs: {
       corpusBaseline: committed.corpusBaseline
         ? { source: 'bench/cve-replay/corpus-baseline.json', generatedAt: committed.corpusBaseline.generatedAt, total: committed.corpusBaseline.total, passing: committed.corpusBaseline.passing }
@@ -279,6 +315,73 @@ export function renderScorecardMarkdown(m) {
   L.push('| --- | --- | --- | --- |');
   for (const r of c.byTier) L.push(rateRow(r));
   L.push('');
+  L.push('## Taint-layer recall by language');
+  L.push('');
+  L.push('Two views of the same layer-recall instrument, because reporting only the');
+  L.push('first would silently overstate taint capability and reporting only the');
+  L.push('second would understate coverage of what the corpus actually contains:');
+  L.push('');
+  L.push('- **Whole corpus** — diagnostic only. The large majority of this corpus is');
+  L.push('  caught by the pattern/structural layers without needing taint at all, so a language\'s');
+  L.push('  rate here is diluted by every entry that never exercised the taint');
+  L.push('  engine. A language reading near-zero here is not necessarily a taint');
+  L.push('  defect — see `docs/METRICS.md`.');
+  L.push('- **Deep-tier only (the taint-shaped subset)** — the number to quote for');
+  L.push('  taint capability. Every entry in this bucket is required, before it can');
+  L.push('  be committed, to be provably invisible with the deep engine off and');
+  L.push('  detected with it on (`bench/cve-replay/CONTRIBUTING.md`, "deep/" tier).');
+  L.push('  A language absent from this table has no deep-tier entry yet — that is');
+  L.push('  "not yet measured", never "zero capability".');
+  L.push('');
+  L.push('**No taint-specific precision percentage is reported here, deliberately —');
+  L.push('same reasoning as the corpus-wide F1 omission above.** A precision figure');
+  L.push('needs a labelled population containing both true and false positives; this');
+  L.push('section\'s denominator is all-vulnerable by construction (`pre/` fixtures),');
+  L.push('so it cannot supply one. The false-positive side is instrumented instead as');
+  L.push('a gate, not a rate: `bench/self-scan/fixtures/polyglot/` carries one');
+  L.push('untainted, negative-control fixture per language, covering eight of the');
+  L.push('nine first-class languages (C/C++ has no fixture in this set yet), and');
+  L.push('`bench:self-scan:check`\'s existing exact per-file drift gate fails the');
+  L.push('build the moment any of them stops reading zero. See the self-scan section');
+  L.push('below for current counts.');
+  L.push('');
+  L.push('### Whole corpus (diagnostic)');
+  L.push('');
+  L.push(`Entries scored: ${m.taintRecall.wholeCorpus.entriesScored}`);
+  L.push('');
+  L.push('| Language | IR-TAINT recall |');
+  L.push('| --- | --- |');
+  for (const r of m.taintRecall.wholeCorpus.byLanguage) {
+    L.push(`| ${r.language} | ${formatRate(r.taint.n, r.taint.d)} |`);
+  }
+  L.push('');
+  L.push('### Deep-tier only — taint-shaped subset (headline)');
+  L.push('');
+  L.push(`Entries scored: ${m.taintRecall.deepTierOnly.entriesScored}`);
+  L.push('');
+  if (m.taintRecall.deepTierOnly.byLanguage.length) {
+    L.push('| Language | IR-TAINT recall |');
+    L.push('| --- | --- |');
+    for (const r of m.taintRecall.deepTierOnly.byLanguage) {
+      L.push(`| ${r.language} | ${formatRate(r.taint.n, r.taint.d)} |`);
+    }
+  } else {
+    L.push('No deep-tier entries scored this run.');
+  }
+  L.push('');
+  // INTEGRITY CONTRACT above requires unmeasured things "disclosed by name",
+  // not just described generically — so name the languages that are present
+  // in the whole-corpus view but have no deep-tier entry at all, rather than
+  // leaving that as an unnamed implication of the two tables above.
+  const deepLangs = new Set(m.taintRecall.deepTierOnly.byLanguage.map(r => r.language));
+  const notYetMeasured = m.taintRecall.wholeCorpus.byLanguage
+    .map(r => r.language)
+    .filter(l => !deepLangs.has(l))
+    .sort();
+  if (notYetMeasured.length) {
+    L.push(`Not yet measured on this subset: ${notYetMeasured.join(', ')}`);
+    L.push('');
+  }
   L.push('## Precision-side signal: self-scan (measured this run)');
   L.push('');
   L.push('The engine scanned its own repository. These are absolute finding');

package/src/runScan.js

@@ -4,7 +4,7 @@ import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import * as cp from 'node:child_process';
 import { listFiles } from './util/glob.js';
-import { runFullScan, shouldScan } from './engine.js';
+import { runFullScan, shouldScan, isKubernetesManifest } from './engine.js';
 import { appendScanSnapshot } from './posture/security-trend.js';
 import { recover as recoverFixHistory } from './posture/fix-history.js';
 import { stampScan } from './posture/ruleset-version.js';
@@ -45,7 +45,10 @@ export async function readTree(root, { ignore = [] } = {}) {
     else if (/\.proto$/i.test(base)) depFileContents[rel] = content;
     else if (/\.(?:graphql|gql)$/i.test(base)) depFileContents[rel] = content;
     else if (/\.tf$/i.test(base)) depFileContents[rel] = content;
-    if (shouldScan(rel)) fileContents[rel] = content;
+    // A Kubernetes manifest is admitted on CONTENT, not on living under a
+    // directory named k8s/ — see isKubernetesManifest. Without this the
+    // k8s-admission detector is wired into the dispatch and never invoked by it.
+    if (shouldScan(rel) || isKubernetesManifest(rel, content)) fileContents[rel] = content;
     // Auxiliary files: .properties files are referenced by Java rules
     // (e.g. OWASP Benchmark's benchmark.properties resolves algorithm
     // aliases). They are not scannable for vulns themselves, but the

package/src/sast/CLAUDE.md

@@ -43,7 +43,7 @@ Both key on the SECRET-NESS of the identifier, never on the comparison or the ty
 
 ## Gotchas
 
-- **Comments confuse detectors.** Always go through `blankComments()` from `_comment-strip.js` before scanning a file body.
+- **Comments confuse detectors — now handled centrally, but read this before relying on it.** `runFullScan` (`../engine.js`) computes ONE comment-blanked, line-and-offset-preserving view per file (`cc`, via `blankComments` + `_commentLangFor`) and passes it to the SAST dispatch, so a new module gets comment-blindness by default and does **not** need its own `blankComments()` call. Calling it anyway is harmless (idempotent) and still correct for modules invoked outside that dispatch. Two things to know: (1) **~20 detectors deliberately receive RAW source** — the LLM/agent/prompt-injection family (instructions hidden in a comment are the attack, not a false positive), the two secrets scanners (a committed credential is leaked whether or not its line executes), and `scanTodosNearSecurity` (comments are its subject). If your rule belongs in that group, say so explicitly at the call site. (2) **Language-awareness is not optional**: `#` is a comment in Python/Ruby/shell but `#include`/`#region` in the C family, and `//` is a comment in C-family languages but **floor division in Python** — blanking it there deletes real code. `_commentLangFor()` owns that mapping; extend it rather than hand-rolling a regex. The property is pinned end-to-end by `test/comment-blindness.test.js` (including a positive control and a Python-floor-division guard), so a regression shows up as a test failure rather than as quietly inflated findings.
 - **Detector snippet attribution.** Don't grab `lines[matchLine - 1]` blindly — for multi-line patterns (`exec('ping' + req.body.host, …)`), the match index and the readable sink line can diverge. Premortem item — fixed in the dataflow engine; if you're regressing on it, your fix probably needs to use the actual sink expression, not the regex's match offset.
 - **Severity floor.** No detector should emit `severity: 'critical'` without strong evidence; the calibrator amplifies critical-rated findings and a flood drowns real ones. If in doubt, emit `high` and let `annotateExploitability` push it up.
 - **Family field for calibration.** If you can't tell what family your rule belongs to, that's a signal the rule covers too much. Split it.

package/src/sast/_auth-signals.js

@@ -0,0 +1,141 @@
+// Shared cross-framework "is this handler actually protected?" resolver.
+//
+// WHY THIS EXISTS (PRD Theme 1, T1.2). Every authz-adjacent detector used to
+// hand-roll its own list of blessed middleware/dependency names, and each list
+// was a closed enumeration. Real codebases name their auth helpers whatever
+// they like, so the enumerations missed, and the detectors emitted findings
+// asserting an ABSENCE that the same file visibly contradicts.
+//
+// The measured cost of that, from the 2026-08-17 independent-population audit:
+// GHSA-3cg5-48j3-v4gv scored as a TRUE POSITIVE for "FastAPI mutating endpoint
+// create_folder() has no Security() / Depends() auth dependency" against a
+// function whose signature reads `user=Depends(get_verified_user)` and whose
+// first statement is `await check_folders_permission(request, user, db=db)`.
+// The claim was false about the code; it scored only because the CWE and file
+// happened to line up with an unrelated fix 200 lines away. Two more entries in
+// the same population failed the same way.
+//
+// The rule this module encodes: an absence-claim must be checked against BOTH
+// the handler's injected dependencies AND its body. A detector that looks only
+// at a signature cannot see `check_folders_permission(...)`, and one that looks
+// only for known names cannot see a project's own convention.
+//
+// Deliberately biased toward RECOGNISING auth. A false "this is protected"
+// costs one missed finding; a false "this is unprotected" is a wrong statement
+// about code the reader can see, which is what destroys trust in every other
+// finding the tool emits.
+
+/**
+ * Security NOUNS — the concepts that make an identifier about authentication
+ * or authorization. Matched against a CALLEE or PARAMETER name, never against
+ * free text, so a comment or string literal cannot satisfy it.
+ *
+ * Deliberately nouns, not action verbs. An earlier draft included bare
+ * `session`, `access`, `verify` and `require`, and its own test immediately
+ * caught the consequence: `Depends(get_async_session)` — a DATABASE session —
+ * read as authentication evidence and would have silently suppressed real
+ * missing-auth findings. Over-suppression is the dangerous direction for this
+ * module (it hides vulnerabilities), so ambiguous stems are excluded and only
+ * their unambiguous compounds are listed. Verbs are handled separately in
+ * hasAuthInBody, where they must co-occur with one of these nouns.
+ */
+const AUTH_NAME_RE = new RegExp([
+  'auth', 'authn', 'authz', 'authoriz', 'authoris',
+  'login', 'logged_?in', 'jwt', 'oauth', 'oidc', 'saml',
+  'principal', 'identity', 'credential', 'password',
+  'user',                          // covers current_/verified_/active_/request_user
+  'permission', 'privilege', 'role', 'scope',
+  'admin', 'superuser', 'staff',
+  'api_?key', 'apikey', 'bearer', 'access_?token', 'access_?control',
+  '(?:user|auth|login|web|http)_?session', 'session_?(?:user|token|id)',
+].join('|'), 'i');
+
+/**
+ * A dependency-injection wrapper: FastAPI Depends()/Security(), NestJS, etc.
+ * Group 1 is the wrapper, group 2 the injected callee (absent for `Security()`).
+ */
+const DI_CALL_RE = /\b(Depends|Security)\s{0,8}\(\s{0,8}([A-Za-z_$][\w$.]{0,128})?/g;
+
+/**
+ * Does a handler's PARAMETER LIST carry injected auth?
+ *
+ * Recognises the DI shape first (`Depends(x)` / `Security(x)` with an
+ * auth-shaped callee), then falls back to an auth-shaped parameter NAME —
+ * `user`, `current_user`, `principal` — which is how most frameworks surface
+ * an already-resolved identity.
+ */
+export function hasAuthInParams(paramsText) {
+  const params = String(paramsText || '');
+  if (!params.trim()) return null;
+
+  DI_CALL_RE.lastIndex = 0;
+  let m;
+  while ((m = DI_CALL_RE.exec(params))) {
+    const wrapper = m[1];
+    const callee = m[2] || '';
+    // `Security(...)` is an auth construct by definition, whatever it wraps —
+    // FastAPI has no non-security use for it. `Depends(...)` is generic
+    // dependency injection (DB sessions, config, pagination), so it only
+    // counts when the injected callee itself names a security concept.
+    if (wrapper === 'Security' || AUTH_NAME_RE.test(callee)) {
+      return { authenticated: true, reason: `dependency-injected auth: ${wrapper}(${callee || '…'})` };
+    }
+  }
+
+  // Parameter name shapes: `user: User`, `user=Depends(...)`, `current_user`.
+  for (const p of params.split(',')) {
+    const name = (p.split(/[:=]/)[0] || '').trim().replace(/^\*+/, '');
+    if (!name) continue;
+    if (/^(?:user|current_user|principal|identity|viewer|actor|me)$/i.test(name)) {
+      return { authenticated: true, reason: `auth-shaped handler parameter: ${name}` };
+    }
+  }
+  return null;
+}
+
+/**
+ * Does a handler BODY perform an explicit authorization check?
+ *
+ * This is the half the FastAPI detector was missing entirely. A project's own
+ * `check_folders_permission(...)` is not in anyone's enumeration of blessed
+ * names, but it is unmistakably an authorization call at the call site.
+ */
+export function hasAuthInBody(bodyText) {
+  const body = String(bodyText || '');
+  if (!body.trim()) return null;
+  // Call shape: <name>(...) where the callee name is auth-shaped AND reads as
+  // an action (check/require/verify/ensure/assert/validate/has/can/enforce).
+  // Bounded repetition throughout: this walks third-party source, so a
+  // pathological identifier chain must not become a scanner-side ReDoS.
+  // Only the FINAL segment is used, so the dotted qualifier is not matched at
+  // all — which also keeps this free of the nested quantifier the project's own
+  // redos-nfa.js correctly flags on `(?:\w+\.)*` shapes.
+  const callRe = /\b([A-Za-z_$][\w$]{0,63})\s{0,8}\(/g;
+  let m;
+  while ((m = callRe.exec(body))) {
+    const callee = m[1];
+    const actiony = /^(?:check|require|ensure|verify|assert|validate|enforce|has|can|is|get|authorize|authorise|guard)/i.test(callee);
+    if (actiony && AUTH_NAME_RE.test(callee)) {
+      return { authenticated: true, reason: `explicit authorization call in body: ${callee}()` };
+    }
+  }
+  // Raise-on-forbidden shape: an explicit 401/403 the handler itself emits.
+  if (/\b(?:HTTP_401_UNAUTHORIZED|HTTP_403_FORBIDDEN|UnauthorizedError|ForbiddenError|status_code\s*=\s*40[13]|\b40[13]\b\s*,)/.test(body)) {
+    return { authenticated: true, reason: 'handler raises an explicit 401/403' };
+  }
+  return null;
+}
+
+/**
+ * The single question every authz detector should ask before asserting that a
+ * handler is unprotected. Returns null when there is no evidence (i.e. the
+ * detector may fire), or {authenticated:true, reason} when it must not.
+ *
+ * `reason` exists so the finding — or its absence — is explainable, per the
+ * PRD's T2.2 requirement that an absence-claim record what it looked for.
+ */
+export function routeAuthEvidence({ params = '', body = '' } = {}) {
+  return hasAuthInParams(params) || hasAuthInBody(body) || null;
+}
+
+export const _internals = { AUTH_NAME_RE, hasAuthInParams, hasAuthInBody };

package/src/sast/_comment-strip.js

@@ -15,43 +15,110 @@
 //
 // Skips comment-like content inside string literals (single/double/backtick).
 //
+//   - Ruby: `#` line comments PLUS `=begin` / `=end` block comments, which
+//     must start at column 0. No other supported language has this form, so a
+//     `#`-only pass leaves the whole block intact and every dangerous
+//     construct inside it reads as live code.
+//
 // The `lang` parameter is optional; pass 'py' to treat `#` as a line comment
-// (and skip `//`/`/* */`), or 'php' to strip all three comment forms.
+// (and skip `//`/`/* */`), 'rb' for Python's `#` handling plus Ruby's
+// `=begin`/`=end` blocks, or 'php' to strip all three comment forms.
 
+// PERFORMANCE. This runs on every scanned file, and `engine.js` calls it
+// through `stripNoise` roughly fifteen times per file, so it sits directly on
+// the hot path. The original implementation appended ONE CHARACTER AT A TIME
+// (`out += c`) for the whole file, which measured a 19.7% end-to-end scan
+// regression on a 307-file entry once it replaced the old native-regex
+// stripper.
+//
+// This version keeps the identical state machine — it must still inspect every
+// character to know whether a `//` sits inside a string literal — but emits
+// output in BULK: untouched code is pushed as a single `slice()` of the input,
+// and only the comment runs (a small minority of any real file) are rewritten,
+// via a native regex for the newline-preserving cases. Characters are scanned;
+// they are no longer individually concatenated.
 export function blankComments(s, lang) {
-  let out = '';
+  const parts = [];
+  let verbatimFrom = 0;   // start of the run of input not yet emitted as-is
   let inS = null;
   let i = 0;
-  const isPy = lang === 'py';
+  const isRb = lang === 'rb';
+  const isPy = lang === 'py' || isRb;
   const isPhp = lang === 'php';
   const stripSlashForms = !isPy || isPhp;
   const stripHash = isPy || isPhp;
+  // Flush the pending verbatim run, then blank [start, end) with newlines kept
+  // so every byte offset and line number in the output still matches the input.
+  const blank = (start, end) => {
+    if (start > verbatimFrom) parts.push(s.slice(verbatimFrom, start));
+    parts.push(s.slice(start, end).replace(/[^\n]/g, ' '));
+    verbatimFrom = end;
+  };
   while (i < s.length) {
     const c = s[i];
     if (inS) {
-      out += c;
-      if (c === '\\' && i + 1 < s.length) { out += s[i+1]; i += 2; continue; }
+      // A `'` or `"` string cannot span a line in any language handled here, so
+      // a newline ends it. Without this reset an ODD number of quotes on one
+      // line — which regex literals produce routinely, e.g.
+      // `/"(?:sh|bash)"\s*,\s*(?!"[^"]*")/` — leaves the scanner stuck in
+      // string mode for the WHOLE REST OF THE FILE, silently disabling comment
+      // stripping from that point on. Measured on this repo's own
+      // `sast/go-extended.js`, where it resurrected a false positive out of a
+      // comment six lines below the regex.
+      //
+      // Backticks are exempt: JS template literals and Go raw strings are
+      // genuinely multi-line. Erring toward "this is code" is the safe
+      // direction — the failure it causes is a stripped comment, whereas the
+      // opposite error hides every subsequent comment in the file.
+      if (c === '\n' && inS !== '`') { inS = null; i++; continue; }
+      if (c === '\\' && i + 1 < s.length) { i += 2; continue; }
       if (c === inS) inS = null;
       i++; continue;
     }
-    if (c === "'" || c === '"' || c === '`') { inS = c; out += c; i++; continue; }
+    // Ruby `=begin` … `=end`: only recognised at the start of a line, which is
+    // what makes it distinguishable from an ordinary `=` assignment.
+    if (isRb && c === '=' && (i === 0 || s[i - 1] === '\n') && s.startsWith('=begin', i)) {
+      let end = i;
+      for (;;) {
+        const nl = s.indexOf('\n', end);
+        if (nl < 0) { end = s.length; break; }
+        if (s.startsWith('=end', nl + 1)) {
+          const after = s.indexOf('\n', nl + 1);
+          end = after < 0 ? s.length : after;
+          break;
+        }
+        end = nl + 1;
+      }
+      blank(i, end);
+      i = end;
+      continue;
+    }
+    if (c === "'" || c === '"' || c === '`') { inS = c; i++; continue; }
     if (stripSlashForms && c === '/' && s[i+1] === '/') {
-      while (i < s.length && s[i] !== '\n') { out += ' '; i++; }
+      const nl = s.indexOf('\n', i);
+      const end = nl < 0 ? s.length : nl;
+      blank(i, end);
+      i = end;
       continue;
     }
     if (stripSlashForms && c === '/' && s[i+1] === '*') {
-      const end = s.indexOf('*/', i + 2);
-      const stop = end < 0 ? s.length : end + 2;
-      while (i < stop) { out += (s[i] === '\n' ? '\n' : ' '); i++; }
+      const close = s.indexOf('*/', i + 2);
+      const end = close < 0 ? s.length : close + 2;
+      blank(i, end);
+      i = end;
       continue;
     }
     // PHP 8 attributes (`#[Route(...)]`) use the same `#` prefix as a line
     // comment — `#[` is never a comment, so don't blank it.
     if (stripHash && c === '#' && s[i+1] !== '[') {
-      while (i < s.length && s[i] !== '\n') { out += ' '; i++; }
+      const nl = s.indexOf('\n', i);
+      const end = nl < 0 ? s.length : nl;
+      blank(i, end);
+      i = end;
       continue;
     }
-    out += c; i++;
+    i++;
   }
-  return out;
+  if (verbatimFrom < s.length) parts.push(s.slice(verbatimFrom));
+  return parts.join('');
 }

package/src/sast/codegen-sink.js

@@ -0,0 +1,110 @@
+// PRD T4.3 — code generation as an injection sink. 5 of the 96 root-caused
+// real-world misses.
+//
+// A NEW SINK CATEGORY, not a new sink entry. Every injection rule in this
+// codebase asks "does untrusted data reach a dangerous CALL" — eval, exec,
+// a query, a shell. Here there is no dangerous call at all: the program
+// WRITES A FILE, and the file happens to be source code that something else
+// imports and runs later. The execution is in a different process, often on a
+// different machine, minutes or months afterwards.
+//
+// The real entries, all in code generators:
+//   - a JSON-Schema `x-python-type` / `default_factory` / `customTypePath`
+//     spliced verbatim into a generated .py type annotation or import
+//     (GHSA-m34r-v34r-rf9q, GHSA-5578-w22f-pfx9, GHSA-386q-5hp3-95m9)
+//   - field/mode strings interpolated into generated validator source
+//     (GHSA-8m8r-38jm-f355)
+//   - an `--extra-template-data` comment field unescaped for \r, so a
+//     generated source COMMENT can hide executable statements from a reviewer
+//     (GHSA-wjv6-jcfj-mf9r)
+//
+// Precision: a template engine writing HTML is not this. The rule requires
+// BOTH that the written artifact is source code (a code-ish extension, or a
+// clearly code-shaped template) AND that an interpolated value comes from a
+// parsed document / config surface rather than a literal — and it stays silent
+// when the value passes through an identifier validator, which is what every
+// one of these advisories added as its fix.
+import { blankComments } from './_comment-strip.js';
+
+const SRC_RE = /\.(?:py|js|jsx|ts|tsx|mjs|cjs)$/i;
+
+/** Writing a file whose name looks like source code. */
+const CODE_WRITE_RE = new RegExp([
+  // open("out.py", "w") / Path(...).write_text(...) / fs.writeFile("x.ts", ...)
+  'open\\s{0,4}\\([^)]{0,200}\\.(?:py|js|ts|rb|go|java|php|sh)["\\\']',
+  'write_text\\s{0,4}\\(', 'writeFileSync?\\s{0,4}\\([^)]{0,200}\\.(?:py|js|ts|mjs|cjs)["\\\']',
+  '\\.write\\s{0,4}\\(',
+].join('|'), 'i');
+
+/** The generated artifact is program text: an import, def, class, or assignment. */
+const CODE_SHAPED_RE = /(?:^|["'`\s])(?:import\s|from\s+\w|def\s|class\s|return\s|lambda\s|=\s*lambda|@\w)/;
+
+/** Interpolation of a non-literal into that text. */
+const INTERPOLATION_RE = /(?:f["'][^"']{0,200}\{|\$\{|%\s{0,2}\(|\.format\s{0,4}\(|\+\s{0,4}\w|Template\s{0,4}\(|render\w{0,10}\s{0,4}\()/;
+
+/** Values that come from a parsed document / caller config, not from source. */
+const EXTERNAL_FIELD_RE =
+  /\b(?:extras?|schema|spec|definition|properties|metadata|template_?data|extra_?template|custom\w{0,20}|x-[\w-]{1,30}|config|options|field_?name|user_\w{1,20})\b/i;
+
+/** The mitigation every one of these advisories shipped. */
+const IDENTIFIER_VALIDATION_RE = new RegExp([
+  'isidentifier\\s{0,4}\\(', 'str\\.isidentifier',
+  'VALID\\w{0,20}_RE', '_RE\\.(?:match|fullmatch)\\s{0,4}\\(',
+  're\\.(?:match|fullmatch)\\s{0,4}\\(', 'allow_?list', 'ALLOWED_\\w{1,30}',
+  'sanitiz\\w{0,6}\\s{0,4}\\(', 'escape\\w{0,10}\\s{0,4}\\(',
+  'validate_\\w{1,30}\\s{0,4}\\(', 'is_?safe\\w{0,20}\\s{0,4}\\(',
+].join('|'), 'i');
+
+const _lineOf = (raw, i) => raw.slice(0, i).split('\n').length;
+const _win = (raw, line, half = 14) => {
+  const l = raw.split('\n');
+  return l.slice(Math.max(0, line - 1 - half), Math.min(l.length, line - 1 + half)).join('\n');
+};
+
+export function scanCodegenSink(file, raw) {
+  if (!raw || typeof raw !== 'string' || raw.length > 500_000) return [];
+  if (!SRC_RE.test(file)) return [];
+  // Cheap relevance gate: only files that both emit and interpolate.
+  if (!CODE_WRITE_RE.test(raw) || !EXTERNAL_FIELD_RE.test(raw)) return [];
+  const code = blankComments(raw, /\.py$/i.test(file) ? 'py' : null);
+
+  const out = [];
+  const seen = new Set();
+  const lines = code.split('\n');
+  for (let i = 0; i < lines.length; i++) {
+    const text = lines[i];
+    // The line must be assembling program text with an interpolation in it.
+    if (!CODE_SHAPED_RE.test(text) || !INTERPOLATION_RE.test(text)) continue;
+    const line = i + 1;
+    const win = _win(raw, line);
+    if (!CODE_WRITE_RE.test(win)) continue;            // not actually emitted as a file
+    if (!EXTERNAL_FIELD_RE.test(win)) continue;        // value isn't caller-supplied
+    if (IDENTIFIER_VALIDATION_RE.test(win)) continue;  // validated — the fix
+    if (seen.has(line)) continue;
+    seen.add(line);
+    out.push({
+      id: `codegen-sink:generated-source:${file}:${line}`,
+      file, line,
+      vuln: 'Untrusted value interpolated into generated source code',
+      severity: 'high',
+      cwe: 'CWE-94',
+      family: 'code-injection',
+      subfamily: 'generated-source',
+      parser: 'CODEGEN',
+      confidence: 0.5,
+      description:
+        'A value taken from a parsed schema/config surface is interpolated into text that this program writes out '
+        + 'as source code, with no identifier or allow-list validation in between. The generated file is later '
+        + 'imported and executed, so the injection executes in a different process than the one that emitted it — '
+        + 'which is why no eval/exec appears anywhere near this line and why ordinary injection rules do not see it.',
+      remediation:
+        'Validate every interpolated value against the grammar of what it becomes — `str.isidentifier()` for a '
+        + 'name, an explicit allow-list for a type or import path — and reject embedded newlines and carriage '
+        + 'returns, which can smuggle statements past a generated comment.',
+      checkedFor: 'an identifier/allow-list/escape validation applied to the interpolated value within 14 lines',
+    });
+  }
+  return out;
+}
+
+export const _internals = { CODE_WRITE_RE, CODE_SHAPED_RE, INTERPOLATION_RE, EXTERNAL_FIELD_RE, IDENTIFIER_VALIDATION_RE };