@clear-capabilities/agentic-security-scanner 0.74.0

package/src/dataflow/string-domain.js

@@ -0,0 +1,234 @@
+// String-value abstract domain (P4.4).
+//
+// The taint engine treats every string as opaque — "tainted" or "clean."
+// Real codebases have lots of strings that are KNOWN at compile time:
+//
+//   const url = "https://internal.example.com/health";
+//   await fetch(url);
+//
+// `url` is constant. SSRF is *impossible*. The current engine doesn't fire
+// (because the literal isn't tainted), but it ALSO doesn't actively prove
+// safety — and when a project mixes constants with user-influenced fragments,
+// the engine over-approximates conservatively.
+//
+// This module models strings with a three-element lattice:
+//
+//   Const(literal)         "https://internal.example.com"
+//   Concat(parts)          "https://" + host + "/" + path
+//   Unknown                anything we can't statically analyze
+//
+// And provides:
+//   - abstract(expr) → returns the abstract value for an IR expression
+//   - isSafeUrl(absVal, allowedHosts) → bool, prove the URL is safe
+//   - join(a, b) → lattice meet (used at branch joins)
+//
+// v1: enough to handle the common SSRF / open-redirect "constant URL" case.
+// v2 would add prefix/suffix analysis, regex membership, etc.
+
+export const TOP = { kind: 'Unknown' };
+export const BOTTOM = { kind: 'Const', value: '' };   // empty string = bottom of useful domain
+
+export function makeConst(value) {
+  if (typeof value !== 'string') return TOP;
+  return { kind: 'Const', value };
+}
+
+/**
+ * v0.69 #4a — regex-constrained string value.
+ *
+ * Represents a string whose concrete value is unknown but whose CHARSET +
+ * SHAPE are bounded to a regex. Sanitizers produce these:
+ *   encodeURIComponent(x) → Regex(/^[A-Za-z0-9-_.!~*'()%]*$/)
+ *   parseInt(x).toString() → Regex(/^-?\d+$/)
+ *   bcrypt.hash(x) → Regex(/^\$2[aby]?\$\d{1,2}\$[./A-Za-z0-9]{53}$/)
+ *
+ * The pattern MUST be anchored with ^ and $ to be sound.
+ */
+export function makeRegex(pattern) {
+  if (!(pattern instanceof RegExp)) return TOP;
+  const src = pattern.source;
+  if (!src.startsWith('^') || !src.endsWith('$')) return TOP;
+  return { kind: 'Regex', pattern };
+}
+
+export function makeConcat(parts) {
+  // Optimize: if every part is Const, collapse to a single Const.
+  if (parts.every(p => p && p.kind === 'Const')) {
+    return makeConst(parts.map(p => p.value).join(''));
+  }
+  // If any part is Unknown, the whole concat is Unknown.
+  if (parts.some(p => !p || p.kind === 'Unknown')) return TOP;
+  return { kind: 'Concat', parts };
+}
+
+/**
+ * Lattice join: a ⊔ b. Returns the least-upper-bound.
+ *
+ *   Const(s) ⊔ Const(s) = Const(s)
+ *   Const(s) ⊔ Const(t) = Regex(escape(s)|escape(t)) if both anchor-friendly
+ *   Regex(p) ⊔ Const(s) where s matches p = Regex(p)
+ *   Regex(p1) ⊔ Regex(p2) = Regex(p1) if patterns identical, else TOP
+ *   anything ⊔ Unknown = Unknown
+ */
+export function join(a, b) {
+  if (!a) return b;
+  if (!b) return a;
+  if (a.kind === 'Unknown' || b.kind === 'Unknown') return TOP;
+  if (a.kind === 'Const' && b.kind === 'Const') {
+    if (a.value === b.value) return a;
+    return TOP;     // distinct constants from two branches — be conservative
+  }
+  if (a.kind === 'Regex' && b.kind === 'Regex') {
+    return a.pattern.source === b.pattern.source ? a : TOP;
+  }
+  if (a.kind === 'Regex' && b.kind === 'Const') {
+    return a.pattern.test(b.value) ? a : TOP;
+  }
+  if (b.kind === 'Regex' && a.kind === 'Const') {
+    return b.pattern.test(a.value) ? b : TOP;
+  }
+  return TOP;
+}
+
+/**
+ * Abstract an IR expression into a string-value abstract value. The engine
+ * walks expressions during evaluation; this helper gives us the
+ * `Const | Concat | Unknown` summary alongside the boolean taint check.
+ */
+export function abstract(expr) {
+  if (!expr) return TOP;
+  switch (expr.kind) {
+    case 'literal':
+      if (typeof expr.value === 'string') return makeConst(expr.value);
+      return TOP;
+    case 'tpl':
+      if (Array.isArray(expr.parts)) return makeConcat(expr.parts.map(abstract));
+      return TOP;
+    case 'binary': {
+      if (expr.op === '+' || expr.op === '+=') {
+        return makeConcat([abstract(expr.left), abstract(expr.right)]);
+      }
+      return TOP;
+    }
+    case 'call': {
+      // v0.69 #4a — sanitizer-call output is regex-constrained.
+      const tail = String(expr.callee || '').split('.').pop();
+      const r = SANITIZER_OUTPUT_REGEX[tail];
+      if (r) return makeRegex(r);
+      return TOP;
+    }
+    default:
+      return TOP;
+  }
+}
+
+/**
+ * Catalog of known sanitizer output regexes. The output of these calls is
+ * provably bounded to the listed charset. This is what powers the
+ * `provenClean` flag for non-SQL injection classes.
+ *
+ * Patterns are conservative — only listed when the spec REQUIRES the
+ * output to fit the regex. Empty / null returns are part of the domain.
+ */
+const SANITIZER_OUTPUT_REGEX = {
+  // URL-safe encoding (RFC 3986 reserved + unreserved with %xx escapes).
+  encodeURIComponent: /^[A-Za-z0-9\-_.!~*'()%]*$/,
+  encodeURI:          /^[A-Za-z0-9\-_.!~*'();/?:@&=+$,#%]*$/,
+  // Numeric-coerced.
+  parseInt:           /^-?\d+$/,
+  parseFloat:         /^-?\d+(?:\.\d+)?$/,
+  // bcrypt / scrypt output format.
+  hashSync:           /^\$2[aby]?\$\d{1,2}\$[.\/A-Za-z0-9]{53}$/,
+  // Hex digest from crypto.
+  digest:             /^[0-9a-f]+$/,
+  toString:           /^[A-Za-z0-9+/=]*$/,    // when called on a Buffer with 'base64' — over-approximate, narrowed by argIndex in v2
+  // Java URLEncoder.encode — RFC 3986 + spaces as '+'.
+  // (We can't distinguish overloads from regex name alone; conservative listing.)
+  // PHP htmlspecialchars / htmlentities — HTML-entity escape.
+  htmlspecialchars:   /^[^<>&"']*(?:&(?:lt|gt|amp|quot|#039);)*[^<>&"']*$/,
+};
+
+/**
+ * SAFE-CHARSET PROOF — does the abstract value provably fit the given regex?
+ *
+ * Used by sanitizer-proof.js to verify that a sanitizer's output cannot
+ * contain the metacharacters of a target injection family (no `'` for SQL,
+ * no `<` for XSS, no `\r\n` for response-splitting, etc.).
+ *
+ * Returns true iff EVERY concrete string in the abstract value's denotation
+ * matches `safe`.
+ */
+export function provablyMatches(absVal, safe) {
+  if (!absVal || !(safe instanceof RegExp)) return false;
+  if (absVal.kind === 'Const') return safe.test(absVal.value);
+  if (absVal.kind === 'Regex') {
+    // Sound approximation: same source string → provable. Otherwise we'd
+    // need regex-subset, which is undecidable in general; v2 could do
+    // structural checks for common cases.
+    return absVal.pattern.source === safe.source;
+  }
+  if (absVal.kind === 'Concat') {
+    // A concat is provably safe iff every part is provably safe AND the
+    // safe regex permits arbitrary repetition (i.e. is of the form ^X*$).
+    if (!/^\^.+\*\$$/.test(safe.source)) return false;
+    return absVal.parts.every(p => provablyMatches(p, safe));
+  }
+  return false;
+}
+
+/**
+ * Render an abstract string back to a textual form for diagnostics.
+ *
+ *   Const("hello") → "hello"
+ *   Concat([Const("a"), Unknown, Const("b")]) → "a${...}b"
+ *   Unknown → "${...}"
+ */
+export function render(absVal) {
+  if (!absVal || absVal.kind === 'Unknown') return '${...}';
+  if (absVal.kind === 'Const') return absVal.value;
+  if (absVal.kind === 'Concat') {
+    return absVal.parts.map(p => render(p)).join('');
+  }
+  if (absVal.kind === 'Regex') return `${absVal.pattern.source}`;
+  return '${...}';
+}
+
+/**
+ * SSRF guard: given an abstract URL value and a list of trusted hosts,
+ * return true iff the URL is provably to one of the trusted hosts.
+ *
+ *   isProvablyToHost(makeConst("https://internal.example.com/x"), ["internal.example.com"]) → true
+ *   isProvablyToHost(TOP, [...]) → false (can't prove anything about Unknown)
+ *   isProvablyToHost(Concat(["https://" + Unknown]), [...]) → false
+ */
+export function isProvablyToHost(absVal, allowedHosts) {
+  if (!absVal || absVal.kind !== 'Const') return false;
+  if (!Array.isArray(allowedHosts) || !allowedHosts.length) return false;
+  let url;
+  try {
+    url = new URL(absVal.value);
+  } catch { return false; }
+  return allowedHosts.includes(url.host);
+}
+
+/**
+ * Open-redirect safe? An abstract URL value passed to res.redirect is safe
+ * when it's either provably to an allowed host OR a relative path with no
+ * scheme/host parts.
+ */
+export function isSafeRedirectTarget(absVal, allowedHosts) {
+  if (!absVal) return false;
+  if (absVal.kind === 'Const') {
+    // Relative path starting with / and not //
+    if (/^\/(?!\/)/.test(absVal.value)) return true;
+    return isProvablyToHost(absVal, allowedHosts);
+  }
+  return false;
+}
+
+/**
+ * Hash an abstract value for cache-key purposes.
+ */
+export function hashAbstract(absVal) {
+  return render(absVal);
+}

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

@@ -0,0 +1,100 @@
+// Type-stub-aware taint filter (v0.73).
+//
+// v0.70 added scanner/src/ir/type-stubs.js but only wired it into the
+// receiver-context lookup. This post-pass closes the loop: after the
+// taint engine emits findings, we consult the stubs map to demote
+// findings whose source/sink type pair is provably incompatible with
+// the vulnerability class.
+//
+// Example: a source that returns `number` (per stub signature) flowing
+// to an XSS sink is suppressable — a number coerced to string can only
+// produce digits/decimal/sign, which can't form the metacharacters
+// (<, >, ', ") required to break out of an HTML context.
+//
+// Rules per vuln family:
+//   XSS (CWE-79):       source type ∈ {number, boolean, Date, RegExp} → demote
+//   SQL inj (CWE-89):   source type ∈ {number, boolean, Date}         → demote
+//   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.
+
+const FAMILY_SAFE_TYPES = {
+  'CWE-79':  new Set(['number', 'boolean', 'Date', 'RegExp', 'bigint']),
+  'CWE-89':  new Set(['number', 'boolean', 'Date', 'bigint']),
+  'CWE-78':  new Set(['number', 'boolean', 'bigint']),
+  'CWE-22':  new Set(['number', 'boolean']),
+  'CWE-918': new Set(['number', 'boolean']),
+};
+
+/**
+ * Try to resolve the type of the finding's source from the type-stubs map.
+ * The lookup chain: (1) the finding's source.label or trace[0].sourceLabel
+ * is the catalog source id; (2) the stub signature for the source's
+ * underlying function. Returns the type string ('string', 'number', …)
+ * or null if unknown.
+ */
+function _sourceTypeFromStubs(finding, stubs) {
+  if (!stubs || !stubs.signatures) return null;
+  const trace = Array.isArray(finding.trace) ? finding.trace : [];
+  const src = trace[0] || finding.source;
+  const label = src?.sourceLabel || src?.label || '';
+  // The label is shaped like 'req.body' / 'request.GET' / etc. The
+  // underlying function lookup uses the LAST identifier as a callable name.
+  const tail = String(label).split('.').pop();
+  if (!tail) return null;
+  const sig = stubs.signatures.get(tail);
+  if (!sig) return null;
+  return _normalizeType(sig.returnType);
+}
+
+function _normalizeType(t) {
+  if (!t) return null;
+  const trimmed = String(t).trim().toLowerCase();
+  if (trimmed === 'number' || trimmed === 'numeric' || /^int(8|16|32|64)?$/.test(trimmed)) return 'number';
+  if (trimmed === 'bigint') return 'bigint';
+  if (trimmed === 'boolean' || trimmed === 'bool') return 'boolean';
+  if (trimmed === 'date')   return 'Date';
+  if (trimmed === 'regexp') return 'RegExp';
+  if (trimmed === 'string' || trimmed === 'str') return 'string';
+  if (trimmed.endsWith('[]') || trimmed.startsWith('array<')) return 'array';
+  return trimmed;
+}
+
+/**
+ * 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.
+ *
+ * Returns the (mutated) findings array with `_stubFilterStats` non-
+ * enumerable sidecar.
+ */
+export function applyStubAwareFilter(findings, stubs) {
+  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++;
+  }
+  Object.defineProperty(findings, '_stubFilterStats', {
+    value: { demoted, totalConsidered: findings.length },
+    enumerable: false,
+  });
+  return findings;
+}
+
+export const _internal = { FAMILY_SAFE_TYPES, _sourceTypeFromStubs, _normalizeType };

package/src/dataflow/summaries.js

@@ -0,0 +1,132 @@
+// Function-summary cache for context-sensitive interprocedural taint.
+//
+// PRD §6.2: "k-CFA configurable per analysis." This module implements the
+// k=1 monovariant version — each function gets ONE summary per distinct
+// entry-taint-state, cached by hash. Higher k = exponential blowup we don't
+// pay yet.
+//
+// A summary captures, given a set of tainted parameter names at function
+// entry, what the function does:
+//   - which return value(s) are tainted
+//   - which call-site arguments get mutated to tainted (by-reference)
+//   - which global / module variables get tainted
+//   - which findings emit
+//
+// The taint engine (engine.js) consults the summary cache before re-analyzing
+// a callee. Cache key = `${qid}::${sorted-taint-state}`. Cache hits are O(1).
+//
+// Limitations:
+//   - 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.
+//   - 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.
+
+import * as crypto from 'node:crypto';
+import { canonicalize as canonicalizeAccessSet } from './access-paths.js';
+import { hashReceiverType } from './receiver-context.js';
+
+function _hashState(taintedParams) {
+  if (!taintedParams || taintedParams.size === 0) return 'empty';
+  // P1.1: canonicalize the access-path lattice before hashing so equivalent
+  // states (e.g. {"x", "x.y"} and {"x"}) produce the same cache key.
+  const canon = canonicalizeAccessSet(taintedParams);
+  const sorted = [...canon].sort().join('|');
+  return crypto.createHash('sha256').update(sorted).digest('hex').slice(0, 12);
+}
+
+export class SummaryCache {
+  constructor() {
+    this._cache = new Map(); // qid::hash → summary
+    this._stack = new Set(); // qids currently being analyzed (recursion guard)
+    this._iter = 0;
+    this._maxIter = 5000;
+  }
+
+  _key(qid, taintedParams, receiverType) {
+    // P1.2: when a receiver type is provided, extend the cache key with
+    // its hash. Backward-compatible: no receiverType → same key as before.
+    const base = `${qid}::${_hashState(taintedParams)}`;
+    if (!receiverType) return base;
+    return `${base}::${hashReceiverType(receiverType)}`;
+  }
+
+  get(qid, taintedParams, receiverType) {
+    return this._cache.get(this._key(qid, taintedParams, receiverType));
+  }
+
+  set(qid, taintedParams, summary, receiverType) {
+    this._cache.set(this._key(qid, taintedParams, receiverType), summary);
+  }
+
+  has(qid, taintedParams, receiverType) {
+    return this._cache.has(this._key(qid, taintedParams, receiverType));
+  }
+
+  // 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: [] }
+  compute(qid, taintedParams, analyze) {
+    const k = this._key(qid, taintedParams);
+    if (this._cache.has(k)) return this._cache.get(k);
+    if (this._stack.has(qid)) {
+      // Recursion — return bottom summary; fixed-point iter will refine.
+      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);
+    try {
+      const summary = analyze(qid, taintedParams);
+      this._cache.set(k, summary);
+      return summary;
+    } finally {
+      this._stack.delete(qid);
+    }
+  }
+
+  // Helper: apply a summary to a caller's taint state given the call site's
+  // argument bindings. Returns { calleeReturnTainted, mutated: Set of caller-side
+  // var names that should become tainted because the callee mutated them }.
+  applyAtCallSite(summary, paramNames, callArgs, callerTaintedVars) {
+    if (!summary) return { returnTainted: false, mutated: new Set() };
+    const mutated = new Set();
+    if (summary.mutatedParams && summary.mutatedParams.size) {
+      // Map each mutated parameter position back to the caller-side argument name.
+      for (const paramName of summary.mutatedParams) {
+        const idx = paramNames.indexOf(paramName);
+        if (idx < 0) continue;
+        const arg = callArgs[idx];
+        if (arg && arg.kind === 'ident') mutated.add(arg.name);
+      }
+    }
+    return { returnTainted: !!summary.returnTainted, mutated };
+  }
+
+  size() { return this._cache.size; }
+  clear() { this._cache.clear(); this._iter = 0; }
+}
+
+// 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.
+export function entryStateFromCall(paramNames, callArgs, callerTaintedVars) {
+  const out = new Set();
+  if (!Array.isArray(paramNames) || !Array.isArray(callArgs)) return out;
+  for (let i = 0; i < paramNames.length && i < callArgs.length; i++) {
+    const arg = callArgs[i];
+    if (!arg) continue;
+    if (arg.kind === 'ident' && callerTaintedVars.has(arg.name)) {
+      out.add(paramNames[i]);
+    } else if (arg.kind === 'member' && arg.object?.kind === 'ident') {
+      const base = arg.object.name;
+      if (callerTaintedVars.has(base) || callerTaintedVars.has(`${base}.${arg.prop}`)) {
+        out.add(paramNames[i]);
+      }
+    }
+  }
+  return out;
+}