@clear-capabilities/agentic-security-scanner 0.185.0 → 0.186.2

package/src/posture/proof-fabric/generate-haskell.js

@@ -0,0 +1,205 @@
+// Reproducer generation for Haskell (PRD 1), the third language of `generate.js`. Same contract as JavaScript and Python: a
+// DETERMINISTIC proposal built from the flagged file alone, then run through the ordinary runner, oracle, 3-of-3 repetition and
+// independent replay. A generated reproducer is a proposal that execution either confirms or does not.
+//
+// The program is run by GHC's interpreter (`ghc -e`), not compiled. Why: it needs no C compiler and no linker (so no dependence on
+// the platform's developer tools), it leaves no object files or binaries to account for, it starts in about half a second where a
+// compile-then-run takes a second or more, and there is one process tree to confine instead of a build stage followed by a run
+// stage. Interpreted bytecode calls the same installed libraries a compiled program would, so a shell string reaches the same
+// `System.Process` either way. The tradeoff is stated, not hidden: a program whose behaviour depends on compiled code (FFI, an
+// optimisation-sensitive race) is refused, and `-O` is never in play. A hand-written reproducer may still use `build`/`run` with
+// `{{GHC}}` to compile; both paths run under the same sandbox, timeout and output cap.
+//
+// Two shapes, as in the other languages:
+//   script    the file reads `getArgs`: it is run as `:main "<payload>"`, so the payload arrives as the first argument;
+//   function  a top-level function around the flagged line that has a type signature of `String`/`FilePath` parameters and an `IO`
+//             result: `ghc -e 'fn "<payload>" ...'` loads the module with every top-level name in scope (the module need not export
+//             it) and calls it with the payload in every parameter.
+//
+// Only what the proof environment can load is accepted: the file's imports must be modules of the packages that ship with GHC (the
+// global package database, read from the installed GHC) or other `.hs` files in the repository. A web framework, a database binding
+// or any Hackage package is refused with the package named where it is known. Template Haskell, quasi-quotes, CPP, the foreign
+// function interface and compiler-plugin options are refused too: they run code at load time, before the payload is involved.
+//
+// Classes: command injection (CWE-78) and path traversal by a write (CWE-22). SSRF (CWE-918) is refused for Haskell on purpose: no
+// HTTP client ships with GHC, so a request-making program necessarily imports a package the stdlib-only rule already refuses, and
+// nothing could be proven honestly. Nothing is executed on a refusal.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { parseHaskell } from '../../language/haskell-parser.js';
+import { validateReproducer } from './reproducer.js';
+import { hostTools } from './runner.js';
+
+const MAX_SOURCE = 256 * 1024;
+const MAX_FILES = 8;
+const fail = (reason, extra = {}) => ({ ok: false, reason, ...extra });
+
+// Well-known packages that are NOT part of a GHC install, by module prefix, so a refusal can name the package to install.
+const THIRD_PARTY = [
+  ['Web.Scotty', 'scotty'], ['Network.Wai', 'wai'], ['Network.HTTP.Types', 'http-types'], ['Network.HTTP.Client', 'http-client'],
+  ['Network.HTTP.Simple', 'http-conduit'], ['Network.HTTP.Conduit', 'http-conduit'], ['Network.Wreq', 'wreq'], ['Network.Socket', 'network'],
+  ['Servant', 'servant'], ['Yesod', 'yesod'], ['Snap', 'snap'], ['Happstack', 'happstack-server'], ['Data.Aeson', 'aeson'],
+  ['Database.SQLite.Simple', 'sqlite-simple'], ['Database.PostgreSQL.Simple', 'postgresql-simple'], ['Database.Persist', 'persistent'],
+  ['Database.MySQL', 'mysql-simple'], ['System.Random', 'random'], ['Data.Vector', 'vector'], ['Data.Hashable', 'hashable'],
+  ['Data.HashMap', 'unordered-containers'], ['Control.Lens', 'lens'], ['Test.', 'a test framework'], ['Turtle', 'turtle'],
+  ['Shelly', 'shelly'], ['System.Process.Typed', 'typed-process'], ['Conduit', 'conduit'], ['Control.Monad.Logger', 'monad-logger'],
+  ['Options.Applicative', 'optparse-applicative'], ['Data.Text.Lazy.Builder', null],
+];
+
+const libCache = new Map();
+/** The modules the installed GHC exposes from its global package database (what a program can import with no extra packages). */
+export function bootModuleSet(ghc) {
+  if (libCache.has(ghc)) return libCache.get(ghc);
+  let set = null;
+  try {
+    const r = spawnSync(ghc, ['--print-libdir'], { encoding: 'utf8', timeout: 10_000 });
+    const dir = r.status === 0 ? path.join(r.stdout.trim(), 'package.conf.d') : null;
+    if (dir && fs.existsSync(dir)) {
+      set = new Set();
+      for (const f of fs.readdirSync(dir)) {
+        if (!f.endsWith('.conf')) continue;
+        const text = fs.readFileSync(path.join(dir, f), 'utf8');
+        if (/^exposed:\s*False/m.test(text)) continue;
+        const m = /^exposed-modules:\s*\n?([\s\S]*?)(?=^\S)/m.exec(text);
+        if (!m) continue;
+        for (const tok of m[1].split(/[\s,]+/)) if (/^[A-Z][\w']*(?:\.[A-Z][\w']*)*$/.test(tok)) set.add(tok);
+      }
+      if (!set.has('Prelude')) set = null; // a database that does not even list Prelude was not read correctly
+    }
+  } catch { set = null; }
+  libCache.set(ghc, set);
+  return set;
+}
+
+function readInside(root, rel) {
+  let real; try { real = fs.realpathSync(path.resolve(root, rel)); } catch { return null; }
+  const base = fs.realpathSync(root);
+  if (!(real === base || real.startsWith(base + path.sep))) return null;
+  const st = fs.statSync(real);
+  return st.isFile() && st.size <= MAX_SOURCE ? { real, text: fs.readFileSync(real, 'utf8') } : null;
+}
+
+/** Split a type on its top-level arrows (arrows inside parentheses or brackets belong to a function-typed argument). */
+function splitArrows(type) {
+  const parts = []; let depth = 0; let cur = '';
+  for (let i = 0; i < type.length; i++) {
+    const c = type[i];
+    if ('([{'.includes(c)) depth++; else if (')]}'.includes(c)) depth--;
+    if (depth === 0 && c === '-' && type[i + 1] === '>') { parts.push(cur.trim()); cur = ''; i++; continue; }
+    cur += c;
+  }
+  parts.push(cur.trim());
+  return parts;
+}
+
+// Compile-time code execution and options that change what runs before the payload is involved.
+function loadTimeHazard(text) {
+  if (/\{-#\s*LANGUAGE[^#]*\b(?:TemplateHaskell|TemplateHaskellQuotes|QuasiQuotes|CPP|ForeignFunctionInterface|CApiFFI)\b/i.test(text)) return 'it enables Template Haskell, quasi-quotes, CPP or the foreign function interface, which run or require code at load time';
+  if (/\{-#\s*OPTIONS(?:_GHC)?\b[^#]*(?:-fplugin|-pgm|-opt[a-zA-Z]|-F\b|-cpp|-fobject-code)/i.test(text)) return 'its OPTIONS_GHC pragma names a plugin, a preprocessor or an external program';
+  if (/^\s*foreign\s+(?:import|export)\b/m.test(text)) return 'it uses the foreign function interface';
+  return null;
+}
+
+function classify(mod, pkg, boot) {
+  if (pkg) return { ok: false, name: String(pkg).replace(/^"|"$/g, '') };
+  if (boot.has(mod)) return { ok: true };
+  for (const [prefix, name] of THIRD_PARTY) if (mod === prefix || mod.startsWith(prefix.endsWith('.') ? prefix : `${prefix}.`)) return { ok: false, name: name ?? mod };
+  return { ok: false, name: mod };
+}
+
+/** @param {{finding: object, root: string, cls: {name: string, payload: string, oracle: object, network?: string, watch?: object, needsHs?: RegExp}, bootModules?: Set<string>}} o */
+export function generateHaskellReproducer({ finding, root, cls, bootModules }) {
+  const rel = String(finding.file);
+  if (cls.name === 'ssrf') return fail('ssrf: no HTTP client ships with GHC, so any program that makes a request imports a package outside the proof environment; this class is not proven for Haskell');
+  const src = readInside(root, rel);
+  if (!src) return fail('the flagged file is missing, outside the repository, or too large');
+  const hazard = loadTimeHazard(src.text);
+  if (hazard) return fail(`the flagged file is refused: ${hazard}`);
+  const info = parseHaskell(src.text);
+  if (!info || info.status !== 'parsed') return fail('the flagged file could not be parsed as Haskell');
+  const lines = src.text.split('\n');
+  const sinkLine = lines[finding.line - 1] ?? '';
+  const around = lines.slice(Math.max(0, finding.line - 3), finding.line + 2).join('\n');
+  if (cls.needsHs && !cls.needsHs.test(sinkLine) && !cls.needsHs.test(around)) return fail(`${cls.name}: the flagged code is not a write, and this class is only proven for write sinks`);
+
+  const tools = hostTools();
+  const boot = bootModules ?? (tools.ghc ? bootModuleSet(tools.ghc) : null);
+  if (!boot) return fail('no working GHC was found to list the modules the proof environment can import (install ghc, or run `agentic-security proof doctor`)');
+
+  // the entry module is placed at its module path so that other modules can import it; Main goes to Main.hs
+  const modName = info.module?.name ?? 'Main';
+  const entry = `${modName.replaceAll('.', '/')}.hs`;
+  const rootReal = fs.realpathSync(root);
+  const entryDir = path.dirname(src.real);
+  const modRel = modName.replaceAll('.', path.sep);
+  const srcRoot = src.real.endsWith(`${modRel}.hs`) ? src.real.slice(0, src.real.length - modRel.length - 3) : `${entryDir}${path.sep}`;
+  const searchRoots = [...new Set([srcRoot.replace(/[\\/]$/, ''), ...['src', 'app', 'lib', ''].map((d) => path.join(rootReal, d))])];
+  const sources = {}; const external = []; const seen = new Set([modName]);
+  let count = 0;
+  const visit = (imports) => {
+    for (const imp of imports) {
+      const mod = imp.module;
+      if (seen.has(mod)) continue;
+      seen.add(mod);
+      let local = null;
+      for (const base of searchRoots) { const cand = path.join(base, `${mod.replaceAll('.', '/')}.hs`); const r = readInside(root, path.relative(rootReal, cand)); if (r) { local = r; break; } }
+      if (local && !imp.package) {
+        if (++count > MAX_FILES) return fail(`the file pulls in more than ${MAX_FILES} repository modules`);
+        const dep = parseHaskell(local.text);
+        if (!dep || dep.status !== 'parsed') return fail(`the module ${mod} could not be parsed as Haskell`);
+        const h = loadTimeHazard(local.text); if (h) return fail(`the module ${mod} is refused: ${h}`);
+        sources[`${mod.replaceAll('.', '/')}.hs`] = path.relative(rootReal, local.real);
+        const r = visit(dep.imports ?? []); if (r) return r;
+        continue;
+      }
+      const c = classify(mod, imp.package, boot);
+      if (!c.ok) external.push(c.name);
+    }
+    return null;
+  };
+  const bad = visit(info.imports ?? []);
+  if (bad) return bad;
+  if (external.length) return fail(`the flagged code needs ${[...new Set(external)].slice(0, 4).join(', ')}, which is not available in the proof environment; only the packages that ship with GHC and files in the repository can be loaded`, { missing: [...new Set(external)] });
+  sources[entry] = rel;
+
+  const assumptions = [];
+  const base = { schema: 'agentic-security/reproducer', version: 1, findingId: String(finding.stableId ?? finding.id ?? 'generated'), lang: 'haskell', oracle: cls.oracle, network: cls.network ?? 'none', ...(cls.watch ? { watch: cls.watch } : {}) };
+  if (cls.watch) assumptions.push('the write target is assumed to be one directory below the working directory (the payload is ../escaped.txt); if the code uses another base, the proof will not confirm it');
+  const ghcRun = (expr) => ['{{GHC}}', '-ignore-dot-ghci', '-e', expr, entry];
+  const literal = (s) => JSON.stringify(s); // payloads are fixed strings with no quote or backslash; this is a plain Haskell string literal
+
+  // shape 1: a program that reads its payload from the command line
+  const hasMain = (info.functions ?? []).some((f) => f.scope === 'top' && f.name === 'main');
+  if (/\bgetArgs\b/.test(src.text) && hasMain) {
+    assumptions.push('the payload is passed as the first and only command-line argument; a program that expects other arguments will not reach the flagged line');
+    const reproducer = { ...base, sources, run: ghcRun(`:main ${literal(cls.payload)}`) };
+    const errs = validateReproducer(reproducer);
+    return errs.length ? fail(`the generated reproducer is invalid: ${errs[0]}`) : { ok: true, reproducer, basis: { shape: 'script', class: cls.name, entry: rel, line: finding.line, assumptions } };
+  }
+
+  // shape 2: a top-level function around the flagged line
+  const fn = (info.functions ?? []).filter((f) => f.scope === 'top' && f.name !== 'main' && /^[a-z_][\w']*$/.test(f.name)).find((f) => {
+    const end = Math.max(f.span.endLine, ...(f.clauses ?? []).map((c) => c.span?.endLine ?? 0));
+    return f.span.startLine <= finding.line && end >= finding.line;
+  });
+  if (!fn) return fail('the flagged line is not inside a top-level function, and the file does not read getArgs in a main');
+  const sig = (info.signatures ?? []).find((s) => s.scope === 'top' && s.names.includes(fn.name));
+  if (!sig) return fail(`${fn.name} has no type signature, so the proof cannot tell what to pass it`);
+  const sigText = lines.slice(sig.span.startLine - 1, sig.span.endLine).join(' ');
+  const m = new RegExp(`${fn.name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}[^:]*::\\s*([\\s\\S]*)$`).exec(sigText);
+  if (!m) return fail(`the type signature of ${fn.name} could not be read`);
+  const type = m[1].replace(/--.*$/, '').trim();
+  if (type.includes('=>') || /\bforall\b/.test(type)) return fail(`${fn.name} is polymorphic or constrained (${type.slice(0, 60)}), so the proof cannot choose its arguments`);
+  const parts = splitArrows(type);
+  const result = parts[parts.length - 1]; const params = parts.slice(0, -1);
+  if (!/^IO\b/.test(result)) return fail(`${fn.name} returns ${result.slice(0, 40)}, not IO, so calling it would not perform the flagged operation`);
+  if (!params.length) return fail(`${fn.name} takes no parameters, so the payload has no way in`);
+  const bad2 = params.find((p) => !/^(?:String|FilePath|\[Char\])$/.test(p));
+  if (bad2) return fail(`${fn.name} takes a parameter of type ${bad2.slice(0, 40)}; only String and FilePath can be filled with a payload`);
+  assumptions.push('the payload is passed in every parameter (a String has no request-like stand-in), which is an approximation of how the function is really called');
+  const call = `${fn.name} ${params.map(() => literal(cls.payload)).join(' ')} >>= \\_ -> return ()`;
+  const reproducer = { ...base, sources, run: ghcRun(call) };
+  const errs = validateReproducer(reproducer);
+  return errs.length ? fail(`the generated reproducer is invalid: ${errs[0]}`) : { ok: true, reproducer, basis: { shape: 'function', class: cls.name, entry: rel, line: finding.line, function: `${fn.name}(${params.length} String)`, assumptions } };
+}

package/src/posture/proof-fabric/generate.js

@@ -6,7 +6,7 @@
 // independent replay as any other. A generated reproducer is not a verdict; it is a proposal that is either confirmed by execution
 // or not.
 //
-// What this is not: a general exploit generator. It handles JavaScript (here) and Python (`generate-python.js`), and only code the proof environment can actually load:
+// What this is not: a general exploit generator. It handles JavaScript (here), Python (`generate-python.js`) and Haskell (`generate-haskell.js`), and only code the proof environment can actually load:
 // the file's imports must be Node built-ins or relative files inside the repository (a package from node_modules is not there in
 // the sandbox, so a handler that needs `express` is refused, with the package named). Anything outside that returns `{ ok: false }`
 // with the reason, and nothing is executed.
@@ -27,10 +27,11 @@ import { builtinModules } from 'node:module';
 import { parse } from '@babel/parser';
 import { validateReproducer } from './reproducer.js';
 import { generatePythonReproducer } from './generate-python.js';
+import { generateHaskellReproducer } from './generate-haskell.js';
 
 const CLASSES = {
   'CWE-78': { name: 'command-injection', payload: 'x; touch {{CANARY:command}}', oracle: { type: 'command_execution', params: { canary: 'command' } } },
-  'CWE-22': { needsPy: /\bopen\s*\([^)]*['"][wax]b?\+?['"]|\.write_(?:text|bytes)\s*\(|\bshutil\.(?:copy|move)/, name: 'path-traversal', payload: '../escaped.txt', oracle: { type: 'filesystem_mutation', params: { canary: 'fs' } }, watch: { fs: 'escaped.txt' }, needs: /\b(?:writeFile|writeFileSync|appendFile|appendFileSync|createWriteStream)\b/ },
+  'CWE-22': { needsPy: /\bopen\s*\([^)]*['"][wax]b?\+?['"]|\.write_(?:text|bytes)\s*\(|\bshutil\.(?:copy|move)/, name: 'path-traversal', payload: '../escaped.txt', oracle: { type: 'filesystem_mutation', params: { canary: 'fs' } }, watch: { fs: 'escaped.txt' }, needsHs: /\b(?:writeFile|appendFile|copyFile|copyFileWithMetadata|renameFile|openBinaryFile)\b|\b(?:openFile|withFile|withBinaryFile)\b[^\n]*\b(?:WriteMode|AppendMode|ReadWriteMode)\b/, needs: /\b(?:writeFile|writeFileSync|appendFile|appendFileSync|createWriteStream)\b/ },
   'CWE-918': { name: 'ssrf', payload: '{{CALLBACK_URL}}', oracle: { type: 'outbound_callback' }, network: 'callback' },
 };
 const MAX_SOURCE = 256 * 1024;
@@ -138,9 +139,11 @@ export function generateReproducer({ finding, root }) {
   if (!cls) return fail(`no payload and oracle exist for ${cwe ?? 'this finding'}; supported: ${Object.keys(CLASSES).join(', ')} (others need a database, a deserializer or a native harness)`);
   const rel = String(finding?.file ?? '');
   const isPy = /\.py$/i.test(rel);
-  if (!isPy && !/\.(?:js|mjs|cjs)$/i.test(rel)) return fail(`no harness builder for ${path.extname(rel) || 'this file type'}; JavaScript and Python only`);
+  const isHs = /\.hs$/i.test(rel);
+  if (!isPy && !isHs && !/\.(?:js|mjs|cjs)$/i.test(rel)) return fail(`no harness builder for ${path.extname(rel) || 'this file type'}; JavaScript, Python and Haskell only`);
   if (!Number.isInteger(finding?.line)) return fail('the finding has no line number');
   if (isPy) return generatePythonReproducer({ finding, root, cls });
+  if (isHs) return generateHaskellReproducer({ finding, root, cls });
   const src = readSource(root, rel);
   if (!src) return fail('the flagged file is missing, outside the repository, or too large');
   const ast = parseSource(src.text);

package/src/posture/proof-fabric/reproducer.js

@@ -8,12 +8,12 @@ import { validateAttackFacts } from '../dnr/attack-facts.js';
 
 const REPRODUCER_SCHEMA = 'agentic-security/reproducer';
 const REPRODUCER_VERSION = 1;
-export const LANGUAGES = Object.freeze(['javascript', 'typescript', 'python', 'java', 'c', 'cpp', 'csharp']);
+export const LANGUAGES = Object.freeze(['javascript', 'typescript', 'python', 'java', 'c', 'cpp', 'csharp', 'haskell']);
 export const MAX_FILES = 64;
 export const MAX_FILE_BYTES = 256 * 1024;
 const MAX_TOTAL_BYTES = 1024 * 1024;
 const PLACEHOLDER_RE = /\{\{([A-Z_]+)(?::([a-z0-9_-]{1,32}))?\}\}/g;
-const ALLOWED_PLACEHOLDERS = new Set(['NONCE', 'SECRET', 'CANARY', 'CALLBACK_URL', 'CALLBACK_PORT', 'ROOT', 'NODE', 'PYTHON', 'JAVA', 'JAVAC', 'CC']);
+const ALLOWED_PLACEHOLDERS = new Set(['NONCE', 'SECRET', 'CANARY', 'CALLBACK_URL', 'CALLBACK_PORT', 'ROOT', 'NODE', 'PYTHON', 'JAVA', 'JAVAC', 'CC', 'GHC', 'RUNGHC']);
 
 export function isSafeRelPath(rel) {
   if (typeof rel !== 'string' || !rel || rel.length > 200) return false;
@@ -105,6 +105,8 @@ export function substitute(text, ctx) {
       case 'JAVA': return ctx.tools.java ?? whole;
       case 'JAVAC': return ctx.tools.javac ?? whole;
       case 'CC': return ctx.tools.cc ?? whole;
+      case 'GHC': return ctx.tools.ghc ?? whole;
+      case 'RUNGHC': return ctx.tools.runghc ?? whole;
       default: return whole;
     }
   });

package/src/posture/proof-fabric/runner.js

@@ -24,13 +24,13 @@ export const DEFAULT_LIMITS = Object.freeze({
 
 const CONTAINER_IMAGES = Object.freeze({
   javascript: 'node:24-slim', typescript: 'node:24-slim', python: 'python:3-slim', java: 'eclipse-temurin:21',
-  c: 'gcc:latest', cpp: 'gcc:latest', csharp: 'mcr.microsoft.com/dotnet/sdk:8.0',
+  c: 'gcc:latest', cpp: 'gcc:latest', csharp: 'mcr.microsoft.com/dotnet/sdk:8.0', haskell: 'haskell:9',
 });
 
 const SIGNALS = { 134: 'SIGABRT', 135: 'SIGBUS', 136: 'SIGFPE', 132: 'SIGILL', 139: 'SIGSEGV' };
 
 // only language toolchains are probed; the container engine has its own, richer health check (`container.js`)
-const PROBED_TOOLS = new Set(['java', 'javac', 'python3', 'cc', 'gcc', 'dotnet']);
+const PROBED_TOOLS = new Set(['java', 'javac', 'python3', 'cc', 'gcc', 'dotnet', 'ghc', 'runghc']);
 const probeCache = new Map();
 /** A launcher that exists is not a toolchain that works: macOS ships /usr/bin/java and /usr/bin/python3 as stubs that only prompt for an
  * install. A tool counts only if it answers its version flag, within a short timeout, with exit 0. */
@@ -61,12 +61,12 @@ function findTool(name, pathEnv = process.env.PATH || '') {
 }
 
 export function hostTools() {
-  return { node: process.execPath, python: findTool('python3'), java: findTool('java'), javac: findTool('javac'), cc: findTool('cc') || findTool('gcc'), dotnet: findTool('dotnet') };
+  return { node: process.execPath, python: findTool('python3'), java: findTool('java'), javac: findTool('javac'), cc: findTool('cc') || findTool('gcc'), dotnet: findTool('dotnet'), ghc: findTool('ghc'), runghc: findTool('runghc') };
 }
 
 /** Language -> tools it needs. Missing tools make the language `unsupported` with a typed reason, never a pass. */
 export function languageSupport(lang, tools = hostTools()) {
-  const need = { javascript: ['node'], typescript: ['node'], python: ['python'], java: ['java', 'javac'], c: ['cc'], cpp: ['cc'], csharp: ['dotnet'] }[lang];
+  const need = { javascript: ['node'], typescript: ['node'], python: ['python'], java: ['java', 'javac'], c: ['cc'], cpp: ['cc'], csharp: ['dotnet'], haskell: ['ghc', 'runghc'] }[lang];
   if (!need) return { supported: false, reason: `unsupported language: ${lang}` };
   const missing = need.filter((t) => !tools[t]);
   return missing.length ? { supported: false, reason: `missing toolchain: ${missing.join(', ')}` } : { supported: true, reason: null };

package/src/sast/CLAUDE.md

@@ -39,6 +39,8 @@ Both key on the SECRET-NESS of the identifier, never on the comparison or the ty
 
 **Bench-shape adapters (label-leakage, OFF by default)** — `bench-shape/` directory, plus `cpp-bench-extras.js`, `java-bench-extras.js`, `juliet-shape.js`, `primary-cwe-java.js`. These read Juliet / OWASP-Benchmark answer keys. Disabled unless `AGENTIC_SECURITY_BENCH_SHAPE=1`; `AGENTIC_SECURITY_BLIND_BENCH=1` overrides to force everything off. **Never use their emissions as a quality signal.**
 
+**Precision guards (bench/dag).** Small, general recognisers that answer one semantic question each about the TEXT of a call, shared by every emitter that can fire on it. Each is tested as a pair (the safe construct stays quiet, the near-miss that changes the semantics keeps its verdict) in `test/dag-precision.test.js` and `bench/mutation/cases.mjs` (`DAG_PRECISION_CASES`). `_call-args.js` (quote- and bracket-aware argument splitter; a window that ends inside the call yields the arguments completed so far, flagged `partial`), `redirect-target.js` (CWE-601: a literal prefix that fixes the origin, `'/user/' + id` or `'https://host/' + p`, cannot be steered off-origin; `'/' + x`, `'//' + x` and a host with no closing slash can), `reflected-input.js` (CWE-79: only the properties of `req` that carry the client's input count, and not inside an HTML escaper; `req.session`/`req.user`/`req.app` are server state), `send-file-root.js` (CWE-22: `sendFile`/`download` with an inline `root` option confine the path), `init-scope.js` (CWE-400: is a position inside a function body, including expression-bodied arrows and class bodies, or at module load; a block is a function unless it is positively a control block or a literal, because the error that matters is hiding a finding), `listen-bind-address.js` (the `address` a `listen` callback receives is the bound socket address, not personal data). Wired in `../engine.js` (`dropGuardedFindings` for redirect and file serving, the `predicate` hook of the structural patterns for reflection and blocking I/O, `_detectSafeSinkShape`), `sensitive-data-logging.js` and `../dataflow/privacy-taint.js`. `engine.js` `_usedIdentifiers` is the same idea for the flow-pair detector: words inside string literals and property names after a dot are not reads of a variable of that name.
+
 **Helpers** — `_comment-strip.js` strips comments while preserving line numbers (so finding `line` stays accurate). `index.js` is the public re-export.
 
 ## Gotchas

package/src/sast/_call-args.js

@@ -0,0 +1,70 @@
+// Argument splitting for guard recognisers that must look at WHAT a call is
+// given, not at the text around it. Quote- and bracket-aware; handles template
+// literal substitutions. Not a parser: it answers "where does each top-level
+// argument start and end" for text that begins right after a call's '('.
+
+const isQuote = (c) => c === '"' || c === "'" || c === '`';
+
+/**
+ * Split the text that follows a call's opening paren into its top-level
+ * arguments (source text, quotes intact). Returns null when the closing paren
+ * is not in the text given, so a caller never reasons about a truncated call.
+ */
+export function callArguments(text) {
+  const args = [];
+  let depth = 0;
+  let start = 0;
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    if (isQuote(c)) {
+      const q = c;
+      i++;
+      while (i < text.length && text[i] !== q) {
+        if (text[i] === '\\') { i += 2; continue; }
+        if (q === '`' && text[i] === '$' && text[i + 1] === '{') {
+          let d = 1; i += 2;
+          while (i < text.length && d > 0) { if (text[i] === '{') d++; else if (text[i] === '}') d--; i++; }
+          continue;
+        }
+        i++;
+      }
+      i++;
+      continue;
+    }
+    if (c === '(' || c === '[' || c === '{') depth++;
+    else if (c === ')' || c === ']' || c === '}') {
+      if (depth === 0) {
+        const last = text.slice(start, i);
+        if (last.trim() !== '' || args.length > 0) args.push(last);
+        return args;
+      }
+      depth--;
+    } else if (c === ',' && depth === 0) {
+      args.push(text.slice(start, i));
+      start = i + 1;
+    }
+    i++;
+  }
+  // The window ended inside the call (a long callback, a wrapped call). The
+  // arguments completed so far are still exactly what the call was given; the
+  // unfinished last one is dropped rather than guessed. `partial` lets a caller
+  // that needs the whole call refuse.
+  if (args.length === 0) return null;
+  args.partial = true;
+  return args;
+}
+
+/**
+ * Find the first call on or just after `line` (1-based) whose callee matches
+ * `calleeRe` (which must end at the opening paren) and return its arguments.
+ * Looks at the finding line and the next three, because a call is routinely
+ * wrapped. Returns null when there is no such call or it is not closed.
+ */
+export function callArgumentsAt(lines, line, calleeRe) {
+  if (!Array.isArray(lines) || !Number.isInteger(line) || line < 1) return null;
+  const text = lines.slice(line - 1, line + 3).join('\n');
+  const m = calleeRe.exec(text);
+  if (!m) return null;
+  return callArguments(text.slice(m.index + m[0].length));
+}

package/src/sast/init-scope.js

@@ -0,0 +1,87 @@
+// Is a source position inside a function body, or at module/initialisation
+// level? Some hazards exist only while the process is serving work: a blocking
+// call made once at module load (reading a TLS key, a config file) delays
+// startup once, and nothing is waiting on the event loop yet. The same call in
+// a request callback stalls every connection.
+//
+// A position is inside a function when it is inside
+//   * a `{ ... }` block opened by `=>`, a `function` header, a method or class
+//     member header (`name(params) {`), or an async/generator form,
+//   * the body of an expression-bodied arrow (`(p) => fs.readFileSync(p)`),
+//     which runs when the arrow is CALLED, not where it is written, or
+//   * a class body (field initialisers run per instance).
+// Plain blocks (`if`, `for`, `try`, `else`) and object literals are not function scopes.
+//
+// Operates on a comment- and string-blanked view so braces in strings or
+// comments never count. It is a lexical approximation (no parse). The one error
+// that matters is calling a function body "module level", because that hides a
+// finding, so a block is classed as a function unless it is positively a control
+// block or a literal, and parameter lists are matched by bracket depth, not by a
+// pattern that stops at a fixed nesting.
+
+const CONTROL_KEYWORDS = new Set(['if', 'for', 'while', 'switch', 'catch', 'with', 'else', 'try', 'finally', 'do']);
+const CLASS_HEAD = /\bclass\b\s*[\w$]*(?:\s+extends\s+[\w$.()]+)?\s*$/;
+
+/** Index of the '(' matching the ')' at `closeIdx`, scanning backwards; -1 if unbalanced. */
+function matchingOpenParen(text, closeIdx) {
+  let depth = 0;
+  for (let i = closeIdx; i >= 0; i--) {
+    const c = text[i];
+    if (c === ')') depth++;
+    else if (c === '(') { depth--; if (depth === 0) return i; }
+  }
+  return -1;
+}
+
+function opensFunction(text, braceIdx) {
+  let end = braceIdx;
+  while (end > 0 && /\s/.test(text[end - 1])) end--;
+  const before = text.slice(Math.max(0, end - 400), end);
+  if (/=>$/.test(before)) return true;
+  if (CLASS_HEAD.test(before)) return true;
+  // `else {`, `try {`, `finally {`, `do {`, `catch {` carry no parenthesised head
+  const bare = /(?:^|[^\w$.])([A-Za-z_$][\w$]*)$/.exec(before);
+  if (bare && CONTROL_KEYWORDS.has(bare[1])) return false;
+  // find the ')' that ends a parameter list, allowing a return type annotation `): Type {`
+  let closeIdx = end - 1;
+  if (text[closeIdx] !== ')') {
+    const m = /\)\s*:\s*[^(){};=]*$/.exec(before);
+    if (!m) return false;
+    closeIdx = end - before.length + m.index;
+  }
+  const openIdx = matchingOpenParen(text, closeIdx);
+  if (openIdx < 0) return true; // cannot match the head: keep findings, so call it a function
+  const head = text.slice(Math.max(0, openIdx - 80), openIdx).replace(/\s+$/, '');
+  const word = /([A-Za-z_$][\w$]*)$/.exec(head);
+  if (word) return !CONTROL_KEYWORDS.has(word[1]); // `if (` `while (` ...: control; any other name( ... ) { is a function or method
+  if (/\bfunction\s*\*?$/.test(head)) return true; // `function (` and `function* (`
+  return false;
+}
+
+/**
+ * @param {string} blanked  source with comments and string bodies blanked
+ * @param {number} offset   index into `blanked`
+ * @returns {boolean} true when `offset` is lexically inside a function body
+ */
+export function insideFunctionBody(blanked, offset) {
+  // entries: 'F' function block, 'B' other block, 'P' paren/bracket, 'A' expression-bodied arrow
+  const stack = [];
+  const end = Math.min(offset, blanked.length);
+  for (let i = 0; i < end; i++) {
+    const c = blanked[i];
+    if (c === '{') stack.push(opensFunction(blanked, i) ? 'F' : 'B');
+    else if (c === '(' || c === '[') stack.push('P');
+    else if (c === '}' || c === ')' || c === ']') {
+      while (stack.length && stack[stack.length - 1] === 'A') stack.pop(); // an arrow body ends where its enclosing bracket closes
+      stack.pop();
+    } else if ((c === ',' || c === ';') && stack[stack.length - 1] === 'A') {
+      stack.pop(); // ... or at a separator at its own nesting level
+    } else if (c === '=' && blanked[i + 1] === '>') {
+      let j = i + 2;
+      while (j < blanked.length && /\s/.test(blanked[j])) j++;
+      if (blanked[j] !== '{') stack.push('A');
+      i++;
+    }
+  }
+  return stack.some((e) => e === 'F' || e === 'A');
+}

package/src/sast/listen-bind-address.js

@@ -0,0 +1,49 @@
+// The `address` a `listen` callback receives.
+//
+//   server.listen({ port }, (err, address) => console.log(`listening on ${address}`))
+//
+// `address` here is the socket address the server just bound (host and port),
+// handed to the callback by the server. It is not a person's postal address, so a
+// rule that classifies a value by the NAME `address` must not treat this binding
+// as personal data. The rule is about the binding site, not about the word: the
+// same name bound anywhere else (a form field, a column, a request property) is
+// unaffected.
+
+/** Index just past the paren that closes the one opened at `openIdx`, or -1 when the text ends first. */
+function closeOfParen(text, openIdx) {
+  let depth = 0;
+  for (let i = openIdx; i < text.length; i++) {
+    const c = text[i];
+    if (c === '"' || c === "'" || c === '`') {
+      const q = c; i++;
+      while (i < text.length && text[i] !== q) { if (text[i] === '\\') i++; i++; }
+    } else if (c === '(') depth++;
+    else if (c === ')') { depth--; if (depth === 0) return i + 1; }
+  }
+  return -1;
+}
+
+/**
+ * Is the identifier at `idx` in `raw` a parameter declared by a callback passed
+ * to a `.listen(` call? `idx` is any position at or after the callback header
+ * (the use site); the header is searched backwards within a bounded window, and
+ * must sit inside the listen call's own parentheses, so a function declared after
+ * the call has closed does not count.
+ */
+export function isListenCallbackParam(raw, idx, name) {
+  if (typeof raw !== 'string' || !name) return false;
+  const from = Math.max(0, idx - 800);
+  const at = raw.slice(from, idx).lastIndexOf('.listen(');
+  if (at < 0) return false;
+  const start = from + at;
+  const openIdx = start + '.listen'.length;
+  const windowEnd = idx + name.length + 80;
+  const close = closeOfParen(raw.slice(start, windowEnd), openIdx - start);
+  // the call closed before the use site: the use is not inside the callback
+  if (close !== -1 && start + close <= idx) return false;
+  const after = raw.slice(start, close === -1 ? windowEnd : Math.min(windowEnd, start + close));
+  const id = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const arrow = new RegExp(String.raw`\([^)]*\b${id}\b[^)]*\)\s*=>|\b${id}\s*=>`);
+  const fn = new RegExp(String.raw`\bfunction\b[^(]*\([^)]*\b${id}\b[^)]*\)`);
+  return arrow.test(after) || fn.test(after);
+}

package/src/sast/redirect-target.js

@@ -0,0 +1,106 @@
+// Open-redirect target shape (CWE-601): can the part of a redirect target the
+// program does not control change the ORIGIN the browser is sent to?
+//
+// A redirect target is attacker-steerable to another origin only if the
+// attacker controls the authority (scheme, host, port) of the resulting URL.
+// A target that begins with a literal which already fixes the authority cannot
+// be moved off-origin by whatever is appended after it:
+//
+//   '/user/' + id                   path-absolute, second character is a name
+//                                   character: same origin, whatever `id` is
+//   'https://app.example.com/' + p  the whole authority is in the literal and a
+//                                   '/' closes it, so `p` is only path/query
+//
+// and these are NOT pinned, because the dynamic part decides the authority:
+//
+//   '/' + x                x = '/evil.example'  gives '//evil.example'
+//   '//' + x, '/\\' + x    protocol-relative (browsers treat '\' as '/')
+//   'https://app.example.com' + x   x = '.evil.example' or '@evil.example'
+//   '' + x, x, x + '/path'          no literal prefix at all
+//
+// This is deliberately the ONLY thing decided here. It reads the text of the
+// redirect call's first argument; it does not decide whether the dynamic part
+// is attacker-controlled (that is the taint layer's question) and it never
+// reads a file name, a fixture name or a label.
+
+import { callArgumentsAt } from './_call-args.js';
+
+const REDIRECT_CALL_RE = /\b(?:redirect|sendRedirect|Redirect|redirect_to|HttpResponseRedirect|RedirectResponse|redirectTo|permanentRedirect)\s*\(/;
+
+/**
+ * Leading literal text of an expression, and whether anything dynamic follows.
+ * Handles 'a' + x, "a" + x + y, `a${x}`, and a lone literal.
+ * `literal` is the decoded-enough prefix (escapes kept verbatim, which is safe
+ * here because the checks below only look at slashes and the first characters).
+ */
+export function leadingLiteral(expr) {
+  const s = String(expr).trim();
+  let i = 0;
+  let prefix = '';
+  let dynamic = false;
+  for (;;) {
+    while (i < s.length && /\s/.test(s[i])) i++;
+    if (i >= s.length) break;
+    const c = s[i];
+    if (c === '"' || c === "'") {
+      let j = i + 1; let body = '';
+      while (j < s.length && s[j] !== c) { if (s[j] === '\\') { body += s[j] + (s[j + 1] || ''); j += 2; } else body += s[j++]; }
+      if (j >= s.length) return { literal: prefix, dynamic: true, closed: false };
+      prefix += body; i = j + 1;
+    } else if (c === '`') {
+      let j = i + 1; let body = '';
+      while (j < s.length && s[j] !== '`') {
+        if (s[j] === '\\') { body += s[j] + (s[j + 1] || ''); j += 2; continue; }
+        if (s[j] === '$' && s[j + 1] === '{') { dynamic = true; break; }
+        body += s[j++];
+      }
+      prefix += body;
+      if (dynamic) return { literal: prefix, dynamic: true, closed: true };
+      if (j >= s.length) return { literal: prefix, dynamic: true, closed: false };
+      i = j + 1;
+    } else {
+      return { literal: prefix, dynamic: true, closed: true };
+    }
+    while (i < s.length && /\s/.test(s[i])) i++;
+    if (i >= s.length) return { literal: prefix, dynamic, closed: true };
+    if (s[i] === '+') { i++; continue; }
+    // anything else after a literal (a call suffix, `.concat`, `%`, ...): not a plain literal
+    return { literal: prefix, dynamic: true, closed: true };
+  }
+  return { literal: prefix, dynamic, closed: true };
+}
+
+/** A literal prefix that fixes the origin of the URL it begins. */
+export function prefixPinsOrigin(prefix) {
+  // Path-absolute: '/' then a character that is neither '/' nor '\' (both are
+  // read as a second slash, turning the reference into a network-path one).
+  if (/^\/[^\/\\\s]/.test(prefix)) return true;
+  // Absolute URL whose authority is complete: scheme://authority/ .
+  if (/^[A-Za-z][A-Za-z0-9+.\-]*:\/\/[^\/?#\\\s]+\//.test(prefix)) return true;
+  return false;
+}
+
+/**
+ * Does the redirect argument keep the destination on a fixed origin?
+ * `arg` is the first argument of the redirect call. A numeric first argument
+ * (`res.redirect(302, url)`) is skipped by the caller, not here.
+ */
+export function redirectArgumentPinsOrigin(arg) {
+  const { literal, dynamic, closed } = leadingLiteral(arg);
+  if (!closed) return false;
+  if (!dynamic) return literal.length > 0; // a fully static target
+  return prefixPinsOrigin(literal);
+}
+
+/**
+ * Inspect source lines starting at `line` (1-based) for a redirect call and
+ * decide whether its target pins the origin. Returns null when no redirect
+ * call is found (no opinion), else true/false.
+ */
+export function redirectTargetPinsOriginAt(lines, line) {
+  const args = callArgumentsAt(lines, line, REDIRECT_CALL_RE);
+  if (!args || args.length === 0) return null;
+  // res.redirect(302, '/x'): the status code is not the target
+  const target = args.length > 1 && /^\s*\d{3}\s*$/.test(args[0]) ? args[1] : args[0];
+  return redirectArgumentPinsOrigin(target);
+}