@clear-capabilities/agentic-security-scanner 0.143.0 → 0.145.0

package/src/ir/CLAUDE.md

@@ -13,7 +13,7 @@ consumed by `scanner/src/dataflow/` for taint analysis.
 | Java     | `parser-java.js`      | `java-parser` npm package (**async only** — the deep path in `engine.js` therefore awaits `buildProjectIRAsync` when any `.java` file is present, and uses the sync builder otherwise).
 ⚠ Three defects made Java taint impossible until v0.136.3+: the sync-only call site; a CST walk looking for `blockStatement` on a `block` (java-parser nests `block → blockStatements → blockStatement`), which emptied every method CFG; and `exprFromCst` missing the `primary → primaryPrefix + primarySuffix` form that models **every** method call. Guarded by `test/java-taint-flow.test.js`. Real parameter names (previously always `params: []`, marked "deferred") plus Spring `@RequestParam`/`@PathVariable`/`@RequestBody`/`@RequestHeader` param annotations (`fn.paramAnnotations`) are extracted in one CST walk over `formalParameterList` (PRD R14(a) Task 5). Varargs parameters (`String... args`) live under a distinct `variableArityParameter` node this walk doesn't extract from — they're gracefully dropped, not corrupted or crashed on. **PRD R9 (partial): `fn.calls` is now populated** via the shared `call-sites.js#callSitesFromCfg` (the same language-agnostic helper `parser-py-cst.js` uses) — Java's CFG nodes (`call`, `assign`, `return`, `if`) already matched the documented contract. This creates real cross-file call-graph edges for Java (`callgraph.js`'s `edges`/`callersOf`/`resolveKnownCallee`, previously always empty for Java) — it does NOT change the generic tainted-call-argument fallback in `engine.js`'s `exprTaint`, which reads CFG expression args directly off `expr.args` and already worked for Java independent of `fn.calls`. However, **same-class (intra-class) method calls do not resolve, in both the bare and `this.`-qualified forms**: `parser-java.js` names functions `"App.buildCmd"` (class-qualified), but a bare call extracts `"buildCmd"` (unqualified) and `callgraph.js`'s name-based resolution cannot match them — this is the most idiomatic Java call shape (private helpers, intra-class delegation) and remains a real gap, documented here as a candidate follow-up PRD item (a per-file bare-tail fallback in `callgraph.js`, mirroring the existing `~bare~`-key collision-refusal pattern, would plausibly fix it without touching `parser-java.js`). `this.buildCmd(id)` is not merely unresolved, it's worse: `parser-java.js:76` lowers any `this.`-qualified call whose prefix isn't a plain FQN to the literal callee string `"unknown"`, so it doesn't fail closed, it fails to a fabricated name. Guarded by `test/parser-java-calls.test.js` (the test's honest caveat discloses this; the fixture shows that edges exist but unresolved) (mirrors `test/parser-rb-calls.test.js`, the identical `fn.calls` wiring, though Ruby's unqualified names make bare-call resolution work there). **PRD R8: `walkStmts` now recurses into `for`/`try`/`switch`/`do`/bare-block bodies** (previously only `if`/`while` were walked — every other braced statement kind silently dropped its body from the CFG, including try-with-resources, the single most idiomatic JDBC shape). A fix round closed two further gaps the initial review found: enhanced-for (`for (x : xs)`) now synthesizes an assign binding the loop variable to the iterated expression, so the variable itself carries taint provenance (mirroring `parser-js.js`'s `ForOfStatement` pattern); and Java 14+ arrow-form `switch` (`case 1 -> …`) is now recognized via a second CST-shape branch. Deferred, not fixed: `forInit`/`forUpdate` clauses of a basic 3-clause `for` loop are still not walked (only the loop body is); `synchronized` blocks and labeled statements are still fully dropped. Guarded by `test/parser-java-control-flow.test.js`. **Measured `bench/layer-recall` impact: unchanged, 1/25 before and after** — the fix is real and directly proven by the dedicated unit tests above, but this corpus's existing 25 Java fixtures happen not to place a sink genuinely inside a braced control-flow body (the ones with `if`/`try` syntax use it as a single-line guard clause ahead of a flat-level sink, not a nested one) — see the PRD R8 status entry for the full explanation and the same finding for C#. **Taint-recall PRD (80%) Tier 4: chained-call CST fix.** `exprFromCst`'s `primaryPrefix` handling previously used `.find(Boolean)` to grab the FIRST `methodInvocationSuffix` in a `primary` node's `primarySuffix[]` array and discarded the rest — so any 2+-level fluent chain (`DocumentBuilderFactory.newInstance().newDocumentBuilder().parse(xml)`, `new SpelExpressionParser().parseExpression(expr).getValue()`) resolved to the wrong (inner, usually untainted) call, and the real sink call at the end of the chain was invisible to the taint walker. Rewritten to walk the full `primarySuffix[]` array in source order, dot-joining bare member-access segments (`{Dot, Identifier}` suffixes) into the callee name and accumulating args from every `methodInvocationSuffix` encountered — same outermost-first accumulation convention (`args.concat(soFar)`) as the `_followChain` helper shared by the other five hand-rolled parsers (this PRD's earlier, language-general fix for the identical class of bug: a trailing call/member continuation being silently dropped rather than followed). A companion catalog entry (`java-spel-getvalue`, receiver-scoped to `^parseExpression`, `argIndex: 'all'`) was added because the chain fix shifts the terminal callee segment from `parseExpression` to `getValue` — same "terminal segment shift" pattern documented for Kotlin/Go/Java elsewhere in this PRD. Fixes `CVE-2018-1000632-java-xxe` (DocumentBuilderFactory chain) and `CVE-2018-1273-java-code-injection` (SpelExpressionParser chain). Guarded by two new cases in `test/java-taint-flow.test.js`. **UPDATE (Tier 3 command-injection audit): the `_SHELL_META` gap this note originally flagged is fixed.** `CVE-2016-10033-java-cmdi`'s real-world shape `Runtime.getRuntime().exec("ping " + host)` was blocked by a SEPARATE, language-agnostic core-engine bug (`engine.js`'s `literalSkeletonMatchesFamily`/`_SHELL_META`, requiring a shell metacharacter in the STATIC portion of a CWE-78 concat — backwards for command injection, see `dataflow/CLAUDE.md`), now removed entirely. The corpus fixture also needed a Tier 2 fixture enrichment (`@RequestParam` on the `host` parameter — the committed fixture had no cataloged source at all, a second, independent blocker this note's original git-stash bisection had isolated away from before concluding `_SHELL_META` was the (sole, at the time) remaining issue). Both fixed together; `CVE-2016-10033-java-cmdi` now scores `pre:TP post:TN`. **Taint-recall PRD (80%) Tier 5: a THIRD, independent chain-CST bug — a constructor STARTING a chain.** Found via `CVE-2019-3799-spring-ssrf-shape`'s real-world shape `new URL(url).openStream()`: the chained-call fix above (the `primarySuffix[]` walk) only handles a chain that starts from an FQN/identifier prefix (`prefix?.children?.fqnOrRefType?.[0]`) — a chain whose FIRST segment is itself `new X(args)` takes a completely different CST shape and was never checked, so both the class name and the constructor's own args were silently dropped, leaving only the trailing `.openStream()` call with no receiver. Root-caused via temporary `console.error(Object.keys(prefix?.children))` tracing (the first guess, matching the STANDALONE `new X(args)` handling elsewhere in this file at `unqualifiedClassInstanceCreationExpression` directly off `node`, was wrong — a chain-starting constructor sits one level deeper, under `prefix?.children?.newExpression?.[0]?.children?.unqualifiedClassInstanceCreationExpression?.[0]`). Fixed by extending the same `primaryPrefix` chain-seed logic to also recognize this shape (`ctorPrefix`), extracting the class name and constructor args exactly like the FQN case, so the chain fix now covers both "chain starts on an identifier" and "chain starts on a constructor". Companion catalog fix: `java-url-openstream` was previously keyed to the (now-unreachable-via-chain) bare `callee: 'URL'`; corrected to `callee: 'openStream', receiver: '^URL'` — the same "terminal segment shift" pattern this PRD documents repeatedly elsewhere (Kotlin/Go). Guarded by `test/catalog-path-ssrf-p3.test.js`. |
 | Go       | `parser-go.js`        | Hand-rolled. **Taint-recall PRD (80%) Tier 4: inline anonymous closures.** Go's dominant HTTP-handler-registration idiom across every framework this file targets (net/http, gin, echo, fiber, chi) is an inline closure passed as the LAST argument to a registration call — `app.Get(path, func(c *fiber.Ctx) error { ... })`, `http.HandleFunc(path, func(w, r) { ... })`. This parser previously had ZERO support for anonymous functions at all: `FUNC_RE` requires a NAME between `func` and `(`, so an inline closure never matched it, and `_lowerExpr`'s generic call-matching regex mis-parsed `func(params) rtype { body }` as a call to something literally named "func" — `matchBalancedCall` correctly captured only `(params)` as that "call"'s own args, and the return-type token plus the ENTIRE closure body were silently discarded (no `.method(...)` continuation follows a return type, so `_followChain` found nothing to recover). This was very likely this PRD's single most consequential Go gap — it made every framework's route-handler BODY invisible to taint analysis regardless of what it did — found via this PRD's Tier 3 command-injection audit, not the parent PRD's original per-language sweep. Fixed by `_extractTrailingClosureArg` detecting a statement's LAST top-level call argument as an inline closure literal and INLINING its body directly into the enclosing function's CFG right after the registration call — a permissive, recall-preserving approximation (the closure genuinely runs later, but what matters for taint is that its statements become real CFG nodes at all), mirroring the Kotlin trailing-lambda / Ruby trailing-block precedent elsewhere in this PRD. The closure's OWN parameter (`c`, `w`, `r`) needs no synthetic taint binding, unlike Kotlin's `.forEach { x -> ... }`: a framework context object isn't itself a source — `c.Query(...)` is recognized by the EXISTING member/call-source catalog matching regardless of which function scope `c` was declared in. Chained calls before the closure arg (`app.Group("/api").Get(path, func(){...})`) are not specially handled — out of scope, matches this file's "handle the dominant shape" precedent elsewhere. Guarded by `test/parser-go.test.js`. Two catalog/engine precision bugs surfaced in the SAME audit, both fixed alongside: `go-os-exec-command`'s `argIndex: 0` checked the WRONG argument (the real dangerous shape is `exec.Command("/bin/sh", "-c", tainted)`, where arg 0 is always the literal interpreter and the tainted content sits later) — widened to `argIndex: 'all'`, gated by a new `match.requireLiteralArg` precision primitive (`catalog.js`/`engine.js`) requiring arg 0 to literally be a shell interpreter, so the safe array-execve form (`exec.Command("ping", "-c", "1", host)`) does not spuriously fire; and a "terminal segment shift" (same pattern as `kt-xpath-evaluate`/`java-spel-getvalue`/`go-r-uquery-get` elsewhere in this PRD) for `exec.Command(...).Output()`/`.Run()`/`.CombinedOutput()`/`.Start()` — chaining a Cmd-execution method directly onto `exec.Command(...)`, the dominant idiom for actually RUNNING the command, collapses the chain into one dotted string whose last segment is no longer "Command". Guarded by `test/catalog-command-injection-p4.test.js`. **Measured `bench/layer-recall` impact: real movement — command-injection (this corpus's dominant Go family) moved from 5/23 → 18/23 across this fix plus the sibling `literalSkeletonMatchesFamily`/CWE-78 engine fix (`dataflow/CLAUDE.md`).** |
-| Ruby     | `parser-rb.js`        | Hand-rolled. **`DEF_RE` must not let `\s*` cross a newline** — it did, and the body slice then started after the method's first statement, silently dropping it from every method (a one-statement body became empty). Guarded by `test/parser-php-rb.test.js`. ⚠ Also emitted no `fn.calls` at all (every OTHER parser does) — `callgraph.js`'s edges/callersOf/resolveKnownCallee are built entirely from `fn.calls`, so this left dead-code demotion and any interprocedural signal that depends on real call-graph resolution (rather than engine.js's generic tainted-call-argument fallback) permanently blind to Ruby. Fixed by deriving `fn.calls` from the CFG via the shared `call-sites.js#callSitesFromCfg` (the same helper `parser-py-cst.js` uses) — Ruby's node shapes already matched its documented contract. Guarded by `test/parser-rb-calls.test.js`. **Taint-recall PRD (80%): full CFG rebuild.** `_buildCfg` previously only recursed into `if`/`unless`/`while`/`until` bodies — `for`, `case`/`when`/`else`, `begin`/`rescue`/`ensure`, and any trailing block attached to a call (`xs.each do |x| … end`, the dominant Rails/ActiveRecord idiom) were silently dropped entirely, with no CFG node at all. `case`/`when` and `begin`/`rescue`/`ensure` use a recall-preserving model (every arm/clause reachable directly from the construct's own entry point, not modeled as mutually exclusive — same tradeoff `parser-kt.js`'s `_buildWhenArms` already established). A `do` block's opener also had to sit at the START of a line to be recognized at all — `_splitStatements`' depth-tracking now scans the WHOLE line (via `_rbLineDepthDelta`) rather than gating on `_RB_OPENERS.test(line)`, so a trailing `do` (mid-line, the common case) is now correctly consolidated instead of splitting its own body into independent nonsense statements. Trailing blocks recurse unconditionally and bind every named block parameter to the call's receiver (permissive by design — Ruby has no equivalent of Kotlin's implicit-this `apply`/`run` that would need to NOT bind). A recursion-depth guard (60) was added, matching every other R8-style rebuild in this codebase. Three further, independent bugs surfaced during the rebuild's own corpus-fixture debugging, all fixed: (1) `::` (Ruby's module-scope call operator, e.g. `Nokogiri::XML(x)`) was entirely invisible to `matchBalancedCall`'s `[\w.]+` callee regex — normalized to `.` on lowering; (2) a subscript-assignment on a member chain (`response.headers[key] = value`) had no assign-target branch at all and was silently dropped — lowered as a synthetic `<receiver>.[]=(key, value)` call, same shape as `parser-py.helper.py`'s `__setitem__` synthesis; (3) `_lowerExpr` checked "does this start with a quote" BEFORE checking for top-level `+` concatenation, so `"/var/data/" + name` was swallowed whole as one opaque literal — reordered, with a new `_splitTopLevelPlus` helper (string/paren/bracket-aware, so `"a+b"` is not mis-split) fixing it the same way `parser-go.js`'s R3 fix did for the identical ordering bug. Also inherits this PRD's shared chained-call fix (`_followChain`, `matchBalancedCall`-based) and keyword-argument fix from earlier in the same PRD. **Known, deliberately deferred gap:** the brace form of a trailing block (`Nokogiri::XML(xml) { |c| … }`) has its TRIGGER call correctly recognized (unlike before, where the trailing `{ }` corrupted or blocked the match), but the block BODY itself is not recursed into — only the `do...end` form got full body recursion, since it is the dominant multi-line Rails idiom and the single corpus fixture needing brace-form support only needed the trigger call's own argument, not its body. **Also known, NOT Ruby-specific:** a sink nested inside ANOTHER call's own argument (e.g. `render plain: URI.open(tainted).read`) is not independently checkable — `engine.js`'s sink-matching operates at CFG-node granularity (the outer `render` call), not on arbitrary nested sub-expressions; the SAME limitation was found via C#/Go/Kotlin corpus work earlier in this PRD, not something this task introduced or fixed. Guarded by `test/parser-rb-control-flow.test.js`. Two genuine ReDoS regexes were caught and fixed by `bench:self-scan:check` during this task — the trailing-block detector's first version had the `(.+?)\s+do` shape (an unbounded lazy prefix, NOT the "optional group between `\s*`" class every other ReDoS fix in this codebase has been; splitting into alternatives alone did not fix it — the leading capturing group itself had to go, replaced with a direct anchored search for `\bdo\b`), and the SAME detector's heuristic still flagged the replacement's residual "optional group between `\s*`" shape even though it measured linear on its own — split into two alternatives to satisfy the detector too. Measured `bench/layer-recall` impact on dataflow-shaped-subset taint recall: real, substantial movement (see `docs/TAINT_RECALL_80PCT_PRD.md`) — Ruby's own family entries moved from mostly-0% to 8/10 taint-detected. **Taint-recall PRD (80%) Tier 3: backtick shell-execution operator.** Found in the command-injection audit: `` `finger #{user}` `` (Kernel#`, equivalent to `%x{...}`) is a completely distinct syntax from a double-quoted string, but had NO recognizer at all — it fell through every `_lowerExpr` branch to `{kind:'unknown'}`, silently dropping the shell command (and any interpolated taint inside it) entirely. Lowered to a synthetic call (`__ruby_backtick_exec__`, an identifier real Ruby code can never actually name a dotted method) carrying the interpolated command as its sole argument, so a normal callee-keyed catalog sink (`rb-backtick-exec`) targets it exactly like any other call-shaped sink. A SEPARATE gap surfaced testing this: a bare backtick expression as its OWN statement (not assigned to a variable — the LAST expression of a `do...end` block, which Ruby implicitly returns, is exactly this shape) matched none of `_lowerStmt`'s branches and was dropped even after the `_lowerExpr` fix; `_lowerStmt` now delegates to `_lowerExpr` directly for this shape. Guarded by `test/catalog-command-injection-p4.test.js`. |
+| Ruby     | `parser-rb.js`        | Hand-rolled. **`DEF_RE` must not let `\s*` cross a newline** — it did, and the body slice then started after the method's first statement, silently dropping it from every method (a one-statement body became empty). Guarded by `test/parser-php-rb.test.js`. ⚠ Also emitted no `fn.calls` at all (every OTHER parser does) — `callgraph.js`'s edges/callersOf/resolveKnownCallee are built entirely from `fn.calls`, so this left dead-code demotion and any interprocedural signal that depends on real call-graph resolution (rather than engine.js's generic tainted-call-argument fallback) permanently blind to Ruby. Fixed by deriving `fn.calls` from the CFG via the shared `call-sites.js#callSitesFromCfg` (the same helper `parser-py-cst.js` uses) — Ruby's node shapes already matched its documented contract. Guarded by `test/parser-rb-calls.test.js`. **Taint-recall PRD (80%): full CFG rebuild.** `_buildCfg` previously only recursed into `if`/`unless`/`while`/`until` bodies — `for`, `case`/`when`/`else`, `begin`/`rescue`/`ensure`, and any trailing block attached to a call (`xs.each do |x| … end`, the dominant Rails/ActiveRecord idiom) were silently dropped entirely, with no CFG node at all. `case`/`when` and `begin`/`rescue`/`ensure` use a recall-preserving model (every arm/clause reachable directly from the construct's own entry point, not modeled as mutually exclusive — same tradeoff `parser-kt.js`'s `_buildWhenArms` already established). A `do` block's opener also had to sit at the START of a line to be recognized at all — `_splitStatements`' depth-tracking now scans the WHOLE line (via `_rbLineDepthDelta`) rather than gating on `_RB_OPENERS.test(line)`, so a trailing `do` (mid-line, the common case) is now correctly consolidated instead of splitting its own body into independent nonsense statements. Trailing blocks recurse unconditionally and bind every named block parameter to the call's receiver (permissive by design — Ruby has no equivalent of Kotlin's implicit-this `apply`/`run` that would need to NOT bind). A recursion-depth guard (60) was added, matching every other R8-style rebuild in this codebase. Three further, independent bugs surfaced during the rebuild's own corpus-fixture debugging, all fixed: (1) `::` (Ruby's module-scope call operator, e.g. `Nokogiri::XML(x)`) was entirely invisible to `matchBalancedCall`'s `[\w.]+` callee regex — normalized to `.` on lowering; (2) a subscript-assignment on a member chain (`response.headers[key] = value`) had no assign-target branch at all and was silently dropped — lowered as a synthetic `<receiver>.[]=(key, value)` call, same shape as `parser-py.helper.py`'s `__setitem__` synthesis; (3) `_lowerExpr` checked "does this start with a quote" BEFORE checking for top-level `+` concatenation, so `"/var/data/" + name` was swallowed whole as one opaque literal — reordered, with a new `_splitTopLevelPlus` helper (string/paren/bracket-aware, so `"a+b"` is not mis-split) fixing it the same way `parser-go.js`'s R3 fix did for the identical ordering bug. Also inherits this PRD's shared chained-call fix (`_followChain`, `matchBalancedCall`-based) and keyword-argument fix from earlier in the same PRD. **Known, deliberately deferred gap:** the brace form of a trailing block (`Nokogiri::XML(xml) { |c| … }`) has its TRIGGER call correctly recognized (unlike before, where the trailing `{ }` corrupted or blocked the match), but the block BODY itself is not recursed into — only the `do...end` form got full body recursion, since it is the dominant multi-line Rails idiom and the single corpus fixture needing brace-form support only needed the trigger call's own argument, not its body. **Also known, NOT Ruby-specific:** a sink nested inside ANOTHER call's own argument (e.g. `render plain: URI.open(tainted).read`) is not independently checkable — `engine.js`'s sink-matching operates at CFG-node granularity (the outer `render` call), not on arbitrary nested sub-expressions; the SAME limitation was found via C#/Go/Kotlin corpus work earlier in this PRD, not something this task introduced or fixed. Guarded by `test/parser-rb-control-flow.test.js`. Two genuine ReDoS regexes were caught and fixed by `bench:self-scan:check` during this task — the trailing-block detector's first version had the `(.+?)\s+do` shape (an unbounded lazy prefix, NOT the "optional group between `\s*`" class every other ReDoS fix in this codebase has been; splitting into alternatives alone did not fix it — the leading capturing group itself had to go, replaced with a direct anchored search for `\bdo\b`), and the SAME detector's heuristic still flagged the replacement's residual "optional group between `\s*`" shape even though it measured linear on its own — split into two alternatives to satisfy the detector too. Measured `bench/layer-recall` impact on dataflow-shaped-subset taint recall: real, substantial movement — Ruby's own family entries moved from mostly-0% to 8/10 taint-detected. **Taint-recall PRD (80%) Tier 3: backtick shell-execution operator.** Found in the command-injection audit: `` `finger #{user}` `` (Kernel#`, equivalent to `%x{...}`) is a completely distinct syntax from a double-quoted string, but had NO recognizer at all — it fell through every `_lowerExpr` branch to `{kind:'unknown'}`, silently dropping the shell command (and any interpolated taint inside it) entirely. Lowered to a synthetic call (`__ruby_backtick_exec__`, an identifier real Ruby code can never actually name a dotted method) carrying the interpolated command as its sole argument, so a normal callee-keyed catalog sink (`rb-backtick-exec`) targets it exactly like any other call-shaped sink. A SEPARATE gap surfaced testing this: a bare backtick expression as its OWN statement (not assigned to a variable — the LAST expression of a `do...end` block, which Ruby implicitly returns, is exactly this shape) matched none of `_lowerStmt`'s branches and was dropped even after the `_lowerExpr` fix; `_lowerStmt` now delegates to `_lowerExpr` directly for this shape. Guarded by `test/catalog-command-injection-p4.test.js`. |
 | PHP      | `parser-php.js`       | Regex-based, hand-rolled. ⚠ **PRD R8 was this codebase's hardest single task — a genuine 3-fix-round debugging saga, all substantially about line-number precision, not detection shape.** The core fix flushes the statement splitter on a closing `}` (previously only on `;`), and adds `try`/`switch` recognizers plus a recursion guard, so statements inside `if`/`while`/`foreach`/`try`/`switch` bodies are now real CFG nodes instead of being dropped or folded into a bogus call node — this alone also resolved a pre-existing bug where `if`/`while`/`foreach` bodies were already being mis-split even before R8 touched them. Round 1 fixed the naive `}`-flush breaking `if`/`else` and multi-clause `try` (via a continuation-keyword lookahead) and switch/case's first-statement drop (via a `:`-based flush, careful to exclude `::` so PHP 8.1 enum cases and `case Foo::BAR:` class-constant labels aren't false-positived) — but round 1's own line-tracking approach was then found wrong for comment-bearing bodies and multi-line headers, a regression the round itself introduced. Round 2 fixed that (comment-skip handlers were discarding newlines uncounted; use exact `_countNewlines`-based computation everywhere) but its own re-review found the overall "exact line" property still failed, due to a *different*, genuinely pre-existing bug in the function-body's own base-line computation (wrong for Allman-brace style, multi-line signatures, blank-line-preceded functions) plus a genuine new regression from round 1 (a comment between `}` and `else`/`catch`/`finally` dropped that continuation's body entirely). Round 3 fixed both and was confirmed clean by an 8-shape holistic sweep. Also fixed along the way: dead `finally` support (greedy regex capture bug), unrecognized `try{}finally{}` with no `catch`, and the `::` case-label false-positive — via a hand-rolled balanced-brace scanner replacing the fragile regex approach. **Known, deliberately deferred gaps** (full list + grouping in the PRD R8 status entry): the PHP 8 `match` expression is unmodeled (same class as Java's arrow-switch); `if`/`else`'s pre-existing greedy-capture bug still drops the else-body's first statement; a heredoc containing a bare `}` loses its sink entirely (a real regression from R8's original commit, not the fix rounds); `elseif`/`else if` chains are still fully unsupported (pre-existing). Guarded by `test/parser-php-control-flow.test.js`. **Measured `bench/layer-recall` impact: unchanged, 1/23 before and after — the corpus's own `1/23 → 2/23` movement is real but belongs to R14(b) (PHP `<module>` top-level lowering), not this task**, confirmed by commit-swap A/B testing (the pre-R8 parser still reproduces 2/23; the pre-R14(b) parser reproduces only 1/23). None of this corpus's `pre/` PHP fixtures place a sink genuinely inside a braced control-flow body — same explanation as the other three languages' rows.
 
 **Taint-recall PRD (80%) Tier 4: comment-unawareness + `"literal" . $var` concat mis-parse.** Two PREVIOUSLY-DEFERRED gaps from the R8 list above, closed together (found while working the same gap class for Kotlin, below): (1) `_extractBody` (the function-BODY brace-matcher, a SEPARATE code path from `_splitStatements`'s own comment handling) had ZERO comment awareness — an apostrophe inside ANY comment ("don't", "it's") toggled its string-tracking state exactly like a real string literal, corrupting brace-depth for everything after it; depending on what followed, this either made `_extractBody` return `null` (silently dropping the **entire file's** IR — a single failed top-level function match corrupts every span downstream) or extracted the wrong body. Fixed by making `_extractBody` skip all three PHP comment forms (`//`, `#`, `/* */`) — the same fix `_splitStatements` already had for two of the three; `#`-comments (PHP's third form, previously invisible to `_splitStatements` too) are now handled there as well, careful to exclude `#[...]` PHP 8 attribute syntax from being mistaken for a comment. (2) `"literal" . $var` — arguably the single most common real-world PHP SQL-injection shape — was swallowed whole into one opaque `literal` node by TWO stacked bugs in `_lowerExpr`, each the same "unanchored prefix" defect class: the double-quoted-interpolation branch (`/^"/.test(s) && s.includes('$')`) matched on the WHOLE concat expression merely because it started with `"` and contained a `$` *anywhere* (in `$var`, outside the string, after the `.`), slicing off the wrong first/last characters as if the entire expression were one interpolated string; once that was fixed, the plain string-literal fallback (`/^"/.test(s)`) did the identical unanchored check one layer down and caught what the first fix now let through. Both are now anchored (`/^"(?:[^"\\]|\\.)*"$/`, full match required) so a concat correctly falls through to the `.`-splitting branch instead of either misreading the trailing ` . $var` as string content or swallowing the whole expression as an opaque literal. Guarded by 6 new cases in `test/parser-php-control-flow.test.js`, including an end-to-end `runScan` test proving real `$_GET`-to-PDO-sink taint flow through this exact concat shape. **Measured `bench/layer-recall` impact: real movement, PHP taint recall 2/23 (9%) → 7/23 (30%)** — the largest single per-language jump measured in this PRD, consistent with how common the `"literal" . $var` idiom is in real PHP code. **Taint-recall PRD (80%) Tier 3: PHP carried zero XSS sink entries.** `echo`/`print` are PHP LANGUAGE CONSTRUCTS, not function calls (`echo "<div>" . $_GET['q'] . "</div>";` has no `(` immediately after the keyword), so the statement-form call regex never matched them — the entire echoed expression, including any reflected taint, was silently dropped. `_lowerStmt` now recognizes `echo`/`print` directly and lowers to a synthetic call (`__php_echo__`, args split on top-level commas since `echo` accepts multiple comma-separated expressions), targeted by a new `php-echo-xss` sink — same synthetic-callee convention as Ruby's `__ruby_backtick_exec__` below. Guarded by `test/catalog-xss-p4.test.js`. |

package/src/llm-validator/index.js

@@ -65,7 +65,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 import { ensureStateDir, safeWriteState, statePath } from '../posture/state-dir.js';
-import { redactSecrets } from './redact.js';
+import { redactPayload } from '../egress/redact.js';
 import { signLastScan } from '../posture/integrity.js';
 
 // Bump on every prompt change so the cache invalidates. Exported as a
@@ -74,6 +74,9 @@ import { signLastScan } from '../posture/integrity.js';
 import { createCostLedger, parseCapUsd, renderCostCeiling } from './cost-ceiling.js';
 import { localEndpointConfig } from './local-endpoint.js';
 import { resolveProvider, buildProviderRequest, providerMatrix } from './providers.js';
+import { evaluateEgress } from '../egress/policy.js';
+import { recordEgressCall, payloadMetrics } from '../egress/audit.js';
+import { MODEL_STATUS, summarizeModelStatus } from './model-status.js';
 
 // The output cap we request. Shared with the cost estimate so the ceiling
 // charges exactly what we permit the model to produce.
@@ -295,7 +298,7 @@ export function sanitizeReasoning(s) {
     .slice(0, 280);
 }
 
-function renderPrompt(finding, fileContents, challenge, nonce) {
+function renderPrompt(finding, fileContents, challenge, nonce, scanRoot) {
   const code = fileContents?.[finding.file];
   let context = '';
   if (code && finding.line) {
@@ -315,12 +318,14 @@ function renderPrompt(finding, fileContents, challenge, nonce) {
   let sterileSnippet = String(finding.snippet || '')
     .replace(/[\r\n]+/g, ' ')
     .slice(0, 400);
-  // R10 — redact likely live credentials (API keys, tokens, private keys,
-  // connection-string passwords, ...) out of BOTH excerpts before anything
-  // leaves the machine. This is the last choke point before the prompt is
-  // assembled — everything downstream sees only redacted text.
-  sterileContext = redactSecrets(sterileContext).text;
-  sterileSnippet = redactSecrets(sterileSnippet).text;
+  // R10 / FR-603 — redact secrets (API keys, tokens, private keys,
+  // connection-string passwords), PII/PHI/PCI/FIN-shaped fields, operator-
+  // configured customer-data patterns, and whole-file content from an
+  // operator-configured proprietary path out of BOTH excerpts before
+  // anything leaves the machine. This is the last choke point before the
+  // prompt is assembled — everything downstream sees only redacted text.
+  sterileContext = redactPayload({ text: sterileContext, filePath: finding.file, scanRoot }).text;
+  sterileSnippet = redactPayload({ text: sterileSnippet, filePath: finding.file, scanRoot }).text;
   return PROMPT_TEMPLATE
     .replace(/\{\{nonce\}\}/g, nonce)
     .replace(/\{\{challenge\}\}/g, challenge)
@@ -440,8 +445,35 @@ export async function validateOne(finding, fileContents, scanRoot, ledger = null
   if (!cfg) {
     finding.validator_verdict = 'unvalidated';
     finding.unvalidated = true;
+    // FR-606: distinguish "the local preset refused a configured but
+    // non-loopback endpoint" (a policy decision) from "nothing was
+    // configured at all" (the tier is simply off) — endpointConfig()
+    // leaves _localPresetRefusal set only for the former.
+    finding.llmValidationStatus = _localPresetRefusal ? MODEL_STATUS.POLICY_BLOCKED : MODEL_STATUS.DISABLED;
     return { verdict: 'unvalidated' };
   }
+  // FR-601: egress policy evaluated before anything about this finding is
+  // rendered into a prompt (renderPrompt runs later, at line ~486) and before
+  // callEndpoint's fetch. A denial short-circuits here — no prompt is ever
+  // built for a denied endpoint, and the finding gets a distinct, honest
+  // error tag rather than being silently lumped in with "no answer received".
+  // FR-602: role/model are already resolved above (resolveProvider's own
+  // 'validate' role, cfg.model) — threading them through here is what
+  // makes the model/role constraint dimensions genuinely enforceable for a
+  // real caller, not just a mechanism nothing exercises.
+  const egressDecision = evaluateEgress({ scanRoot, purpose: 'llm-validator', endpoint: cfg.endpoint, role: 'validate', model: cfg.model });
+  if (!egressDecision.allowed) {
+    finding.validator_verdict = 'unvalidated';
+    finding.unvalidated = true;
+    finding._validatorError = 'egress-policy-denied';
+    finding._egressDecision = egressDecision;
+    finding.llmValidationStatus = MODEL_STATUS.POLICY_BLOCKED;
+    // FR-604: a denied call still gets an audit entry — purpose/provider/
+    // model/policy/outcome are all known without ever building a prompt,
+    // so byte/token/hash fields are simply absent (nothing was constructed).
+    recordEgressCall({ scanRoot, decision: egressDecision, ctx: { model: cfg.model, region: null } });
+    return { verdict: 'unvalidated', error: 'egress-policy-denied', egressDecision };
+  }
   // Pre-flight: refuse to validate location-less findings. Without a precise
   // file:line, the response cross-check degenerates and the validator can be
   // spoofed by trivially-true echoes.
@@ -479,11 +511,20 @@ export async function validateOne(finding, fileContents, scanRoot, ledger = null
     // against any future write-path regression that might cache un-sanitized text).
     finding.validator_reasoning = sanitizeReasoning(cached.reasoning);
     finding._validatorCache = 'hit';
+    // FR-606: a cache hit means the model DID answer at some point — not
+    // re-asking is an optimization, not a different outcome.
+    finding.llmValidationStatus = MODEL_STATUS.COMPLETED;
     return cached;
   }
   const challenge = crypto.randomBytes(8).toString('hex');
   const nonce     = crypto.randomBytes(8).toString('hex');
-  const prompt = renderPrompt(finding, fileContents, challenge, nonce);
+  const prompt = renderPrompt(finding, fileContents, challenge, nonce, scanRoot);
+  // FR-604: audit the allowed call now that the final (redacted) outbound
+  // payload is known — byte/token counts and a content hash, never the
+  // payload text itself. Recorded even if the call below fails or is
+  // blocked by the cost ceiling: the egress DECISION was 'allow' and a
+  // real payload was built, which is the fact this entry attests to.
+  recordEgressCall({ scanRoot, decision: egressDecision, ctx: { model: cfg.model, region: null }, metrics: payloadMetrics(prompt) });
 
   // R12 — the hard ceiling. Checked BEFORE the call, against a conservative
   // estimate: input from the prompt we are about to send, output at the full
@@ -503,6 +544,9 @@ export async function validateOne(finding, fileContents, scanRoot, ledger = null
       finding.validator_verdict = 'unvalidated';
       finding.unvalidated = true;
       finding.validator_skipped_reason = afford.reason;
+      // FR-606: a cost ceiling is an operator-configured policy denying the
+      // call, the same bucket as an egress denial — not a network failure.
+      finding.llmValidationStatus = MODEL_STATUS.POLICY_BLOCKED;
       return { verdict: 'unvalidated', error: 'cost-ceiling' };
     }
   }
@@ -522,6 +566,11 @@ export async function validateOne(finding, fileContents, scanRoot, ledger = null
     finding.validator_verdict = 'unvalidated';
     finding.unvalidated = true;
     finding._validatorError = resp.error;
+    // FR-606: the call was attempted and failed before any usable response
+    // arrived (non-2xx HTTP, or a fetch/network exception in callEndpoint)
+    // — the endpoint is unavailable right now, distinct from a policy
+    // refusal or a malformed reply.
+    finding.llmValidationStatus = MODEL_STATUS.UNAVAILABLE;
     return { verdict: 'unvalidated', error: resp.error };
   }
   const obj = parseLastJsonObject(resp.text);
@@ -533,6 +582,11 @@ export async function validateOne(finding, fileContents, scanRoot, ledger = null
     finding._validatorError = `verify-failed:${v.reason}`;
     finding.llm_confidence = 0.5;
     finding.validator_reasoning = sanitizeReasoning(`escalate (verify-failed:${v.reason})`);
+    // FR-606: a response DID come back, but its content could not be
+    // parsed/verified into a usable answer — the model answered something,
+    // just not something usable. Distinct from UNAVAILABLE (no response at
+    // all) and from a real verdict.
+    finding.llmValidationStatus = MODEL_STATUS.MALFORMED;
     return { verdict: 'escalate', error: v.reason };
   }
   const parsed = v.parsed;
@@ -541,6 +595,7 @@ export async function validateOne(finding, fileContents, scanRoot, ledger = null
   finding.llm_confidence = parsed.confidence;
   finding.validator_reasoning = parsed.reasoning;
   finding._validatorCache = 'miss';
+  finding.llmValidationStatus = MODEL_STATUS.COMPLETED;
   return parsed;
 }
 
@@ -563,12 +618,19 @@ export async function validateMany(findings, { fileContents, scanRoot, concurren
   const optOut = process.env.AGENTIC_SECURITY_LLM_VALIDATE === '0';
   const enabled = !!cfg && !optOut;
   if (!enabled) {
+    // FR-606: same distinction as validateOne's own !cfg branch — a
+    // configured-but-refused endpoint (local preset, non-loopback) is
+    // policy-blocked; nothing configured, OR an explicit operator opt-out
+    // (AGENTIC_SECURITY_LLM_VALIDATE=0), is the tier simply being off.
+    const status = _localPresetRefusal ? MODEL_STATUS.POLICY_BLOCKED : MODEL_STATUS.DISABLED;
     for (const f of findings) {
       f.validator_verdict = 'unvalidated';
       f.unvalidated = true;
       if (_localPresetRefusal) f.validator_skipped_reason = _localPresetRefusal;
+      f.llmValidationStatus = status;
     }
     if (_localPresetRefusal) findings.localPathRefusal = _localPresetRefusal;
+    findings.llmValidatorStatus = summarizeModelStatus(findings);
     return findings;
   }
   const candidates = findings.filter(f =>
@@ -593,7 +655,11 @@ export async function validateMany(findings, { fileContents, scanRoot, concurren
       f.validator_verdict = 'unvalidated';
       f.unvalidated = true;
       f.validator_skipped_reason = e.message;
+      // FR-606: a malformed operator config is a policy problem, same
+      // bucket as a valid-but-exceeded cost ceiling — not a network failure.
+      f.llmValidationStatus = MODEL_STATUS.POLICY_BLOCKED;
     }
+    findings.llmValidatorStatus = summarizeModelStatus(findings);
     return findings;
   }
 
@@ -606,6 +672,11 @@ export async function validateMany(findings, { fileContents, scanRoot, concurren
         // FAIL-CLOSED on exception too.
         candidates[idx].validator_verdict = 'escalate';
         candidates[idx]._validatorError = e.message;
+        // FR-606: an unexpected exception during validation (not a
+        // network-layer failure — those are already caught inside
+        // callEndpoint/validateOne) still means no usable answer was
+        // produced; closest of the five to what actually happened.
+        candidates[idx].llmValidationStatus = MODEL_STATUS.UNAVAILABLE;
       }
     }
   }
@@ -635,7 +706,13 @@ export async function validateMany(findings, { fileContents, scanRoot, concurren
     if (f.validator_verdict) continue;
     f.validator_verdict = 'unvalidated';
     f.unvalidated = true;
+    // FR-606 defensive fallback: every real branch above already sets this;
+    // reaching here means a candidate was filtered out (not a model-tier
+    // pass at all) — DO NOT stamp llmValidationStatus for those, the same
+    // "not applicable" convention validateOne itself uses for SCA locators
+    // and no-precise-location findings.
   }
+  findings.llmValidatorStatus = summarizeModelStatus(findings);
   return findings;
 }
 

package/src/llm-validator/model-status.js

@@ -0,0 +1,66 @@
+// FR-606 (assurance-hardening PRD): the 5-state model-status vocabulary
+// reports must distinguish, so an LLM-backed feature never converts "the
+// model didn't answer" into an undifferentiated clean result.
+//
+// Before this module, every degrade path in llm-validator/index.js set the
+// SAME finding.validator_verdict ('unvalidated'), with the actual reason
+// scattered across an inconsistently-populated free-text field
+// (_validatorError: 'egress-policy-denied' | 'cost-ceiling' | 'HTTP 500' |
+// an arbitrary exception message | ...unset entirely for the "nothing
+// configured" case). A reader — human or downstream tool — had no reliable
+// way to answer "did the model tier even run, and if not, why" from that
+// shape alone.
+//
+// Attached to each finding llm-validator touches as
+// finding.llmValidationStatus, carrying EXACTLY one of the five values
+// below (never a sixth ad-hoc string), and aggregated into a scan-level
+// summary via summarizeModelStatus so a reader gets the headline without
+// inspecting every finding.
+//
+// Deliberately NOT stamped on findings the validator skips for reasons
+// that have nothing to do with MODEL availability (an SCA locator with no
+// line number, a finding with no precise file:line at all) — those already
+// have their own honest verdict ('not-applicable') and status; forcing
+// them into this taxonomy would misrepresent a finding-suitability
+// question as a model-availability one.
+
+export const MODEL_STATUS = Object.freeze({
+  // No endpoint resolved at all — no API key, no BYO endpoint, nothing
+  // configured. The tier is off, not broken; nothing was attempted.
+  DISABLED: 'model-disabled',
+  // Something WAS configured, but a policy refused to use it before any
+  // network call was attempted — the egress policy's mode:deny/local-only/
+  // provider allow-deny lists, the local preset's own loopback-only
+  // refusal, or an internal cost-ceiling cap.
+  POLICY_BLOCKED: 'policy-blocked',
+  // The call was attempted and failed before a usable response arrived —
+  // a network error, a timeout, or a non-2xx HTTP status.
+  UNAVAILABLE: 'unavailable',
+  // A response DID come back, but its content could not be parsed into a
+  // usable answer, or failed the challenge/nonce cross-check — the model
+  // answered something, just not something usable.
+  MALFORMED: 'malformed',
+  // A real, validated verdict was produced (including a cache hit of one
+  // produced earlier — the model answered at some point; not re-asking is
+  // an optimization, not a different outcome).
+  COMPLETED: 'completed',
+});
+
+const ALL_STATUSES = Object.values(MODEL_STATUS);
+
+/**
+ * Aggregate the per-finding llmValidationStatus values into scan-level
+ * counts. Findings with no llmValidationStatus at all (not applicable to
+ * model availability — see the module header) are counted separately and
+ * never silently folded into one of the five buckets.
+ */
+export function summarizeModelStatus(findings) {
+  const counts = Object.fromEntries(ALL_STATUSES.map(s => [s, 0]));
+  let notApplicable = 0;
+  for (const f of findings || []) {
+    const s = f?.llmValidationStatus;
+    if (s && Object.prototype.hasOwnProperty.call(counts, s)) counts[s]++;
+    else notApplicable++;
+  }
+  return { counts, notApplicable, total: (findings || []).length };
+}

package/src/lsp/server.js

@@ -18,6 +18,7 @@ import * as path from 'node:path';
 import * as readline from 'node:readline';
 import { runScan } from '../runScan.js';
 import { resetCustomRulesBudget } from '../posture/custom-rules.js';
+import { withStateWritesDisabled } from '../posture/state-dir.js';
 import { redactFinding } from '../mcp/redact.js';
 import { _remediationOf } from '../report/index.js';
 
@@ -156,7 +157,34 @@ async function scanFile(uri) {
     // whose source and sink are connected only through a call. Scoped to
     // exactly the saved file (fileContents has one entry), so this does not
     // turn every keystroke's save into a full-project deep scan.
-    const { scan } = await runScan(_rootDir, { fileContents, depFileContents, deep: true, deepInCi: true });
+    // withStateWritesDisabled, for the same reason mcp/tools.js's scan_diff
+    // wraps its own partial-set scan (FR-704). This is a DIAGNOSTIC surface: it
+    // runs on every file save, against the user's real project root, with a
+    // fileContents map holding exactly one file. Without the wrapper,
+    // runFullScan's state writers fire on every keystroke-save — dpia.md,
+    // ropa.md, privacy-framework.json, threat-model.json and the rest, written
+    // into the user's tree by an editor plugin they never asked to mutate
+    // anything.
+    //
+    // The provenance lifecycle store makes that actively destructive rather
+    // than merely noisy: updateLifecycle marks every open stableId ABSENT from
+    // the finding set it is handed as `remediated`, and this set is one file's
+    // worth of findings. Every save would remediate the whole project, and the
+    // next real scan would reintroduce it.
+    //
+    // Chosen over forwarding `provenance:false` through runScan because that
+    // would fix only the lifecycle half and leave the other state writers
+    // firing. The flag is process-global (see its KNOWN LIMITATION), which is
+    // harmless here: this server is a read-only surface whose every scan wants
+    // writes off, so overlapping saves can only ever agree, and the `finally`
+    // restores the prior value either way. exceptCategories:['provenance-cache']
+    // (M2 §2.4) is the one deliberate exception — every OTHER write this scan
+    // would make stays suppressed, but the provenance disk cache stays live so
+    // repeated saves of the same file are not each paying the full uncached
+    // resolution cost.
+    const { scan } = await withStateWritesDisabled(() =>
+      runScan(_rootDir, { fileContents, depFileContents, deep: true, deepInCi: true }),
+      { exceptCategories: ['provenance-cache'] });
     // Stage 6 correctness audit: this only ever read scan.findings (the SAST
     // channel). scan.secrets and scan.logicVulns are separate arrays on the
     // raw runScan() result — normalizeFindings is what merges all four
@@ -298,7 +326,26 @@ export function startLspServer() {
 }
 
 // Allow direct invocation as a bin entry: `node lsp/server.js`.
-if (import.meta.url === `file://${process.argv[1]}`) {
+//
+// `import.meta.url === file://${process.argv[1]}` looks equivalent but is
+// NOT: when this script is invoked through a symlink (exactly what
+// `npm install -g`, `npx`, and `node_modules/.bin/<name>` all do for a
+// package's `bin` entries — and `agentic-security-lsp` IS one of this
+// package's bin entries), Node resolves `import.meta.url` to the symlink's
+// realpath while `process.argv[1]` stays the symlink path as invoked, so the
+// two never match, the guard is always false, and the server silently exits
+// with no output — an editor would see the language server start and
+// immediately die with nothing on stderr to explain it. `import.meta.main` is
+// resolved correctly through a symlink. It was added in Node v24.2.0
+// (backported to v22.18.0) and is currently Stability 1.0 (early development)
+// per Node's own docs — NOT stable, and NOT available on v20.11. Concretely:
+// it is `undefined` on Node 24.0.0/24.1.x, which satisfy this repo's declared
+// `engines.node: ">=24.0.0"` floor, so `import.meta.main` alone would
+// reproduce this exact bug on a plain non-symlinked invocation under those two
+// point releases. The `??` fallback covers that gap without bumping the
+// engines floor. Identical to bin/agentic-security.js's guard, deliberately —
+// see the long-form note there.
+if (import.meta.main ?? (import.meta.url === `file://${process.argv[1]}`)) {
   startLspServer();
 }