@clear-capabilities/agentic-security-scanner 0.74.0

package/src/dataflow/path-feasibility.js

@@ -0,0 +1,114 @@
+// Path feasibility — lite version.
+//
+// Real path-sensitive feasibility requires an SMT solver to check whether a
+// path's accumulated constraints are satisfiable. This module does the cheap
+// version: constant-fold simple boolean conditions and prune obviously
+// infeasible CFG edges before the taint engine walks them.
+//
+// Patterns we catch:
+//   if (false)                     — consequent unreachable
+//   if (true)                      — alternate unreachable
+//   if (process.env.NODE_ENV === 'production')   — alternate unreachable in prod
+//   if (typeof x === 'string')      — both branches reachable but tagged
+//   if (x === x)                    — alternate unreachable
+//
+// Patterns deliberately deferred (would need SMT or symbolic execution):
+//   - Comparisons of unrelated variables
+//   - Comparisons involving function call return values
+//   - Aliasing-aware constraint propagation
+//
+// Output: mutates the CFG node's `succ` array to drop unreachable edges. The
+// existing taint engine then never walks them. Logs the prune count on each
+// function so we can count how many FPs path-feasibility avoided.
+
+function evalConst(expr) {
+  if (!expr) return undefined;
+  switch (expr.kind) {
+    case 'literal': return expr.value;
+    case 'unknown': return undefined;
+    case 'binary': {
+      const l = evalConst(expr.left);
+      const r = evalConst(expr.right);
+      if (l === undefined || r === undefined) return undefined;
+      switch (expr.op) {
+        case '===': return l === r;
+        case '!==': return l !== r;
+        case '==':  return l == r;
+        case '!=':  return l != r;
+        case '<':   return l < r;
+        case '<=':  return l <= r;
+        case '>':   return l > r;
+        case '>=':  return l >= r;
+        case '+':   return l + r;
+        case '-':   return l - r;
+        case '*':   return l * r;
+        case '/':   return l / r;
+      }
+      return undefined;
+    }
+    case 'logical': {
+      const l = evalConst(expr.left);
+      if (l === undefined) return undefined;
+      if (expr.op === '&&') return l ? evalConst(expr.right) : l;
+      if (expr.op === '||') return l ? l : evalConst(expr.right);
+      return undefined;
+    }
+    case 'ident': {
+      // Some idents are well-known true/false (e.g. constants we've folded).
+      if (expr.name === 'undefined') return undefined;
+      return undefined;
+    }
+    case 'member': {
+      // x === x style: the engine can't fold this without symbolic equality.
+      return undefined;
+    }
+  }
+  return undefined;
+}
+
+// True iff `a` and `b` reference the same variable in obviously the same way.
+function syntacticallyEqual(a, b) {
+  if (!a || !b) return false;
+  if (a.kind !== b.kind) return false;
+  if (a.kind === 'ident') return a.name === b.name;
+  if (a.kind === 'member') {
+    return a.prop === b.prop && syntacticallyEqual(a.object, b.object);
+  }
+  return false;
+}
+
+export function applyPathFeasibility(fn) {
+  if (!fn || !fn.cfg || !fn.cfg.nodes) return { pruned: 0 };
+  let pruned = 0;
+  for (const id of Object.keys(fn.cfg.nodes)) {
+    const node = fn.cfg.nodes[id];
+    if (!node || node.kind !== 'if') continue;
+    const cond = node.cond;
+    if (!cond) continue;
+    // Constant cond?
+    const val = evalConst(cond);
+    if (val === true) {
+      // Drop the second successor (the false branch).
+      if (node.succ.length > 1) {
+        node.succ.splice(1, node.succ.length - 1);
+        pruned++;
+      }
+    } else if (val === false) {
+      // Drop the first successor (the true branch).
+      if (node.succ.length > 0) {
+        node.succ.splice(0, 1);
+        pruned++;
+      }
+    } else if (cond.kind === 'binary' && (cond.op === '===' || cond.op === '!==') &&
+               syntacticallyEqual(cond.left, cond.right)) {
+      // `x === x` → always true. `x !== x` → always false (except NaN, which
+      // we accept the FP risk on — vanishingly rare in real code).
+      if (cond.op === '===') {
+        if (node.succ.length > 1) { node.succ.splice(1); pruned++; }
+      } else {
+        if (node.succ.length > 0) { node.succ.splice(0, 1); pruned++; }
+      }
+    }
+  }
+  return { pruned };
+}

package/src/dataflow/points-to.js

@@ -0,0 +1,337 @@
+// Steensgaard points-to / alias analysis (v0.70 #2).
+//
+// Unification-based, near-linear pointer analysis. The classical reference
+// is Steensgaard, "Points-to analysis in almost linear time" (POPL'96).
+//
+// The idea: every program variable belongs to an equivalence class. Two
+// variables in the same class point to the same set of abstract heap
+// locations. When the analysis sees:
+//
+//   a = b        → unify class(a) with class(b)
+//   a.f = c      → for the abstract object class(a) points to, its `f`-slot
+//                  is unified with class(c)
+//   x = a.f      → reverse: class(x) unifies with the `f`-slot of what a
+//                  points to
+//   a = new T()  → fresh abstract location L; class(a) points to L
+//
+// In Steensgaard, every step is a UNION, never a copy. This gives O(n α(n))
+// time but loses some precision: `a = b; a = c` unifies class(b) and class(c)
+// even though they were never directly compared. Worth the speed; the
+// alternative (Andersen, inclusion-based) is cubic.
+//
+// We use it for ONE specific purpose: at taint-time, when checking whether
+// a variable name `x` is in the tainted state, also check every alias of
+// `x` per the points-to graph. A taint propagated through one alias is
+// visible through all of them.
+//
+// Out of scope for v1:
+//   - Heap snapshots (we don't model allocation freshness)
+//   - Context-sensitivity (one graph per function; merged at call sites
+//     via parameter unification)
+//   - Containers (arrays, maps) — modelled as single abstract objects
+//   - Reflection / dynamic dispatch
+//
+// Wiring: AGENTIC_SECURITY_POINTS_TO=1 in dataflow/index.js builds the
+// graph before runTaintEngine. The engine reads `opts._pointsTo` and
+// consults `aliasesOf(x)` inside exprTaint and the assign transfer.
+
+// ─── Union-Find ──────────────────────────────────────────────────────────
+
+class UnionFind {
+  constructor() {
+    this.parent = new Map();   // name → name (canonical rep)
+    this.rank = new Map();     // canonical rep → tree depth
+  }
+  // Ensure `x` has a node. Idempotent.
+  add(x) {
+    if (!this.parent.has(x)) {
+      this.parent.set(x, x);
+      this.rank.set(x, 0);
+    }
+  }
+  // Find canonical rep of `x` with path compression.
+  find(x) {
+    this.add(x);
+    let cur = x;
+    while (this.parent.get(cur) !== cur) cur = this.parent.get(cur);
+    // Path compression — point every visited node directly to the root.
+    let next = x;
+    while (this.parent.get(next) !== cur) {
+      const p = this.parent.get(next);
+      this.parent.set(next, cur);
+      next = p;
+    }
+    return cur;
+  }
+  // Union the classes of `a` and `b`. Returns the new canonical rep.
+  union(a, b) {
+    const ra = this.find(a);
+    const rb = this.find(b);
+    if (ra === rb) return ra;
+    const ranka = this.rank.get(ra);
+    const rankb = this.rank.get(rb);
+    let winner, loser;
+    if (ranka < rankb) { winner = rb; loser = ra; }
+    else if (ranka > rankb) { winner = ra; loser = rb; }
+    else { winner = ra; loser = rb; this.rank.set(winner, ranka + 1); }
+    this.parent.set(loser, winner);
+    return winner;
+  }
+  // Every name registered with the union-find.
+  members() { return [...this.parent.keys()]; }
+  // Map of canonical-rep → list of members.
+  classes() {
+    const out = new Map();
+    for (const x of this.parent.keys()) {
+      const r = this.find(x);
+      if (!out.has(r)) out.set(r, []);
+      out.get(r).push(x);
+    }
+    return out;
+  }
+}
+
+// ─── PointsToGraph ───────────────────────────────────────────────────────
+
+export class PointsToGraph {
+  constructor() {
+    this.uf = new UnionFind();
+    // For each class, the abstract object it points to (also a class id).
+    // Steensgaard's "pending" / lazy-unify trick: when two classes both have
+    // distinct pointees, those pointees must themselves be unified.
+    this.pointee = new Map();    // classId → classId (its pointee)
+    // For each pointee-class, a per-field map of field-pointees.
+    this.fields = new Map();     // pointeeId → Map<fieldName, classId>
+  }
+
+  _ensure(name) {
+    this.uf.add(name);
+    return this.uf.find(name);
+  }
+
+  // a = b  (or a = b's value flows into a)
+  unify(a, b) {
+    const ra = this._ensure(a);
+    const rb = this._ensure(b);
+    this._unifyClasses(ra, rb);
+  }
+
+  _unifyClasses(ra, rb) {
+    if (ra === rb) return ra;
+    const merged = this.uf.union(ra, rb);
+    const other = merged === ra ? rb : ra;
+    // If both classes had a pointee, unify the pointees.
+    const pa = this.pointee.get(ra);
+    const pb = this.pointee.get(rb);
+    this.pointee.delete(other);
+    if (pa && pb) {
+      this.pointee.set(merged, this._unifyClasses(pa, pb));
+    } else if (pa || pb) {
+      this.pointee.set(merged, pa || pb);
+    }
+    // Same for field maps.
+    const fa = this.fields.get(ra);
+    const fb = this.fields.get(rb);
+    this.fields.delete(other);
+    if (fa && fb) {
+      const merged_f = new Map(fa);
+      for (const [k, v] of fb) {
+        if (merged_f.has(k)) merged_f.set(k, this._unifyClasses(merged_f.get(k), v));
+        else merged_f.set(k, v);
+      }
+      this.fields.set(merged, merged_f);
+    } else if (fa || fb) {
+      this.fields.set(merged, fa || fb);
+    }
+    return merged;
+  }
+
+  // a = new ... → bind `a` to a fresh pointee class
+  alloc(a, locationId) {
+    const ra = this._ensure(a);
+    const loc = `__loc:${locationId}`;
+    this._ensure(loc);
+    const existing = this.pointee.get(ra);
+    if (existing) this._unifyClasses(existing, this.uf.find(loc));
+    else this.pointee.set(ra, this.uf.find(loc));
+  }
+
+  // a.f = c
+  fieldStore(a, field, c) {
+    const ra = this._ensure(a);
+    const rc = this._ensure(c);
+    // Get the pointee class of `a`; if absent, create a virtual one.
+    let pa = this.pointee.get(ra);
+    if (!pa) {
+      pa = `__virt:${ra}`;
+      this._ensure(pa);
+      this.pointee.set(ra, this.uf.find(pa));
+      pa = this.uf.find(pa);
+    }
+    if (!this.fields.has(pa)) this.fields.set(pa, new Map());
+    const fmap = this.fields.get(pa);
+    if (fmap.has(field)) {
+      // Unify the existing field-pointee with rc.
+      this._unifyClasses(fmap.get(field), rc);
+    } else {
+      fmap.set(field, rc);
+    }
+  }
+
+  // x = a.f
+  fieldLoad(x, a, field) {
+    const rx = this._ensure(x);
+    const ra = this._ensure(a);
+    // Get or create pointee of `a`.
+    let pa = this.pointee.get(ra);
+    if (!pa) {
+      pa = `__virt:${ra}`;
+      this._ensure(pa);
+      this.pointee.set(ra, this.uf.find(pa));
+      pa = this.uf.find(pa);
+    }
+    // Get or create the field-pointee.
+    if (!this.fields.has(pa)) this.fields.set(pa, new Map());
+    const fmap = this.fields.get(pa);
+    if (fmap.has(field)) {
+      this._unifyClasses(fmap.get(field), rx);
+    } else {
+      fmap.set(field, rx);
+    }
+  }
+
+  // Return all variable names in the same equivalence class as `name`,
+  // INCLUDING `name` itself.
+  aliasesOf(name) {
+    if (!this.uf.parent.has(name)) return [name];
+    const root = this.uf.find(name);
+    // O(n) scan — for v1, fine; v2 would index class→members on each union.
+    const out = [];
+    for (const v of this.uf.parent.keys()) {
+      if (this.uf.find(v) === root) out.push(v);
+    }
+    return out;
+  }
+
+  // Diagnostic snapshot.
+  snapshot() {
+    return {
+      classes: [...this.uf.classes()].map(([root, members]) => ({ root, members })),
+      pointees: [...this.pointee].map(([k, v]) => ({ class: k, points: v })),
+      fields: [...this.fields].map(([k, m]) => ({ class: k, fields: [...m] })),
+    };
+  }
+}
+
+// ─── Build the graph from an IR universe ─────────────────────────────────
+
+/**
+ * Walk every function in the call graph and feed assign/call nodes into
+ * the PointsToGraph. Returns the populated graph.
+ *
+ * Naming convention for the union-find:
+ *   - Local variable `x` in function `qid` is named `qid::x`.
+ *   - Global / unresolved references are named `::<name>`.
+ *   - Allocation sites are named `__loc:<qid>:<line>`.
+ */
+export function buildPointsTo(perFileIR, callGraph) {
+  const g = new PointsToGraph();
+  if (!callGraph || !callGraph.functions) return g;
+  for (const fn of callGraph.functions.values()) {
+    _processFunction(fn, g);
+  }
+  // Interprocedural step: at every resolved call site, unify caller-arg
+  // names with callee-param names. This makes parameter aliasing visible.
+  for (const fn of callGraph.functions.values()) {
+    if (!fn.cfg || !fn.cfg.nodes) continue;
+    for (const nid of Object.keys(fn.cfg.nodes)) {
+      const node = fn.cfg.nodes[nid];
+      if (!node || node.kind !== 'call') continue;
+      const resolved = callGraph.resolve ? callGraph.resolve(node.callee) : null;
+      const target = resolved && resolved.qid ? resolved : null;
+      if (!target || !Array.isArray(target.params)) continue;
+      const args = node.args || [];
+      for (let i = 0; i < target.params.length && i < args.length; i++) {
+        const argName = _nameForExpr(fn.qid, args[i]);
+        if (!argName) continue;
+        g.unify(argName, `${target.qid}::${target.params[i]}`);
+      }
+    }
+  }
+  return g;
+}
+
+function _processFunction(fn, g) {
+  if (!fn || !fn.cfg || !fn.cfg.nodes) return;
+  for (const nid of Object.keys(fn.cfg.nodes)) {
+    const node = fn.cfg.nodes[nid];
+    if (!node) continue;
+    if (node.kind === 'assign') _processAssign(fn, node, g);
+  }
+}
+
+function _processAssign(fn, node, g) {
+  const target = typeof node.target === 'string' ? node.target : null;
+  if (!target) return;
+  const tgtName = `${fn.qid}::${target}`;
+  const src = node.source;
+  if (!src) return;
+  // x = y
+  if (src.kind === 'ident' && typeof src.name === 'string') {
+    g.unify(tgtName, `${fn.qid}::${src.name}`);
+    return;
+  }
+  // x = y.f
+  if (src.kind === 'member' && src.object && src.object.kind === 'ident' && typeof src.prop === 'string') {
+    g.fieldLoad(tgtName, `${fn.qid}::${src.object.name}`, src.prop);
+    return;
+  }
+  // x = new T()  / x = {} / x = []
+  if (src.kind === 'object' || src.kind === 'array') {
+    g.alloc(tgtName, `${fn.qid}:${node.line || 0}`);
+    return;
+  }
+  if (src.kind === 'call' && typeof src.callee === 'string' && /^new\s+/.test(src.callee)) {
+    g.alloc(tgtName, `${fn.qid}:${node.line || 0}`);
+    return;
+  }
+  // Member-store: x.f = y handled by the `assign` whose TARGET is a string
+  // path like "x.f". Our IR may emit `target: 'x.f'`; handle that.
+  if (target.includes('.') && src.kind === 'ident') {
+    const [recv, ...rest] = target.split('.');
+    if (recv && rest.length === 1) {
+      g.fieldStore(`${fn.qid}::${recv}`, rest[0], `${fn.qid}::${src.name}`);
+      return;
+    }
+  }
+}
+
+function _nameForExpr(qid, expr) {
+  if (!expr) return null;
+  if (expr.kind === 'ident' && typeof expr.name === 'string') return `${qid}::${expr.name}`;
+  return null;
+}
+
+// ─── Engine consumption helpers ──────────────────────────────────────────
+
+/**
+ * Given a points-to graph and a function qid + variable name, return all
+ * known aliases (full qid-prefixed names) that the engine should also
+ * check against the taint state.
+ */
+export function aliasesForVar(pointsTo, qid, varName) {
+  if (!pointsTo || !pointsTo.aliasesOf) return [varName];
+  const fullName = `${qid}::${varName}`;
+  const aliases = pointsTo.aliasesOf(fullName);
+  const out = new Set([varName]);
+  for (const a of aliases) {
+    // Strip the qid prefix for engine-state lookups (engine state is per-fn).
+    const idx = a.indexOf('::');
+    if (idx > 0) {
+      const local = a.slice(idx + 2);
+      // Skip __loc: / __virt: synthetic names.
+      if (local && !local.startsWith('__')) out.add(local);
+    }
+  }
+  return [...out];
+}

package/src/dataflow/polyglot.js

@@ -0,0 +1,190 @@
+// Polyglot embedded-language taint (P4.7).
+//
+// Strings embedded inside one language often carry a second language that
+// has its own sinks. The classic example: a SQL string literal inside Java
+// is technically just a String to Java, but it's a SQL statement to the DB.
+// If a tainted value is concatenated into it BEFORE handing to .executeQuery,
+// it's a SQL injection — even if no obvious sink shape is matched.
+//
+// Embeddings we recognize:
+//   - SQL          inside Java / C# / Python / Go / Node strings
+//   - HTML         inside JS template literals + .innerHTML/.outerHTML lhs
+//   - JavaScript   inside HTML <script>, inline `on*` attrs, javascript: URIs
+//   - Shell        inside .exec/.execSync/.spawn strings (existing sink)
+//   - Regex        inside .new RegExp(<concat>) — REDoS surface
+//   - CSS          inside style="..." HTML attrs, .style.cssText assignments
+//   - JSON-as-code inside eval/Function constructors
+//   - LDAP         inside .search(filter:) calls
+//   - XPath        inside .evaluate(expr:) calls
+//   - Mongo $where inside aggregate / find expressions
+//   - JNDI         inside lookup() / context.lookup() strings (Log4Shell shape)
+//
+// This module's job is to RECOGNIZE the embedded language inside a string
+// expression and tell the engine "this string is actually X — apply X's
+// sink rules to any concatenation/template-hole inside it." It does NOT
+// re-parse the embedded grammar; the heuristic is shape-based, with a
+// confidence score so the engine can demote weak matches.
+//
+// Public API:
+//   identifyEmbedding(strValue)       → { lang, confidence, evidence }
+//   findInterpolationHoles(strNode)   → [{ index, expr }] for template literals
+//   shouldFlagPolyglot(lang, holeExpr, holeTainted)
+//                                     → boolean — should we emit a finding?
+
+/** SQL recognition — keyword + structure. */
+const SQL_KEYWORDS = /\b(SELECT|INSERT|UPDATE|DELETE|UPSERT|MERGE|CREATE|DROP|ALTER|TRUNCATE|GRANT|REVOKE)\b/i;
+const SQL_CLAUSE   = /\b(FROM|WHERE|JOIN|UNION|ORDER\s+BY|GROUP\s+BY|HAVING|LIMIT|OFFSET|INTO|SET|VALUES)\b/i;
+
+/** HTML recognition. */
+const HTML_TAG     = /<\/?\s*[a-zA-Z][a-zA-Z0-9-]*(\s[^>]*)?>/;
+const HTML_ENTITY  = /&(?:lt|gt|amp|quot|apos|nbsp|#\d+);/;
+
+/** JS recognition (inside HTML or eval). */
+const JS_KEYWORDS  = /\b(function|var|let|const|return|new\s+\w+|console\.|document\.|window\.|=>)\b/;
+
+/** Shell — common command words at start, after whitespace. */
+const SHELL_CMD    = /(^|;|\|\||&&|\|)\s*(cat|ls|rm|cp|mv|chmod|chown|curl|wget|bash|sh|sudo|tar|grep|sed|awk|find|kill|ps|netstat|ip|iptables|nc|ssh|scp)\b/;
+
+/** LDAP filter shape. */
+const LDAP_FILTER  = /\(\s*[a-zA-Z]+\s*=\s*[^)]+\)/;
+
+/** XPath shape. */
+const XPATH_SHAPE  = /\/\/?[a-zA-Z*][a-zA-Z0-9_-]*(\[.*?\])?(\/|$)/;
+
+/** JNDI / JNDI lookup pattern. */
+const JNDI_PATTERN = /\$\{(jndi|ldap|rmi|dns):/i;
+
+/** Mongo $where as JS expression. */
+const MONGO_WHERE  = /this\.\w+\s*[=<>!]/;
+
+/** CSS — property:value pairs. */
+const CSS_PROP     = /^[^{}]*\{?\s*[a-zA-Z-]+\s*:\s*[^;]+;?/;
+
+/**
+ * Identify the embedded language of a string value (the literal text of
+ * a string literal or the concatenation skeleton of a template). Returns
+ * { lang, confidence: 0..1, evidence: [matchedPattern, ...] }.
+ *
+ * lang values:
+ *   'sql' | 'html' | 'js' | 'shell' | 'ldap' | 'xpath' | 'jndi' |
+ *   'mongo' | 'css' | 'regex' | 'none'
+ */
+export function identifyEmbedding(strValue) {
+  if (typeof strValue !== 'string' || !strValue) return { lang: 'none', confidence: 0, evidence: [] };
+  const s = strValue;
+  const evidence = [];
+  let lang = 'none';
+  let confidence = 0;
+
+  // JNDI first — single pattern, very high signal.
+  if (JNDI_PATTERN.test(s)) {
+    return { lang: 'jndi', confidence: 1.0, evidence: ['jndi:lookup pattern'] };
+  }
+
+  if (SQL_KEYWORDS.test(s) && SQL_CLAUSE.test(s)) {
+    evidence.push('sql-keyword+clause');
+    return { lang: 'sql', confidence: 0.95, evidence };
+  }
+  if (SQL_KEYWORDS.test(s)) {
+    evidence.push('sql-keyword');
+    confidence = 0.6; lang = 'sql';
+  }
+
+  if (HTML_TAG.test(s) && (HTML_ENTITY.test(s) || s.includes('</'))) {
+    return { lang: 'html', confidence: 0.9, evidence: ['html-tag+entity/closer'] };
+  }
+  if (HTML_TAG.test(s) && lang === 'none') {
+    evidence.push('html-tag');
+    lang = 'html'; confidence = 0.6;
+  }
+
+  if (lang === 'html' && JS_KEYWORDS.test(s) && /<script\b/i.test(s)) {
+    // HTML embedding JS — call it HTML (the host); but flag js-in-html
+    // separately via shouldFlagPolyglot.
+    evidence.push('script-block');
+    confidence = Math.max(confidence, 0.85);
+  }
+
+  if (SHELL_CMD.test(s)) {
+    return { lang: 'shell', confidence: 0.7, evidence: ['shell-builtin'] };
+  }
+  if (LDAP_FILTER.test(s) && /\(\|/.test(s)) {
+    return { lang: 'ldap', confidence: 0.85, evidence: ['ldap-filter+or'] };
+  }
+  if (LDAP_FILTER.test(s) && lang === 'none') {
+    evidence.push('ldap-filter');
+    lang = 'ldap'; confidence = 0.5;
+  }
+  if (XPATH_SHAPE.test(s) && lang === 'none') {
+    evidence.push('xpath-shape');
+    lang = 'xpath'; confidence = 0.6;
+  }
+  if (MONGO_WHERE.test(s) && lang === 'none') {
+    return { lang: 'mongo', confidence: 0.7, evidence: ['mongo-where'] };
+  }
+  if (CSS_PROP.test(s) && /[a-z-]+:[^;]+;/.test(s) && lang === 'none') {
+    evidence.push('css-prop');
+    lang = 'css'; confidence = 0.45;
+  }
+  return { lang, confidence, evidence };
+}
+
+/**
+ * For a template literal AST node, return the array of interpolation holes
+ * with their `index` (position among quasis) and `expr` (AST subtree).
+ *
+ * Expected shape: { kind: 'template', quasis: [string,...], expressions: [expr,...] }
+ */
+export function findInterpolationHoles(strNode) {
+  if (!strNode || strNode.kind !== 'template') return [];
+  const exprs = strNode.expressions || [];
+  return exprs.map((e, i) => ({ index: i, expr: e }));
+}
+
+/** Stitch a template literal into its skeleton string (placeholders blanked). */
+export function templateSkeleton(strNode) {
+  if (!strNode || strNode.kind !== 'template') {
+    if (strNode && strNode.kind === 'literal' && typeof strNode.value === 'string') return strNode.value;
+    return '';
+  }
+  const qs = strNode.quasis || [];
+  // Stitch with a sentinel that won't confuse the recognizers.
+  return qs.join(' __HOLE__ ');
+}
+
+/**
+ * Decide whether an interpolation hole in an embedded-language string
+ * should fire a polyglot finding. The engine calls this after identifying
+ * the host string and checking which holes are tainted.
+ */
+export function shouldFlagPolyglot(lang, hole, holeTainted, opts = {}) {
+  if (!holeTainted) return false;
+  if (!lang || lang === 'none') return false;
+  // Some embeddings are always sensitive when tainted.
+  const sensitive = new Set(['sql', 'shell', 'jndi', 'ldap', 'xpath', 'mongo', 'js']);
+  if (sensitive.has(lang)) return true;
+  // For HTML, only flag if the hole appears in an attribute or script context.
+  // We don't have positional info here; defer to engine context.
+  if (lang === 'html') return !!opts.inAttribute || !!opts.inScript;
+  if (lang === 'css')  return !!opts.inExpression || !!opts.inUrlFn;
+  return true;
+}
+
+/**
+ * Map a recognized embedded language to a finding family / CWE for emission.
+ */
+export function embeddingToCwe(lang) {
+  switch (lang) {
+    case 'sql':   return { family: 'sql-injection',        cwe: 'CWE-89'  };
+    case 'shell': return { family: 'command-injection',    cwe: 'CWE-78'  };
+    case 'html':  return { family: 'xss',                  cwe: 'CWE-79'  };
+    case 'js':    return { family: 'xss-script',           cwe: 'CWE-79'  };
+    case 'ldap':  return { family: 'ldap-injection',       cwe: 'CWE-90'  };
+    case 'xpath': return { family: 'xpath-injection',      cwe: 'CWE-643' };
+    case 'mongo': return { family: 'nosql-injection',      cwe: 'CWE-943' };
+    case 'jndi':  return { family: 'jndi-injection',       cwe: 'CWE-1188'};
+    case 'css':   return { family: 'css-injection',        cwe: 'CWE-79'  };
+    case 'regex': return { family: 'redos',                cwe: 'CWE-1333'};
+    default:      return null;
+  }
+}