@clear-capabilities/agentic-security-scanner 0.162.0 → 0.163.0

package/src/dataflow/guard-dominance.js

@@ -0,0 +1,352 @@
+// Does a guard actually DOMINATE the sink it is said to protect? (QA-005.AC02)
+//
+// `dropGuardedFindings` and the safe-sink-shape check recognise a guard by shape inside a window of source lines
+// around the sink, then correlate on a shared identifier. That answers "is there guard-looking text near this sink",
+// which is not the question that justifies dropping a finding: "is every path that reaches the sink forced through
+// this guard". Text can be near a sink without protecting it:
+//   - a guard written AFTER the sink (the window reaches several lines below it);
+//   - a guard in a DIFFERENT function that happens to sit above;
+//   - a guard inside a block that has already closed (`if (dev) { check(x); }  fetch(x)`);
+//   - an `if (allowed(x)) { log() }` whose failing branch does not stop anything, followed by an unconditional sink;
+//   - a membership test whose boolean result is computed and never branched on.
+// This module decides that, over the same source lines, with no new dependency. It is deliberately conservative toward
+// KEEPING a finding: when it cannot establish dominance it says so, and the caller leaves the finding in place. The
+// cost of being wrong in that direction is a reviewable false positive; the other direction deletes a real defect.
+//
+// Pure: lines in, verdict out. It reads no file name beyond an extension, no label and no answer key, and works on text alone.
+// It is NOT a control-flow graph: it recognises the structured shapes real handlers use (straight-line statements,
+// early-exit checks, a sink nested in the guarded branch) and reports `unknown-shape` for anything else it cannot
+// place, which counts as "not proven".
+
+const TERMINATOR = /\b(?:return|throw|raise|continue|break|exit|abort|die|panic|halt|fail|next)\b|\b(?:sys\.exit|os\._exit|process\.exit|http\.Error|t\.Fatal|log\.Fatal)\b|\.\s*(?:status|sendStatus|abort|AbortWithStatus|AbortWithStatusJSON|Error)\s*\(/;
+const CONDITIONAL_HEAD = /^\s*(?:\}\s*)?(?:else\s+)?(?:if|unless|elif|elsif|while|until|when|guard|switch)\b/;
+const MODIFIER_EXIT = /^\s*(?:return|raise|throw|next|break|continue|abort|halt|fail|die)\b[^\n]*\b(?:if|unless)\b|\b(?:or|\|\|)\s+(?:raise|die|throw|return|abort|exit)\b/;
+// A function or method DECLARATION line, across the languages this engine reads. A guard above one is in another function.
+const NOT_A_DECL_HEAD = /^\s*(?:return|await|new|throw|else|yield|typeof|delete|case|if|for|while|switch|catch|try|do|elif|elsif|unless|until|when|guard|print|echo)\b/;
+const MODIFIER = /^(?:public|private|protected|internal|static|final|abstract|override|async|export|default|virtual|sealed|extern|pub|suspend)\s+/;
+const ANNOTATION = /^@\w+(?:\([^)]*\))?\s*/;
+const DECL_START = /^(?:function\s*\*?\s*\w+\s*\(|def\s+\w+|fn\s+\w+|fun\s+\w+|func\s+(?:\([^)]*\)\s*)?\w+\s*\(|sub\s+\w+)/;
+// A typed method header (`public String find(String q) throws E {`) or a bare class-method shorthand (`handle(req, res) {`): the head before the
+// parenthesis is a few words, the opening brace ends the line. Written without nested quantifiers and capped in length, because these run per line.
+const BRACE_METHOD = /^([^(){};=]{0,120}?)\(([^;)]{0,300})\)\s*(?:throws\s+[\w.,\s]{1,120})?\s*\{\s*$/;
+const MAX_DECL_LINE = 400;
+function isFunctionBoundary(line) {
+  if (line.length > MAX_DECL_LINE || NOT_A_DECL_HEAD.test(line)) return false;
+  // peel annotations and modifiers one at a time (a loop, not a repeated group)
+  let rest = line.trimStart();
+  for (let n = 0; n < 8; n++) { const m = ANNOTATION.exec(rest); if (!m) break; rest = rest.slice(m[0].length); }
+  for (let n = 0; n < 8; n++) { const m = MODIFIER.exec(rest); if (!m) break; rest = rest.slice(m[0].length); }
+  if (DECL_START.test(rest)) return true;
+  const m = BRACE_METHOD.exec(line);
+  if (!m) return false;
+  const words = m[1].trim().split(/\s+/).filter(Boolean);
+  // the last word is the method name; any earlier words are modifiers or a return type
+  return words.length >= 1 && words.length <= 6 && /^\w+$/.test(words[words.length - 1]) && !/^(?:if|for|while|switch|catch|else|function|return)$/.test(words[words.length - 1]);
+}
+// A pure DATA declaration: a name bound to a literal, a collection or a constructor (`const ALLOWED = new Set([...])`, `DENY = ["a"]`,
+// `static final Set<String> ALLOW = Set.of(...)`, `var allowed = map[string]bool{...}`). It defines the allow-list; it does not CHECK anything
+// against it, so it cannot guard a sink however guard-shaped its name is.
+const DATA_DECL = /^\s*(?:(?:export|public|private|protected|internal|static|final|readonly|const|let|var|val|def|pub|mut)\s+)*(?:[\w$.<>\[\],?:&* ]+?\s+)?[A-Za-z_$][\w$]*\s*(?::[^=\n]+)?(?::=|=)\s*(?:new\b|\[|\{|%[wi]|Set\.of|List\.of|Map\.of|Arrays\.asList|listOf|setOf|mapOf|hashSetOf|set\(|frozenset\(|list\(|dict\(|tuple\(|vec!|HashSet|map\[|[A-Z]\w*\{|["'`])(?!.*(?:=>|->|\bfunction\b))/;
+// An assignment whose value is a membership/prefix/equality TEST: a boolean, which protects nothing until something branches on it.
+const BOOLEAN_ASSIGN = /^\s*(?:(?:const|let|var|val|final|bool|boolean|auto)\s+)?([A-Za-z_$][\w$]*)\s*(?::=|=)\s*(?!.*\b(?:basename|abspath|realpath|resolve|normalize|secure_filename|safe_join|sanitize\w*|escape\w*)\b)[^=\n]*(?:\.\s*(?:has|includes|contains|startsWith|startswith|StartsWith|endsWith|HasPrefix|starts_with|match|test|matches)\s*\(|\bin\s|===|!==|==|!=)/;
+
+/** Source line with string literals and trailing line comments blanked, so brace counting is not fooled by either. */
+function code(line) {
+  return String(line ?? '')
+    .replace(/"(?:\\.|[^"\\])*"|'(?:\\.|[^'\\])*'|`(?:\\.|[^`\\])*`/g, '""')
+    .replace(/\/\/.*$/, '')
+    .replace(/(^|\s)#.*$/, '$1');
+}
+
+const indentOf = (line) => { const m = /^[ \t]*/.exec(line)[0]; return m.replace(/\t/g, '    ').length; };
+const countBraces = (s) => ({ open: (s.match(/\{/g) || []).length, close: (s.match(/\}/g) || []).length });
+const blank = (s) => !/\S/.test(s);
+
+// Block style of the file: indentation (Python, Ruby) or braces. The extension decides when known; otherwise the whole file votes, never just
+// the few lines between guard and sink (two brace-free lines of JavaScript are not an indentation language).
+function looksIndented(lines, file) {
+  if (/\.(?:py|pyi|rb|rake|ru)$/i.test(file || '')) return true;
+  if (/\.[A-Za-z0-9]+$/.test(file || '')) return false;
+  let brace = 0; let colon = 0;
+  for (const l of lines) {
+    const c = code(l);
+    if (/[{}]\s*$/.test(c)) brace++;
+    else if (/^\s*(?:def|if|elif|else|for|while|class|try|except|finally|with)\b.*:\s*$/.test(c)) colon++;
+  }
+  return colon > brace;
+}
+
+function result(dominates, reason) { return { dominates, reason }; }
+
+/**
+ * @param {object} o
+ * @param {string[]} o.lines     the file's source lines (original text)
+ * @param {number} o.guardIdx    0-based index of the line the guard-shaped text matched on
+ * @param {number} o.sinkIdx     0-based index of the sink line
+ * @param {string} [o.file]      path, used ONLY to pick the block style (indentation vs braces) from its extension
+ * @returns {{dominates: boolean, reason: string}}
+ */
+export function guardDominatesSink({ lines, guardIdx, sinkIdx, file = null, depth = 0 }) {
+  if (!Array.isArray(lines) || !Number.isInteger(guardIdx) || !Number.isInteger(sinkIdx)) return result(false, 'unknown-shape');
+  if (guardIdx < 0 || sinkIdx < 0 || guardIdx >= lines.length || sinkIdx >= lines.length) return result(false, 'unknown-shape');
+  if (guardIdx > sinkIdx) return result(false, 'guard-after-sink');
+
+  const indentStyle = looksIndented(lines, file);
+  // Which named function holds the guard? A guard in a function that has ENDED before the sink protects the sink only through a call to
+  // that function (a validator helper); a guard at module level does not reach into a function declared after it.
+  const fn = enclosingFunction(lines, guardIdx, indentStyle);
+  if (fn && sinkIdx > fn.endIdx) return calleeGuardDominates({ lines, guardIdx, sinkIdx, fn, file, depth });
+  if (!fn) {
+    for (let i = guardIdx + 1; i <= sinkIdx; i++) if (isFunctionBoundary(code(lines[i]))) return result(false, 'different-function');
+  }
+  const gl = code(lines[guardIdx]);
+
+  // Same line: `if (!ok(x)) return; fetch(x)` or `x = safe(x); use(x)`. Order within the line is not tracked, but a guard that
+  // shares the sink's line is positioned by the author as part of the same statement run.
+  if (guardIdx === sinkIdx) return result(true, 'same-line');
+
+  // A line that only DEFINES the allow-list is not a check.
+  if (DATA_DECL.test(gl) && !/\.\s*(?:has|includes|contains|startsWith|startswith|StartsWith)\s*\(/.test(gl)) return result(false, 'data-declaration-not-a-check');
+
+  // A membership/equality result that is computed and never branched on protects nothing.
+  const boolAssign = BOOLEAN_ASSIGN.exec(gl);
+  if (boolAssign && !CONDITIONAL_HEAD.test(gl)) {
+    const v = boolAssign[1].replace(/[$]/g, '\\$');
+    const used = new RegExp(`(?:\\b(?:if|unless|while|assert|require|ensure|guard)\\b|&&|\\|\\||\\?|\\bnot\\b|!)[^\\n]*\\b${v}\\b|\\b${v}\\b[^\\n]*(?:&&|\\|\\||\\?)`);
+    let branched = false;
+    for (let i = guardIdx + 1; i <= sinkIdx && !branched; i++) branched = used.test(code(lines[i]));
+    if (!branched) return result(false, 'result-never-branched-on');
+  }
+
+  if (indentStyle) return indentDominates(lines, guardIdx, sinkIdx, gl);
+  return braceDominates(lines, guardIdx, sinkIdx, gl);
+}
+
+function declaredName(declLine) {
+  const c = code(declLine);
+  const kw = /(?:function\s*\*?\s*|def\s+|fn\s+|fun\s+|func\s+(?:\([^)]*\)\s*)?|sub\s+)([A-Za-z_$][\w$]*)/.exec(c);
+  if (kw) return kw[1];
+  const typed = /([A-Za-z_$][\w$]*)\s*\(/.exec(c);
+  return typed ? typed[1] : null;
+}
+
+/** The named function that contains line `idx`, as `{ declIdx, endIdx }`, or null at module level. */
+function enclosingFunction(lines, idx, indentStyle) {
+  if (indentStyle) return enclosingFunctionByIndent(lines, idx, indentOf(lines[idx]));
+  let need = 0;
+  for (let i = idx - 1; i >= 0; i--) {
+    const c = code(lines[i]);
+    for (let k = c.length - 1; k >= 0; k--) {
+      if (c[k] === '}') need++;
+      else if (c[k] === '{') {
+        if (need > 0) { need--; continue; }
+        const head = isFunctionBoundary(c) ? i : (/^\s*\{\s*$/.test(c) && i > 0 && isFunctionBoundary(code(lines[i - 1])) ? i - 1 : -1);
+        if (head >= 0) {
+          let depth = 0; let end = lines.length - 1;
+          scan: for (let m = i; m < lines.length; m++) {
+            const t = code(lines[m]);
+            for (const ch of t) { if (ch === '{') depth++; else if (ch === '}') { depth--; if (depth === 0) { end = m; break scan; } } }
+          }
+          return { declIdx: head, endIdx: end };
+        }
+      }
+    }
+  }
+  return null;
+}
+
+function enclosingFunctionByIndent(lines, idx, ind) {
+  for (let i = idx - 1; i >= 0; i--) {
+    if (blank(lines[i])) continue;
+    const cur = indentOf(lines[i]);
+    if (cur >= ind) continue;
+    if (isFunctionBoundary(code(lines[i]))) {
+      let end = i;
+      for (let k = i + 1; k < lines.length; k++) { if (blank(lines[k])) continue; if (indentOf(lines[k]) <= cur) break; end = k; }
+      return { declIdx: i, endIdx: end };
+    }
+    ind = cur;
+  }
+  return null;
+}
+
+/** The guard is in a helper function that ended before the sink. It protects the sink only if the sink's code calls that helper first and the guard cannot be skipped inside it. */
+function calleeGuardDominates({ lines, guardIdx, sinkIdx, fn, file, depth }) {
+  if (depth >= 3) return result(false, 'call-chain-too-deep');
+  const name = declaredName(lines[fn.declIdx]);
+  if (!name) return result(false, 'different-function');
+  const call = new RegExp(`\\b${name.replace(/[$]/g, '\\$')}\\s*\\(`);
+  let callIdx = -1;
+  for (let i = fn.endIdx + 1; i <= sinkIdx; i++) { if (call.test(code(lines[i])) && !isFunctionBoundary(code(lines[i]))) { callIdx = i; break; } }
+  if (callIdx < 0) return result(false, 'different-function');
+  // 1. inside the helper the guard must be on every path to the helper's exit: at the function's own level, and either a straight-line
+  //    statement or a check whose failing branch leaves. (The helper's exit is not a "sink", so this is judged on its own.)
+  const forced = guardForcedBeforeExit(lines, guardIdx, fn, looksIndented(lines, file));
+  if (!forced.ok) return result(false, `callee-guard-not-forced:${forced.reason}`);
+  // 2. in the sink's code the call must itself run before the sink
+  const outside = guardDominatesSink({ lines, guardIdx: callIdx, sinkIdx, file, depth: depth + 1 });
+  if (!outside.dominates) return result(false, `callee-not-forced-before-sink:${outside.reason}`);
+  return result(true, 'validator-helper-called-before-sink');
+}
+
+/** Is the guard on every path to the end of its own function? */
+function guardForcedBeforeExit(lines, guardIdx, fn, indentStyle) {
+  const gl = code(lines[guardIdx]);
+  if (DATA_DECL.test(gl)) return { ok: false, reason: 'data-declaration-not-a-check' };
+  // The guard must sit at the function body's own nesting level, not inside an `if`, loop or `try` of its own.
+  if (indentStyle) {
+    let bodyIndent = -1;
+    for (let i = fn.declIdx + 1; i <= fn.endIdx; i++) if (!blank(lines[i])) { bodyIndent = indentOf(lines[i]); break; }
+    if (indentOf(lines[guardIdx]) !== bodyIndent) return { ok: false, reason: 'guard-nested-in-helper' };
+  } else {
+    let depth = 0; let opened = false;
+    for (let i = fn.declIdx; i < guardIdx; i++) {
+      for (const ch of code(lines[i])) { if (ch === '{') { depth++; opened = true; } else if (ch === '}') depth--; }
+    }
+    if (!opened || depth !== 1) return { ok: false, reason: 'guard-nested-in-helper' };
+  }
+  const conditional = CONDITIONAL_HEAD.test(gl);
+  if (!conditional) return { ok: true, reason: 'straight-line-in-helper' };
+  if (branchExits(lines, guardIdx, indentStyle)) return { ok: true, reason: 'failing-branch-exits' };
+  return { ok: false, reason: 'failing-branch-does-not-exit' };
+}
+
+const LITERAL_ASSIGN = /^\s*(?:[\w$.]+\s+)?([A-Za-z_$][\w$]*(?:\.[\w$]+)*)\s*=\s*(?:'[^']*'|"[^"]*"|`[^`]*`|""|null|None|nil|undefined|false|0)\s*;?\s*$/;
+const identsOf = (text) => new Set((String(text).match(/[A-Za-z_$][\w$]*/g) || []).map((x) => x.replace(/^\$/, '')));
+
+/**
+ * Does the failing branch REPLACE the value the condition checked with a literal (`if (bad($next)) { $next = "/"; }`)? Then no path reaches
+ * the sink carrying the unchecked value, which is what a guard is for. The assigned name must be one the condition names.
+ */
+function branchNeutralizes(lines, guardIdx, indentStyle) {
+  const gl = code(lines[guardIdx]);
+  const checked = identsOf(gl.replace(/^\s*(?:\}\s*)?(?:else\s+)?(?:if|unless|elif|elsif|while|until|when|guard)\b/, ''));
+  const bodyIdx = [];
+  if (indentStyle) {
+    const gi = indentOf(lines[guardIdx]);
+    for (let i = guardIdx + 1; i < lines.length; i++) { if (blank(lines[i])) continue; if (indentOf(lines[i]) <= gi) break; bodyIdx.push(i); }
+  } else {
+    const block = branchRange(lines, guardIdx);
+    if (block) for (let i = block.start; i <= block.end; i++) bodyIdx.push(i);
+  }
+  for (const i of bodyIdx) {
+    const stmt = code(lines[i]).replace(/^[^{]*\{/, '').replace(/\}\s*$/, '');
+    for (const part of stmt.split(';')) {
+      const m = LITERAL_ASSIGN.exec(part.trim());
+      if (m && checked.has(m[1].replace(/^\$/, '').split('.')[0])) return true;
+    }
+  }
+  return false;
+}
+
+/** Does the branch a conditional guard opens leave the function (throw, return, exit, abort)? Polarity is not judged. */
+function branchExits(lines, guardIdx, indentStyle) {
+  if (branchNeutralizes(lines, guardIdx, indentStyle)) return true;
+  const gl = code(lines[guardIdx]);
+  if (indentStyle) {
+    if (MODIFIER_EXIT.test(gl)) return true;
+    const gi = indentOf(lines[guardIdx]);
+    if (/:\s*\S/.test(gl) && TERMINATOR.test(gl.slice(gl.lastIndexOf(':') + 1))) return true;
+    const body = [];
+    for (let i = guardIdx + 1; i < lines.length; i++) { if (blank(lines[i])) continue; if (indentOf(lines[i]) <= gi) break; body.push(i); }
+    const inner = body.length ? indentOf(lines[body[0]]) : -1;
+    return body.some((i) => indentOf(lines[i]) === inner && TERMINATOR.test(code(lines[i])));
+  }
+  const block = branchRange(lines, guardIdx);
+  const afterCond = gl.replace(/^\s*(?:\}\s*)?(?:else\s+)?(?:if|unless|elif|elsif|while|until|when|guard)\b/, '');
+  if (!block || block.start === guardIdx) {
+    if (TERMINATOR.test(afterCond.replace(/^\s*\([^)]*\)/, '')) || /\breturn\b|\bthrow\b/.test(afterCond)) return true;
+  }
+  return !!(block && branchTerminates(lines, block));
+}
+
+function braceDominates(lines, guardIdx, sinkIdx, gl) {
+  // Depth at the START of each line, relative to the guard line's own start.
+  const depthStart = new Array(sinkIdx - guardIdx + 2).fill(0);
+  let depth = 0;
+  for (let i = guardIdx; i <= sinkIdx; i++) {
+    depthStart[i - guardIdx] = depth;
+    const c = code(lines[i]);
+    const { open, close } = countBraces(c);
+    depth += open - close;
+  }
+  // The guard's enclosing block must still be open at the sink: nothing between may dip below the guard's own level.
+  for (let i = guardIdx + 1; i <= sinkIdx; i++) {
+    if (depthStart[i - guardIdx] < 0) return result(false, 'guard-block-closed-before-sink');
+  }
+
+  if (!CONDITIONAL_HEAD.test(gl) && !/\?[^:]*:/.test(gl)) return result(true, 'straight-line-before-sink');
+  if (/\?[^:]*:/.test(gl) && !CONDITIONAL_HEAD.test(gl)) return result(false, 'unknown-shape');
+
+  // A conditional guard. Case 1: the sink sits INSIDE the branch the condition opens.
+  const block = branchRange(lines, guardIdx);
+  if (block && sinkIdx > block.start && sinkIdx <= block.end) return result(true, 'sink-inside-guarded-branch');
+  // Case 2: the condition guards an early exit and the sink comes after it.
+  const afterCond = gl.replace(/^\s*(?:\}\s*)?(?:else\s+)?(?:if|unless|elif|elsif|while|until|when|guard)\b/, '');
+  if (!block || block.start === guardIdx) {
+    // Single-line form: `if (!allowed(h)) return;` : an exit on the same line, after the condition.
+    if (TERMINATOR.test(afterCond.replace(/^\s*\([^)]*\)/, '')) || /\breturn\b|\bthrow\b/.test(afterCond)) return result(true, 'early-exit-on-guard-line');
+  }
+  if (block && branchTerminates(lines, block)) return result(true, 'failing-branch-exits');
+  if (branchNeutralizes(lines, guardIdx, false)) return result(true, 'failing-branch-neutralizes-value');
+  return result(false, 'failing-branch-does-not-exit');
+}
+
+/** [start, end] line indices of the `{ ... }` block opened at or after `idx`, or null. */
+function branchRange(lines, idx) {
+  let depth = 0; let start = -1;
+  for (let i = idx; i < Math.min(lines.length, idx + 40); i++) {
+    const c = code(lines[i]);
+    for (const ch of c) {
+      if (ch === '{') { if (start < 0) start = i; depth++; }
+      else if (ch === '}') { depth--; if (start >= 0 && depth === 0) return { start, end: i }; }
+    }
+    // A brace-less single statement ends the search at the next line that is not part of the condition.
+    if (start < 0 && i > idx && !/[(&|,]\s*$/.test(code(lines[i - 1]))) return null;
+  }
+  return null;
+}
+
+function branchTerminates(lines, block) {
+  let depth = 0;
+  for (let i = block.start; i <= block.end; i++) {
+    const c = code(lines[i]);
+    // Only a statement at the branch's own top level counts: a `return` buried in a nested `if` inside it does not stop the branch.
+    const startDepth = depth;
+    depth += countBraces(c).open - countBraces(c).close;
+    const topLevel = i === block.start ? true : startDepth === 1;
+    if (topLevel && TERMINATOR.test(i === block.start ? c.slice(c.indexOf('{') + 1) : c)) return true;
+  }
+  return false;
+}
+
+function indentDominates(lines, guardIdx, sinkIdx, gl) {
+  const gi = indentOf(lines[guardIdx]);
+  // The guard's block must still enclose the sink: no non-blank line between may be LESS indented than the guard.
+  for (let i = guardIdx + 1; i <= sinkIdx; i++) {
+    if (blank(lines[i])) continue;
+    if (indentOf(lines[i]) < gi) return result(false, 'guard-block-closed-before-sink');
+  }
+  if (MODIFIER_EXIT.test(gl)) return result(true, 'early-exit-on-guard-line');
+  const head = CONDITIONAL_HEAD.test(gl) || /\bif\b|\bunless\b/.test(gl) && /:\s*$/.test(gl);
+  if (!head) return result(true, 'straight-line-before-sink');
+
+  // A conditional: collect the indented block that follows the header.
+  const bodyLines = [];
+  for (let i = guardIdx + 1; i < lines.length; i++) {
+    if (blank(lines[i])) continue;
+    if (indentOf(lines[i]) <= gi) break;
+    bodyLines.push(i);
+  }
+  if (bodyLines.includes(sinkIdx) || (bodyLines.length && sinkIdx > bodyLines[0] && sinkIdx <= bodyLines[bodyLines.length - 1])) {
+    return result(true, 'sink-inside-guarded-branch');
+  }
+  // One-liner `if not ok(x): raise ...`.
+  const afterColon = gl.slice(gl.lastIndexOf(':') + 1);
+  if (/:\s*\S/.test(gl) && TERMINATOR.test(afterColon)) return result(true, 'early-exit-on-guard-line');
+  // Direct statements of the block (one indent level in) that exit.
+  const inner = bodyLines.length ? indentOf(lines[bodyLines[0]]) : -1;
+  if (bodyLines.some((i) => indentOf(lines[i]) === inner && TERMINATOR.test(code(lines[i])))) return result(true, 'failing-branch-exits');
+  if (branchNeutralizes(lines, guardIdx, true)) return result(true, 'failing-branch-neutralizes-value');
+  return result(false, 'failing-branch-does-not-exit');
+}

package/src/discovery/CLAUDE.md

@@ -53,6 +53,15 @@ panel · `judge.js` shapes findings and dedupes against the prior scan ·
 one area), merged areas are capped, and hunter prompts for Haskell and Nix are redacted (split literals joined first) before they
 leave the process. `hunt` includes `.hs`, `.lhs` and `.nix`. With no endpoint every run is degraded and says so.
 
+## Invariant proposals (X-402)
+
+`lenses.js` `invariantProposalFor(candidate)` maps a candidate from a state-oriented lens (`authz`, `business-logic`, and
+`feature-abuse` when it is about tenants) to a PROPOSED invariant skeleton (`posture/invariants/lifecycle.js`): authored by the
+model, with the candidate as source evidence and a high uncertainty. `runDiscovery` reports them as `invariantProposals` only when
+`opts.invariantProposals = { config }` is passed AND the `invariant-scenarios` feature is enabled in that config; nothing else in the
+report changes. A proposal is a hypothesis: it can be run as a scenario and its violations are reported as candidates, but only a
+human reviewer's signed approval in the invariant ledger makes it a requirement, so a hunter never establishes its own ground truth.
+
 ## Advisory/gating separation (X-207)
 
 Hunt output stays advisory in code, not just by convention. `memory.js` writes only through

package/src/discovery/index.js

@@ -8,7 +8,7 @@
 // pass that half failed and reports "no findings" is indistinguishable from a
 // clean codebase unless it says so.
 import { partitionCallGraph, partitionNixFiles } from './partition.js';
-import { LENSES, lensByKey } from './lenses.js';
+import { LENSES, lensByKey, invariantProposalFor } from './lenses.js';
 import { runHunter } from './hunter.js';
 import { confirmAll } from './confirm.js';
 import { disprovePanel } from './disprove.js';
@@ -16,6 +16,7 @@ import { judgeCandidates } from './judge.js';
 import { loadMemory, saveMemory, rememberRun, previouslyRefuted, nextWavePlan } from './memory.js';
 import { emitVerification, headCommit } from '../posture/verification/emit.js';
 import { promoteHypothesis } from '../posture/verification/hypothesis-promotion.js';
+import { featureStatus } from '../posture/assurance/config.js';
 
 // Bridge a candidate to the deterministic layer. A taint finding at or within
 // two lines of the candidate corroborates it; a modelled sink on the line
@@ -295,6 +296,18 @@ export async function runDiscovery(ctx = {}, opts = {}) {
     if (e.ok) verificationRecords.push(e.record);
   }
 
+  // X-402: opt-in invariant proposals. A candidate from a state-oriented lens can suggest a contract; the suggestion is advisory,
+  // `proposed`, authored by the model and never approved here. Off unless `opts.invariantProposals = { config }` and the
+  // `invariant-scenarios` feature is enabled in that config.
+  let invariantProposals = null;
+  if (opts.invariantProposals && featureStatus(opts.invariantProposals.config, 'invariant-scenarios').status === 'ok') {
+    invariantProposals = [];
+    for (const f of fresh) {
+      const inv = invariantProposalFor({ lens: f.discovery?.lens, title: f.vuln, description: f.description, file: f.file, line: f.line });
+      if (inv) invariantProposals.push({ hypothesisId: f.stableId, invariant: inv });
+    }
+  }
+
   // X-207: opt-in promotion. A hypothesis crosses into a finding ONLY through `promoteHypothesis` (trusted verifier receipt,
   // explicit policy, audit record). `fresh` is unchanged; promoted findings and every decision's audit record are reported
   // separately, and nothing here writes `last-scan.json`. `opts.promote = { policy, verify(hypothesis) -> runOracle result }`.
@@ -316,6 +329,7 @@ export async function runDiscovery(ctx = {}, opts = {}) {
     fresh,
     verificationRecords,
     ...(promotions ? { promotions } : {}),
+    ...(invariantProposals ? { invariantProposals } : {}),
     duplicates,
     suppressed,
     // `refutedCandidates` holds RAW candidates straight from `disprovePanel`,

package/src/discovery/lenses.js

@@ -8,6 +8,7 @@
 // no single prompt reaches. `wildcard` exists because a fixed taxonomy is a
 // ceiling, and the classes worth finding are the ones not on the list.
 import { redactPayload } from '../egress/redact.js';
+import { inferredInvariant } from '../posture/invariants/lifecycle.js';
 export const LENSES = Object.freeze([
   { key: 'injection', title: 'Injection', family: 'injection', cwe: 'CWE-74',
     brief: 'Untrusted input reaching an interpreter: SQL, shell, template, XPath, LDAP, or deserialization. Follow the value, not the function name.' },
@@ -25,6 +26,23 @@ export const LENSES = Object.freeze([
     brief: 'Anything the other lenses do not cover. Prefer the surprising and specific over the generic; report nothing rather than something already obvious.' },
 ]);
 
+// X-402: the lenses that reason about who may do what to whose data can propose an INVARIANT for a candidate they raise. The
+// proposal is a skeleton contract authored by the model (`proposed`, with the candidate as source evidence and a high uncertainty),
+// advisory until a reviewer approves it in the signed ledger. A lens whose candidates are not about state (injection, crypto) has
+// no mapping and proposes nothing.
+const TENANT_HINT = /tenant|idor|ownership|object reference|cross[- ]?(?:account|user|org)|leak|another user|other user/i;
+const WORKFLOW_HINT = /refund|order|status|workflow|state machine|out[- ]of[- ]order|step|approval|checkout|paid|ship/i;
+
+export function invariantProposalFor(candidate) {
+  const text = `${candidate?.title || ''} ${candidate?.description || ''} ${candidate?.rationale || ''}`;
+  let cls = null;
+  if (candidate?.lens === 'authz') cls = TENANT_HINT.test(text) ? 'tenant-isolation' : 'privilege-constraint';
+  else if (candidate?.lens === 'feature-abuse' && TENANT_HINT.test(text)) cls = 'tenant-isolation';
+  else if (candidate?.lens === 'business-logic' && WORKFLOW_HINT.test(text)) cls = 'workflow-order';
+  if (!cls || typeof candidate.file !== 'string') return null;
+  return inferredInvariant({ class: cls, source: 'discovery-lens', evidence: { file: candidate.file, line: Number.isInteger(candidate.line) ? candidate.line : null, lens: candidate.lens }, uncertainty: 0.85 });
+}
+
 export function lensByKey(key) {
   if (typeof key !== 'string') return null;
   return LENSES.find(l => l.key === key) || null;

package/src/engine.js

@@ -243,6 +243,7 @@ import { applyLearnedCalibration } from './posture/triage-learning.js';
 import { annotateFormalVerification } from './dataflow/formal-verify.js';
 import { annotateProofGate } from './dataflow/proof-gate.js';
 import { applySanitizerGate } from './dataflow/sanitizer-gate.js';
+import { guardDominatesSink } from './dataflow/guard-dominance.js';
 import { annotateFalsification } from './posture/falsification.js';
 import { routeModelForFinding } from './posture/model-routing.js';
 import { buildEntrypointInventory } from './posture/entrypoint-inventory.js';
@@ -1468,10 +1469,38 @@ function _guardWindow(ctx, before = 25, after = 5) {
   const line = ctx.line || 1;
   const lo = Math.max(0, line - before);
   const hi = Math.min(ctx.lines.length, line + after);
-  return ctx.lines.slice(lo, hi).join('\n')
-    .replace(/\/\*[\s\S]*?\*\//g, ' ')
-    .replace(/\/\/[^\n]*/g, ' ')
-    .replace(/(^|[^\w'"`])#[^\n]*/g, '$1 ');
+  return _stripCommentsKeepLines(ctx.lines.slice(lo, hi).join('\n'));
+}
+
+// Comment removal that is aware of string literals and keeps every newline, so a line index in the result is a line index in the file.
+// The previous regex chain treated the `//` in `"https://"` as the start of a comment and erased the rest of the line, which is where the
+// allow-list check usually is (`in_array("https://" . $host, $allowed)`): a guard written on that line disappeared from the window and a
+// neighbouring declaration happened to stand in for it. Strings never span lines here; a stray apostrophe therefore costs at most one line.
+function _stripCommentsKeepLines(text) {
+  let out = '';
+  let i = 0; const n = text.length;
+  let quote = null;
+  while (i < n) {
+    const c = text[i]; const d = text[i + 1];
+    if (c === '\n') { quote = null; out += c; i++; continue; }
+    if (quote) {
+      out += c;
+      if (c === '\\' && i + 1 < n && text[i + 1] !== '\n') { out += text[i + 1]; i += 2; continue; }
+      if (c === quote) quote = null;
+      i++; continue;
+    }
+    if (c === '"' || c === "'" || c === '`') { quote = c; out += c; i++; continue; }
+    if (c === '/' && d === '*') {
+      const end = text.indexOf('*/', i + 2);
+      const body = text.slice(i, end < 0 ? n : end + 2);
+      out += body.replace(/[^\n]/g, ' ');
+      i += body.length; continue;
+    }
+    if (c === '/' && d === '/') { while (i < n && text[i] !== '\n') { out += ' '; i++; } continue; }
+    if (c === '#' && (i === 0 || !/[\w'"`]/.test(text[i - 1]))) { while (i < n && text[i] !== '\n') { out += ' '; i++; } continue; }
+    out += c; i++;
+  }
+  return out;
 }
 
 // PRD R15: a guard-shaped token anywhere in the -25/+5 window used to be
@@ -1524,7 +1553,20 @@ function _guardMatchNearSinkIdentifier(ctx, guardRe, span = 2) {
   const w = _guardWindow(ctx);
   const re = new RegExp(guardRe.source, guardRe.flags.includes('g') ? guardRe.flags : guardRe.flags + 'g');
   const ids = _sinkLineIdentifiers(ctx);
-  if (!ids.size) return re.test(w); // can't correlate — fall back to the old shape-only check
+  // QA-005.AC02: text that LOOKS like a guard is not enough; it must dominate the sink. `_guardWindow` starts at `winLo` in the file.
+  const winLo = Math.max(0, (ctx.line || 1) - 25);
+  const sinkIdx = (ctx.line || 1) - 1;
+  const dominates = (windowLineIdx) => {
+    const v = guardDominatesSink({ lines: ctx.lines, guardIdx: winLo + windowLineIdx, sinkIdx, file: ctx.file });
+    if (v.dominates) ctx._guardEvidence = { guardLine: winLo + windowLineIdx + 1, dominance: v.reason };
+    else if (_stageEvidenceOn()) _stageEvidence.guard.push({ file: ctx.file || null, sinkLine: sinkIdx + 1, guardLine: winLo + windowLineIdx + 1, rejectedBecause: v.reason });
+    return v.dominates;
+  };
+  if (!ids.size) { // can't correlate by identifier: shape-only, but the shape must still dominate
+    let nm; const probe = new RegExp(re.source, re.flags);
+    while ((nm = probe.exec(w))) { if (dominates(w.slice(0, nm.index).split('\n').length - 1)) return true; if (nm.index === probe.lastIndex) probe.lastIndex++; }
+    return false;
+  }
   const wLines = w.split('\n');
   const sinkLineText = (ctx.lines && ctx.lines[(ctx.line || 1) - 1]) || '';
   let m;
@@ -1547,7 +1589,7 @@ function _guardMatchNearSinkIdentifier(ctx, guardRe, span = 2) {
     const hi = Math.min(wLines.length, guardLineIdx + span + 1);
     const local = wLines.slice(lo, hi).filter((l) => l !== sinkLineText).join('\n');
     for (const id of ids) {
-      if (new RegExp(`\\b${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`).test(local)) return true;
+      if (new RegExp(`\\b${id.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}\\b`).test(local) && dominates(guardLineIdx)) return true;
     }
   }
   return false;
@@ -1555,6 +1597,16 @@ function _guardMatchNearSinkIdentifier(ctx, guardRe, span = 2) {
 
 function _hasSsrfHostGuard(ctx) { return _guardMatchNearSinkIdentifier(ctx, _SSRF_HOST_GUARD_RE); }
 
+// An open-redirect (CWE-601) target guard: a framework's local-URL / safe-redirect predicate, a relative-path check (`startsWith("/")`),
+// or a host allow-list. QA-006: once the taint layer sees a handler's implicit request parameters, a redirect that is validated
+// by the framework's own predicate (`LocalRedirect(Url.IsLocalUrl(next) ? next : "/")`) reaches this pass like any other guarded
+// sink, and is cleared by the same rule as SSRF and path guards: the guard must name the sink's identifier AND dominate the sink.
+const _REDIRECT_GUARD_RE = new RegExp(
+  String.raw`\b(?:IsLocalUrl|is_safe_url|url_has_allowed_host_and_scheme|safe_redirect|safeRedirect|isSafeRedirect|isRelativeUrl|is_relative_url|validateRedirect|validate_redirect|SafeRedirect)\b`
+  + String.raw`|\.\s*(?:startsWith|startswith|StartsWith|HasPrefix)\s*\(\s*['"]/['"]\s*\)|\bstr_starts_with\s*\(|\bstrpos\s*\(\s*\$?\w+\s*,\s*['"]/['"]\s*\)`
+  + '|' + _SSRF_HOST_GUARD_RE.source, _SSRF_HOST_GUARD_RE.flags);
+function _hasRedirectGuard(ctx) { return _guardMatchNearSinkIdentifier(ctx, _REDIRECT_GUARD_RE); }
+
 // A path-traversal containment guard near the file sink: a basename/strip
 // helper that removes directory components, a framework safe-join, or a
 // canonicalize-then-startsWith containment check.
@@ -1609,7 +1661,7 @@ function _hasXssOutputEncoding(ctx) {
 // detector produced them, using the same comment-stripped window guards.
 // Recall-safe: a genuinely-unguarded sink has no guard in its window (the
 // cve-replay vulnerable-tier TP count is the invariant that proves this).
-export function dropGuardedFindings(findings, fileContents) {
+export function dropGuardedFindings(findings, fileContents, onDrop = null) {
   if (!Array.isArray(findings)) return findings;
   const cache = new Map();
   const linesOf = (file) => {
@@ -1641,7 +1693,7 @@ export function dropGuardedFindings(findings, fileContents) {
     if (f.family === 'sibling-guard-omission') return true;
     const cwe = f.cwe || '';
     const isXss = cwe === 'CWE-79' && /reflected xss/i.test(f.vuln || '');
-    if (cwe !== 'CWE-918' && cwe !== 'CWE-22' && !isXss) return true;
+    if (cwe !== 'CWE-918' && cwe !== 'CWE-22' && cwe !== 'CWE-601' && !isXss) return true;
     // Flow-pair findings (REGEX parser) carry the line on sink/source, not at
     // the top level; fall back to those before parsing it out of the id.
     let line = f.line;
@@ -1655,10 +1707,12 @@ export function dropGuardedFindings(findings, fileContents) {
     if (typeof line !== 'number') return true;
     const lines = linesOf(f.file);
     if (!lines) return true;
-    const ctx = { lines, line };
-    if (cwe === 'CWE-918' && _hasSsrfHostGuard(ctx)) return false;
-    if (cwe === 'CWE-22' && _hasPathGuard(ctx)) return false;
-    if (isXss && _hasXssOutputEncoding(ctx)) return false;
+    const ctx = { lines, line, file: f.file };
+    const dropped = (kind) => { if (onDrop) onDrop(f, { kind, line, evidence: ctx._guardEvidence || null }); return false; };
+    if (cwe === 'CWE-918' && _hasSsrfHostGuard(ctx)) return dropped('ssrf-host-guard');
+    if (cwe === 'CWE-22' && _hasPathGuard(ctx)) return dropped('path-containment-guard');
+    if (cwe === 'CWE-601' && _hasRedirectGuard(ctx)) return dropped('redirect-target-guard');
+    if (isXss && _hasXssOutputEncoding(ctx)) return dropped('xss-output-encoding');
     return true;
   });
 }
@@ -2693,7 +2747,14 @@ const _PROTOCOL_CONSTANT_VAL_RE = new RegExp('^(?:'
 }
 // Module-level suppression log; cleared at the start of each runFullScan invocation.
 const _suppressionLog = [];
-function _resetSuppressions(){ _suppressionLog.length = 0; }
+function _resetSuppressions(){ _suppressionLog.length = 0; _stageEvidence.dedupe.length = 0; _stageEvidence.guard.length = 0; }
+// QA-005: stage-level diagnostics for the evaluation's why-missed analysis. DIAGNOSTIC ONLY: it records what the filter and
+// dedupe stages did and never changes a finding (test/posture-level pin: findings are identical with it on and off). Collected
+// only when AGENTIC_SECURITY_STAGE_EVIDENCE=1, because a normal scan has no reader for it.
+//   guard:  guard-shaped text the recognizer found but that did NOT dominate its sink, so did not clear the finding
+//   dedupe: findings collapsed into a winner, with the loser's own location kept (matchable identity)
+const _stageEvidence = { dedupe: [], guard: [] };
+const _stageEvidenceOn = () => process.env.AGENTIC_SECURITY_STAGE_EVIDENCE === '1';
 // R8: the per-file taint result minus the four arrays that are also appended
 // wholesale to the aggregates. Resume rebuilds those from the aggregate slices
 // so pfr[p] and the aggregates share object identity, exactly as in a normal run.
@@ -6587,6 +6648,7 @@ function dedupeFindingsWithEvidence(findings){
       : (SEV_RANK[f.severity]??9) < (SEV_RANK[kept.severity]??9);
     const winner = keepNew ? f : kept;
     const loser  = keepNew ? kept : f;
+    if(_stageEvidenceOn())_stageEvidence.dedupe.push({file,family:fam,winner:{id:winner.id||null,file:winner.file||null,line:winner.line??null,parser:winner.parser||null},loser:{id:loser.id||null,file:loser.file||null,line:loser.line??null,parser:loser.parser||null}});
     if(!winner.evidence)winner.evidence=[winner.parser||"UNKNOWN"];
     if(loser.parser&&!winner.evidence.includes(loser.parser))winner.evidence.push(loser.parser);
     if(loser.vuln&&loser.vuln!==winner.vuln){
@@ -9602,7 +9664,10 @@ function _deterministicFileTimings(timings) {
   // #1 — centralized SSRF/path guard recognition: drop CWE-918/CWE-22 findings
   // on code hardened by a host allow/deny check or a path containment guard,
   // regardless of which detector emitted them. Opt out: AGENTIC_SECURITY_NO_GUARD_RECOGNITION=1.
-  if(process.env.AGENTIC_SECURITY_NO_GUARD_RECOGNITION!=='1'){try{finalFindings=dropGuardedFindings(finalFindings,fc);}catch(_){}}
+  if(process.env.AGENTIC_SECURITY_NO_GUARD_RECOGNITION!=='1'){try{finalFindings=dropGuardedFindings(finalFindings,fc,(f,why)=>{
+    // QA-005.AC01: a guard-recognized drop is a suppression and goes in the ledger with the identity a later analysis needs to match it.
+    _suppressionLog.push({vuln:f.vuln,file:f.file,line:why.line,snippet:f.snippet||'',reason:'guard-recognized:'+why.kind+(why.evidence?':dominates@'+why.evidence.guardLine+':'+why.evidence.dominance:''),id:f.id||null,cwe:f.cwe||null,family:f.family||null});
+  });}catch(_){}}
   // 0.34.6: filter out Java FPs where a sanitizer pattern (argv-form ProcessBuilder,
   // parameterized prepareStatement, constant-folded dead-branch) is present.
   // applyJavaBenchSuppressions is a no-op on non-.java files.
@@ -11098,7 +11163,7 @@ function _deterministicFileTimings(timings) {
     compliance: _complianceReport ? { stale: _complianceReport.summary?.stale || 0 } : null,
   });
   } // end if (!skipAnnotators) — FR-PROV-029
-  return{entrypointInventory:_entrypointInventory,rootCauseSweep:_rootCauseSweep,proofCoverage:_proofCoverage,kevCatalog:kevCatalogMeta(),routes:dd(aR,r=>`${r.method}:${r.path}:${r.file}:${r.line}`),findings:finalFindings,sources:aSrc,sinks:aSink,sanitizers:aSan,filesScanned:files.length,linesScanned:Object.values(fc).reduce((_n,_c)=>_n+(typeof _c==='string'?_c.split("\n").length:0),0),crossFileCount:cf.length,logicVulns:aLogic,supplyChain,components:annotatedComponents,secrets:aSecrets,ciphers:{atRest:aCiphersRest,inTransit:aCiphersTransit},pfr,fc,depFileContents,suppressions:_getSuppressions(),_v3,_scanMeta,_engineErrors:{cppDataflowParseErrors:_cppDataflowParseErrors.value},annotatorErrors:_annotatorErrors,detectorErrors:_detectorErrors,executionProof:_executionProofSummary,logicClaims:_logicClaims,vulnHistory:_vulnHistory,threatModel:_threatModel,privacyFramework:_privacyFramework,privacyIrBacked:_privacyIrBacked,privacyTaxonomyVersion:_privacyTaxonomyVersion,sbomDiff:_sbomDiff,complianceReport:_complianceReport,exploitBundles:_exploitBundles,pqcPlan:_pqcPlan,licenseGraph:_licenseGraph,attributions:_attributions,attackTaxonomy:_taxonomySummary,scanHealth:_scanHealth,coverageLedger:_coverageLedger,lineageGraph:_lineageGraph,lineageStatus:_lineageStatus,languageBridges:_languageBridges,languageBom:_languageBom,aiAssistance:_aiAssistance};}
+  return{entrypointInventory:_entrypointInventory,rootCauseSweep:_rootCauseSweep,proofCoverage:_proofCoverage,kevCatalog:kevCatalogMeta(),routes:dd(aR,r=>`${r.method}:${r.path}:${r.file}:${r.line}`),findings:finalFindings,sources:aSrc,sinks:aSink,sanitizers:aSan,filesScanned:files.length,linesScanned:Object.values(fc).reduce((_n,_c)=>_n+(typeof _c==='string'?_c.split("\n").length:0),0),crossFileCount:cf.length,logicVulns:aLogic,supplyChain,components:annotatedComponents,secrets:aSecrets,ciphers:{atRest:aCiphersRest,inTransit:aCiphersTransit},pfr,fc,depFileContents,suppressions:_getSuppressions(),...(_stageEvidenceOn()?{stageEvidence:{dedupe:[..._stageEvidence.dedupe],guard:[..._stageEvidence.guard]}}:{}),_v3,_scanMeta,_engineErrors:{cppDataflowParseErrors:_cppDataflowParseErrors.value},annotatorErrors:_annotatorErrors,detectorErrors:_detectorErrors,executionProof:_executionProofSummary,logicClaims:_logicClaims,vulnHistory:_vulnHistory,threatModel:_threatModel,privacyFramework:_privacyFramework,privacyIrBacked:_privacyIrBacked,privacyTaxonomyVersion:_privacyTaxonomyVersion,sbomDiff:_sbomDiff,complianceReport:_complianceReport,exploitBundles:_exploitBundles,pqcPlan:_pqcPlan,licenseGraph:_licenseGraph,attributions:_attributions,attackTaxonomy:_taxonomySummary,scanHealth:_scanHealth,coverageLedger:_coverageLedger,lineageGraph:_lineageGraph,lineageStatus:_lineageStatus,languageBridges:_languageBridges,languageBom:_languageBom,aiAssistance:_aiAssistance};}
 
 // Post-aggregation classification: every source becomes "unsafe"|"safe"; every sink becomes "confirmed"|"safe".
 // Orphans (no finding linkage) are bucketed by file-local heuristic so the UI shows binary states only.