@clear-capabilities/agentic-security-scanner 0.77.0 → 0.79.0

package/src/dataflow/engine.js

@@ -38,6 +38,7 @@ import { accessPathOf, isCoveredBy, addPath, removePathAndDescendants, joinSets
 import { aliasesForVar } from './points-to.js';
 import { higherOrderTaintFlow } from './higher-order.js';
 import { SummaryCache, entryStateFromCall } from './summaries.js';
+import { lookupBuiltinSummary } from './builtin-summaries.js';
 
 // v0.70 #2 — addPath that also taints every alias of the variable.
 // When `target` is a dotted path like "a.x" and the root `a` has aliases
@@ -61,13 +62,13 @@ function _addPathAliasAware(state, path, callContext) {
   return s;
 }
 
+let _activeConstantVars = null;
+
 function exprTaint(expr, state) {
-  // Returns true iff this expression evaluates to a tainted value under the
-  // given taint state. ALSO treats catalog-registered source patterns as
-  // tainted at-read — `req.body.host` used inline (no intermediate local)
-  // is tainted because the source resolves at the read site.
   if (expr && expr.kind === 'member' && exprIsSource(expr)) return true;
   if (!expr) return false;
+  // Constant propagation: variables assigned from literals are never tainted
+  if (expr.kind === 'ident' && _activeConstantVars && _activeConstantVars.has(expr.name)) return false;
   // P1.1 — field-sensitive access path: if the expression is a pure
   // ident/member chain ("x.y.z"), ask the access-path lattice whether any
   // shorter prefix in the state covers it. This is what makes
@@ -156,13 +157,35 @@ function exprIsSource(expr) {
     const hit = matchSource(expr);
     if (hit) return hit;
   }
-  // Recurse — `req.body.name` should still find `req.body` as source.
   if (expr.kind === 'member' && expr.object) {
     return exprIsSource(expr.object);
   }
   return null;
 }
 
+const _SQL_KEYWORDS = /\b(SELECT|INSERT|UPDATE|DELETE|DROP|ALTER|CREATE|UNION|WHERE|FROM|JOIN|INTO|VALUES|SET|EXEC|EXECUTE)\b/i;
+const _HTML_META = /[<>'"&]|innerHTML|outerHTML|document\.write/;
+const _SHELL_META = /[;|`$(){}]|&&|\|\|/;
+
+function _literalPartsOfExpr(expr) {
+  if (!expr) return [];
+  if (expr.kind === 'literal') return [String(expr.value || '')];
+  if (expr.kind === 'tpl') return (expr.parts || []).filter(p => p.kind === 'literal').map(p => String(p.value || ''));
+  if (expr.kind === 'binary') return [..._literalPartsOfExpr(expr.left), ..._literalPartsOfExpr(expr.right)];
+  return [];
+}
+
+function literalSkeletonMatchesFamily(expr, cwe) {
+  const literals = _literalPartsOfExpr(expr);
+  if (!literals.length) return true;
+  const joined = literals.join(' ');
+  if (!joined.trim()) return true;
+  if (cwe === 'CWE-89' || cwe === 'CWE-943') return _SQL_KEYWORDS.test(joined);
+  if (cwe === 'CWE-79') return _HTML_META.test(joined);
+  if (cwe === 'CWE-78') return _SHELL_META.test(joined);
+  return true;
+}
+
 // Apply a CFG node to a taint-state. Returns the new state + any finding emitted.
 function step(node, stateIn, callContext) {
   const state = new Set(stateIn);
@@ -176,9 +199,13 @@ function step(node, stateIn, callContext) {
       return { state, findings };
 
     case 'assign': {
-      // Source detection on RHS.
       const src = exprIsSource(node.source);
       const target = typeof node.target === 'string' ? node.target : null;
+      // Constant propagation: track variables assigned from literals
+      if (target && _activeConstantVars) {
+        if (node.source && node.source.kind === 'literal') _activeConstantVars.set(target, node.source.value);
+        else _activeConstantVars.delete(target);
+      }
       let newState = state;
       // Premortem #7: interprocedural return-taint via SummaryCache. If the
       // RHS is a call to a known callee whose empty-entry-state summary says
@@ -242,6 +269,25 @@ function step(node, stateIn, callContext) {
             for (const v of mutated.mutated) newState = addPath(newState, v);
           }
           if (sum && sum.returnTainted) return { state: newState, findings: [] };
+        } else if (target && calleeName) {
+          // Fallback: check builtin summaries for unresolved external calls
+          const builtin = lookupBuiltinSummary(calleeName);
+          if (builtin) {
+            if (builtin.returnTainted && (node.source.args || []).some(a => exprTaint(a, newState))) {
+              newState = _addPathAliasAware(newState, target, callContext);
+            } else if (!builtin.returnTainted) {
+              newState = removePathAndDescendants(newState, target);
+              return { state: newState, findings: [] };
+            }
+            if (builtin.mutatedParams && builtin.mutatedParams.size) {
+              for (const idx of builtin.mutatedParams) {
+                const argExpr = (node.source.args || [])[parseInt(idx)];
+                if (argExpr && argExpr.kind === 'ident' && (node.source.args || []).some(a => exprTaint(a, newState))) {
+                  newState = _addPathAliasAware(newState, argExpr.name, callContext);
+                }
+              }
+            }
+          }
         }
       }
       if (src && target) {
@@ -293,6 +339,24 @@ function step(node, stateIn, callContext) {
           }
         }
       }
+      // Built-in mutation functions: Object.assign(target, ...sources),
+      // _.merge(target, ...sources), etc. When any source arg is tainted,
+      // taint the target in the caller's scope.
+      const calleeName = typeof node.callee === 'string' ? node.callee : null;
+      if (calleeName && /^(?:Object\.assign|_\.merge|_\.extend|_\.defaultsDeep|_\.defaults|Object\.defineProperties?)$/.test(calleeName)) {
+        const targetArg = (node.args || [])[0];
+        const sourceArgsTainted = argTaints.slice(1).some(Boolean);
+        if (targetArg && targetArg.kind === 'ident' && sourceArgsTainted) {
+          state = _addPathAliasAware(state, targetArg.name, callContext);
+          callContext._taintSources.push({
+            varName: targetArg.name,
+            sourceId: `builtin-mutation:${calleeName}`,
+            sourceLabel: `${calleeName} mutation`,
+            provenance: 'mutation',
+            line: node.line,
+          });
+        }
+      }
       if (cat) {
         for (const e of cat) {
           if (e.kind === 'sink' && (
@@ -302,6 +366,8 @@ function step(node, stateIn, callContext) {
             const taintedArgIdx = e.argIndex === 'all'
               ? argTaints.findIndex(Boolean) : e.argIndex;
             const taintedArgExpr = (node.args || [])[taintedArgIdx];
+            // String content analysis: skip if literal skeleton doesn't match injection family
+            if (e.vuln && taintedArgExpr && !literalSkeletonMatchesFamily(taintedArgExpr, e.vuln.cwe)) continue;
             // Premortem #10: attribute the source for THIS sink to the
             // source(s) that taint the actual argument expression — not the
             // first source the worklist happened to record. We walk the
@@ -400,12 +466,13 @@ function step(node, stateIn, callContext) {
 // every 100 iterations. A pathological CFG (large generated file with dense
 // control flow) can otherwise hold past the global timeout.
 function analyzeFunction(fn, entryState, callContext) {
-  const nodes = fn.cfg.nodes; // plain object
+  const nodes = fn.cfg.nodes;
   const work = [];
-  const inStates = new Map(); // nodeId → Set<varName>
+  const inStates = new Map();
   const outStates = new Map();
   inStates.set(fn.cfg.entry, new Set(entryState));
   work.push(fn.cfg.entry);
+  _activeConstantVars = new Map();
   // v0.70 #2 — points-to context for the step() transfer. Setting it here
   // (instead of plumbing through step's signature) keeps the worklist loop
   // unchanged and lets `step` consult `aliasesForVar` when callContext._pointsTo
@@ -535,6 +602,64 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
     if (summaryCache.size() === prevCacheSize) break;
     prevCacheSize = summaryCache.size();
   }
+  // Class-field cross-taint pass: when a method writes tainted data to _this_.field,
+  // re-analyze other methods of the same class with those fields in the entry state.
+  const classTaintedFields = new Map();
+  for (const fn of fnList) {
+    if (Date.now() > deadlineMs) break;
+    const sum = summaryCache.get(fn.qid, new Set());
+    if (!sum || !sum.mutatedParams) continue;
+    for (const p of sum.mutatedParams) {
+      if (typeof p === 'string' && p.startsWith('_this_.')) {
+        const classPrefix = fn.qid.split('::')[0] + '::';
+        if (!classTaintedFields.has(classPrefix)) classTaintedFields.set(classPrefix, new Set());
+        classTaintedFields.get(classPrefix).add(p);
+      }
+    }
+  }
+  for (const [classPrefix, fields] of classTaintedFields) {
+    if (Date.now() > deadlineMs) break;
+    for (const fn of fnList) {
+      if (!fn.qid.startsWith(classPrefix)) continue;
+      if (summaryCache.has(fn.qid, fields)) continue;
+      const ctx = {
+        _findings: [], _taintSources: [], _returnTainted: false,
+        _stack: new Set(), deadlineMs,
+        _summaryCache: summaryCache, _callGraph: callGraph,
+        _mutatedParamsOut: new Set(),
+      };
+      try { analyzeFunction(fn, fields, ctx); } catch {}
+      summaryCache.set(fn.qid, fields, {
+        returnTainted: !!ctx._returnTainted,
+        mutatedParams: ctx._mutatedParamsOut || new Set(),
+        taintedGlobals: new Set(),
+        findings: [],
+      });
+    }
+  }
+
+  // k=2 pass: compute tainted-entry-state summaries for functions with params
+  // AND at least one caller in the call graph. This catches "safe when called
+  // clean, dangerous when called with tainted input" wrapper patterns.
+  for (const fn of fnList) {
+    if (Date.now() > deadlineMs) break;
+    if (!fn.params || !fn.params.length) continue;
+    const taintedEntry = new Set(fn.params);
+    if (summaryCache.has(fn.qid, taintedEntry)) continue;
+    const ctx = {
+      _findings: [], _taintSources: [], _returnTainted: false,
+      _stack: new Set(), deadlineMs,
+      _summaryCache: summaryCache, _callGraph: callGraph,
+      _mutatedParamsOut: new Set(),
+    };
+    try { analyzeFunction(fn, taintedEntry, ctx); } catch {}
+    summaryCache.set(fn.qid, taintedEntry, {
+      returnTainted: !!ctx._returnTainted,
+      mutatedParams: ctx._mutatedParamsOut || new Set(),
+      taintedGlobals: new Set(),
+      findings: [],
+    });
+  }
   for (const fn of fnList) {
     if (++n > fnLimit) break;
     if (Date.now() > deadlineMs) break;  // global timeout
@@ -552,6 +677,39 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
     try {
       analyzeFunction(fn, new Set(), callContext);
     } catch { continue; }
+    // Process higher-order invocations: resolve callbacks and analyze with
+    // tainted first-param. Feed findings back into the caller's finding set.
+    const hoInvocations = callContext._higherOrderInvocations || [];
+    const HO_CAP = 50;
+    for (let hi = 0; hi < Math.min(hoInvocations.length, HO_CAP); hi++) {
+      if (Date.now() > deadlineMs) break;
+      const inv = hoInvocations[hi];
+      if (!inv.callee || !inv.taintedParam) continue;
+      const resolved = callGraph.resolve ? callGraph.resolve(inv.callee) : null;
+      const cbFn = resolved && resolved.qid ? resolved : null;
+      if (!cbFn || !cbFn.params || !cbFn.params.length) continue;
+      const cbEntry = new Set([cbFn.params[inv.paramIndex || 0]]);
+      let cbSummary = summaryCache.get(cbFn.qid, cbEntry);
+      if (!cbSummary) {
+        cbSummary = summaryCache.compute(cbFn.qid, cbEntry, () => {
+          const inner = {
+            _findings: [], _taintSources: [], _returnTainted: false,
+            _stack: new Set(), deadlineMs,
+            _summaryCache: summaryCache, _callGraph: callGraph,
+            _mutatedParamsOut: new Set(),
+          };
+          try { analyzeFunction(cbFn, cbEntry, inner); } catch {}
+          // Merge any findings from the callback analysis into the caller.
+          callContext._findings.push(...inner._findings.map(f => ({ ...f, _funcQid: fn.qid, _via: 'higher-order' })));
+          return {
+            returnTainted: !!inner._returnTainted,
+            mutatedParams: inner._mutatedParamsOut || new Set(),
+            taintedGlobals: new Set(),
+            findings: [],
+          };
+        });
+      }
+    }
     for (const f of callContext._findings) {
       const key = `${f.sinkId}:${fn.file}:${f.line}`;
       if (seen.has(key)) continue;
@@ -583,6 +741,21 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
     }
   }
   // v0.69 — expose cache to caller (runDeepAnalysis) for incremental persistence.
+  // Dead code suppression: demote findings in functions with zero callers
+  // (except route handlers which are entry points)
+  const calledQids = new Set();
+  if (callGraph.edges) for (const e of callGraph.edges) calledQids.add(typeof e.to === 'string' ? e.to : e.to?.qid);
+  if (callGraph.callersOf) for (const [qid, callers] of callGraph.callersOf) { if (callers && callers.size) calledQids.add(qid); }
+  for (const f of all) {
+    if (!f._funcQid) continue;
+    const fn = callGraph.functions?.get(f._funcQid);
+    if (!fn) continue;
+    if (calledQids.has(f._funcQid)) continue;
+    if (/handler|route|controller|middleware|endpoint/i.test(fn.name || '')) continue;
+    f._inDeadCode = true;
+    const dg = { critical: 'high', high: 'medium', medium: 'low', low: 'info' };
+    if (dg[f.severity]) f.severity = dg[f.severity];
+  }
   Object.defineProperty(all, '_summaryCache', { value: summaryCache, enumerable: false });
   return all;
 }

package/src/dataflow/implicit-flow.js

@@ -34,7 +34,8 @@
 import { addPath } from './access-paths.js';
 
 export function isImplicitFlowEnabled() {
-  return process.env.AGENTIC_SECURITY_IMPLICIT_FLOW === '1';
+  if (process.env.AGENTIC_SECURITY_IMPLICIT_FLOW === '0') return false;
+  return true;
 }
 
 /**
@@ -62,11 +63,25 @@ export function buildImplicitContext(cfg, exprTaint) {
     const n = cfg.nodes[nid];
     if (!n) continue;
     if (n.kind === 'if' && n.cond && exprTaint(n.cond)) {
-      // Push the consequent at depth+1. We don't have a separate alternate
-      // edge in this v1 IR — `succ` carries both. v2 should add `then`/`else`
-      // distinguishing edges.
+      // Config-constant filter: if condition is `ident === literal` where
+      // ident is NOT tainted, skip (it's a config check, not a taint branch).
+      if (n.cond.kind === 'binary' && (n.cond.op === '===' || n.cond.op === '==' || n.cond.op === 'Eq') &&
+          n.cond.right && n.cond.right.kind === 'literal' &&
+          n.cond.left && n.cond.left.kind === 'ident' &&
+          !exprTaint(n.cond.left)) {
+        for (const s of (n.succ || [])) {
+          stack.push({ nid: s, depth, label });
+        }
+      } else {
+        for (const s of (n.succ || [])) {
+          stack.push({ nid: s, depth: depth + 1, label: _formatCondLabel(n.cond) });
+        }
+      }
+    } else if (n.kind === 'loop-header' && depth > 0) {
+      // Loop-body exclusion: don't escalate implicit depth inside loops —
+      // loop iteration count is not a taint channel for most vuln classes.
       for (const s of (n.succ || [])) {
-        stack.push({ nid: s, depth: depth + 1, label: _formatCondLabel(n.cond) });
+        stack.push({ nid: s, depth: Math.max(depth - 1, 0), label });
       }
     } else {
       for (const s of (n.succ || [])) {
@@ -94,6 +109,9 @@ export function implicitAssignTarget(node, ctx) {
   if (!node || node.kind !== 'assign') return null;
   if (!ctx || !ctx.tainted) return null;
   if (typeof node.target !== 'string') return null;
+  // Literal-assignment filter: assigning a constant in a tainted branch
+  // is not an implicit information leak.
+  if (node.source && node.source.kind === 'literal') return null;
   return node.target;
 }
 
@@ -119,7 +137,7 @@ export function createImplicitFinding(node, conditionLabel) {
   return {
     kind: 'taint',
     implicit: true,
-    confidence: 0.5,
+    confidence: 0.40,
     vuln: `Implicit flow — variable mutated inside tainted-conditional branch (condition: ${conditionLabel || '?'})`,
     severity: 'medium',
     cwe: 'CWE-200',

package/src/dataflow/stub-aware-filter.js

@@ -72,23 +72,81 @@ function _normalizeType(t) {
  * Returns the (mutated) findings array with `_stubFilterStats` non-
  * enumerable sidecar.
  */
-export function applyStubAwareFilter(findings, stubs) {
+const TYPE_GUARD_PATTERNS = [
+  { re: /typeof\s+(\w+)\s*===?\s*['"]number['"]/, type: 'number' },
+  { re: /typeof\s+(\w+)\s*===?\s*['"]boolean['"]/, type: 'boolean' },
+  { re: /Number\.isInteger\s*\(\s*(\w+)\s*\)/, type: 'number' },
+  { re: /Number\.isFinite\s*\(\s*(\w+)\s*\)/, type: 'number' },
+  { re: /!isNaN\s*\(\s*(\w+)\s*\)/, type: 'number' },
+];
+
+function _extractTypeGuardType(condExpr) {
+  if (!condExpr) return null;
+  const condStr = _exprToString(condExpr);
+  if (!condStr) return null;
+  for (const { re, type } of TYPE_GUARD_PATTERNS) {
+    if (re.test(condStr)) return type;
+  }
+  return null;
+}
+
+function _exprToString(expr) {
+  if (!expr) return null;
+  if (expr.kind === 'literal') return String(expr.value || '');
+  if (expr.kind === 'ident') return expr.name;
+  if (expr.kind === 'binary') return `${_exprToString(expr.left)} ${expr.op} ${_exprToString(expr.right)}`;
+  if (expr.kind === 'call') return `${typeof expr.callee === 'string' ? expr.callee : _exprToString(expr.callee)}(${(expr.args || []).map(_exprToString).join(',')})`;
+  if (expr.kind === 'member') return `${_exprToString(expr.object)}.${expr.prop}`;
+  if (expr.kind === 'unknown') return 'typeof';
+  return null;
+}
+
+function _hasTypeGuardOnPath(finding, perFileIR) {
+  if (!perFileIR || !finding.file) return null;
+  const ir = perFileIR[finding.file];
+  if (!ir || !ir.functions) return null;
+  const fn = ir.functions.find(f => {
+    const sinkLine = finding.line || 0;
+    return sinkLine >= f.line && sinkLine <= f.line + Object.keys(f.cfg.nodes).length * 3;
+  });
+  if (!fn) return null;
+  for (const node of Object.values(fn.cfg.nodes)) {
+    if (node.kind === 'if' && node.cond) {
+      const guardType = _extractTypeGuardType(node.cond);
+      if (guardType) return guardType;
+    }
+  }
+  return null;
+}
+
+export function applyStubAwareFilter(findings, stubs, perFileIR) {
   if (!Array.isArray(findings) || findings.length === 0) return findings;
-  if (!stubs || !stubs.signatures) return findings;
   let demoted = 0;
   for (const f of findings) {
     if (!f || f.parser !== 'IR-TAINT') continue;
     const safeSet = FAMILY_SAFE_TYPES[f.cwe];
     if (!safeSet) continue;
-    const sourceType = _sourceTypeFromStubs(f, stubs);
-    if (!sourceType) continue;
-    if (!safeSet.has(sourceType)) continue;
-    f._stubTypeDemoted = true;
-    f._stubTypeReason = `source type ${sourceType} cannot carry ${f.cwe} metacharacters`;
-    f._stubTypeOriginalSeverity = f.severity;
-    const downgrade = { critical: 'high', high: 'medium', medium: 'low', low: 'info' };
-    if (downgrade[f.severity]) f.severity = downgrade[f.severity];
-    demoted++;
+    // Check 1: stub-based type demotion
+    const sourceType = stubs ? _sourceTypeFromStubs(f, stubs) : null;
+    if (sourceType && safeSet.has(sourceType)) {
+      f._stubTypeDemoted = true;
+      f._stubTypeReason = `source type ${sourceType} cannot carry ${f.cwe} metacharacters`;
+      f._stubTypeOriginalSeverity = f.severity;
+      const downgrade = { critical: 'high', high: 'medium', medium: 'low', low: 'info' };
+      if (downgrade[f.severity]) f.severity = downgrade[f.severity];
+      demoted++;
+      continue;
+    }
+    // Check 2: type-guard narrowing on CFG path
+    const guardType = _hasTypeGuardOnPath(f, perFileIR);
+    if (guardType && safeSet.has(guardType)) {
+      f._stubTypeDemoted = true;
+      f._stubTypeReason = `type guard narrows to ${guardType}, safe for ${f.cwe}`;
+      f._stubTypeOriginalSeverity = f.severity;
+      const downgrade = { critical: 'high', high: 'medium', medium: 'low', low: 'info' };
+      if (downgrade[f.severity]) f.severity = downgrade[f.severity];
+      demoted++;
+    }
   }
   Object.defineProperty(findings, '_stubFilterStats', {
     value: { demoted, totalConsidered: findings.length },

package/src/dataflow/summaries.js

@@ -68,20 +68,38 @@ export class SummaryCache {
   // Compute the summary for a function (or return cached). The `analyze`
   // callback is the per-function walker that returns
   //   { returnTainted, mutatedParams: Set, taintedGlobals: Set, findings: [] }
+  //
+  // Fixed-point iteration: when a recursive call returns a bottom stub,
+  // re-analyze up to FP_MAX times until the summary stabilizes.
   compute(qid, taintedParams, analyze) {
     const k = this._key(qid, taintedParams);
-    if (this._cache.has(k)) return this._cache.get(k);
+    if (this._cache.has(k)) {
+      const cached = this._cache.get(k);
+      if (!cached._recursive) return cached;
+    }
     if (this._stack.has(qid)) {
-      // Recursion — return bottom summary; fixed-point iter will refine.
+      this._hitRecursion = true;
       return { returnTainted: false, mutatedParams: new Set(), taintedGlobals: new Set(), findings: [], _recursive: true };
     }
     if (++this._iter > this._maxIter) {
       return { returnTainted: false, mutatedParams: new Set(), taintedGlobals: new Set(), findings: [], _budgetExceeded: true };
     }
     this._stack.add(qid);
+    this._hitRecursion = false;
     try {
-      const summary = analyze(qid, taintedParams);
+      let summary = analyze(qid, taintedParams);
       this._cache.set(k, summary);
+      if (this._hitRecursion) {
+        const FP_MAX = 3;
+        for (let fp = 0; fp < FP_MAX; fp++) {
+          if (++this._iter > this._maxIter) break;
+          const prev = summary;
+          summary = analyze(qid, taintedParams);
+          if (_summaryEq(prev, summary)) break;
+          this._cache.set(k, summary);
+        }
+      }
+      if (summary._recursive) delete summary._recursive;
       return summary;
     } finally {
       this._stack.delete(qid);
@@ -110,6 +128,13 @@ export class SummaryCache {
   clear() { this._cache.clear(); this._iter = 0; }
 }
 
+function _summaryEq(a, b) {
+  if (!a || !b) return a === b;
+  if (!!a.returnTainted !== !!b.returnTainted) return false;
+  if ((a.mutatedParams?.size || 0) !== (b.mutatedParams?.size || 0)) return false;
+  return true;
+}
+
 // Build the entry-taint-state for a callee from a call site:
 //   given the callee's param names + the caller's tainted-var set + the
 //   call args, return a Set of param names that are tainted at entry.

package/src/engine-parallel.js

@@ -0,0 +1,70 @@
+// Worker-thread parallelism infrastructure for per-file SAST analysis.
+//
+// Gated behind AGENTIC_SECURITY_PARALLEL=1 (default OFF).
+// When enabled, distributes per-file detector execution across a bounded
+// worker pool (default 2 workers, max 4).
+//
+// Architecture:
+//   - Main thread: orchestrates file distribution, collects findings
+//   - Workers: receive (filepath, content), run detectors, return findings[]
+//   - Bounded queue prevents memory exhaustion on large monorepos
+//
+// v1: stub infrastructure. The actual worker dispatch is deferred until
+// the per-file detectors are refactored into a single function that can
+// be serialized to a worker. Today the detectors import 60+ modules with
+// shared state (e.g., _GLOBAL_JAVA_TAINTED_METHODS), making them
+// non-trivially parallelizable.
+
+import { availableParallelism } from 'node:os';
+
+export function isParallelEnabled() {
+  return process.env.AGENTIC_SECURITY_PARALLEL === '1';
+}
+
+export function recommendedWorkerCount() {
+  const cpus = availableParallelism();
+  return Math.max(1, Math.min(4, Math.floor(cpus / 2)));
+}
+
+export function createParallelContext(opts = {}) {
+  const workerCount = opts.workers || recommendedWorkerCount();
+  return {
+    enabled: isParallelEnabled(),
+    workerCount,
+    filesProcessed: 0,
+    totalMs: 0,
+    _stats: {
+      dispatched: 0,
+      completed: 0,
+      errors: 0,
+      avgMs: 0,
+    },
+  };
+}
+
+export async function runParallelFileScans(files, fileContents, detectorFn, opts = {}) {
+  if (!isParallelEnabled()) return null;
+
+  const ctx = createParallelContext(opts);
+  const results = [];
+
+  // v1 stub: run sequentially but through the parallel context for testing.
+  // v2 will use worker_threads with a bounded queue.
+  for (const fp of files) {
+    const content = fileContents[fp];
+    if (!content) continue;
+    const t0 = Date.now();
+    try {
+      const findings = detectorFn(fp, content);
+      results.push(...(findings || []));
+      ctx._stats.completed++;
+    } catch {
+      ctx._stats.errors++;
+    }
+    ctx._stats.dispatched++;
+    ctx.totalMs += Date.now() - t0;
+    ctx.filesProcessed++;
+  }
+  ctx._stats.avgMs = ctx.filesProcessed ? Math.round(ctx.totalMs / ctx.filesProcessed) : 0;
+  return { findings: results, stats: ctx._stats };
+}