@clear-capabilities/agentic-security-scanner 0.184.0 → 0.186.1

package/src/dataflow/access-paths.js

@@ -153,9 +153,13 @@ export function canonicalize(set) {
   const sorted = [...set].sort((a, b) => a.length - b.length || (a < b ? -1 : 1));
   const out = new Set();
   for (const path of sorted) {
+    // A kept path covers `path` exactly when it is one of the dot-delimited prefixes of it, so look those up
+    // (a handful per path) instead of testing every kept path (the set can hold hundreds in a large function).
     let covered = false;
-    for (const existing of out) {
-      if (pathIsCoveredByPrefix(path, existing)) { covered = true; break; }
+    if (typeof path === 'string') {
+      for (let i = path.indexOf('.'); i >= 0; i = path.indexOf('.', i + 1)) {
+        if (out.has(path.slice(0, i))) { covered = true; break; }
+      }
     }
     if (!covered) out.add(path);
   }
@@ -176,6 +180,12 @@ export function hashSet(set) {
 export function setsEqual(a, b) {
   if (a === b) return true;
   if (!a || !b) return false;
+  // Identical members are equal under any canonicalization; only a difference needs the canonical forms.
+  if (a.size === b.size) {
+    let same = true;
+    for (const x of a) if (!b.has(x)) { same = false; break; }
+    if (same) return true;
+  }
   const ca = canonicalize(a), cb = canonicalize(b);
   if (ca.size !== cb.size) return false;
   for (const x of ca) if (!cb.has(x)) return false;

package/src/dataflow/backward.js

@@ -49,6 +49,15 @@ function _reverseEdges(cfg) {
   return rev;
 }
 
+/**
+ * CFG reverse-edge index (node id -> predecessor ids), exported so the demand
+ * selector (demand-query.js) and this slicer share one definition of the
+ * incoming-edge relation instead of each deriving its own.
+ */
+export function reverseEdgesOf(cfg) {
+  return _reverseEdges(cfg);
+}
+
 /**
  * Build a backward slice from a finding's sink site to its source(s).
  *
@@ -75,10 +84,28 @@ function _reverseEdges(cfg) {
  *   ]
  */
 export function sliceBackward(fn, sinkNode, sinkArgPath) {
+  return sliceBackwardWithCompletion(fn, sinkNode, sinkArgPath).slice;
+}
+
+/**
+ * Same slice, plus a completion record (DAG-07 R07.1): { slice, completion }.
+ * A slice that stopped at SLICE_BUDGET_NODES is a prefix of the real
+ * backward closure; the record carries how many queued steps were left, so a
+ * consumer (the SMT infeasibility check among them) can tell "no source
+ * found" from "stopped looking". `sliceBackward` itself still returns the
+ * bare array for existing callers, with the same record attached as a
+ * non-enumerable `completion` property.
+ */
+export function sliceBackwardWithCompletion(fn, sinkNode, sinkArgPath) {
   const out = [];
-  if (!fn || !sinkNode) return out;
+  const completion = { status: 'complete', reasons: [], unexploredFrontierCount: 0, visited: 0, limits: { maxNodes: SLICE_BUDGET_NODES } };
+  const finish = () => {
+    Object.defineProperty(out, 'completion', { value: completion, enumerable: false, configurable: true });
+    return { slice: out, completion };
+  };
+  if (!fn || !sinkNode) { completion.status = 'unavailable'; completion.reasons = ['no-function-or-sink']; return finish(); }
   const cfg = fn.cfg;
-  if (!cfg || !cfg.nodes) return out;
+  if (!cfg || !cfg.nodes) { completion.status = 'unavailable'; completion.reasons = ['no-cfg']; return finish(); }
   const rev = _reverseEdges(cfg);
 
   // Map node-id to itself lookup for nodes in this CFG.
@@ -90,7 +117,7 @@ export function sliceBackward(fn, sinkNode, sinkArgPath) {
   for (const id of Object.keys(nodes)) {
     if (nodes[id] === sinkNode) { sinkNid = id; break; }
   }
-  if (!sinkNid) return out;
+  if (!sinkNid) { completion.status = 'unavailable'; completion.reasons = ['sink-not-in-cfg']; return finish(); }
 
   out.push({
     line: sinkNode.line || 0,
@@ -104,7 +131,12 @@ export function sliceBackward(fn, sinkNode, sinkArgPath) {
   let visitedCount = 0;
 
   while (work.length) {
-    if (++visitedCount > SLICE_BUDGET_NODES) break;
+    if (++visitedCount > SLICE_BUDGET_NODES) {
+      completion.status = 'partial';
+      completion.reasons = ['slice-node-budget'];
+      completion.unexploredFrontierCount = work.length;
+      break;
+    }
     const { nid, queryPath } = work.shift();
     const key = `${nid}::${queryPath}`;
     if (visited.has(key)) continue;
@@ -206,8 +238,10 @@ export function sliceBackward(fn, sinkNode, sinkArgPath) {
     }
   }
 
+  completion.visited = Math.min(visitedCount, SLICE_BUDGET_NODES);
   // Reverse so the trace reads source-first.
-  return out.reverse();
+  out.reverse();
+  return finish();
 }
 
 /**
@@ -233,7 +267,7 @@ export function annotateBackwardSlices(findings, perFileIR, callGraph) {
   if (callGraph && callGraph.functions) {
     for (const fn of callGraph.functions.values()) fnByQid.set(fn.qid, fn);
   }
-  let annotated = 0, skipped = 0, exhausted = false;
+  let annotated = 0, skipped = 0, exhausted = false, partialSlices = 0;
   for (const f of findings) {
     if (Date.now() > deadline) { exhausted = true; skipped++; continue; }
     if (!f || !f._funcQid) { skipped++; continue; }
@@ -278,6 +312,7 @@ export function annotateBackwardSlices(findings, perFileIR, callGraph) {
         if (!slice) slice = candidateSlice;
       }
     }
+    if (slice && slice.completion && slice.completion.status !== 'complete') partialSlices++;
     if (slice && slice.length) {
       f.backwardSlice = slice;
       f.pathSteps = (f.pathSteps || []).concat(slice.map(s => ({
@@ -291,7 +326,7 @@ export function annotateBackwardSlices(findings, perFileIR, callGraph) {
     }
   }
   Object.defineProperty(findings, '_annotateBackwardSlicesStats', {
-    value: { annotated, skipped, exhausted, budgetMs },
+    value: { annotated, skipped, exhausted, budgetMs, partialSlices },
     enumerable: false,
   });
   return findings;

package/src/dataflow/cross-service-taint.js

@@ -63,6 +63,8 @@ import * as path from 'node:path';
 import * as yaml from '../util/yaml.js';
 
 import { statePath } from '../posture/state-dir.js';
+import { runTaintEngine } from './engine.js';
+import { bindBoundaryContracts, boundaryAttribution, BOUNDARY_CONTRACTS_FILENAME, validateBoundaryContract } from '../lineage/boundary-contract.js';
 const SERVICES_FILE_NAMES = ['services.yml', 'services.yaml'];
 
 export function loadServiceGraph(scanRoot) {
@@ -342,4 +344,84 @@ export function runCrossServiceTaint(scanRoot, findings) {
   return annotateCrossServiceFindings(findings, graph, current);
 }
 
-export const _internals = { _normalizeGraph, SERVICES_FILE_NAMES, _pathTemplateMatches, _escapeRegex };
+// ─── DAG-08: boundary-contract consumer seeding ──────────────────────────────
+//
+// The SCOPE NOTE above stays true of the `consumes` annotation pass: it never invents a source. This section is the separate,
+// explicit mechanism that does. A versioned boundary contract (lineage/boundary-contract.js) that BINDS to a parser-resolved
+// consumer function and parameter seeds the declared, mapped fields of that parameter as a MODELED untrusted input. The seed is
+// handed to the engine through `fn.boundarySeeds` (read by engine.js's `_unionAnnotationTaint`) for the duration of one run and
+// always removed afterwards, so the shared call graph is never left seeded.
+//
+// A finding produced this way carries `boundary: {..., modeledInput: true, observed: false, exploited: false}`. A declaration
+// establishes where taint is assumed to enter; it never establishes that a value was seen or that the sink is exploitable. A
+// contract that does not bind produces a coverage gap and NO finding.
+
+const DEFAULT_MAX_BOUNDARY_RUNS = 64;
+
+function loadBoundaryContracts(scanRoot) {
+  if (!scanRoot) return { contracts: [], errors: [] };
+  const fp = statePath(scanRoot, BOUNDARY_CONTRACTS_FILENAME);
+  if (!fs.existsSync(fp)) return { contracts: [], errors: [] };
+  try {
+    const doc = JSON.parse(fs.readFileSync(fp, 'utf8'));
+    const list = Array.isArray(doc) ? doc : Array.isArray(doc && doc.contracts) ? doc.contracts : [];
+    return { contracts: list, errors: [] };
+  } catch (e) {
+    return { contracts: [], errors: [`Failed to parse ${fp}: ${e.message}`] };
+  }
+}
+
+/**
+ * Run the taint engine with each bound contract's consumer fields seeded, one seed at a time so a finding is attributed to the
+ * exact consumer field that reached it (a sibling field the contract does not map is never seeded and so never attributed).
+ * When `contracts` is null/undefined they are read from `<scanRoot>/.agentic-security/boundary-contracts.json` (opts.scanRoot).
+ * @returns {{findings: object[], bindings: object[], gaps: object[], rejected: object[], coverage: object, loadErrors: string[]}}
+ */
+export function runBoundaryTaint(perFileIR, callGraph, contracts, opts = {}) {
+  let loadErrors = [];
+  if (contracts === null || contracts === undefined) { const l = loadBoundaryContracts(opts.scanRoot); contracts = l.contracts; loadErrors = l.errors; }
+  const maxRuns = Number.isFinite(opts.maxRuns) ? opts.maxRuns : DEFAULT_MAX_BOUNDARY_RUNS;
+  const { bindings, gaps, rejected } = bindBoundaryContracts(contracts, callGraph);
+  const fnByQid = new Map();
+  for (const f of callGraph.functions.values()) fnByQid.set(f.qid, f);
+  const baseline = new Set(runTaintEngine(perFileIR, callGraph, opts.engine || {}).map((f) => f.id));
+  const found = new Map();
+  let runs = 0; let truncated = false;
+  for (const b of bindings) {
+    const fn = fnByQid.get(b.qid);
+    for (const seed of b.seeds) {
+      if (runs >= maxRuns) { truncated = true; break; }
+      runs++;
+      const prior = fn.boundarySeeds;
+      fn.boundarySeeds = [seed];
+      let out = [];
+      try { out = runTaintEngine(perFileIR, callGraph, opts.engine || {}); } finally { if (prior === undefined) delete fn.boundarySeeds; else fn.boundarySeeds = prior; }
+      const mapping = b.mappedFields.find((m) => seed.endsWith(`.${m.to}`) || seed === m.to) || null;
+      for (const f of out) {
+        if (baseline.has(f.id)) continue;
+        let rec = found.get(f.id);
+        if (!rec) { rec = { finding: { ...f }, attributions: [] }; found.set(f.id, rec); }
+        rec.attributions.push({ binding: b, seed, mapping });
+      }
+    }
+    if (truncated) break;
+  }
+  const findings = [...found.values()].map(({ finding, attributions }) => {
+    const first = attributions[0];
+    finding.boundary = {
+      ...boundaryAttribution(first.binding),
+      fields: attributions.map((a) => ({ seed: a.seed, producerField: a.mapping && a.mapping.from, consumerField: a.mapping && a.mapping.to })),
+      discoveredBy: 'boundary-contract-seed',
+    };
+    finding.boundarySeeded = true;
+    return finding;
+  }).sort((a, b) => (a.id < b.id ? -1 : 1));
+  const allGaps = [...gaps];
+  if (truncated) allGaps.push({ kind: 'budget', reason: 'engine-run-budget', detail: `stopped after ${maxRuns} seeded runs; remaining seeds were not analyzed` });
+  return {
+    findings, bindings, gaps: allGaps, rejected, loadErrors,
+    coverage: { contracts: (contracts || []).length, bound: bindings.length, unbound: gaps.filter((g) => g.side === 'consumer').length, rejected: rejected.length, engineRuns: runs, truncated },
+  };
+}
+
+export const _internals = { _normalizeGraph, SERVICES_FILE_NAMES, _pathTemplateMatches, _escapeRegex, validateBoundaryContract };