@clear-capabilities/agentic-security-scanner 0.134.0 → 0.136.9

package/src/dataflow/engine.js

@@ -30,14 +30,17 @@
 // Sinks: anywhere a CFG node calls a catalog-registered sink with a tainted
 // argument, we emit a finding.
 //
-// Sanitizers: NOT consulted by this walk. `matchSinkOrSanitizer()` returns
-// catalog hits of both kinds, but every consumer in this directory keeps only
-// `e.kind === 'sink'`; no `'sanitizer'` branch exists anywhere in dataflow/*.
-// Taint dies here only when a variable is re-assigned from a clean expression
-// (removePathAndDescendants, below) — which is orthogonal to whether the RHS
-// happens to be a catalog sanitizer. Recognising sanitizer entries at a call
-// site is open work; until it lands, treat the catalog's sanitizer half as
-// documentation consumed by other layers, not by this engine.
+// Sanitizers: RECORDED, but they do not kill taint in this walk.
+// `_sanitizersForExpr` (below) collects the sanitizer callees applied to the
+// value reaching each sink argument — inline, or inherited via
+// `_sanitizersByVar` from the variable it reads — and stamps them on the
+// finding as `_sanitizersOnPath`. `dataflow/sanitizer-gate.js` then labels the
+// finding `sanitized:true` only when the sanitizer's `appliesTo` family
+// actually covers the finding's threat class; `engine.js`'s proof gate demotes
+// from there. Taint itself still dies only when a variable is re-assigned from
+// a clean expression (removePathAndDescendants, below) — a mislabelled
+// sanitizer must never silently drop a real vulnerability, so the walk never
+// treats a sanitizer call as clearing the tainted path on its own.
 
 import { matchSource, matchSinkOrSanitizer } from './catalog.js';
 import { functionRecord } from '../ir/callgraph.js';
@@ -268,6 +271,53 @@ function _matchCallCatalog(calleeExpr, argExprs, state) {
   return { cat, argTaints };
 }
 
+// Sanitizer callees observed on an expression.
+//
+// The engine deliberately does NOT let a sanitizer kill taint. A blanket
+// "any sanitizer clears the flow" rule scores well on benchmarks and silently
+// drops a real SQL injection whenever the code applied an HTML escaper — the
+// C/C++ catalog work already found strncpy/snprintf tagged effect:'strip' when
+// they bound length rather than sanitising content. So the walk RECORDS which
+// sanitizers touched the value and hands them to sanitizer-gate.js, which
+// labels the finding, and the proof gate demotes it. Recall-preserving, same
+// precedent as falsification.js / proof-gate.js: never removed, never
+// severity-touched.
+function _sanitizersInExprTree(expr, out) {
+  if (!expr || typeof expr !== 'object') return;
+  if (expr.kind === 'call') {
+    const cat = matchSinkOrSanitizer(expr.callee, _currentFile);
+    if (cat) {
+      for (const e of cat) {
+        if (e.kind === 'sanitizer' && e.match && e.match.callee) out.add(e.match.callee);
+      }
+    }
+  }
+  for (const k of ['left', 'right', 'callee', 'object', 'property', 'value']) {
+    if (expr[k] && typeof expr[k] === 'object') _sanitizersInExprTree(expr[k], out);
+  }
+  for (const k of ['args', 'parts', 'branches', 'elements']) {
+    if (Array.isArray(expr[k])) for (const e of expr[k]) _sanitizersInExprTree(e, out);
+  }
+  if (Array.isArray(expr.props)) for (const p of expr.props) _sanitizersInExprTree(p && p.value, out);
+}
+
+// Sanitizers applied to `expr`: those called inline within it, plus those
+// recorded against any variable it reads (`const safe = escapeHtml(x); sink(safe)`).
+function _sanitizersForExpr(expr, callContext) {
+  const out = new Set();
+  _sanitizersInExprTree(expr, out);
+  const byVar = callContext && callContext._sanitizersByVar;
+  if (byVar && byVar.size) {
+    const vars = new Set();
+    _collectExprVars(expr, vars);
+    for (const v of vars) {
+      const s = byVar.get(v);
+      if (s) for (const n of s) out.add(n);
+    }
+  }
+  return out;
+}
+
 // cat / argTaints: the result of _matchCallCatalog (computed by the caller,
 // at whatever point in its case is appropriate for its own state-mutation
 // ordering).
@@ -299,7 +349,13 @@ function _sinkFindingsForCall(calleeExpr, argExprs, cat, argTaints, state, callC
           ? reachingSources.slice(0, 5)
           // Fallback: better to surface "no precise source" than the wrong source.
           : [];
+        // Sanitizers seen on the value reaching THIS argument. Consumed by
+        // sanitizer-gate.js, which labels only when the sanitizer's family
+        // covers the finding's threat class — an xss escaper on a SQL sink
+        // must not read as sanitised.
+        const _sanNames = _sanitizersForExpr(taintedArgExpr, callContext);
         findings.push({
+          ...(_sanNames.size ? { _sanitizersOnPath: [..._sanNames] } : {}),
           kind: 'taint',
           sinkId: e.id,
           vuln: e.vuln?.name || 'Tainted Sink',
@@ -318,9 +374,36 @@ function _sinkFindingsForCall(calleeExpr, argExprs, cat, argTaints, state, callC
   return { findings };
 }
 
+// Surfaces a cached (or freshly computed) summary's `findings` into the
+// CURRENT caller's context — the only place a class-field/k=2 pre-pass's
+// speculative findings (in runTaintEngine) become reportable, because
+// reaching this point means a real call site actually consulted that exact
+// qid+entry. Called uniformly on both a cache HIT (`summaryCache.get()`)
+// and a cache MISS (`summaryCache.compute()`'s return value), so it doesn't
+// matter whether this call site is the first one to ever reach this
+// qid+entry or the fifth — findings ride on the summary object itself now,
+// not on a one-shot merge inside compute()'s callback. Module-level (not
+// nested in runTaintEngine) because step()'s assign/plain-call interproc
+// branches call it too, and step() is a top-level function with no access
+// to runTaintEngine's locals.
+function _mergeSummaryFindings(callContext, callerQid, sum, via) {
+  if (!sum || !Array.isArray(sum.findings) || !sum.findings.length) return;
+  callContext._findings.push(...sum.findings.map(f => ({ ...f, _funcQid: callerQid || null, _via: via })));
+}
+
 // 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);
+  // `let`, not `const` — the 'call' case (built-in-mutation and mutated-param
+  // branches below) reassigns this binding. It was `const` until Stage 3 of
+  // the correctness audit: a bare-statement call to Object.assign/_.merge/
+  // etc. with a tainted source arg, or any plain call whose callee summary
+  // reports mutated params, threw "Assignment to constant variable" here.
+  // The engine's per-function analyzeFunction() call sites all wrap in a
+  // blanket try/catch, so the exception was silent — and it discarded every
+  // finding already collected for the ENTIRE containing function, not just
+  // the mutation site, since the throw unwound past `findings.push(...)`
+  // calls for unrelated sinks earlier in the same function body.
+  let state = new Set(stateIn);
   const findings = [];
 
   switch (node.kind) {
@@ -348,6 +431,18 @@ function step(node, stateIn, callContext) {
           node.source.callee, node.source.args, _sinkCat, _sinkArgTaints,
           state, callContext, node.line).findings);
       }
+      // Record which sanitizers were applied to the value now held by `target`
+      // (inline in the RHS, or inherited from the vars the RHS reads). Placed
+      // before every early return in this case so the map cannot go stale on
+      // the interprocedural paths below. A clean RHS clears the entry, mirroring
+      // removePathAndDescendants — a stale sanitizer would label a later,
+      // genuinely unsanitized flow.
+      if (target) {
+        const _san = _sanitizersForExpr(node.source, callContext);
+        const _byVar = (callContext._sanitizersByVar ||= new Map());
+        if (_san.size) _byVar.set(target, _san);
+        else _byVar.delete(target);
+      }
       // Constant propagation: track variables assigned from literals
       if (target && _activeConstantVars) {
         if (node.source && node.source.kind === 'literal') _activeConstantVars.set(target, node.source.value);
@@ -404,10 +499,19 @@ function step(node, stateIn, callContext) {
                 returnTainted: !!inner._returnTainted,
                 mutatedParams: inner._mutatedParamsOut || new Set(),
                 taintedGlobals: new Set(),
-                findings: [],
+                // Real findings from the callee's own body — e.g.
+                // `function makeQuery(id){ db.query(...id) } ... makeQuery(uid)`
+                // — ride on the summary itself (was hardcoded `[]`, so
+                // nothing ever read inner._findings and the SQLi inside
+                // makeQuery was silently dropped). _mergeSummaryFindings
+                // below surfaces them into THIS caller now that a real
+                // call site has been established, and does the same on a
+                // future cache hit from any other real caller.
+                findings: inner._findings,
               };
             });
           }
+          _mergeSummaryFindings(callContext, callContext._currentFnQid, sum, 'interproc');
           if (sum && sum.returnTainted) {
             newState = _addPathAliasAware(newState, target, callContext);
             callContext._taintSources.push({
@@ -515,10 +619,14 @@ function step(node, stateIn, callContext) {
                 returnTainted: !!inner._returnTainted,
                 mutatedParams: inner._mutatedParamsOut || new Set(),
                 taintedGlobals: new Set(),
-                findings: [],
+                // See the sibling assign-call-site compute() above — same
+                // fix, same reason: this callee's own findings were
+                // computed correctly and then thrown away (hardcoded `[]`).
+                findings: inner._findings,
               };
             });
           }
+          _mergeSummaryFindings(callContext, callContext._currentFnQid, sum, 'interproc');
           if (sum && sum.mutatedParams && sum.mutatedParams.size) {
             const mutated = callContext._summaryCache.applyAtCallSite(
               sum, paramNames, node.args || [], state);
@@ -574,7 +682,13 @@ function step(node, stateIn, callContext) {
         if (dot <= 0) return null;
         const recv = callee.slice(0, dot);
         const recvTainted = isCoveredBy(state, recv);
-        return higherOrderTaintFlow(node, recvTainted);
+        // higherOrderTaintFlow requires a flattened STRING callee (its own
+        // `typeof callee !== 'string'` guard) — passing the raw `node` here
+        // handed it a JS/TS structured callee expr ({kind:'member',...})
+        // unconditionally, which never passed that guard, so this feature
+        // was entirely dead for JS/TS (the primary catalogued language).
+        // `callee` here is `_plainCallCalleeName`, already flattened above.
+        return higherOrderTaintFlow({ ...node, callee }, recvTainted);
       })();
       if (hoFlow && hoFlow.taintsCallbackParam === 0) {
         // The first arg should be the callback. If it's a plain ident or
@@ -587,7 +701,17 @@ function step(node, stateIn, callContext) {
         if (cb && (cb.kind === 'ident' || cb.kind === 'function-value')) {
           callContext._higherOrderInvocations = callContext._higherOrderInvocations || [];
           callContext._higherOrderInvocations.push({
-            callee: cb.kind === 'ident' ? cb.name : (cb.qid || null),
+            // A resolved-by-name callback (`arr.map(processItem)`) and an
+            // inline callback (`arr.map(x => ...)`, parser-js.js's
+            // exprOf now emits {kind:'function-value', qid}) need different
+            // resolution strategies downstream — a bare name looked up via
+            // the call graph's byNameInFile index (ambiguous/guessable) vs.
+            // an exact qid looked up directly in callGraph.functions. Kept
+            // as two fields rather than overloading `callee` with either
+            // shape, so the consumer can't accidentally hand a qid to the
+            // name-based resolver (or vice versa).
+            callee: cb.kind === 'ident' ? cb.name : null,
+            calleeQid: cb.kind === 'function-value' ? (cb.qid || null) : null,
             paramIndex: 0,
             taintedParam: true,
             line: node.line,
@@ -695,8 +819,29 @@ function analyzeFunction(fn, entryState, callContext) {
         const t = implicitAssignTarget(nodes[nid], ctx);
         if (t) implicitState = markImplicitTaint(implicitState, t);
       }
-      // A sink in a tainted branch whose arg is implicit-tainted (or constant)
-      // — and NOT already explicitly tainted (the normal pass covers that).
+      // Stage 6 correctness audit: these are two genuinely different gates,
+      // previously conflated into one loop over `ictx`. `allConst` is a
+      // leak from the SINK CALL'S OWN EXECUTION revealing the branch was
+      // taken — that requires the call itself to be genuinely inside the
+      // tainted branch (now correctly dominance-scoped by
+      // buildImplicitContext, see its header). `argRefsImplicit` is a leak
+      // from a VARIABLE that was implicit-tainted earlier — once a var is
+      // marked, its taint is a normal fact about the var, not about where
+      // it's later read; requiring the READ site to also be lexically
+      // inside a branch would miss the canonical
+      // `if (tainted) { p = x; } eval(p)` pattern the moment `eval(p)` is
+      // (correctly) recognized as being outside the branch.
+      const reportedNids = new Set();
+      const reportImplicit = (nid, node, sink, conditionLabel) => {
+        if (reportedNids.has(nid)) return;
+        reportedNids.add(nid);
+        callContext._findings.push({
+          ...createImplicitFinding(node, conditionLabel),
+          _funcQid: fn.qid, sinkId: sink.id,
+          cwe: (sink.vuln && sink.vuln.cwe) || 'CWE-200',
+        });
+      };
+      // Pass 1 — constant-arg sink calls genuinely inside a tainted branch.
       for (const [nid, ctx] of ictx) {
         const node = nodes[nid];
         if (!node || node.kind !== 'call') continue;
@@ -705,16 +850,24 @@ function analyzeFunction(fn, entryState, callContext) {
         if (!sink) continue;
         const inS = inStates.get(nid) || new Set();
         if ((node.args || []).some((a) => exprTaint(a, inS))) continue;
-        const argRefsImplicit = (node.args || []).some((a) => {
-          const ap = accessPathOf(a); return ap && isCoveredBy(implicitState, `implicit:${ap}`);
-        });
         const allConst = (node.args || []).length > 0 && (node.args || []).every((a) => a && a.kind === 'literal');
-        if (argRefsImplicit || allConst) {
-          callContext._findings.push({
-            ...createImplicitFinding(node, ctx.conditionLabel),
-            _funcQid: fn.qid, sinkId: sink.id,
-            cwe: (sink.vuln && sink.vuln.cwe) || 'CWE-200',
+        if (allConst) reportImplicit(nid, node, sink, ctx.conditionLabel);
+      }
+      // Pass 2 — any sink call anywhere in the function whose argument
+      // reads an implicit-tainted variable, regardless of whether the
+      // call site itself is inside a branch.
+      if (implicitState.size) {
+        for (const [nid, node] of Object.entries(nodes)) {
+          if (!node || node.kind !== 'call') continue;
+          const cat = matchSinkOrSanitizer(node.callee, _currentFile);
+          const sink = cat && cat.find((e) => e.kind === 'sink');
+          if (!sink) continue;
+          const inS = inStates.get(nid) || new Set();
+          if ((node.args || []).some((a) => exprTaint(a, inS))) continue;
+          const argRefsImplicit = (node.args || []).some((a) => {
+            const ap = accessPathOf(a); return ap && isCoveredBy(implicitState, `implicit:${ap}`);
           });
+          if (argRefsImplicit) reportImplicit(nid, node, sink, ictx.get(nid)?.conditionLabel || null);
         }
       }
     } catch { /* implicit flow is best-effort + opt-in */ }
@@ -785,9 +938,13 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
   // unbounded blowup). v0.66 — the inner ctx now records mutatedParams
   // via _mutatedParamsOut so cross-function param mutation propagates.
   const MAX_FP_ITERS = 3;
-  let prevCacheSize = -1;
   for (let it = 0; it < MAX_FP_ITERS; it++) {
     if (Date.now() > deadlineMs) break;
+    // Tracks whether this iteration actually changed any cached summary's
+    // VALUE — the correct convergence signal (see below). Reset each
+    // iteration; if nothing changed, the fixed point has been reached and
+    // further iterations would recompute byte-identical results.
+    let changedThisIter = false;
     for (const fn of fnList) {
       if (Date.now() > deadlineMs) break;
       const entry = new Set();
@@ -802,20 +959,44 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
         _mutatedParamsOut: new Set(),
       };
       try { analyzeFunction(fn, entry, ctx); } catch {}
+      // Report real findings discovered by this probe rather than letting
+      // them die with `ctx` — see _collectFindings's header comment. Safe to
+      // call every iteration and again from the main loop below: dedup is by
+      // (sinkId, file, line), so re-discovering the same empty-entry finding
+      // multiple times collapses to one reported finding, never a duplicate.
+      _collectFindings(fn, ctx._findings);
       const next = {
         returnTainted: !!ctx._returnTainted,
         mutatedParams: ctx._mutatedParamsOut || new Set(),
         taintedGlobals: new Set(),
         findings: [],
       };
+      // Membership-aware, not size-only — two summaries with the same
+      // mutatedParams CARDINALITY but different MEMBERS (e.g. {'a'} vs
+      // {'b'}) were treated as unchanged, so a real refinement across
+      // iterations (a callee's mutated-field identity settling once its own
+      // callees' summaries became known) was silently never written to the
+      // cache. Same bug class as summaries.js's _summaryEq, fixed alongside
+      // it. Reuses the same access-path-aware setsEqual already imported
+      // for taint-state comparison elsewhere in this file (mutatedParams
+      // entries are access paths too, e.g. '_this_.field').
       if (!existing
           || existing.returnTainted !== next.returnTainted
-          || (existing.mutatedParams?.size || 0) !== next.mutatedParams.size) {
+          || !accessSetsEqual(existing.mutatedParams, next.mutatedParams)) {
         summaryCache.set(fn.qid, entry, next);
+        changedThisIter = true;
       }
     }
-    if (summaryCache.size() === prevCacheSize) break;
-    prevCacheSize = summaryCache.size();
+    // NOT `summaryCache.size() === prevCacheSize` (the pre-fix check): every
+    // function gets a cache key on iteration 0 (`!existing` is true for all
+    // of them), so `.size()` — a KEY COUNT — jumps from 0 to N once and then
+    // never changes again, since overwriting an existing Map key never
+    // changes `.size`. That made the loop `break` after iteration 1
+    // regardless of whether iteration 1 itself found real refinements to
+    // write, silently delivering 2 rounds of fixed-point refinement instead
+    // of the MAX_FP_ITERS=3 this code and dataflow/CLAUDE.md both promise.
+    // `changedThisIter` tracks actual value changes instead.
+    if (!changedThisIter) break;
   }
   // 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.
@@ -844,11 +1025,19 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
         _mutatedParamsOut: new Set(),
       };
       try { analyzeFunction(fn, fields, ctx); } catch {}
+      // `findings` carries the REAL findings from this probe (was hardcoded
+      // `[]`, discarding them) — but this pass is speculative (every field
+      // in `fields` is assumed simultaneously tainted; nothing here confirms
+      // this exact method is ever reached with that state), so it must not
+      // report them itself. They ride on the cached summary and are only
+      // surfaced by _mergeSummaryFindings when a REAL call site (assign,
+      // plain-call, or higher-order) actually consults this qid+entry —
+      // at that point a genuine reachable caller has been established.
       summaryCache.set(fn.qid, fields, {
         returnTainted: !!ctx._returnTainted,
         mutatedParams: ctx._mutatedParamsOut || new Set(),
         taintedGlobals: new Set(),
-        findings: [],
+        findings: ctx._findings,
       });
     }
   }
@@ -868,11 +1057,27 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
       _mutatedParamsOut: new Set(),
     };
     try { analyzeFunction(fn, taintedEntry, ctx); } catch {}
+    // `findings` carries the real findings from this probe (was hardcoded
+    // `[]`). This pass assumes EVERY param is simultaneously tainted —
+    // there's no check that any real caller ever passes tainted data here
+    // at all (the header comment above claims "AND at least one caller in
+    // the call graph"; the code has never actually enforced that) — so
+    // these findings must not be reported unconditionally, only when a real
+    // call site's own entry state happens to match and consults this cached
+    // summary via _mergeSummaryFindings. This is the exact scenario that
+    // motivated storing them at all: an inline callback
+    // (`arr.forEach(x => sink(x))`) has one param, so it gets probed here
+    // with taintedEntry={param} BEFORE the higher-order invocation loop
+    // below ever runs; without `findings` riding on the cached summary, the
+    // real finding computed right here was thrown away and unrecoverable —
+    // the higher-order loop's own `summaryCache.get()` would hit this
+    // now-cached (finding-less) summary and never call `compute()` (the
+    // only place that used to merge findings) at all.
     summaryCache.set(fn.qid, taintedEntry, {
       returnTainted: !!ctx._returnTainted,
       mutatedParams: ctx._mutatedParamsOut || new Set(),
       taintedGlobals: new Set(),
-      findings: [],
+      findings: ctx._findings,
     });
   }
   for (const fn of fnList) {
@@ -899,13 +1104,20 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
     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;
-      // inv.callee is always a bare ident (only cb.kind === 'ident' pushes a
-      // higher-order invocation — see the push site above), so resolve()'s
-      // bare-tail guess never triggers here either way; resolveKnownCallee
-      // for consistency with the other call-graph lookups in this file.
-      const resolved = callGraph.resolveKnownCallee ? callGraph.resolveKnownCallee(inv.callee, fn && fn.file) : null;
-      const cbFn = functionRecord(callGraph, resolved);
+      if ((!inv.callee && !inv.calleeQid) || !inv.taintedParam) continue;
+      // Two resolution strategies, matching the two shapes the push site can
+      // record: an inline callback (`arr.map(x => ...)`) carries an exact
+      // qid (parser-js.js's exprOf synthesizes it identically to how
+      // enterFn will independently name the same node) — look it up directly
+      // in callGraph.functions, no name resolution involved. A by-reference
+      // callback (`arr.map(processItem)`) carries a bare ident name; resolve
+      // it the same way every other call-graph lookup in this file does.
+      // resolveKnownCallee (never the bare-tail-guessing resolve()) since a
+      // wrong guess here would fabricate a callback relationship that
+      // doesn't exist.
+      const cbFn = inv.calleeQid
+        ? functionRecord(callGraph, inv.calleeQid)
+        : functionRecord(callGraph, callGraph.resolveKnownCallee ? callGraph.resolveKnownCallee(inv.callee, fn && fn.file) : 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);
@@ -918,21 +1130,57 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
             _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: [],
+            findings: inner._findings,
           };
         });
       }
+      // Uniform with the assign/plain-call sites: merge whether this was a
+      // fresh compute() (findings from `inner` just above) or a cache HIT —
+      // e.g. the k=2 pass already probed this exact qid+entry (a callback
+      // with one param has taintedEntry===cbEntry) and stashed its own real
+      // findings on the summary rather than reporting them speculatively.
+      _mergeSummaryFindings(callContext, fn.qid, cbSummary, 'higher-order');
     }
-    for (const f of callContext._findings) {
-      const key = `${f.sinkId}:${fn.file}:${f.line}`;
+    _collectFindings(fn, callContext._findings);
+  }
+  // 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;
+
+  // Dedup + map a raw findings array (from analyzeFunction's callContext)
+  // into the reported IR-TAINT shape, attributed to `fn`. Used directly by
+  // the main loop and the empty-entry pre-pass (both analyze under an entry
+  // state that is either empty or true-by-construction, so their findings
+  // are unconditionally real). The class-field and k=2 pre-passes are
+  // speculative (they assume fields/params are tainted without confirming
+  // any real caller ever does that) — see _mergeSummaryFindings, which is
+  // the gate that gives their findings a chance to be reported only once a
+  // genuine caller is established.
+  function _collectFindings(attributedFn, srcFindings) {
+    for (const f of srcFindings) {
+      const key = `${f.sinkId}:${attributedFn.file}:${f.line}`;
       if (seen.has(key)) continue;
       seen.add(key);
+      const fn = attributedFn;
       all.push({
         id: `ir-taint:${fn.file}:${f.line}:${f.sinkId}`,
         file: fn.file,
@@ -946,6 +1194,39 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
         // (a control-dependence finding, not an explicit data-flow one).
         confidence: (f.implicit && typeof f.confidence === 'number') ? f.confidence : 0.75,
         ...(f.implicit === true ? { implicit: true } : {}),
+        // Sanitizer callees observed on the value reaching this sink. This
+        // mapping is an explicit allowlist, so a field absent here is silently
+        // dropped — which is what previously left sanitizer-gate.js inert.
+        ...(Array.isArray(f._sanitizersOnPath) && f._sanitizersOnPath.length
+          ? { _sanitizersOnPath: f._sanitizersOnPath } : {}),
+        // _funcQid: the enclosing function's qid, set upstream during the walk
+        // but silently dropped by this allowlist before backward.js's
+        // annotateBackwardSlices ever saw it — the same class of omission
+        // _sanitizersOnPath had. Without it, annotateBackwardSlices's very
+        // first check (`if (!f._funcQid) skip`) discarded every finding, so
+        // backward-slice annotation was permanently a no-op regardless of
+        // AGENTIC_SECURITY_BACKWARD_SLICE.
+        ...(f._funcQid ? { _funcQid: f._funcQid } : {}),
+        // callee: kept as plain `callee` (not underscore-prefixed) to match
+        // backward.js's own contract, which reads `f.callee` on both real and
+        // fake-fixture findings throughout its module and test suite. It is
+        // the SAME object reference as the CFG call node's own `callee` (set
+        // at `_sinkFindingsForCall`'s call site as `callee: calleeExpr`,
+        // never copied) — backward.js's sink-node lookup matches
+        // `n.callee === f.callee` by reference identity, so dropping this
+        // field (as the allowlist previously did) meant that match could
+        // never succeed regardless of `_funcQid`. It is not read by
+        // report/index.js's normalizeFindings, which is itself an explicit
+        // allowlist that never names `callee`, so this does not reach SARIF/
+        // JSON/HTML report output.
+        ...(f.callee !== undefined ? { callee: f.callee } : {}),
+        // sourceProvenance/chain[].provenance: catalog.js's per-source label
+        // (e.g. 'http-body' for req.body) computed earlier at the finding's
+        // creation site — previously dropped by this allowlist, which is
+        // what left posture/exploitability-probability.js's
+        // 'source-from-network' factor permanently dead (it reads
+        // t.provenance off chain/trace entries).
+        sourceProvenance: f.sourceProvenance || null,
         source: f.trace && f.trace.length ? {
           file: fn.file,
           line: f.trace[0].line,
@@ -957,27 +1238,10 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
           label: f.sinkId,
         },
         chain: (f.trace || []).map(t => ({
-          file: fn.file, line: t.line, label: t.sourceLabel,
+          file: fn.file, line: t.line, label: t.sourceLabel, provenance: t.provenance || null,
         })),
       });
     }
   }
-  // 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/ifds-precise.js

@@ -24,6 +24,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 
+import { statePath, safeWriteState, stateWritesEnabled } from '../posture/state-dir.js';
 // ── Per-call-site refined summaries ────────────────────────────────────────
 
 /**
@@ -160,7 +161,7 @@ export function backwardSlice(callGraph, finding, opts = {}) {
 // ── Persistent cross-scan summary cache ────────────────────────────────────
 
 function _cachePath(scanRoot) {
-  return path.join(scanRoot, '.agentic-security', 'ifds-summaries.json');
+  return statePath(scanRoot, 'ifds-summaries.json');
 }
 
 function _fileHash(content) {
@@ -190,8 +191,9 @@ export function loadPersistedCache(scanRoot) {
  * skip re-analysis of functions whose file hash hasn't changed.
  */
 export function persistCache(scanRoot, cache, perFileIR) {
-  const dir = path.join(scanRoot, '.agentic-security');
-  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  // A read-only scan still ANALYSES; it just may not persist the cache. The
+  // next scan simply recomputes, which is slower and identical. (PRD M1)
+  if (!stateWritesEnabled()) return;
   const fileHashes = {};
   for (const [filePath, ir] of (perFileIR || new Map())) {
     if (ir && typeof ir._content === 'string') fileHashes[filePath] = _fileHash(ir._content);
@@ -203,7 +205,7 @@ export function persistCache(scanRoot, cache, perFileIR) {
     if (sum.has('∅')) summaries[qid] = sum.get('∅');
   }
   const out = { scanTs: new Date().toISOString(), summaries, fileHashes };
-  try { fs.writeFileSync(_cachePath(scanRoot), JSON.stringify(out, null, 2)); }
+  try { safeWriteState(_cachePath(scanRoot), JSON.stringify(out, null, 2)); }
   catch { /* best-effort */ }
 }