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

package/src/posture/witness-runtime.js

@@ -0,0 +1,276 @@
+// Runtime support, feasibility and exploit-proof evidence for a path witness (DAG-10, R10.3 to R10.7).
+//
+// Pure: no fs, no network, never throws, never mutates its inputs. It READS the per-edge states that
+// `lineage/runtime-edge-states.js` already derives and adds the one thing those states cannot say: whether
+// the observed edges of a path belong to ONE execution.
+//
+// FOUR EVIDENCE STATUSES, NEVER MERGED
+// ------------------------------------
+//   modeledPath    the static analysis connected source to sink (complete or partial)
+//   feasibility    a predicate / control check on the path (a nullable slot until DAG-04 supplies it)
+//   runtimeSupport what telemetry says about the path (this file)
+//   exploitProof   explicit, execution-backed proof bound to this sink, value and configuration
+// They are reported side by side. There is deliberately no function here (and the verifier rejects any bundle
+// field) that combines them into a score, a level or a single confidence.
+//
+// WHAT RUNTIME SUPPORT MAY CLAIM
+// ------------------------------
+//   * Several edges observed does NOT prove one end-to-end execution. `path_supported` needs ONE causal group
+//     (a trace or session the caller can name) that covers EVERY edge, in a compatible environment,
+//     deployment, time window and identity scope, with unambiguous edge mappings. Edges seen in unrelated
+//     traces are `edge_partial`, however many there are.
+//   * Low-confidence and ambiguous mappings stay CANDIDATES (`candidate_only`); they never count as observed.
+//   * No telemetry is not evidence of safety: `no_observation_in_window` and `not_consulted` are different
+//     answers and neither says "the path is not exercised".
+//   * A denied observation proves only that attempt was refused (`blocked_attempt`), not every execution.
+//
+// KNOWN LIMIT: the closed-world RuntimeObservation contract carries no trace or session token (by design:
+// it is metadata-only). Causal groups are therefore supplied by the caller from a source that has one, and
+// without them the strongest honest answer from the observation store alone is `edge_partial`.
+
+import * as crypto from 'node:crypto';
+import { redactString } from '../mcp/redact.js';
+import { makeIdentityTokenizer } from '../lineage/identity-token.js';
+
+export const RUNTIME_SUPPORT_STATUSES = Object.freeze([
+  'not_consulted', 'no_observation_in_window', 'candidate_only', 'edge_partial', 'path_supported', 'blocked_attempt',
+]);
+export const EXPLOIT_PROOF_STATUSES = Object.freeze(['none', 'bound', 'rejected']);
+export const FEASIBILITY_STATUSES = Object.freeze(['not_assessed', 'feasible', 'infeasible', 'unknown']);
+export const MODELED_PATH_STATUSES = Object.freeze(['connected_complete', 'connected_partial']);
+export const EVIDENCE_STATUS_KEYS = Object.freeze(['modeledPath', 'feasibility', 'runtimeSupport', 'exploitProof']);
+
+const DEFAULT_MAX_WINDOW_MS = 5 * 60 * 1000;
+const TRUSTED_CONFIDENCE = new Set(['high', 'medium']);
+const REF_RE = /^[A-Za-z0-9._:@/-]{1,160}$/;
+const isObj = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+const arr = (v) => (Array.isArray(v) ? v : []);
+const sha = (s) => crypto.createHash('sha256').update(String(s)).digest('hex');
+
+/** A caller trace/session id becomes an opaque reference: comparable, never the raw value. */
+function pseudonymizeSessionRef(raw) {
+  return typeof raw === 'string' && raw.length > 0 ? `sref_${sha(`session-ref:v1:${raw}`).slice(0, 16)}` : null;
+}
+
+function iso(v) {
+  if (typeof v !== 'string') return null;
+  const t = Date.parse(v);
+  return Number.isFinite(t) ? t : null;
+}
+
+/**
+ * Reduce caller-supplied causal groups to the closed set of fields the assessment reads. Unknown fields are
+ * dropped and only COUNTED (their names could themselves carry a value). Identities are tokenized with the
+ * existing keyed-hash convention; a raw identity with no tokenizer is dropped, never kept.
+ */
+export function sanitizeCausalGroups(groups, { tokenize = makeIdentityTokenizer() } = {}) {
+  const out = []; const rejected = []; let droppedFields = 0;
+  const GROUP_KEYS = new Set(['id', 'sessionRef', 'sessionId', 'traceId', 'environment', 'deploymentRef', 'deploymentConfigDigest',
+    'identity', 'identityToken', 'firstObservedAt', 'lastObservedAt', 'edgeObservations']);
+  const OBS_KEYS = new Set(['edgeId', 'firstObservedAt', 'lastObservedAt', 'matchConfidence', 'matchedEdgeIds', 'observationIds']);
+  arr(groups).forEach((g, i) => {
+    if (!isObj(g)) { rejected.push({ index: i, reason: 'not-an-object' }); return; }
+    droppedFields += Object.keys(g).filter((k) => !GROUP_KEYS.has(k)).length;
+    // Idempotent: an already-opaque reference is kept, so re-sanitizing a recorded group (replay) changes nothing.
+    const ref = typeof g.sessionRef === 'string' && /^sref_[0-9a-f]{16}$/.test(g.sessionRef)
+      ? g.sessionRef : pseudonymizeSessionRef(g.sessionRef ?? g.sessionId ?? g.traceId);
+    const token = typeof g.identityToken === 'string' && /^idt_[0-9a-f]{16}$/.test(g.identityToken)
+      ? g.identityToken : (typeof g.identity === 'string' ? tokenize(g.identity) : null);
+    const ident = (v) => (typeof v === 'string' && REF_RE.test(v) ? v : null);
+    const edgeObservations = [];
+    for (const o of arr(g.edgeObservations)) {
+      if (!isObj(o) || typeof o.edgeId !== 'string' || !REF_RE.test(o.edgeId)) continue;
+      droppedFields += Object.keys(o).filter((k) => !OBS_KEYS.has(k)).length;
+      edgeObservations.push({
+        edgeId: o.edgeId,
+        firstObservedAt: iso(o.firstObservedAt) === null ? null : o.firstObservedAt,
+        lastObservedAt: iso(o.lastObservedAt) === null ? null : o.lastObservedAt,
+        matchConfidence: ['high', 'medium', 'low', 'ambiguous'].includes(o.matchConfidence) ? o.matchConfidence : 'ambiguous',
+        matchedEdgeIds: arr(o.matchedEdgeIds).filter((x) => typeof x === 'string' && REF_RE.test(x)).sort(),
+        observationIds: arr(o.observationIds).filter((x) => typeof x === 'string' && REF_RE.test(x)).sort().slice(0, 8),
+      });
+    }
+    out.push({
+      id: ident(g.id) ?? `group-${i}`,
+      sessionRef: ref,
+      environment: ident(g.environment),
+      deploymentRef: ident(g.deploymentRef),
+      deploymentConfigDigest: ident(g.deploymentConfigDigest),
+      identityToken: token ?? null,
+      firstObservedAt: iso(g.firstObservedAt) === null ? null : g.firstObservedAt,
+      lastObservedAt: iso(g.lastObservedAt) === null ? null : g.lastObservedAt,
+      edgeObservations: edgeObservations.sort((a, b) => (a.edgeId < b.edgeId ? -1 : a.edgeId > b.edgeId ? 1 : 0)),
+    });
+  });
+  return { groups: out, rejected, droppedFields };
+}
+
+/** Why a single causal group cannot support the WHOLE path (empty list means it can). */
+function groupIncompatibilities(group, pathEdgeIds, expected, maxWindowMs) {
+  const why = [];
+  if (!group.sessionRef) why.push('no-session-or-trace-reference');
+  const covered = new Map(group.edgeObservations.map((o) => [o.edgeId, o]));
+  const missing = pathEdgeIds.filter((id) => !covered.has(id));
+  if (missing.length) why.push(`edges-not-in-group:${missing.length}`);
+  if (!expected.environment) why.push('environment-unspecified');
+  else if (group.environment !== expected.environment) why.push('environment-mismatch');
+  if (!expected.deploymentRef) why.push('deployment-unspecified');
+  else if (group.deploymentRef !== expected.deploymentRef) why.push('deployment-mismatch');
+  if (expected.deploymentConfigDigest && group.deploymentConfigDigest && expected.deploymentConfigDigest !== group.deploymentConfigDigest) {
+    why.push('deployment-configuration-mismatch');
+  }
+  if (expected.identityToken && group.identityToken && expected.identityToken !== group.identityToken) why.push('identity-scope-mismatch');
+  const first = iso(group.firstObservedAt); const last = iso(group.lastObservedAt);
+  if (first === null || last === null) why.push('time-window-missing');
+  else {
+    if (last < first) why.push('time-window-inverted');
+    if (last - first > maxWindowMs) why.push('time-window-too-wide');
+    const w = expected.window;
+    if (w && (iso(w.start) !== null && first < iso(w.start) || iso(w.end) !== null && last > iso(w.end))) why.push('outside-requested-window');
+  }
+  // Edge-level mapping and order: each edge's own interval is inside the group window and the path order
+  // is not contradicted (an edge cannot have been last seen before its predecessor was first seen).
+  let prevFirst = null;
+  for (const id of pathEdgeIds) {
+    const o = covered.get(id);
+    if (!o) continue;
+    if (!TRUSTED_CONFIDENCE.has(o.matchConfidence) || o.matchedEdgeIds.length > 1) { why.push('ambiguous-edge-mapping'); break; }
+    const f = iso(o.firstObservedAt); const l = iso(o.lastObservedAt);
+    if (f === null || l === null) { why.push('edge-time-missing'); break; }
+    if (first !== null && last !== null && (f < first || l > last)) { why.push('edge-outside-group-window'); break; }
+    if (prevFirst !== null && l < prevFirst) { why.push('causal-order-violated'); break; }
+    prevFirst = f;
+  }
+  return why;
+}
+
+/**
+ * Assess what telemetry says about ONE path.
+ *
+ * @param {object} p
+ * @param {string[]} p.pathEdgeIds  DataFlowGraph edge ids of the path, source first.
+ * @param {object|null} p.edgeStates the result of `deriveEdgeStates` (null or evaluated:false means no telemetry was consulted)
+ * @param {object[]} [p.causalGroups]
+ * @param {object} [p.expected] { environment, deploymentRef, deploymentConfigDigest, identityToken, window, maxWindowMs }
+ */
+export function assessRuntimeSupport({ pathEdgeIds, edgeStates, causalGroups = [], expected = {}, tokenize } = {}) {
+  const ids = arr(pathEdgeIds).filter((x) => typeof x === 'string');
+  const base = {
+    pathEdgeCount: ids.length, observedEdgeIds: [], unobservedEdgeIds: [], candidateEdgeIds: [], blockedEdgeIds: [],
+    wholePath: { supported: false, groupId: null, reasons: [] }, groupsConsidered: 0, rejectedGroups: 0, droppedFields: 0,
+    statements: [],
+  };
+  if (!ids.length || !isObj(edgeStates) || !edgeStates.evaluated) {
+    return { ...base, status: 'not_consulted', statements: ['No telemetry was consulted for this path. That is not an observation of absence.'] };
+  }
+  const sanitized = sanitizeCausalGroups(causalGroups, { tokenize });
+  base.groupsConsidered = sanitized.groups.length; base.rejectedGroups = sanitized.rejected.length; base.droppedFields = sanitized.droppedFields;
+
+  for (const id of ids) {
+    const s = edgeStates.byEdge?.[id];
+    const states = arr(s?.states);
+    if (states.includes('RUNTIME_OBSERVED')) base.observedEdgeIds.push(id);
+    else if (states.includes('RUNTIME_BLOCKED')) base.blockedEdgeIds.push(id);
+    else {
+      base.unobservedEdgeIds.push(id);
+      if ((s?.uncertainObservations ?? 0) > 0) base.candidateEdgeIds.push(id);
+    }
+    // An edge observed AND denied keeps both facts.
+    if (states.includes('RUNTIME_OBSERVED') && states.includes('RUNTIME_BLOCKED')) base.blockedEdgeIds.push(id);
+  }
+
+  const allObserved = base.observedEdgeIds.length === ids.length;
+  if (allObserved) {
+    const maxWindowMs = Number.isFinite(expected.maxWindowMs) && expected.maxWindowMs > 0 ? expected.maxWindowMs : DEFAULT_MAX_WINDOW_MS;
+    let best = null;
+    for (const g of sanitized.groups) {
+      const why = groupIncompatibilities(g, ids, expected, maxWindowMs);
+      if (!why.length) { best = { g, why: [] }; break; }
+      if (!best || why.length < best.why.length) best = { g, why };
+    }
+    if (best && !best.why.length) {
+      base.wholePath = { supported: true, groupId: best.g.id, reasons: [] };
+      return { ...base, status: 'path_supported', statements: [
+        'Every edge was observed inside ONE compatible trace or session. This supports that this path executed in that session; it does not prove the data was sensitive or that the path is exploitable.',
+      ] };
+    }
+    base.wholePath.reasons = best ? best.why : ['no-causal-group-supplied'];
+  } else {
+    base.wholePath.reasons = ['not-every-edge-observed'];
+  }
+
+  if (base.blockedEdgeIds.length && base.blockedEdgeIds.some((id) => !base.observedEdgeIds.includes(id))) {
+    return { ...base, status: 'blocked_attempt', statements: [
+      'A denied observation proves only that this attempt was refused. It does not show every execution of this path is blocked.',
+    ] };
+  }
+  if (base.observedEdgeIds.length) {
+    return { ...base, status: 'edge_partial', statements: [
+      'Some edges were observed, but not within one compatible trace or session. Independently observed edges do not establish an end-to-end execution.',
+    ] };
+  }
+  if (base.candidateEdgeIds.length) {
+    return { ...base, status: 'candidate_only', statements: [
+      'Only low-confidence or ambiguous mappings were seen. They remain candidates and are not counted as observed.',
+    ] };
+  }
+  return { ...base, status: 'no_observation_in_window', statements: [
+    'Telemetry was consulted and nothing mapped to this path in the window. That is not evidence that the path is unreachable or safe.',
+  ] };
+}
+
+/**
+ * R10.6: external proof references are bound to the sink, the value and the configuration. A reference that is
+ * stale or mismatched is REJECTED with its reasons; it is never re-attached to the changed graph.
+ */
+export function bindExploitProofs(proofs, expected) {
+  const bound = []; const rejected = [];
+  for (const [i, p] of arr(proofs).entries()) {
+    const id = isObj(p) && typeof p.id === 'string' && REF_RE.test(p.id) ? p.id : `proof-${i}`;
+    if (!isObj(p)) { rejected.push({ id, reasons: ['not-an-object'] }); continue; }
+    const reasons = [];
+    if (!['proof', 'dnr-hunt', 'incident'].includes(p.kind)) reasons.push('unknown-kind');
+    if (!p.sinkRef || !p.dataElementId || !p.graphDigest || !p.analysisConfigDigest) reasons.push('unbound');
+    else {
+      if (p.sinkRef !== expected.sinkRef) reasons.push('sink-mismatch');
+      if (p.dataElementId !== expected.dataElementId) reasons.push('value-mismatch');
+      if (p.graphDigest !== expected.graphDigest) reasons.push('stale-graph');
+      if (p.analysisConfigDigest !== expected.analysisConfigDigest) reasons.push('configuration-mismatch');
+    }
+    if (reasons.length) rejected.push({ id, reasons });
+    else bound.push({ id, kind: p.kind, executionBacked: p.kind === 'proof', note: typeof p.note === 'string' ? redactString(p.note).slice(0, 200) : null });
+  }
+  bound.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  rejected.sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+  // Rejected references stay listed with their reasons whatever the status; they are never silently dropped.
+  return { status: bound.length ? 'bound' : rejected.length ? 'rejected' : 'none', bound, rejected };
+}
+
+/** Validate the nullable DAG-04 slot. Returns { ok, errors }. */
+export function validateControlEvidence(ce, pathEdgeIds) {
+  if (ce === null) return { ok: true, errors: [] };
+  const errors = [];
+  if (!isObj(ce)) return { ok: false, errors: ['control evidence must be an object or null'] };
+  if (!FEASIBILITY_STATUSES.includes(ce.status) || ce.status === 'not_assessed') errors.push('control evidence status must be feasible, infeasible or unknown');
+  const set = new Set(pathEdgeIds);
+  for (const k of ['predicateRefs', 'controlRefs']) {
+    if (!Array.isArray(ce[k])) { errors.push(`${k} must be an array`); continue; }
+    for (const r of ce[k]) {
+      if (!isObj(r) || !set.has(r.edgeId) || typeof r.ref !== 'string' || !REF_RE.test(r.ref)) errors.push(`${k} entry must name an edge on this path and an identifier-shaped ref`);
+    }
+  }
+  return { ok: errors.length === 0, errors };
+}
+
+/**
+ * The four statuses, side by side. Returns exactly the four keys in EVIDENCE_STATUS_KEYS and nothing that
+ * ranks, scores or combines them.
+ */
+export function buildEvidenceStatuses({ pathComplete, controlEvidence, runtime, exploit }) {
+  return {
+    modeledPath: { status: pathComplete ? 'connected_complete' : 'connected_partial' },
+    feasibility: { status: controlEvidence ? controlEvidence.status : 'not_assessed' },
+    runtimeSupport: { status: runtime.status },
+    exploitProof: { status: exploit.status },
+  };
+}

package/src/report/index.js

@@ -339,6 +339,8 @@ export function normalizeFindings(scan){
       // (posture/proof-tier.js) actually attached it. Never synthesised here;
       // a finding with no proof backing simply omits these fields.
       ...(f.proofTier !== undefined ? { proofTier: f.proofTier } : {}),
+      // DAG-05 R05.7: whether this finding was replayed from the cross-scan cache or analysed in this scan; present only when the cache was in use.
+      ...(f.cacheProvenance !== undefined ? { cacheProvenance: f.cacheProvenance } : {}),
       ...(f.proofEvidence !== undefined ? { proofEvidence: f.proofEvidence } : {}),
       // X-206: the version-1 verification record and its shared projection, ADDITIVE and present only when the finding carries
       // a record (a plain scan output is byte-identical). `verificationReplay` is the typed prerequisite list of a replay attempt.

package/src/sast/CLAUDE.md

@@ -39,6 +39,8 @@ Both key on the SECRET-NESS of the identifier, never on the comparison or the ty
 
 **Bench-shape adapters (label-leakage, OFF by default)** — `bench-shape/` directory, plus `cpp-bench-extras.js`, `java-bench-extras.js`, `juliet-shape.js`, `primary-cwe-java.js`. These read Juliet / OWASP-Benchmark answer keys. Disabled unless `AGENTIC_SECURITY_BENCH_SHAPE=1`; `AGENTIC_SECURITY_BLIND_BENCH=1` overrides to force everything off. **Never use their emissions as a quality signal.**
 
+**Precision guards (bench/dag).** Small, general recognisers that answer one semantic question each about the TEXT of a call, shared by every emitter that can fire on it. Each is tested as a pair (the safe construct stays quiet, the near-miss that changes the semantics keeps its verdict) in `test/dag-precision.test.js` and `bench/mutation/cases.mjs` (`DAG_PRECISION_CASES`). `_call-args.js` (quote- and bracket-aware argument splitter; a window that ends inside the call yields the arguments completed so far, flagged `partial`), `redirect-target.js` (CWE-601: a literal prefix that fixes the origin, `'/user/' + id` or `'https://host/' + p`, cannot be steered off-origin; `'/' + x`, `'//' + x` and a host with no closing slash can), `reflected-input.js` (CWE-79: only the properties of `req` that carry the client's input count, and not inside an HTML escaper; `req.session`/`req.user`/`req.app` are server state), `send-file-root.js` (CWE-22: `sendFile`/`download` with an inline `root` option confine the path), `init-scope.js` (CWE-400: is a position inside a function body, including expression-bodied arrows and class bodies, or at module load; a block is a function unless it is positively a control block or a literal, because the error that matters is hiding a finding), `listen-bind-address.js` (the `address` a `listen` callback receives is the bound socket address, not personal data). Wired in `../engine.js` (`dropGuardedFindings` for redirect and file serving, the `predicate` hook of the structural patterns for reflection and blocking I/O, `_detectSafeSinkShape`), `sensitive-data-logging.js` and `../dataflow/privacy-taint.js`. `engine.js` `_usedIdentifiers` is the same idea for the flow-pair detector: words inside string literals and property names after a dot are not reads of a variable of that name.
+
 **Helpers** — `_comment-strip.js` strips comments while preserving line numbers (so finding `line` stays accurate). `index.js` is the public re-export.
 
 ## Gotchas

package/src/sast/_call-args.js

@@ -0,0 +1,70 @@
+// Argument splitting for guard recognisers that must look at WHAT a call is
+// given, not at the text around it. Quote- and bracket-aware; handles template
+// literal substitutions. Not a parser: it answers "where does each top-level
+// argument start and end" for text that begins right after a call's '('.
+
+const isQuote = (c) => c === '"' || c === "'" || c === '`';
+
+/**
+ * Split the text that follows a call's opening paren into its top-level
+ * arguments (source text, quotes intact). Returns null when the closing paren
+ * is not in the text given, so a caller never reasons about a truncated call.
+ */
+export function callArguments(text) {
+  const args = [];
+  let depth = 0;
+  let start = 0;
+  let i = 0;
+  while (i < text.length) {
+    const c = text[i];
+    if (isQuote(c)) {
+      const q = c;
+      i++;
+      while (i < text.length && text[i] !== q) {
+        if (text[i] === '\\') { i += 2; continue; }
+        if (q === '`' && text[i] === '$' && text[i + 1] === '{') {
+          let d = 1; i += 2;
+          while (i < text.length && d > 0) { if (text[i] === '{') d++; else if (text[i] === '}') d--; i++; }
+          continue;
+        }
+        i++;
+      }
+      i++;
+      continue;
+    }
+    if (c === '(' || c === '[' || c === '{') depth++;
+    else if (c === ')' || c === ']' || c === '}') {
+      if (depth === 0) {
+        const last = text.slice(start, i);
+        if (last.trim() !== '' || args.length > 0) args.push(last);
+        return args;
+      }
+      depth--;
+    } else if (c === ',' && depth === 0) {
+      args.push(text.slice(start, i));
+      start = i + 1;
+    }
+    i++;
+  }
+  // The window ended inside the call (a long callback, a wrapped call). The
+  // arguments completed so far are still exactly what the call was given; the
+  // unfinished last one is dropped rather than guessed. `partial` lets a caller
+  // that needs the whole call refuse.
+  if (args.length === 0) return null;
+  args.partial = true;
+  return args;
+}
+
+/**
+ * Find the first call on or just after `line` (1-based) whose callee matches
+ * `calleeRe` (which must end at the opening paren) and return its arguments.
+ * Looks at the finding line and the next three, because a call is routinely
+ * wrapped. Returns null when there is no such call or it is not closed.
+ */
+export function callArgumentsAt(lines, line, calleeRe) {
+  if (!Array.isArray(lines) || !Number.isInteger(line) || line < 1) return null;
+  const text = lines.slice(line - 1, line + 3).join('\n');
+  const m = calleeRe.exec(text);
+  if (!m) return null;
+  return callArguments(text.slice(m.index + m[0].length));
+}

package/src/sast/init-scope.js

@@ -0,0 +1,87 @@
+// Is a source position inside a function body, or at module/initialisation
+// level? Some hazards exist only while the process is serving work: a blocking
+// call made once at module load (reading a TLS key, a config file) delays
+// startup once, and nothing is waiting on the event loop yet. The same call in
+// a request callback stalls every connection.
+//
+// A position is inside a function when it is inside
+//   * a `{ ... }` block opened by `=>`, a `function` header, a method or class
+//     member header (`name(params) {`), or an async/generator form,
+//   * the body of an expression-bodied arrow (`(p) => fs.readFileSync(p)`),
+//     which runs when the arrow is CALLED, not where it is written, or
+//   * a class body (field initialisers run per instance).
+// Plain blocks (`if`, `for`, `try`, `else`) and object literals are not function scopes.
+//
+// Operates on a comment- and string-blanked view so braces in strings or
+// comments never count. It is a lexical approximation (no parse). The one error
+// that matters is calling a function body "module level", because that hides a
+// finding, so a block is classed as a function unless it is positively a control
+// block or a literal, and parameter lists are matched by bracket depth, not by a
+// pattern that stops at a fixed nesting.
+
+const CONTROL_KEYWORDS = new Set(['if', 'for', 'while', 'switch', 'catch', 'with', 'else', 'try', 'finally', 'do']);
+const CLASS_HEAD = /\bclass\b\s*[\w$]*(?:\s+extends\s+[\w$.()]+)?\s*$/;
+
+/** Index of the '(' matching the ')' at `closeIdx`, scanning backwards; -1 if unbalanced. */
+function matchingOpenParen(text, closeIdx) {
+  let depth = 0;
+  for (let i = closeIdx; i >= 0; i--) {
+    const c = text[i];
+    if (c === ')') depth++;
+    else if (c === '(') { depth--; if (depth === 0) return i; }
+  }
+  return -1;
+}
+
+function opensFunction(text, braceIdx) {
+  let end = braceIdx;
+  while (end > 0 && /\s/.test(text[end - 1])) end--;
+  const before = text.slice(Math.max(0, end - 400), end);
+  if (/=>$/.test(before)) return true;
+  if (CLASS_HEAD.test(before)) return true;
+  // `else {`, `try {`, `finally {`, `do {`, `catch {` carry no parenthesised head
+  const bare = /(?:^|[^\w$.])([A-Za-z_$][\w$]*)$/.exec(before);
+  if (bare && CONTROL_KEYWORDS.has(bare[1])) return false;
+  // find the ')' that ends a parameter list, allowing a return type annotation `): Type {`
+  let closeIdx = end - 1;
+  if (text[closeIdx] !== ')') {
+    const m = /\)\s*:\s*[^(){};=]*$/.exec(before);
+    if (!m) return false;
+    closeIdx = end - before.length + m.index;
+  }
+  const openIdx = matchingOpenParen(text, closeIdx);
+  if (openIdx < 0) return true; // cannot match the head: keep findings, so call it a function
+  const head = text.slice(Math.max(0, openIdx - 80), openIdx).replace(/\s+$/, '');
+  const word = /([A-Za-z_$][\w$]*)$/.exec(head);
+  if (word) return !CONTROL_KEYWORDS.has(word[1]); // `if (` `while (` ...: control; any other name( ... ) { is a function or method
+  if (/\bfunction\s*\*?$/.test(head)) return true; // `function (` and `function* (`
+  return false;
+}
+
+/**
+ * @param {string} blanked  source with comments and string bodies blanked
+ * @param {number} offset   index into `blanked`
+ * @returns {boolean} true when `offset` is lexically inside a function body
+ */
+export function insideFunctionBody(blanked, offset) {
+  // entries: 'F' function block, 'B' other block, 'P' paren/bracket, 'A' expression-bodied arrow
+  const stack = [];
+  const end = Math.min(offset, blanked.length);
+  for (let i = 0; i < end; i++) {
+    const c = blanked[i];
+    if (c === '{') stack.push(opensFunction(blanked, i) ? 'F' : 'B');
+    else if (c === '(' || c === '[') stack.push('P');
+    else if (c === '}' || c === ')' || c === ']') {
+      while (stack.length && stack[stack.length - 1] === 'A') stack.pop(); // an arrow body ends where its enclosing bracket closes
+      stack.pop();
+    } else if ((c === ',' || c === ';') && stack[stack.length - 1] === 'A') {
+      stack.pop(); // ... or at a separator at its own nesting level
+    } else if (c === '=' && blanked[i + 1] === '>') {
+      let j = i + 2;
+      while (j < blanked.length && /\s/.test(blanked[j])) j++;
+      if (blanked[j] !== '{') stack.push('A');
+      i++;
+    }
+  }
+  return stack.some((e) => e === 'F' || e === 'A');
+}

package/src/sast/listen-bind-address.js

@@ -0,0 +1,49 @@
+// The `address` a `listen` callback receives.
+//
+//   server.listen({ port }, (err, address) => console.log(`listening on ${address}`))
+//
+// `address` here is the socket address the server just bound (host and port),
+// handed to the callback by the server. It is not a person's postal address, so a
+// rule that classifies a value by the NAME `address` must not treat this binding
+// as personal data. The rule is about the binding site, not about the word: the
+// same name bound anywhere else (a form field, a column, a request property) is
+// unaffected.
+
+/** Index just past the paren that closes the one opened at `openIdx`, or -1 when the text ends first. */
+function closeOfParen(text, openIdx) {
+  let depth = 0;
+  for (let i = openIdx; i < text.length; i++) {
+    const c = text[i];
+    if (c === '"' || c === "'" || c === '`') {
+      const q = c; i++;
+      while (i < text.length && text[i] !== q) { if (text[i] === '\\') i++; i++; }
+    } else if (c === '(') depth++;
+    else if (c === ')') { depth--; if (depth === 0) return i + 1; }
+  }
+  return -1;
+}
+
+/**
+ * Is the identifier at `idx` in `raw` a parameter declared by a callback passed
+ * to a `.listen(` call? `idx` is any position at or after the callback header
+ * (the use site); the header is searched backwards within a bounded window, and
+ * must sit inside the listen call's own parentheses, so a function declared after
+ * the call has closed does not count.
+ */
+export function isListenCallbackParam(raw, idx, name) {
+  if (typeof raw !== 'string' || !name) return false;
+  const from = Math.max(0, idx - 800);
+  const at = raw.slice(from, idx).lastIndexOf('.listen(');
+  if (at < 0) return false;
+  const start = from + at;
+  const openIdx = start + '.listen'.length;
+  const windowEnd = idx + name.length + 80;
+  const close = closeOfParen(raw.slice(start, windowEnd), openIdx - start);
+  // the call closed before the use site: the use is not inside the callback
+  if (close !== -1 && start + close <= idx) return false;
+  const after = raw.slice(start, close === -1 ? windowEnd : Math.min(windowEnd, start + close));
+  const id = name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const arrow = new RegExp(String.raw`\([^)]*\b${id}\b[^)]*\)\s*=>|\b${id}\s*=>`);
+  const fn = new RegExp(String.raw`\bfunction\b[^(]*\([^)]*\b${id}\b[^)]*\)`);
+  return arrow.test(after) || fn.test(after);
+}

package/src/sast/redirect-target.js

@@ -0,0 +1,106 @@
+// Open-redirect target shape (CWE-601): can the part of a redirect target the
+// program does not control change the ORIGIN the browser is sent to?
+//
+// A redirect target is attacker-steerable to another origin only if the
+// attacker controls the authority (scheme, host, port) of the resulting URL.
+// A target that begins with a literal which already fixes the authority cannot
+// be moved off-origin by whatever is appended after it:
+//
+//   '/user/' + id                   path-absolute, second character is a name
+//                                   character: same origin, whatever `id` is
+//   'https://app.example.com/' + p  the whole authority is in the literal and a
+//                                   '/' closes it, so `p` is only path/query
+//
+// and these are NOT pinned, because the dynamic part decides the authority:
+//
+//   '/' + x                x = '/evil.example'  gives '//evil.example'
+//   '//' + x, '/\\' + x    protocol-relative (browsers treat '\' as '/')
+//   'https://app.example.com' + x   x = '.evil.example' or '@evil.example'
+//   '' + x, x, x + '/path'          no literal prefix at all
+//
+// This is deliberately the ONLY thing decided here. It reads the text of the
+// redirect call's first argument; it does not decide whether the dynamic part
+// is attacker-controlled (that is the taint layer's question) and it never
+// reads a file name, a fixture name or a label.
+
+import { callArgumentsAt } from './_call-args.js';
+
+const REDIRECT_CALL_RE = /\b(?:redirect|sendRedirect|Redirect|redirect_to|HttpResponseRedirect|RedirectResponse|redirectTo|permanentRedirect)\s*\(/;
+
+/**
+ * Leading literal text of an expression, and whether anything dynamic follows.
+ * Handles 'a' + x, "a" + x + y, `a${x}`, and a lone literal.
+ * `literal` is the decoded-enough prefix (escapes kept verbatim, which is safe
+ * here because the checks below only look at slashes and the first characters).
+ */
+export function leadingLiteral(expr) {
+  const s = String(expr).trim();
+  let i = 0;
+  let prefix = '';
+  let dynamic = false;
+  for (;;) {
+    while (i < s.length && /\s/.test(s[i])) i++;
+    if (i >= s.length) break;
+    const c = s[i];
+    if (c === '"' || c === "'") {
+      let j = i + 1; let body = '';
+      while (j < s.length && s[j] !== c) { if (s[j] === '\\') { body += s[j] + (s[j + 1] || ''); j += 2; } else body += s[j++]; }
+      if (j >= s.length) return { literal: prefix, dynamic: true, closed: false };
+      prefix += body; i = j + 1;
+    } else if (c === '`') {
+      let j = i + 1; let body = '';
+      while (j < s.length && s[j] !== '`') {
+        if (s[j] === '\\') { body += s[j] + (s[j + 1] || ''); j += 2; continue; }
+        if (s[j] === '$' && s[j + 1] === '{') { dynamic = true; break; }
+        body += s[j++];
+      }
+      prefix += body;
+      if (dynamic) return { literal: prefix, dynamic: true, closed: true };
+      if (j >= s.length) return { literal: prefix, dynamic: true, closed: false };
+      i = j + 1;
+    } else {
+      return { literal: prefix, dynamic: true, closed: true };
+    }
+    while (i < s.length && /\s/.test(s[i])) i++;
+    if (i >= s.length) return { literal: prefix, dynamic, closed: true };
+    if (s[i] === '+') { i++; continue; }
+    // anything else after a literal (a call suffix, `.concat`, `%`, ...): not a plain literal
+    return { literal: prefix, dynamic: true, closed: true };
+  }
+  return { literal: prefix, dynamic, closed: true };
+}
+
+/** A literal prefix that fixes the origin of the URL it begins. */
+export function prefixPinsOrigin(prefix) {
+  // Path-absolute: '/' then a character that is neither '/' nor '\' (both are
+  // read as a second slash, turning the reference into a network-path one).
+  if (/^\/[^\/\\\s]/.test(prefix)) return true;
+  // Absolute URL whose authority is complete: scheme://authority/ .
+  if (/^[A-Za-z][A-Za-z0-9+.\-]*:\/\/[^\/?#\\\s]+\//.test(prefix)) return true;
+  return false;
+}
+
+/**
+ * Does the redirect argument keep the destination on a fixed origin?
+ * `arg` is the first argument of the redirect call. A numeric first argument
+ * (`res.redirect(302, url)`) is skipped by the caller, not here.
+ */
+export function redirectArgumentPinsOrigin(arg) {
+  const { literal, dynamic, closed } = leadingLiteral(arg);
+  if (!closed) return false;
+  if (!dynamic) return literal.length > 0; // a fully static target
+  return prefixPinsOrigin(literal);
+}
+
+/**
+ * Inspect source lines starting at `line` (1-based) for a redirect call and
+ * decide whether its target pins the origin. Returns null when no redirect
+ * call is found (no opinion), else true/false.
+ */
+export function redirectTargetPinsOriginAt(lines, line) {
+  const args = callArgumentsAt(lines, line, REDIRECT_CALL_RE);
+  if (!args || args.length === 0) return null;
+  // res.redirect(302, '/x'): the status code is not the target
+  const target = args.length > 1 && /^\s*\d{3}\s*$/.test(args[0]) ? args[1] : args[0];
+  return redirectArgumentPinsOrigin(target);
+}