@clear-capabilities/agentic-security-scanner 0.144.0 → 0.147.0

package/src/fix/apply-fix-service.js

@@ -366,6 +366,7 @@ export async function applyVerifiedFix({ scanRoot, finding, files, fixMeta = nul
         stableId: finding.stableId || null,
         ruleId: finding.ruleId || finding.cwe || finding.family || null,
         vuln: finding.vuln || finding.title || null,
+        findingProvenance: finding.findingProvenance || null,
       });
       written.push({ file: rel, historyId: entry.id, backupPath: entry.backupPath, attemptOrdinal: entry.attemptOrdinal });
     }

package/src/history-scan.js

@@ -18,12 +18,16 @@
 import { spawnSync } from 'node:child_process';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import { hardenGitArgs, hardenGitEnv } from './util/git-hardening.js';
 import { runFullScan } from './engine.js';
 
 const MAX_FILES_PER_SCAN = 5000;
 
+// `root` is the scan target's repository, not this project's own trusted
+// checkout — hardened per FR-PROV-024 / the second Finding Provenance PRD
+// audit (same exposure class as provenance/git-evidence.js's `_run`).
 function _git(root, args) {
-  const r = spawnSync('git', args, { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  const r = spawnSync('git', hardenGitArgs(args), { cwd: root, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, env: hardenGitEnv() });
   return { ok: r.status === 0, stdout: r.stdout || '', stderr: r.stderr || '' };
 }
 
@@ -83,7 +87,10 @@ function _listFilesAtRef(root, ref) {
 }
 
 function _readFileAtRef(root, ref, file) {
-  const r = _git(root, ['show', `${ref}:${file}`]);
+  // `--no-textconv`: this blob-cat form of `show` was verified NOT
+  // reachable via a hostile textconv driver in current git — kept for
+  // defense-in-depth/uniformity, same as pr-delta.js's equivalent.
+  const r = _git(root, ['show', '--no-textconv', `${ref}:${file}`]);
   if (!r.ok) return null;
   return r.stdout;
 }
@@ -95,7 +102,13 @@ async function _scanAtRef(root, ref) {
     const c = _readFileAtRef(root, ref, f);
     if (c != null) fileContents[f] = c;
   }
-  const scan = await runFullScan({ fileContents, scanRoot: root }, () => {});
+  // `provenance:false` — this is a HISTORICAL ref, not "the state of this repo
+  // right now". Two things must not happen here: resolving git provenance for
+  // findings that already are a point in history (pure waste), and letting
+  // updateLifecycle see this partial, historical finding set as the current
+  // one — it marks every open stableId NOT in the set as `remediated`, so one
+  // per-ref scan would mass-remediate the whole project's real open findings.
+  const scan = await runFullScan({ fileContents, scanRoot: root, provenance: false }, () => {});
   return {
     ref,
     fileCount: Object.keys(fileContents).length,
@@ -177,8 +190,12 @@ export async function runWhatIf(root, { overlays = [], remove = [] } = {}) {
     }
   }
   // Baseline (without overlays) for delta computation.
-  const baseScan = await runFullScan({ fileContents: _baselineFor(fileContents, overlays, remove, root), scanRoot: root }, () => {});
-  const whatIfScan = await runFullScan({ fileContents, scanRoot: root }, () => {});
+  // Both legs are hypothetical snapshots being differenced against each other,
+  // never the repo's current state — `provenance:false` for the same reason as
+  // _scanAtRef above (no provenance to resolve, and updateLifecycle must not
+  // treat either snapshot as "what is open right now").
+  const baseScan = await runFullScan({ fileContents: _baselineFor(fileContents, overlays, remove, root), scanRoot: root, provenance: false }, () => {});
+  const whatIfScan = await runFullScan({ fileContents, scanRoot: root, provenance: false }, () => {});
   const baseIds = new Set((baseScan.findings || []).map(f => f.stableId || f.id));
   const wIds = new Set((whatIfScan.findings || []).map(f => f.stableId || f.id));
   const introduced = (whatIfScan.findings || []).filter(f => !baseIds.has(f.stableId || f.id)).map(_compact);

package/src/ir/CLAUDE.md

@@ -10,10 +10,11 @@ consumed by `scanner/src/dataflow/` for taint analysis.
 | JS / TS  | `parser-js.js`        | `@babel/parser`. **Taint-recall PRD (80%) Tier 3: JSX had ZERO IR modeling** — every `JSXElement` fell through `exprOf`'s switch to `{kind:'unknown'}`, so `return <div dangerouslySetInnerHTML={{__html: html}} />` (React's canonical XSS sink, and a real corpus miss) silently dropped `html`'s taint entirely, even though the plain-JS member-write form (`x.dangerouslySetInnerHTML = {...}`) was already cataloged. Deliberately narrow, not general JSX modeling: `exprOf`'s new `JSXElement` case (via `_findDangerouslySetInnerHTML`) extracts ONLY the `dangerouslySetInnerHTML` attribute's `__html` property value — found on the element itself or, recursively, any descendant (the attribute can sit on a nested element, not just the one directly returned) — and lowers it to a synthetic call (`__jsx_dangerously_set_inner_html__`), targeted by a sink of the same name (`react-jsx-dangerouslySetInnerHTML`) sibling to the existing member-write entry. Ordinary JSX children (`<div>{unsafeText}</div>`) are deliberately NOT modeled — React auto-escapes children by default, so that shape isn't itself a vulnerability the way `dangerouslySetInnerHTML` is. Guarded by `test/catalog-xss-p4.test.js`. |
 | Python   | `parser-py-cst.js`    | Python 3.8+ stdlib `ast` via subprocess (default when available) |
 | Python   | `parser-py.js`        | Hand-rolled regex parser (fallback when python3 missing) |
+| (tool capability probe) | `chrome-probe.mjs` | Chrome/Chromium binary discovery — optional local tool, detects and probes availability via `probeChromeAvailable()`, following `parser-py-cst.js`'s established graceful-degradation pattern. Consumed by Milestone 4's image export functions (`exportPng`/`exportPdf`/`exportSvg` in `scripts/export-image.mjs`) for headless rendering. |
 | 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/ir/chrome-probe.mjs

@@ -0,0 +1,150 @@
+// chrome-probe.mjs — Milestone 4, sub-project PNG/SVG/PDF export.
+//
+// Chrome/Chromium binary discovery, mirroring parser-py-cst.js's own
+// already-proven probePythonAvailable() pattern exactly — this
+// codebase's established convention for "optional local tool, detect
+// and degrade gracefully" (see that file's own header comment for the
+// full rationale this file inherits without repeating).
+
+import * as cp from 'node:child_process';
+import * as fs from 'node:fs';
+
+let _capability = null;
+
+// A malformed env var (e.g. AGENTIC_SECURITY_CHROME_PROBE_TIMEOUT_MS=oops)
+// must fall back to the default, never reach spawnSync as NaN — found by
+// the final whole-branch review: `Number('oops')` is NaN, and NaN as a
+// spawnSync `timeout` option throws ERR_OUT_OF_RANGE synchronously.
+// _tryBinary's own try/catch swallows that throw and returns null for
+// EVERY candidate, so probeChromeAvailable would misreport
+// `no-chrome-found` on a machine with a perfectly working Chrome install.
+//
+// Blank/whitespace-only is treated as unset (falls back), not as `0` —
+// found by this fix's own scoped re-review: `Number('')` is `0`, and a
+// naive `n >= 0` guard let an empty-but-exported env var (a blanked
+// .env line, an unset-but-exported CI var) through as a real `timeout:
+// 0`, which spawnSync treats as NO timeout at all — an unbounded hang
+// risk inside this exact capability probe, the failure class
+// parser-py-cst.js's own probePythonAvailable() is already careful
+// about. An explicit `"0"` is still honored (matches this file's
+// pre-fix behavior for that literal value).
+//
+// Must be a safe INTEGER, not merely finite — found by a second scoped
+// re-review, reproduced live: `Number.isFinite(1.5)` is true, so a
+// fractional env var (e.g. "1.5") passed this guard unchanged and then
+// hit spawnSync's own `timeout` option, which throws ERR_OUT_OF_RANGE
+// for any non-integer — the exact class of uncaught throw this whole
+// function exists to prevent, just for a different malformed input
+// than the original NaN case. `-0` is rejected too (Object.is check):
+// it is a safe integer and `-0 >= 0`, so without the explicit check it
+// would silently mean "no timeout", one character away from the "0"
+// this function deliberately allows.
+// Exported test-only — the outcome-based integration tests (a real
+// probe/export succeeding or not) can't distinguish `timeout: 0` from
+// `timeout: <default>` when the underlying command finishes quickly
+// either way, so a direct table of this function's own input/output
+// pairs is the only thing that actually pins the "0"-vs-default
+// boundary — found by a third scoped re-review: the blank-env-var
+// integration test below passed even with the round-2 blank-handling
+// bug fully reintroduced, for exactly this reason.
+export function _validTimeoutMs(raw, fallback) {
+  const s = String(raw ?? '').trim();
+  if (!s) return fallback;
+  const n = Number(s);
+  if (!Number.isSafeInteger(n) || n < 0 || Object.is(n, -0)) return fallback;
+  return n;
+}
+const PROBE_TIMEOUT_MS = _validTimeoutMs(process.env.AGENTIC_SECURITY_CHROME_PROBE_TIMEOUT_MS, 5000);
+
+// Real, common install locations, per platform. Deliberately excludes
+// AGENTIC_SECURITY_CHROME_PATH — that override is handled separately in
+// probeChromeAvailable() as an authoritative, non-fallback choice (see
+// the comment there for why).
+//
+// KNOWN-GOOD ABSOLUTE PATHS ARE TRIED FIRST, PATH-resolvable bare names
+// LAST — found by the final whole-branch review, reproduced live: with
+// bare names tried first, a `chrome` shell script anywhere earlier on
+// PATH than the real browser is silently preferred and then executed
+// with this process's own render arguments. The `--version` output
+// check (`_tryBinary` below) is a functional smoke test, not a security
+// gate — it cannot distinguish a real Chrome/Chromium binary from any
+// script that echoes a matching string. Preferring the well-known
+// install locations narrows, though does not eliminate, this exposure
+// (a compromised PATH entry named exactly `chrome`/`google-chrome`/etc.
+// is still tried if no absolute-path candidate exists on this machine —
+// this feature already assumes local machine trust, same as every other
+// "optional local tool" this codebase shells out to). The `linux` list
+// below was empty in this fix's first pass — found by the scoped
+// re-review to make the whole reordering a no-op on the platform CI
+// images actually run on, since every Linux candidate was a bare PATH
+// name. Package-manager and snap install locations are now included.
+function _candidatePaths() {
+  const onPath = ['google-chrome-stable', 'google-chrome', 'chromium-browser', 'chromium', 'chrome'];
+  const platformPaths = {
+    darwin: [
+      '/Applications/Google Chrome.app/Contents/MacOS/Google Chrome',
+      '/Applications/Chromium.app/Contents/MacOS/Chromium',
+      `${process.env.HOME || ''}/Applications/Google Chrome.app/Contents/MacOS/Google Chrome`,
+    ],
+    win32: [
+      'C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe',
+      'C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe',
+      `${process.env.LOCALAPPDATA || ''}\\Google\\Chrome\\Application\\chrome.exe`,
+    ],
+    linux: [
+      '/usr/bin/google-chrome-stable',
+      '/usr/bin/google-chrome',
+      '/usr/bin/chromium-browser',
+      '/usr/bin/chromium',
+      '/opt/google/chrome/chrome',
+      '/snap/bin/chromium',
+    ],
+  };
+  const platformSpecific = platformPaths[process.platform] || [];
+  return [...platformSpecific, ...onPath];
+}
+
+// Tries one candidate binary. Returns {ok:true, chrome:bin} on a real,
+// working Chrome/Chromium, or null on any failure (missing binary, spawn
+// error, non-zero exit, unrecognized --version output) — never throws.
+function _tryBinary(bin) {
+  if (!bin) return null;
+  // An absolute-path candidate that doesn't exist can't spawn — skip the
+  // spawnSync call entirely rather than let it throw ENOENT.
+  if (bin.includes('/') || bin.includes('\\')) {
+    if (!fs.existsSync(bin)) return null;
+  }
+  let r;
+  try {
+    r = cp.spawnSync(bin, ['--version'], { encoding: 'utf8', timeout: PROBE_TIMEOUT_MS });
+  } catch { return null; }
+  if (r.error || r.status !== 0) return null;
+  const out = (r.stdout || r.stderr || '');
+  if (!/Chrom(e|ium)/i.test(out)) return null;
+  return { ok: true, chrome: bin };
+}
+
+export function resetChromeProbe() { _capability = null; }
+
+export function probeChromeAvailable() {
+  if (_capability) return _capability;
+
+  // An explicit override is authoritative, not just "try this one first
+  // then fall back": an operator (or CI environment) who deliberately
+  // pointed AGENTIC_SECURITY_CHROME_PATH at a binary wants a failure
+  // reported when that binary doesn't work — not a silent switch to
+  // whatever else this process happens to auto-detect on the machine.
+  const fromEnv = process.env.AGENTIC_SECURITY_CHROME_PATH;
+  if (fromEnv) {
+    const hit = _tryBinary(fromEnv);
+    _capability = hit || { ok: false, reason: 'chrome-path-invalid' };
+    return _capability;
+  }
+
+  for (const bin of _candidatePaths()) {
+    const hit = _tryBinary(bin);
+    if (hit) { _capability = hit; return _capability; }
+  }
+  _capability = { ok: false, reason: 'no-chrome-found' };
+  return _capability;
+}

package/src/ir/parser-js.js

@@ -47,6 +47,30 @@ import presetTypescript from '@babel/preset-typescript';
 let _nodeIdSeq = 0;
 function nextNodeId() { return 'n' + (++_nodeIdSeq); }
 
+// Round-5 lineage-engine finding, generalized in round 6: resolve a Babel
+// object-property-shaped node's key (`ObjectProperty` from either an
+// `ObjectExpression` or an `ObjectPattern` — both share the same
+// `{computed, key}` shape) to either its real, distinct property name, or
+// the explicit unknown marker '*' when the key is computed and not itself
+// a resolvable literal. A computed key that IS a literal (`{[42]: v}`,
+// `{['literal']: v}` — Babel still marks these `computed: true`) still
+// resolves to that literal's own string form; a computed key that is an
+// arbitrary expression (most commonly an Identifier, e.g. `{[field]: v}`)
+// resolves to '*', NEVER to the key expression's own variable name — using
+// `p.key.name` unconditionally there would attribute the property to the
+// key expression's OWN name as if it were a real, distinct property,
+// colliding e.g. `{ field: a, [field]: b }` onto one shared 'field' key.
+// Originally fixed only for `ObjectExpression` (round 5); round 6 found the
+// identical bug, unfixed, in `lhsPath`'s `ObjectPattern` (destructuring)
+// branch and extracted this shared helper so a third instance of the same
+// bug can't appear in some future object-key-reading code path. See
+// DESIGN_INTRAPROCEDURAL.md §4 and CLAUDE.md's "three hop types" note.
+function resolveObjectKey(p) {
+  return p.computed
+    ? (p.key?.value != null ? String(p.key.value) : '*')
+    : (p.key?.name || (p.key?.value != null ? String(p.key.value) : '*'));
+}
+
 // Compact a Babel AST node into our exprDesc.
 function exprOf(n) {
   if (!n) return { kind: 'unknown' };
@@ -91,10 +115,50 @@ function exprOf(n) {
       return { kind: 'union', branches: [exprOf(n.consequent), exprOf(n.alternate)] };
     case 'ObjectExpression':  return {
       kind: 'object',
-      props: (n.properties || []).filter(p => p.type === 'ObjectProperty' && p.key).map(p => ({
-        key: p.key.name || (p.key.value != null ? String(p.key.value) : '*'),
-        value: exprOf(p.value),
-      })),
+      // Round-5 lineage-engine finding: for a COMPUTED property
+      // (`{[k]: v}`, `p.computed === true`), `p.key` is an arbitrary
+      // expression node, not a name — and an Identifier key expression
+      // (`k`) HAS a `.name` ('k'), same as a real, non-computed property
+      // literally named `k` would. Using `p.key.name` unconditionally
+      // therefore attributed a computed property to the key EXPRESSION's
+      // own variable name as if it were a real, distinct property name,
+      // colliding `{ k: user.ssn, [k]: user.email }` onto one shared 'k'
+      // key. A computed key IS still resolvable when it's itself a literal
+      // (`{[42]: v}`, `{['literal']: v}` — Babel marks these
+      // `computed: true` too, but `p.key.value` gives the real value), so
+      // only an Identifier/expression computed key (no `.value`) falls
+      // back to the literal string '*' — mirroring the EXISTING computed-
+      // MEMBER-access convention (`n.computed` handling just above, and
+      // `lhsPath`'s computed-write handling below) rather than inventing a
+      // new one. See DESIGN_INTRAPROCEDURAL.md §4 and CLAUDE.md's "three
+      // hop types" note.
+      //
+      // A `SpreadElement` (`{...user}`) previously fell out of the
+      // `.filter` entirely — `{...user}` and `{}` were byte-identical in
+      // the emitted IR, a real, pre-existing false negative (the identity
+      // vanishes, not merged, not flattened — found and documented but
+      // not fixed by a final review of an earlier plan). Represented here
+      // as a distinct `{spread: true, value: <expr>}` shape (no `key`
+      // field) rather than a regular `{key, value}` property, so
+      // `scanner/src/lineage/engine.js`'s `resolveExprIdentities` can
+      // merge the spread source's OWN field structure directly into this
+      // object's structure (see that file for the full mechanism) — a
+      // DIFFERENT, more precise handling than a computed-unknown-key
+      // property gets (that case folds into one opaque residual bucket; a
+      // spread's contents are fully known, just not yet assigned a key in
+      // THIS literal, so they can and should stay field-distinguished).
+      // Every consumer of `expr.props` outside this package
+      // (scanner/src/dataflow/engine.js, higher-order.js,
+      // privacy-deep-walker.js — audited before this change) reads only
+      // `p.value`, never `p.key`, so this shape is compatible with all of
+      // them without any change there — and several gain correct taint/
+      // privacy detection through object spread as a direct result, since
+      // the spread's value is no longer silently absent from `props`.
+      props: (n.properties || []).map(p => {
+        if (p.type === 'SpreadElement') return { spread: true, value: exprOf(p.argument) };
+        if (p.type !== 'ObjectProperty' || !p.key) return null;
+        return { key: resolveObjectKey(p), value: exprOf(p.value) };
+      }).filter(Boolean),
     };
     case 'ArrayExpression':   return { kind: 'array', elements: (n.elements || []).map(exprOf) };
     case 'SpreadElement':     return exprOf(n.argument);
@@ -170,10 +234,33 @@ function lhsPath(n) {
     return base + '.' + prop;
   }
   if (n.type === 'ObjectPattern') {
-    // Destructured: return an array of (key, alias) pairs the caller can iterate.
+    // Destructured: return an array of (key, alias) pairs the caller can
+    // iterate. Round 6: uses the same `resolveObjectKey` helper
+    // `ObjectExpression` uses above, so a non-literal computed key
+    // (`const { [field]: value } = user`) resolves to '*' instead of
+    // fabricating a colliding key from the key variable's own name — see
+    // `resolveObjectKey`'s header comment for the full rationale.
+    //
+    // A `RestElement` (`const {a, ...rest} = obj`) has its bound identifier
+    // at `.argument`, not `.value` (only a real `ObjectProperty` has
+    // `.value`) — using `.value` unconditionally here made `lhsPath`
+    // resolve to `null` for every rest binding (`lhsPath(undefined)` hits
+    // the `if (!n) return null;` guard before ever reaching the
+    // `RestElement` case below), so the consumer's `if (!alias) continue;`
+    // guard silently skipped it entirely: a real, pre-existing FR-306
+    // violation where the rest binding vanished with no trace, not merged,
+    // not flattened. `resolveObjectKey(p)` already correctly resolves to
+    // '*' for a RestElement (it has no `.key`/`.computed`), which is
+    // exactly the right marker: the consumer already treats a `'*'`-keyed
+    // destructured binding as a computed-unknown-key selection
+    // (`{kind:'member', object: initExpr, prop: '*'}`), and the lineage
+    // engine's existing wildcard-selection machinery (built for `obj[k]`)
+    // already resolves that correctly — conservatively aggregating the
+    // source's full field set, flagged widened. No engine-level change
+    // needed for this fix.
     return { kind: 'object-pattern', props: (n.properties || []).map(p => ({
-      key: p.key?.name || (p.key?.value != null ? String(p.key.value) : '*'),
-      alias: lhsPath(p.value),
+      key: resolveObjectKey(p),
+      alias: lhsPath(p.type === 'RestElement' ? p.argument : p.value),
     }))};
   }
   if (n.type === 'ArrayPattern') {