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

package/src/dataflow/implicit-flow.js

@@ -32,6 +32,7 @@
 //     → new state with the implicit-tainted vars added at confidence 0.5
 
 import { addPath } from './access-paths.js';
+import { computeDominators } from '../ir/ssa.js';
 
 export function isImplicitFlowEnabled() {
   // OPT-IN (default OFF): implicit/control-dependence flow is famously noisy, so
@@ -47,48 +48,79 @@ export function isImplicitFlowEnabled() {
  *   cfg:           the function CFG
  *   exprTaint:     callback (expr) -> bool, using the current taint state
  *
- * Heuristic: walk forward from entry, and when we hit an `if` whose
- * condition is tainted, mark all nodes reachable from the consequent (and,
- * if present, the alternate) until we exit those branches.
+ * Correctness (Stage 6 audit): this used to be a path-dependent DFS that
+ * incremented a "depth" counter on entering a tainted `if`'s successors and
+ * only ever decremented it at a loop-header — there was no mechanism to
+ * detect a branch's natural JOIN point, so once a path entered depth 1,
+ * every node reachable afterward (including everything textually AFTER the
+ * if/else closes, for the rest of the function) stayed marked
+ * `tainted: true` forever. A first fix attempt (reset depth at the join)
+ * was reverted because it broke the equally-real, intentional pattern
+ * `if (tainted) { p = x; } eval(p)`: `p`'s taint must survive past the
+ * branch on the VARIABLE (via markImplicitTaint → the normal forward-taint
+ * state, entirely independent of this map), even though `eval(p)` itself is
+ * not lexically inside the branch.
+ *
+ * The actual invariant this map must encode is narrower than "reachable
+ * after a tainted if": a node N is genuinely INSIDE the branch rooted at
+ * successor B if and only if B DOMINATES N — every path from the function
+ * entry to N passes through B. A join point (reachable via the other
+ * branch, or via any path that bypasses the if) is by definition NOT
+ * dominated by B. This is exactly what `computeDominators` (shared with
+ * ir/ssa.js's SSA φ-node placement) computes, so reuse it instead of a
+ * path-dependent walk that structurally cannot distinguish "inside" from
+ * "after".
+ *
+ * One more wrinkle the CFG shape forces on us: parser-js.js's IfStatement
+ * lowering models a missing `else` as a DIRECT edge from the `if` node to
+ * the post-if join node (`if (!path.node.alternate) linkCfg(fn, condId,
+ * joinId)`), so `n.succ` for an else-less `if` is `[branchEntry, joinId]`
+ * — the join node is literally one of the "successors" too. Naively
+ * dominance-checking every successor as if it were a branch root treats
+ * `joinId` itself as something to dominate through, and `joinId` trivially
+ * dominates everything after it (there's no other way to reach that code),
+ * which resurrects the exact over-attribution this fix exists to close.
+ * Distinguish a genuine branch entry from a join/skip target structurally:
+ * a real branch entry has EXACTLY ONE predecessor — this `if` node itself.
+ * A join node always has a second predecessor (the branch's own tail, or —
+ * for the else-less case — this same direct skip edge), so it never
+ * qualifies.
  */
 export function buildImplicitContext(cfg, exprTaint) {
   const ctxByNid = new Map();
   if (!cfg || !cfg.nodes) return ctxByNid;
-  // Walk forward; track "depth" of how many tainted-branches we're nested in.
-  const visited = new Set();
-  const stack = [{ nid: cfg.entry, depth: 0, label: null }];
-  while (stack.length) {
-    const { nid, depth, label } = stack.pop();
-    if (visited.has(nid)) continue;
-    visited.add(nid);
-    if (depth > 0) ctxByNid.set(nid, { tainted: true, conditionLabel: label });
-    const n = cfg.nodes[nid];
-    if (!n) continue;
-    if (n.kind === 'if' && n.cond && exprTaint(n.cond)) {
-      // 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) });
+  const dom = computeDominators(cfg);
+  const predCount = new Map();
+  const soleParent = new Map();
+  for (const [pid, p] of Object.entries(cfg.nodes)) {
+    for (const s of (p?.succ || [])) {
+      predCount.set(s, (predCount.get(s) || 0) + 1);
+      if (!soleParent.has(s)) soleParent.set(s, pid);
+    }
+  }
+  for (const [nid, n] of Object.entries(cfg.nodes)) {
+    if (!n || n.kind !== 'if' || !n.cond || !exprTaint(n.cond)) continue;
+    // 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)) {
+      continue;
+    }
+    const label = _formatCondLabel(n.cond);
+    for (const branchRoot of (n.succ || [])) {
+      if (branchRoot === nid) continue; // guard against a malformed self-loop
+      // Not a genuine branch entry — it's a join/skip target reachable
+      // some other way too (see header). Marking it (or anything only
+      // reachable through it) would leak taint past the branch's real scope.
+      if ((predCount.get(branchRoot) || 0) !== 1 || soleParent.get(branchRoot) !== nid) continue;
+      for (const [candidate, domSet] of dom) {
+        if (candidate === nid) continue;
+        if (domSet && domSet.has(branchRoot) && !ctxByNid.has(candidate)) {
+          ctxByNid.set(candidate, { tainted: true, conditionLabel: label });
         }
       }
-    } 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: Math.max(depth - 1, 0), label });
-      }
-    } else {
-      for (const s of (n.succ || [])) {
-        stack.push({ nid: s, depth, label });
-      }
     }
   }
   return ctxByNid;

package/src/dataflow/incremental.js

@@ -162,9 +162,24 @@ export function seedSummaryCache(summaryCache, persisted, reusableQids) {
 }
 
 /**
- * Serialize a SummaryCache for persistence. Only persists summaries with
- * `_persistable: true` (set by the engine when the summary is independent
- * of an entry taint-state — typically pure functions or terminal sinks).
+ * Serialize a SummaryCache for persistence.
+ *
+ * ACTUAL current filter: excludes `_budgetExceeded` and `_recursive`
+ * summaries, and caps at MAX_PERSISTED_SUMMARIES. There is no
+ * context-independence filter — nothing in this codebase ever sets a
+ * `_persistable` flag (this comment previously claimed one existed and gated
+ * on it; grep confirms no such flag is set anywhere). Every non-recursive,
+ * non-budget-exceeded summary is persisted regardless of whether it depends
+ * on the entry taint-state it was computed under.
+ *
+ * OPEN QUESTION, not resolved by this comment fix: whether the reseeding
+ * side (`pickReusableSummaries`/`seedSummaryCache`) re-validates a persisted
+ * summary against the CALLER's actual entry taint-state before reuse, or
+ * trusts it as-is. If it trusts it as-is, a summary computed under one
+ * tainted-arg shape could be replayed for a call site with a different shape
+ * next scan — a real correctness question for the k-CFA context-sensitivity
+ * this cache exists to provide, worth a dedicated investigation rather than
+ * a guess made while reconciling documentation.
  *
  * Returns a plain object `{ qid: summary }` safe for JSON.stringify.
  */

package/src/dataflow/index.js

@@ -137,7 +137,8 @@ export function runDeepAnalysis(perFileIR, callGraph, opts = {}) {
   // stub signatures (loaded by ir/type-stubs.js when AGENTIC_SECURITY_TYPE_STUBS=1).
   // If a finding's source type is provably non-stringy (number, boolean,
   // Date, RegExp) AND the sink class can't be triggered by that type,
-  // demote the finding's severity.
+  // demote the finding's confidence/tier (recall-preserving — severity
+  // is never touched).
   if (process.env.AGENTIC_SECURITY_TYPE_STUBS === '1' && opts.scanRoot) {
     try {
       const stubs = loadProjectStubs(opts.scanRoot);

package/src/dataflow/proven-clean.js

@@ -110,17 +110,58 @@ function _findFunction(finding, perFileIR) {
   return chosen;
 }
 
+// Backward BFS via `pred` edges from `startId` — every node that can reach
+// `startId` by following the CFG forward from itself.
+function _backwardReachable(fn, startId) {
+  const visited = new Set();
+  const stack = [startId];
+  while (stack.length) {
+    const id = stack.pop();
+    if (visited.has(id)) continue;
+    visited.add(id);
+    const node = fn.cfg.nodes[id];
+    if (!node) continue;
+    for (const p of node.pred || []) stack.push(p);
+  }
+  return visited;
+}
+
 function _allCallNodesBetween(fn, trace, sinkLine) {
   if (!fn || !fn.cfg || !fn.cfg.nodes) return [];
   const earliestSrcLine = Math.min(
     ...trace.map(t => (typeof t.line === 'number' ? t.line : sinkLine))
   );
+  // Stage 3 correctness audit (detection depth): this used to be a pure
+  // line-number-range filter — ANY call node between the earliest source
+  // line and the sink line, anywhere in the function, regardless of
+  // whether it could ever actually execute before the sink. A
+  // parameterizer call inside an unrelated `if` branch that RETURNS
+  // before ever reaching the sink (a completely different, non-converging
+  // path) satisfied that filter and could falsely "prove" a genuinely
+  // vulnerable SQL concatenation on a different branch was clean — the
+  // dangerous direction for a proof gate, since `provenClean` de-emphasizes
+  // the finding in reports and risk scoring.
+  //
+  // Restrict candidates to nodes CFG-reachable as a predecessor of the
+  // sink's own node (backward BFS via `pred`): a call that cannot execute
+  // on ANY path leading to the sink is excluded. This is still not a full
+  // per-path proof (a parameterizer reachable via SOME but not ALL paths
+  // to the sink, or one that sanitizes an unrelated variable, still
+  // passes) — that's the v2 SMT work the module header already scopes
+  // out — but it closes the specific "unrelated branch that never reaches
+  // the sink at all" false-proof case.
+  const sinkNodeId = Object.keys(fn.cfg.nodes).find(id => {
+    const n = fn.cfg.nodes[id];
+    return n && n.kind === 'call' && n.line === sinkLine;
+  });
+  const reachable = sinkNodeId ? _backwardReachable(fn, sinkNodeId) : null;
   const out = [];
   for (const id of Object.keys(fn.cfg.nodes)) {
     const node = fn.cfg.nodes[id];
     if (!node || node.kind !== 'call') continue;
     if (typeof node.line !== 'number') continue;
     if (node.line < earliestSrcLine || node.line > sinkLine) continue;
+    if (reachable && !reachable.has(id)) continue;
     out.push({ line: node.line, callee: node.callee });
   }
   return out;

package/src/dataflow/sanitizer-gate.js

@@ -1,9 +1,12 @@
 // Generalised, recall-preserving sanitizer gate.
 //
-// The catalog carries 65 sanitizer entries tagged by family via `appliesTo`
-// (sql, xss, url, cmd). Before this module only `appliesTo: ['sql']` was ever
-// consumed — by proven-clean.js — so a correctly sanitized xss/url/cmd flow was
-// still reported at full confidence. That is a pure false-positive source.
+// The catalog carries 381 sanitizer entries (all languages, all kinds; count
+// via CATALOG.filter(e => e.kind === 'sanitizer').length — re-derive rather
+// than trust a hardcoded number here, since this comment has been wrong
+// before) tagged by family via `appliesTo` (sql, xss, url, cmd, *, …). Before
+// this module only `appliesTo: ['sql']` was ever consumed — by
+// proven-clean.js — so a correctly sanitized xss/url/cmd flow was still
+// reported at full confidence. That is a pure false-positive source.
 //
 // This gate NEVER removes a finding. It sets `sanitized` plus a proof object and
 // lets the existing proof gate in engine.js do the demotion, exactly as
@@ -15,20 +18,38 @@ import { CATALOG } from './catalog.js';
 
 // Map a finding to a sanitizer family using its CWE first (stable) and its vuln
 // text second (human-authored, so only a fallback).
+//
+// CWE-22 (path traversal) maps to the catalog's real 'path' family
+// (py-pathlib-resolve / cs-path-getfullpath / kt-path-canonical, all
+// appliesTo:['path']) — it used to collapse to 'url' alongside CWE-918/601,
+// which meant those genuine path-containment sanitizers could never match a
+// CWE-22 finding at all (permanently inert gate for that CWE), AND any
+// url-family sanitizer (URL-percent-encoding: encodeURIComponent etc.)
+// satisfied the family check for CWE-22/918/601 findings even though
+// percent-encoding neutralizes none of them. SSRF (CWE-918) and open
+// redirect (CWE-601) are host/scheme allow-list problems, not encoding
+// problems, and the catalog has no dedicated family for either — mapping
+// them to a family with zero real catalog matches (rather than borrowing
+// 'url') means this gate correctly never fires for them, leaving that
+// containment to engine.js's separate dropGuardedFindings host-allowlist
+// recognition instead of a false "proven clean" from an unrelated encoder.
 const _CWE_FAMILY = {
   'CWE-89': 'sql',
   'CWE-79': 'xss',
   'CWE-78': 'cmd',
-  'CWE-22': 'url',
-  'CWE-918': 'url',
-  'CWE-601': 'url',
+  'CWE-22': 'path',
+  'CWE-918': 'ssrf-host-allowlist-only',   // no catalog family — see above
+  'CWE-601': 'redirect-allowlist-only',    // no catalog family — see above
 };
 
 const _TEXT_FAMILY = [
   [/sql/i, 'sql'],
   [/xss|cross-site scripting/i, 'xss'],
   [/command injection/i, 'cmd'],
-  [/path traversal|ssrf|redirect/i, 'url'],
+  [/path traversal/i, 'path'],
+  // No catalog family for ssrf/redirect — deliberately no fallback entry
+  // (see the _CWE_FAMILY comment above); familyOfFinding returns null and
+  // applySanitizerGate's `if (!fam) continue;` safely no-ops.
 ];
 
 export function familyOfFinding(f) {
@@ -78,7 +99,12 @@ export function applySanitizerGate(findings, ctx) {
     if (!Array.isArray(observed) || !observed.length) continue;
     const matching = observed.filter(name => {
       const fams = index.get(name);
-      return fams && fams.has(fam);
+      // `*` is the catalog's universal tag, carried by the 17 type-coercion
+      // entries (parseInt/intval/Atoi/TryParse/…) that neutralise every
+      // injection family by making the value non-stringy. Matching it
+      // literally against 'sql'/'xss' never succeeds, which left that whole
+      // tier inert.
+      return fams && (fams.has(fam) || fams.has('*'));
     });
     if (!matching.length) continue;
     // Label only. The proof gate decides what to do with the label.

package/src/dataflow/sanitizer-proof.js

@@ -117,11 +117,29 @@ export function verifyProjectSanitizers(perFileIR, catalog) {
     if (!calleeName) continue;
     const fns = fnByName.get(calleeName);
     if (!fns || !fns.length) continue;            // not a project-local sanitizer
+    // Stage 3 correctness audit (detection depth): this used to take only
+    // `appliesTo[0]`, so a multi-family entry (`appliesTo: ['sql', 'xss']`)
+    // was only ever verified against its FIRST tag — silently skipping
+    // whether the project's local function actually behaves as a
+    // sanitizer for the OTHER families it claims to cover. It also fell
+    // back to the literal string `'*'` when `appliesTo` was absent or
+    // wildcard-only, and `'*'` has no entry in `_SHAPE_RULES` — every
+    // wildcard-tagged sanitizer (the 17 catalog type-coercion entries:
+    // parseInt, Number(), etc.) was unconditionally verdicted
+    // `trusted: false, reason: "no shape rule for family '*'"`, even
+    // though `'*'` legitimately covers every family by design (see
+    // sanitizer-gate.js's own header comment on the same wildcard tag).
+    // Fixed: verify against every concrete (non-'*') family the entry
+    // claims; a wildcard-only entry has no per-family shape to check
+    // against and contributes no verdict rather than a misleading false one.
+    const families = (Array.isArray(entry.appliesTo) ? entry.appliesTo : []).filter(f => f !== '*');
+    if (!families.length) continue;
     for (const fn of fns) {
       const bodyText = _stringifyCfgBody(fn);
-      const family = (entry.appliesTo && entry.appliesTo[0]) || '*';
-      const verdict = isValidSanitizerFor(bodyText, family);
-      out.push({ fnQid: fn.qid, family, trusted: verdict.trusted, reason: verdict.reason });
+      for (const family of families) {
+        const verdict = isValidSanitizerFor(bodyText, family);
+        out.push({ fnQid: fn.qid, family, trusted: verdict.trusted, reason: verdict.reason });
+      }
     }
   }
   return out;

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

@@ -17,10 +17,14 @@
 //   Cmd inj (CWE-78):   source type ∈ {number, boolean}               → demote
 //   Path trav (CWE-22): source type ∈ {number, boolean}               → demote
 //
-// Demotion lowers severity by one tier and sets `_stubTypeDemoted: true`
-// with a `_stubTypeReason`. We never DROP findings — the stub-aware
-// reason is shown to the operator so they can override if the stub is
-// wrong or out of date.
+// Demotion lowers confidence + confidenceTier + exploitabilityTier by one
+// step and sets `_stubTypeDemoted: true` with a `_stubTypeReason` — the
+// same recall-preserving shape every other precision annotator in this
+// directory uses (proof-gate.js, verification-separation.js). Severity is
+// never touched and findings are never DROPPED — the stub-aware reason is
+// shown to the operator so they can override if the stub is wrong or out
+// of date. (This module used to mutate severity directly; that violated
+// the convention and was flagged, not designed — see dataflow/CLAUDE.md.)
 
 const FAMILY_SAFE_TYPES = {
   'CWE-79':  new Set(['number', 'boolean', 'Date', 'RegExp', 'bigint']),
@@ -64,10 +68,33 @@ function _normalizeType(t) {
   return trimmed;
 }
 
+// Tier ladders, lowest → highest — identical shape to proof-gate.js's, kept
+// as a local copy rather than importing that module's test-only `_internals`
+// across a module boundary.
+const CONFIDENCE_TIERS = ['very-low', 'low', 'medium', 'high'];
+const EXPLOITABILITY_TIERS = ['low', 'medium', 'high', 'critical'];
+const CONFIDENCE_DEMOTE_FACTOR = 0.4;
+
+function _demoteTier(tier, ladder) {
+  const i = ladder.indexOf(tier);
+  if (i <= 0) return ladder[0];
+  return ladder[i - 1];
+}
+
+function _demote(f) {
+  if (typeof f.confidence === 'number') {
+    f._confidenceBeforeStubFilter = f.confidence;
+    f.confidence = Math.max(0.01, Number((f.confidence * CONFIDENCE_DEMOTE_FACTOR).toFixed(4)));
+  }
+  if (f.confidenceTier) f.confidenceTier = _demoteTier(f.confidenceTier, CONFIDENCE_TIERS);
+  if (f.exploitabilityTier) f.exploitabilityTier = _demoteTier(f.exploitabilityTier, EXPLOITABILITY_TIERS);
+}
+
 /**
  * Post-pass entry. Mutates findings in place: adds `_stubTypeDemoted`,
- * `_stubTypeReason`, downgrades `severity` by one tier when the source
- * type is in the family-safe set for the finding's CWE.
+ * `_stubTypeReason`, demotes confidence/confidenceTier/exploitabilityTier
+ * by one step when the source type is in the family-safe set for the
+ * finding's CWE. Severity is never touched (recall-preserving).
  *
  * Returns the (mutated) findings array with `_stubFilterStats` non-
  * enumerable sidecar.
@@ -131,9 +158,7 @@ export function applyStubAwareFilter(findings, stubs, perFileIR) {
     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];
+      _demote(f);
       demoted++;
       continue;
     }
@@ -142,9 +167,7 @@ export function applyStubAwareFilter(findings, stubs, 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];
+      _demote(f);
       demoted++;
     }
   }
@@ -155,4 +178,4 @@ export function applyStubAwareFilter(findings, stubs, perFileIR) {
   return findings;
 }
 
-export const _internal = { FAMILY_SAFE_TYPES, _sourceTypeFromStubs, _normalizeType };
+export const _internal = { FAMILY_SAFE_TYPES, _sourceTypeFromStubs, _normalizeType, CONFIDENCE_TIERS, EXPLOITABILITY_TIERS, _demoteTier };

package/src/dataflow/summaries.js

@@ -28,7 +28,13 @@
 //   - Field sensitivity is at the parameter granularity only (not arbitrary
 //     access paths). `f(obj)` with obj.foo tainted is treated the same as
 //     obj.bar tainted.
-//   - No higher-order tracking — callbacks passed as args aren't analyzed.
+//   - Higher-order tracking IS modelled, in engine.js (not here): a callback
+//     passed as an argument is recorded via `_higherOrderInvocations`, then
+//     resolved and analyzed with the callback's own tainted parameter, with
+//     its findings merged back into the caller (`higher-order.js`). This
+//     summary cache is unaware of it; the higher-order path is a separate
+//     mechanism layered on top by the caller. (This bullet previously said
+//     no such tracking existed at all, which was true only of THIS module.)
 //   - Recursion: when we'd recurse into a function already on the analysis
 //     stack, we return the bottom summary (no-taint) and rely on fixed-point
 //     iteration. With k=1 this converges in ≤2 iterations for typical code.
@@ -185,10 +191,23 @@ export class SummaryCache {
   clear() { this._cache.clear(); this._iter = 0; this._contextsByQid.clear(); this._contextCapHits = 0; }
 }
 
+// Stage 3 correctness audit (detection depth): this compared mutatedParams
+// by SIZE only, not membership — two summaries with the same cardinality
+// but different members (e.g. {'fieldA'} vs {'fieldB'}, plausible across
+// fixed-point iterations of a recursive helper whose mutated-target
+// identity depends on recursion depth) were treated as equal. compute()'s
+// fixed-point loop (above) then `break`s WITHOUT caching the just-computed
+// `summary` — but still returns it to its immediate caller. Any OTHER,
+// later call site doing a plain cache `.get(qid, sameEntry)` would then
+// silently receive the stale `prev` summary the loop declared "equal to"
+// the fresher one it never cached.
 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;
+  const am = a.mutatedParams || new Set();
+  const bm = b.mutatedParams || new Set();
+  if (am.size !== bm.size) return false;
+  for (const p of am) if (!bm.has(p)) return false;
   return true;
 }