safeey-cli 0.2.0 → 0.6.0

package/src/engine/gitignore.js

@@ -0,0 +1,128 @@
+// src/engine/gitignore.js
+// Answers one question: "would git ignore this path?" We use it to decide
+// whether secrets in a .env file matter. A secret in a *properly ignored* .env
+// is that file doing its job. A secret in a .env that ISN'T ignored is a leak
+// waiting to be committed — that's the finding worth raising.
+//
+// Primary strategy: shell out to `git check-ignore`, which implements the full
+// gitignore spec (nesting, negation, anchoring, core.excludesFile) correctly so
+// we don't have to. Fallback: a focused matcher for trees that aren't git repos
+// (where "no .gitignore at all" correctly resolves to "not ignored" -> flag it).
+
+const { execFileSync } = require("child_process");
+const fs = require("fs");
+const path = require("path");
+
+const IGNORE_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", "out", "vendor", "coverage"]);
+
+function isGitRepo(root) {
+  try {
+    const out = execFileSync("git", ["-C", root, "rev-parse", "--is-inside-work-tree"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    });
+    return out.trim() === "true";
+  } catch {
+    return false;
+  }
+}
+
+// Returns true (ignored), false (not ignored), or null (couldn't determine).
+function gitCheckIgnore(root, relPath) {
+  try {
+    execFileSync("git", ["-C", root, "check-ignore", "-q", "--", relPath], { stdio: "ignore" });
+    return true; // exit 0 => path is ignored
+  } catch (e) {
+    if (e && e.status === 1) return false; // exit 1 => not ignored
+    return null; // 128 / git missing => unknown
+  }
+}
+
+// ---- Non-git fallback ------------------------------------------------------
+
+// Convert a single gitignore pattern to { re, negate, dirOnly } relative to the
+// directory the .gitignore lives in. Intentionally a pragmatic subset of the
+// spec — enough to resolve the env-file cases the tool cares about.
+function patternToMatcher(raw) {
+  let pat = raw.replace(/\r$/, "");
+  if (!pat || pat.startsWith("#")) return null;
+  // Trim unescaped trailing whitespace.
+  pat = pat.replace(/((?:[^\\ ]|\\ )*?)\s+$/, "$1");
+  if (!pat) return null;
+
+  let negate = false;
+  if (pat.startsWith("!")) { negate = true; pat = pat.slice(1); }
+
+  let dirOnly = false;
+  if (pat.endsWith("/")) { dirOnly = true; pat = pat.slice(0, -1); }
+
+  const anchored = pat.startsWith("/") || pat.includes("/");
+  if (pat.startsWith("/")) pat = pat.slice(1);
+
+  // Escape regex metachars, then re-enable glob semantics.
+  let re = pat.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  re = re.replace(/\*\*/g, "\u0000").replace(/\*/g, "[^/]*").replace(/\u0000/g, ".*").replace(/\?/g, "[^/]");
+
+  const body = anchored ? `^${re}(?:/.*)?$` : `(?:^|/)${re}(?:/.*)?$`;
+  return { re: new RegExp(body), negate, dirOnly };
+}
+
+function readGitignores(root) {
+  const found = []; // { dir, matchers: [...] }
+  (function walk(dir) {
+    let entries = [];
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    const gi = path.join(dir, ".gitignore");
+    if (fs.existsSync(gi)) {
+      try {
+        const matchers = fs.readFileSync(gi, "utf8").split(/\n/).map(patternToMatcher).filter(Boolean);
+        found.push({ dir, matchers });
+      } catch { /* unreadable — skip */ }
+    }
+    for (const e of entries) {
+      if (e.isDirectory() && !IGNORE_DIRS.has(e.name)) walk(path.join(dir, e.name));
+    }
+  })(root);
+  return found;
+}
+
+function buildFallbackMatcher(root) {
+  const gitignores = readGitignores(root);
+  return function isIgnored(absPath) {
+    let decision = false;
+    for (const { dir, matchers } of gitignores) {
+      const rel = path.relative(dir, absPath);
+      if (!rel || rel.startsWith("..")) continue; // file not under this .gitignore
+      for (const m of matchers) {
+        if (m.re.test(rel)) decision = !m.negate;
+      }
+    }
+    return decision;
+  };
+}
+
+// ---- Public API ------------------------------------------------------------
+
+function makeIgnoreChecker(root) {
+  const git = isGitRepo(root);
+  const fallback = git ? null : buildFallbackMatcher(root);
+  const cache = new Map();
+  return {
+    mode: git ? "git" : "fallback",
+    // true | false | null(unknown, git-mode only)
+    isIgnored(absPath) {
+      if (cache.has(absPath)) return cache.get(absPath);
+      let res;
+      if (git) {
+        const rel = path.relative(root, absPath) || path.basename(absPath);
+        res = gitCheckIgnore(root, rel);
+      } else {
+        res = fallback(absPath);
+      }
+      cache.set(absPath, res);
+      return res;
+    },
+  };
+}
+
+module.exports = { makeIgnoreChecker };

package/src/engine/infra.js

@@ -0,0 +1,46 @@
+// src/engine/infra.js — run infra rules against a file classified by kind.
+const { normalizeAll } = require("../rules/schema");
+const { INFRA_RULES, classifyInfraFile } = require("../rules/infra");
+
+// Normalize (fills category/owasp/etc.); keep the infra-specific fields around.
+const RULES = normalizeAll(
+  INFRA_RULES.map((r) => ({ ...r, languages: ["*"] })),
+  "pattern"
+).map((n, i) => ({ ...n, kinds: INFRA_RULES[i].kinds, whole: INFRA_RULES[i].whole, absentRe: INFRA_RULES[i].absentRe }));
+
+function analyzeInfra(code, file, base) {
+  const kind = classifyInfraFile(file, base, code);
+  if (!kind) return [];
+  const applicable = RULES.filter((r) => r.kinds.includes(kind));
+  if (applicable.length === 0) return [];
+
+  const findings = [];
+  const lines = code.split(/\r?\n/);
+
+  for (const rule of applicable) {
+    if (rule.whole) {
+      // Whole-file rule: fires when re matches somewhere AND absentRe is absent.
+      if (rule.re.test(code) && rule.absentRe && !rule.absentRe.test(code)) {
+        findings.push(mk(rule, file, 1, 1));
+      }
+      continue;
+    }
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      if (line.length > 2000) continue;
+      const m = rule.re.exec(line);
+      if (m) findings.push(mk(rule, file, i + 1, (m.index ?? 0) + 1));
+    }
+  }
+  return findings;
+}
+
+function mk(rule, file, line, column) {
+  return {
+    ruleId: rule.id, title: rule.title, severity: rule.severity, confidence: rule.confidence,
+    category: rule.category, cwe: rule.cwe, owasp: rule.owasp,
+    file, line, column, message: rule.message, fix: rule.fix,
+  };
+}
+
+module.exports = { analyzeInfra };

package/src/engine/osv.js

@@ -0,0 +1,173 @@
+// src/engine/osv.js — check installed dependencies against known CVEs via OSV.dev.
+//
+// This is the only part of Safeey that makes a network request, so it is
+// OPT-IN (`--osv`). It sends *only* package names and versions (never your
+// source) to OSV.dev, Google's public vulnerability database, and maps any
+// advisories back to findings. Reads the lockfile so it covers transitive
+// dependencies, not just what's in package.json.
+
+const fs = require("fs");
+const path = require("path");
+
+const OSV_BATCH_URL = "https://api.osv.dev/v1/querybatch";
+const OSV_VULN_URL = "https://api.osv.dev/v1/vulns/";
+
+// --- lockfile parsing -------------------------------------------------------
+
+// Returns [{ name, version }] from the best lockfile we can find. npm v2/v3
+// lockfiles ("packages" map) preferred; falls back to legacy "dependencies".
+function readNpmLock(dir) {
+  const lockPath = path.join(dir, "package-lock.json");
+  if (!fs.existsSync(lockPath)) return null;
+  let data;
+  try { data = JSON.parse(fs.readFileSync(lockPath, "utf8")); } catch { return null; }
+  const out = new Map();
+  if (data.packages) {
+    for (const [key, info] of Object.entries(data.packages)) {
+      if (!key || !info || !info.version) continue; // "" is the root project
+      const name = key.startsWith("node_modules/") ? key.slice(key.lastIndexOf("node_modules/") + 13) : info.name;
+      if (name) out.set(`${name}@${info.version}`, { name, version: info.version });
+    }
+  }
+  if (out.size === 0 && data.dependencies) {
+    const walk = (deps) => {
+      for (const [name, info] of Object.entries(deps)) {
+        if (info && info.version) out.set(`${name}@${info.version}`, { name, version: info.version });
+        if (info && info.dependencies) walk(info.dependencies);
+      }
+    };
+    walk(data.dependencies);
+  }
+  return [...out.values()];
+}
+
+// Fallback: pin-only reads from package.json (no transitive coverage).
+function readManifest(dir) {
+  const p = path.join(dir, "package.json");
+  if (!fs.existsSync(p)) return null;
+  let data;
+  try { data = JSON.parse(fs.readFileSync(p, "utf8")); } catch { return null; }
+  const out = [];
+  for (const field of ["dependencies", "devDependencies"]) {
+    for (const [name, range] of Object.entries(data[field] || {})) {
+      const version = String(range).replace(/^[\^~>=<\s]+/, "");
+      if (/^\d/.test(version)) out.push({ name, version });
+    }
+  }
+  return out;
+}
+
+function collectPackages(root) {
+  return readNpmLock(root) || readManifest(root) || [];
+}
+
+// --- OSV API ----------------------------------------------------------------
+
+async function postJson(url, body) {
+  const res = await fetch(url, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  if (!res.ok) throw new Error(`OSV ${res.status}`);
+  return res.json();
+}
+
+// Map an OSV advisory + the package it hit into a Safeey finding.
+function advisoryToFinding(pkg, vuln, rel) {
+  const sev = severityOf(vuln);
+  const id = vuln.id || (vuln.aliases && vuln.aliases[0]) || "advisory";
+  const summary = vuln.summary || (vuln.details ? vuln.details.slice(0, 140) : "known vulnerability");
+  const fixed = fixedVersion(vuln);
+  return {
+    ruleId: `osv/${id}`,
+    title: `Vulnerable dependency: ${pkg.name}@${pkg.version}`,
+    severity: sev,
+    confidence: "high",
+    category: "dependencies",
+    cwe: (vuln.database_specific && vuln.database_specific.cwe_ids && vuln.database_specific.cwe_ids[0]) || null,
+    owasp: "A06:2021 Vulnerable and Outdated Components",
+    file: rel,
+    line: 0,
+    column: 0,
+    message: `${pkg.name}@${pkg.version} is affected by ${id}: ${summary}`,
+    fix: fixText(pkg, vuln),
+    // Consumed by the auto-fixer (src/fix.js):
+    package: { name: pkg.name, version: pkg.version },
+    fixedVersion: fixed,
+  };
+}
+
+function fixText(pkg, vuln) {
+  const fixed = fixedVersion(vuln);
+  if (fixed) return `Upgrade ${pkg.name} to ${fixed} or later.`;
+  return `Upgrade ${pkg.name} to a patched version (see https://osv.dev/vulnerability/${vuln.id}).`;
+}
+
+function fixedVersion(vuln) {
+  for (const aff of vuln.affected || []) {
+    for (const range of aff.ranges || []) {
+      for (const ev of range.events || []) {
+        if (ev.fixed) return ev.fixed;
+      }
+    }
+  }
+  return null;
+}
+
+// OSV severity is inconsistent across sources; derive a coarse level.
+function severityOf(vuln) {
+  const s = (vuln.database_specific && vuln.database_specific.severity) || "";
+  const t = String(s).toUpperCase();
+  if (t.includes("CRITICAL")) return "critical";
+  if (t.includes("HIGH")) return "high";
+  if (t.includes("MODERATE") || t.includes("MEDIUM")) return "medium";
+  if (t.includes("LOW")) return "low";
+  // CVSS vector present? crude parse of the base score.
+  const cvss = (vuln.severity || []).find((x) => /CVSS/.test(x.type));
+  if (cvss && cvss.score) {
+    const m = /\/AV:/.test(cvss.score) ? null : parseFloat(cvss.score);
+    if (m != null && !Number.isNaN(m)) return m >= 9 ? "critical" : m >= 7 ? "high" : m >= 4 ? "medium" : "low";
+  }
+  return "high"; // default: don't under-report an advisory
+}
+
+// Public entry. Returns { findings, checked, error }.
+async function analyzeDependenciesOSV(root, rel = "package-lock.json") {
+  const pkgs = collectPackages(root);
+  if (pkgs.length === 0) return { findings: [], checked: 0, error: null };
+  if (typeof fetch !== "function") {
+    return { findings: [], checked: 0, error: "global fetch unavailable (needs Node 18+)" };
+  }
+
+  try {
+    // Batch query: returns per-package lists of vuln IDs only.
+    const queries = pkgs.map((p) => ({ version: p.version, package: { name: p.name, ecosystem: "npm" } }));
+    const batch = await postJson(OSV_BATCH_URL, { queries });
+    const results = (batch && batch.results) || [];
+
+    // Collect unique vuln IDs, fetch details once each, then map back.
+    const idToPkgs = new Map();
+    results.forEach((r, i) => {
+      for (const v of (r && r.vulns) || []) {
+        if (!idToPkgs.has(v.id)) idToPkgs.set(v.id, []);
+        idToPkgs.get(v.id).push(pkgs[i]);
+      }
+    });
+
+    const findings = [];
+    for (const [id, affectedPkgs] of idToPkgs) {
+      let detail;
+      try {
+        const res = await fetch(OSV_VULN_URL + id);
+        detail = res.ok ? await res.json() : { id };
+      } catch { detail = { id }; }
+      for (const pkg of affectedPkgs) findings.push(advisoryToFinding(pkg, detail, rel));
+    }
+    return { findings, checked: pkgs.length, error: null };
+  } catch (e) {
+    return { findings: [], checked: pkgs.length, error: e.message };
+  }
+}
+
+module.exports = { analyzeDependenciesOSV, collectPackages, advisoryToFinding, severityOf };

package/src/engine/patterns.js

@@ -4,8 +4,9 @@
 
 const { normalizeAll } = require("../rules/schema");
 const { PATTERN_RULES } = require("../rules/patterns");
+const { FRAMEWORK_RULES } = require("../rules/framework");
 
-const RULES = normalizeAll(PATTERN_RULES, "pattern");
+const RULES = normalizeAll([...PATTERN_RULES, ...FRAMEWORK_RULES], "pattern");
 
 // Map file extension -> language tag used in rule.languages.
 const EXT_LANG = {

package/src/engine/secrets.js

@@ -49,6 +49,37 @@ const GENERIC_SECRET = {
 // Lines we shouldn't flag for the generic rule: placeholders and env references.
 const IGNORE = /(process\.env|import\.meta\.env|os\.environ|getenv|example|placeholder|dummy|your[_-]?(key|token|secret)|xxxx+|<[^>]+>|\$\{|\{\{)/i;
 
+// Shannon entropy in bits/char — high values mark random-looking strings
+// (keys/tokens) rather than natural text or identifiers.
+function shannonEntropy(s) {
+  const freq = {};
+  for (const ch of s) freq[ch] = (freq[ch] || 0) + 1;
+  let e = 0;
+  for (const ch in freq) { const p = freq[ch] / s.length; e -= p * Math.log2(p); }
+  return e;
+}
+
+const ENTROPY_RULE = { id: "secret/high-entropy-string", title: "High-entropy string (possible secret)", severity: "medium", confidence: "low" };
+const KEYLIKE = /^[A-Za-z0-9+/_\-]{20,100}={0,2}$/;
+const WORDY = /^[A-Za-z][a-z]+([A-Z][a-z]+)*$/; // camelCase words — not a key
+
+// Flag quoted string literals that look like a high-entropy secret we didn't
+// already match by provider/name. Conservative and low-confidence by design.
+function entropyFindings(line, file, lineNo) {
+  const out = [];
+  const re = /['"]([^'"\n]{20,100})['"]/g;
+  let m;
+  while ((m = re.exec(line))) {
+    const val = m[1];
+    if (!KEYLIKE.test(val) || WORDY.test(val)) continue;
+    const threshold = /^[0-9a-f]+$/i.test(val) ? 3.2 : 4.0; // hex has lower per-char entropy
+    if (shannonEntropy(val) >= threshold) {
+      out.push(makeFinding({ ...ENTROPY_RULE }, file, lineNo, { 0: val, index: m.index + 1 }));
+    }
+  }
+  return out;
+}
+
 function mask(s) {
   const t = s.replace(/['"]/g, "");
   if (t.length <= 10) return t.slice(0, 3) + "****";
@@ -90,7 +121,12 @@ function analyzeSecrets(code, file) {
 
     if (!matchedProvider) {
       const m = GENERIC_SECRET.re.exec(line);
-      if (m && !IGNORE.test(line)) findings.push(makeFinding(GENERIC_SECRET, file, i + 1, m));
+      if (m && !IGNORE.test(line)) {
+        findings.push(makeFinding(GENERIC_SECRET, file, i + 1, m));
+      } else if (!IGNORE.test(line)) {
+        // Last resort: catch key-shaped high-entropy strings with no tell-tale name.
+        for (const f of entropyFindings(line, file, i + 1)) findings.push(f);
+      }
     }
   }
   return findings;

package/src/engine/suppress.js

@@ -0,0 +1,50 @@
+// src/engine/suppress.js — let users silence findings they've reviewed.
+// Without this, aggressive rules just get the whole tool switched off. Two
+// mechanisms: inline comments in code, and a .safeeyignore file for whole paths.
+
+// Inline:
+//   foo(bar)            // safeey-ignore js/command-injection
+//   // safeey-ignore-next-line js/sql-injection
+//   risky()
+// A bare `safeey-ignore` with no rule id suppresses all findings on that line.
+function fileSuppressions(code) {
+  const map = new Map(); // 1-based line -> Set(ruleId) | Set("*")
+  const lines = code.split(/\r?\n/);
+  lines.forEach((line, i) => {
+    const m = /safeey-ignore(-next-line)?\b[ \t]*([^\n]*)$/.exec(line);
+    if (!m) return;
+    const target = m[1] ? i + 2 : i + 1; // next-line -> the following line
+    const ids = (m[2] || "").trim().split(/[\s,]+/).filter(Boolean);
+    const set = map.get(target) || new Set();
+    if (ids.length === 0) set.add("*");
+    else ids.forEach((id) => set.add(id));
+    map.set(target, set);
+  });
+  return map;
+}
+
+function isSuppressed(map, line, ruleId) {
+  const set = map.get(line);
+  if (!set) return false;
+  return set.has("*") || set.has(ruleId);
+}
+
+// .safeeyignore: one glob-ish path pattern per line (# comments allowed).
+// Supports `*` and `**`; matched against the path relative to the scan root.
+function loadPathIgnores(readFile, rootJoin) {
+  const raw = readFile(rootJoin(".safeeyignore"));
+  if (!raw) return () => false;
+  const res = raw.split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith("#"))
+    .map(globToRe);
+  return (relPath) => res.some((re) => re.test(relPath.replace(/\\/g, "/")));
+}
+
+function globToRe(glob) {
+  let g = glob.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  g = g.replace(/\*\*/g, "\u0000").replace(/\*/g, "[^/]*").replace(/\u0000/g, ".*").replace(/\?/g, "[^/]");
+  return new RegExp(`(^|/)${g}($|/)`);
+}
+
+module.exports = { fileSuppressions, isSuppressed, loadPathIgnores };

package/src/engine/taint.js

@@ -0,0 +1,182 @@
+// src/engine/taint.js — lightweight taint tracking for JS/TS.
+//
+// The pattern/AST rules flag a dangerous *sink* regardless of whether its input
+// is attacker-controlled. Taint tracking asks the better question: does
+// untrusted input actually *reach* this sink? Following a value from source
+// (a request field) to sink (exec, a query, a redirect) both catches real
+// vulnerabilities the flat rules miss (input arrives via a variable) and avoids
+// false positives (exec of a constant is fine).
+//
+// Scope: intraprocedural and best-effort. We resolve variables through Babel's
+// scope bindings, propagate taint across assignments, string-building and common
+// pass-through calls, but we do NOT do interprocedural (cross-function) flow.
+// Findings are therefore high-confidence when they fire, but absence of a
+// finding is not proof of safety. Kept deliberately conservative to stay quiet.
+
+const parser = require("@babel/parser");
+const traverseModule = require("@babel/traverse");
+const traverse = traverseModule.default || traverseModule;
+const { memberName } = require("../rules/helpers");
+
+const PARSE_OPTS = {
+  sourceType: "unmodule",
+  errorRecovery: true,
+  allowReturnOutsideFunction: true,
+  plugins: ["jsx", "typescript", "classProperties", "decorators-legacy", "optionalChaining", "nullishCoalescingOperator"],
+};
+
+// Roots that represent untrusted external input.
+const SOURCE_ROOTS = /^(req|request|ctx)$/;
+// Full member paths that are sources on their own.
+const SOURCE_MEMBERS = /^(req|request)\.(query|params|body|headers|cookies|url|originalUrl|hostname|ip)\b/;
+const DIRECT_SOURCES = /^(process\.argv|location\.(search|hash|href|pathname)|document\.(URL|cookie|referrer)|window\.name)$/;
+
+// Pass-through calls: the result stays tainted if the receiver/args are tainted.
+const PASSTHROUGH = /(^|\.)(trim|toString|toLowerCase|toUpperCase|replace|replaceAll|slice|substring|substr|concat|padStart|padEnd|normalize|split|join|at|charAt|repeat)$/;
+const PASSTHROUGH_FUNCS = /^(String|decodeURIComponent|decodeURI|encodeURIComponent|unescape|escape|Buffer\.from|JSON\.parse)$/;
+
+// Sinks: callee (member) name -> { type, cwe, severity, requiresStringBuild }
+const CALL_SINKS = [
+  { re: /(^|\.)(exec|execSync|spawn|spawnSync|execFile|execFileSync)$/, type: "command-injection", cwe: "CWE-78", severity: "critical", title: "User input reaches a shell/command execution sink" },
+  { re: /^(eval)$/, type: "code-injection", cwe: "CWE-95", severity: "critical", title: "User input reaches eval()" },
+  { re: /(^|\.)(query|execute|raw)$/, type: "sql-injection", cwe: "CWE-89", severity: "high", requiresStringBuild: true, title: "User input is string-built into a SQL query" },
+  { re: /(^|\.)redirect$/, type: "open-redirect", cwe: "CWE-601", severity: "medium", title: "User input reaches an HTTP redirect" },
+  { re: /(^|\.)(readFile|readFileSync|writeFile|writeFileSync|createReadStream|createWriteStream|unlink|unlinkSync|readdir|readdirSync)$/, type: "path-traversal", cwe: "CWE-22", severity: "high", title: "User input reaches a filesystem path" },
+  { re: /(^|\.)(send|write|end)$/, type: "reflected-xss", cwe: "CWE-79", severity: "medium", title: "User input reaches an HTTP response body" },
+];
+
+function rootName(node) {
+  let n = node;
+  while (n && n.type === "MemberExpression") n = n.object;
+  return n && n.type === "Identifier" ? n.name : null;
+}
+
+function isStringBuilt(node) {
+  if (!node) return false;
+  if (node.type === "TemplateLiteral") return node.expressions.length > 0;
+  if (node.type === "BinaryExpression" && node.operator === "+") return true;
+  return false;
+}
+
+// Is `node` tainted within the given scope? `seen` guards against cycles.
+function isTainted(node, scope, seen) {
+  if (!node || typeof node !== "object") return false;
+
+  switch (node.type) {
+    case "MemberExpression": {
+      const full = memberName(node);
+      if (full && (SOURCE_MEMBERS.test(full) || DIRECT_SOURCES.test(full))) return true;
+      const root = rootName(node);
+      if (root && SOURCE_ROOTS.test(root)) return true;
+      // tainted if the object chain or a computed property is tainted
+      if (isTainted(node.object, scope, seen)) return true;
+      if (node.computed && isTainted(node.property, scope, seen)) return true;
+      return false;
+    }
+    case "Identifier": {
+      const full = node.name;
+      if (DIRECT_SOURCES.test(full)) return true;
+      if (SOURCE_ROOTS.test(full)) return true;
+      if (!scope) return false;
+      const binding = scope.getBinding(node.name);
+      if (!binding || seen.has(binding)) return false;
+      seen.add(binding);
+      const p = binding.path;
+      if (p && p.node) {
+        if (p.node.type === "VariableDeclarator" && p.node.init) return isTainted(p.node.init, p.scope || scope, seen);
+        // function param named like a source (e.g. the (req,res) handler param)
+        if ((p.node.type === "Identifier") && SOURCE_ROOTS.test(p.node.name)) return true;
+      }
+      // reassignments
+      for (const ref of binding.constantViolations || []) {
+        if (ref.node && ref.node.type === "AssignmentExpression" && isTainted(ref.node.right, ref.scope || scope, seen)) return true;
+      }
+      return false;
+    }
+    case "TemplateLiteral":
+      return node.expressions.some((e) => isTainted(e, scope, seen));
+    case "BinaryExpression":
+      if (node.operator === "+") return isTainted(node.left, scope, seen) || isTainted(node.right, scope, seen);
+      return false;
+    case "LogicalExpression":
+      return isTainted(node.left, scope, seen) || isTainted(node.right, scope, seen);
+    case "ConditionalExpression":
+      return isTainted(node.consequent, scope, seen) || isTainted(node.alternate, scope, seen);
+    case "CallExpression": {
+      const name = memberName(node.callee) || "";
+      if (PASSTHROUGH_FUNCS.test(name) || PASSTHROUGH.test(name)) {
+        if (node.callee.type === "MemberExpression" && isTainted(node.callee.object, scope, seen)) return true;
+        return node.arguments.some((a) => isTainted(a, scope, seen));
+      }
+      return false;
+    }
+    default:
+      return false;
+  }
+}
+
+function analyzeTaint(code, file) {
+  let ast;
+  try {
+    ast = parser.parse(code, { ...PARSE_OPTS, sourceType: "module" });
+  } catch {
+    try { ast = parser.parse(code, { ...PARSE_OPTS, sourceType: "script" }); } catch { return []; }
+  }
+
+  const findings = [];
+  const pushed = new Set();
+
+  function record(node, sink, argNode) {
+    const line = node.loc ? node.loc.start.line : 0;
+    const col = node.loc ? node.loc.start.column + 1 : 0;
+    const key = `${sink.type}|${line}|${col}`;
+    if (pushed.has(key)) return;
+    pushed.add(key);
+    findings.push({
+      ruleId: `taint/${sink.type}`,
+      title: sink.title,
+      severity: sink.severity,
+      confidence: "high",
+      category: sink.type === "reflected-xss" ? "xss" : sink.type === "open-redirect" ? "auth" : sink.type === "path-traversal" ? "path" : "injection",
+      cwe: sink.cwe,
+      owasp: null,
+      file,
+      line,
+      column: col,
+      message: `${sink.title.replace(/^User input/, "Untrusted input")} — the value flows from a request/external source to this call without sanitisation.`,
+      fix: "Validate or encode the value for its context (parameterised queries, an allow-list for paths/redirects, argument arrays instead of shell strings) before it reaches this sink.",
+    });
+  }
+
+  traverse(ast, {
+    CallExpression(path) {
+      const name = memberName(path.node.callee);
+      if (!name) return;
+      for (const sink of CALL_SINKS) {
+        if (!sink.re.test(name)) continue;
+        const arg = path.node.arguments[0];
+        if (!arg) continue;
+        if (sink.requiresStringBuild && !isStringBuilt(arg)) continue;
+        if (isTainted(arg, path.scope, new Set())) { record(path.node, sink, arg); break; }
+      }
+    },
+    NewExpression(path) {
+      if (memberName(path.node.callee) === "Function") {
+        const arg = path.node.arguments[path.node.arguments.length - 1];
+        if (arg && isTainted(arg, path.scope, new Set())) {
+          record(path.node, { type: "code-injection", cwe: "CWE-95", severity: "critical", title: "User input reaches the Function constructor" }, arg);
+        }
+      }
+    },
+    AssignmentExpression(path) {
+      const left = memberName(path.node.left);
+      if (left && /(^|\.)(innerHTML|outerHTML)$/.test(left) && isTainted(path.node.right, path.scope, new Set())) {
+        record(path.node, { type: "reflected-xss", cwe: "CWE-79", severity: "high", title: "User input is assigned to innerHTML" }, path.node.right);
+      }
+    },
+  });
+
+  return findings;
+}
+
+module.exports = { analyzeTaint };