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

package/dist/agentic-security.mjs.sha256

@@ -1 +1 @@
-deeb49d41f22000f35683bc1e9dc2c2368c4b79af6272740c5e96cece4732475  agentic-security.mjs
+2a984aea7cf61f1508f690678b1ff656829081cb34b3e8483cc8ae04ae3c934c  agentic-security.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clear-capabilities/agentic-security-scanner",
-  "version": "0.141.0",
+  "version": "0.143.0",
   "description": "Scanner engine for the agentic-security Claude Code plugin — SAST, SCA (function-level reachability + CISA KEV), secrets, IaC, prompt-injection, MCP/agent-tool audit, auth/authZ deep analysis, attack chains, PoC generation, business logic, toxic-combinations scoring, SBOM, pipeline integrity, compliance attestation, and more.",
   "type": "module",
   "main": "src/index.js",
@@ -67,7 +67,7 @@
     "test:posture": "node --test test/privacy-framework.test.js test/material-change.test.js test/drift.test.js test/scorecard.test.js test/accuracy-scorecard.test.js test/scorecard-gate.test.js test/predeploy-gate.test.js test/release-check.test.js test/pre-push-gate.test.js test/dependency-currency.test.js test/package-contents-check.test.js test/gate-verdict-cache.test.js test/independent-population.test.js test/why-missed.test.js test/independent-scoring.test.js test/evidence-bundle.test.js test/discovery-memory.test.js test/mttr.test.js test/license-policy.test.js test/aibom.test.js test/sbom.test.js test/api-inventory.test.js test/iam-policy.test.js test/container.test.js test/container-runtime.test.js test/image-packages.test.js test/kev.test.js test/dep-confusion.test.js test/sca-deprecated.test.js test/sca-batch.test.js test/composite-risk.test.js test/epss-enrich.test.js test/sca-coverage.test.js test/gradle-deps.test.js test/sca-route-reachable.test.js test/sca-policy.test.js test/sca-verdict.test.js test/install-script.test.js test/sca-linked-findings.test.js test/packs.test.js test/flow-narration.test.js test/regression-test-gen.test.js test/deterministic-fix.test.js test/falsification.test.js test/verification-separation.test.js test/logic-claims.test.js test/attestation.test.js test/verify-attestation-cli.test.js test/comparison.test.js test/determinism-cross-machine.test.js test/fix-honesty-gate.test.js test/model-routing.test.js test/root-cause-sweep.test.js test/entrypoint-inventory.test.js test/relevance.test.js test/untrusted.test.js test/agent-hardening.test.js test/rule-synthesis.test.js test/policy-gate.test.js test/agents-memory.test.js test/cve-lookup.test.js test/cve-alert-daemon.test.js test/fix-verify-loop.test.js test/fix-verify-tests.test.js test/fix-acceptance.test.js test/exploitability-probability.test.js test/history-scan.test.js test/viral-features.test.js test/viral-v074.test.js test/state-dir.test.js test/ignore-pragma.test.js test/license-graph.test.js test/secret-live-check.test.js test/attack-taxonomy.test.js test/triage-memory.test.js test/pr-augment.test.js test/chat-batch2.test.js test/chat-batch3.test.js test/chat-batch4.test.js test/chat-batch5.test.js test/chat-batch6.test.js test/router.test.js test/legacy-alias-redirect.test.js test/cache-economics.test.js test/coverage-report.test.js test/corpus-status.test.js test/provenance.test.js test/secret-history.test.js test/execution-proof.test.js test/fix-metrics.test.js test/corpus-enroll.test.js test/prove-findings.test.js test/corpus-match.test.js test/corpus-provenance.test.js test/learning-quorum.test.js test/llm-cache-integrity.test.js test/proof-artifact.test.js test/providers.test.js test/fleet.test.js test/autopilot.test.js test/autopilot-cli.test.js test/verifier-independence.test.js test/integrity-legacy-key.test.js test/suppression-visibility.test.js test/cost-ceiling.test.js test/local-endpoint.test.js test/model-trust.test.js test/vuln-archaeology.test.js test/scan-checkpoint.test.js test/llm-redact.test.js test/world-class-batch2.test.js test/world-class-modules.test.js test/integration-end-to-end.test.js test/streak-cli-wiring.test.js test/stack-playbook.test.js test/machine-output-flag.test.js test/stdout-flush.test.js test/format-determinism.test.js test/only-flag-channels.test.js test/confidence.test.js test/security-trend.test.js test/calibration-drift.test.js test/validator-metrics.test.js test/clustering-ir-taint-line.test.js test/concurrency-cwe.test.js test/compliance-mapping-liveness.test.js test/family-registry.test.js test/coverage-strength.test.js test/framework-provenance.test.js test/third-party-verification.test.js test/proof-coverage.test.js test/calibration-holdout.test.js test/catalog-freshness.test.js test/incremental-parity.test.js test/surface-smoke.test.js test/fix-coverage.test.js test/raw-source-carveout.test.js test/mlbom-conformance.test.js test/deploy-gate-replay.test.js test/sbom-conformance.test.js test/unscored-claims.test.js test/mcp-rug-pull.test.js test/agent-boundary-taint.test.js test/confinement-adversarial.test.js test/comment-strip-cost.test.js test/reachability-claim.test.js test/entrypoint-breadth.test.js test/dep-file-admission.test.js",
     "test:dataflow": "node --test test/container-taint.test.js test/stored-taint-families.test.js test/py-annotation-sources.test.js test/fn-reach.test.js test/deep-taint.test.js test/calibration.test.js test/holdout-eval.test.js test/cross-lang-meta.test.js test/cross-lang-queues.test.js test/phase5-xlang.test.js test/phase5-coverage.test.js test/phase6-taint.test.js test/llm-validator-consistency.test.js test/llm-validator-default-on.test.js test/llm-validator-preset.test.js test/parser-py-cst.test.js test/parser-cs-kt.test.js test/parser-cs-annotations.test.js test/parser-cs-control-flow.test.js test/parser-kt-control-flow.test.js test/parser-js-annotations.test.js test/parser-java-annotations.test.js test/parser-java-control-flow.test.js test/parser-java-calls.test.js test/parser-go.test.js test/parser-php-rb.test.js test/parser-php-control-flow.test.js test/interproc-k2.test.js test/proven-clean.test.js test/backward-default.test.js test/incremental-cache.test.js test/string-regex-lattice.test.js test/closure-capture.test.js test/points-to.test.js test/type-stubs.test.js test/soft-taint.test.js test/ifds.test.js test/symbolic-exec-proof.test.js test/ifds-summary-edges.test.js test/stub-aware-filter.test.js test/cross-repo.test.js test/proof-gate.test.js test/layer-recall.test.js test/java-taint-flow.test.js test/kt-taint-flow.test.js test/sanitizer-typed-flow.test.js test/sanitizer-gate-unit.test.js test/proof-safe.test.js test/collection-taint.test.js test/kcfa-context.test.js test/kcfa-callstring.test.js test/flow-parity.test.js test/callgraph-resolve.test.js test/import-reachability.test.js test/ir-stats.test.js test/parser-cpp.test.js test/parser-js-decorators.test.js test/parser-js-if-else-cfg.test.js test/cpp-integration.test.js test/engine-reconnect.test.js test/phase2-scoping.test.js test/engine-recall.test.js test/catalog-annotation-source.test.js test/catalog-cs-p1.test.js test/catalog-expanded.test.js test/builtin-summaries.test.js test/interproc-mutation-crash.test.js test/mutated-param-taint.test.js test/return-sink-check.test.js test/higher-order-inline-callback.test.js test/interproc-findings-discard.test.js test/runscan-deep-option.test.js test/summary-cache-convergence.test.js test/parser-rb-calls.test.js test/parser-rb-module-level.test.js test/balanced-call.test.js test/destructuring-taint.test.js test/computed-member-taint.test.js test/string-interpolation-taint.test.js test/dataflow-deadcode-severity.test.js test/catalog-dotted-callee-lookup.test.js test/builtin-summary-family-blind-kill.test.js test/deep-mode-annotator-pipeline.test.js test/receiver-type-and-nested-calls.test.js test/member-write-and-loop-taint.test.js test/parser-py-module-level.test.js test/parser-php-module-level.test.js test/r14b-module-level-e2e.test.js test/annotation-taint-engine.test.js test/interproc-nested-call-taint.test.js test/catalog-xpath-injection.test.js test/catalog-ldap-injection.test.js test/catalog-xxe.test.js test/catalog-response-splitting.test.js test/catalog-code-injection.test.js test/parser-rb-control-flow.test.js test/catalog-ruby-p1.test.js test/callee-receiver-taint.test.js test/catalog-command-injection-p4.test.js test/catalog-xss-p4.test.js test/catalog-path-ssrf-p3.test.js",
     "test:mcp": "node --test test/mcp.test.js test/mcp-protocol-smoke.test.js test/mcp-audit.test.js test/audit-cli.test.js test/mcp-scratchpad.test.js test/mcp-offload.test.js test/sca-upgrade.test.js test/lsp-server.test.js",
-    "test:report": "node --test test/junit.test.js test/ci.test.js test/poc-generator.test.js test/verifier.test.js test/verifier-target.test.js test/annotator-errors.test.js test/grader-calibration.test.js test/pr-delta-gate.test.js test/vex.test.js test/report-render.test.js",
+    "test:report": "node --test test/junit.test.js test/ci.test.js test/poc-generator.test.js test/verifier.test.js test/verifier-target.test.js test/annotator-errors.test.js test/grader-calibration.test.js test/pr-delta-gate.test.js test/vex.test.js test/report-render.test.js test/oscal-conformance.test.js",
     "test:bench-modules": "node --test test/phase4-harness.test.js test/pipeline.test.js test/proof-corpus-lib.test.js test/proof-corpus-runner.test.js",
     "test:lifecycle": "node --test test/lsp-protocol-smoke.test.js test/ide-surfaces.test.js test/detector-liveness.test.js test/bench-watchdog.test.js test/ci-parity.test.js test/dead-code.test.js test/no-dead-modules.test.js test/no-orphan-scripts.test.js test/no-stray-state.test.js test/tree-integrity.test.js test/stop-hook.test.js test/plugin-self-check.test.js test/skills-registry.test.js test/bodyguard.test.js test/cache-invalidator-guard.test.js test/dispatch-pre-tool.test.js test/dispatch-user-prompt.test.js test/session-start-model-capture.test.js test/sandbox.test.js test/sandbox-escape.test.js test/ci-templates.test.js test/agent-mcp-tools.test.js test/triage-command.test.js test/no-orphan-tests.test.js test/supply-command.test.js test/posture-command.test.js test/labs-command.test.js test/compliance-command.test.js test/check-doc-drift.test.js test/dist-chunks-tracked.test.js && node ../scripts/lint-command-descriptions.mjs",
     "test:eval": "node --test test/independent-eval.test.js test/realworld-recall.test.js",
@@ -107,6 +107,7 @@
     "bench:prompt-injection:fetch": "node ../bench/prompt-injection/fetch.mjs",
     "bench:secrets-precision": "node ../bench/secrets-precision/runner.mjs",
     "bench:sca-replay": "node ../bench/sca-replay/runner.mjs",
+    "bench:sca-replay:reachability": "node ../bench/sca-replay/reachability.mjs",
     "bench:sca-replay:fetch": "node ../bench/sca-replay/fetch.mjs",
     "bench:sca-replay:label": "node ../bench/sca-replay/label.mjs",
     "bench:layer-recall": "node ../bench/layer-recall/runner.mjs",
@@ -134,6 +135,8 @@
     "bench:independent:materialise": "node ../bench/independent/materialise-cli.mjs",
     "bench:independent:why-missed": "node ../bench/independent/why-missed.mjs",
     "bench:independent:materialise-new": "node ../bench/independent/materialise-new.mjs",
+    "bench:independent:merge": "node ../bench/independent/merge-chunks.mjs",
+    "bench:independent:agent-delta": "node ../bench/independent/agent-boundary-delta.mjs",
     "bench:independent:deep": "node ../bench/independent/runner.mjs --deep",
     "test:ci-parity": "CI=true GITHUB_ACTIONS=true node --test test/backward-default.test.js test/ci-parity.test.js test/container-taint.test.js test/deep-taint.test.js test/engine-recall.test.js test/engine-reconnect.test.js test/gate-verdict-cache.test.js test/ignore-pragma.test.js test/java-taint-flow.test.js test/kt-taint-flow.test.js test/py-annotation-sources.test.js test/runscan-deep-option.test.js test/sanitizer-typed-flow.test.js"
   },

package/src/dataflow/CLAUDE.md

@@ -42,6 +42,15 @@ Layer-2 taint engine. Walks the Layer-1 IR (`../ir/`) with field-sensitive forwa
 - **Call-string (k>1) context-sensitivity.** Context is the *value* abstraction — which params are tainted at entry — not the call stack. Two call paths that reach a helper with the same tainted-arg shape share a summary. Entry-state granularity is also param-level, not arbitrary access paths (`f(obj)` with `obj.a` tainted ≡ `obj.b` tainted).
 - **Contexts beyond the per-function cap.** Once a function has been computed under `AGENTIC_SECURITY_KCFA_MAX_CONTEXTS` distinct tainted-arg shapes, further shapes fall back to the empty-entry summary (an under-approximation, bounded on purpose).
 - **Implicit flow.** `implicit-flow.js` exists for `if (tainted) { x = "yes" }` propagation but is conservative-by-default.
+- **Sanitizer effect through a summarised return.** `_sanitizersByVar` records the sanitizer callees seen *in this function*, so a sanitizer hoisted into a helper —
+
+  ```js
+  function clean(v) { return escapeHtml(v); }
+  const name = clean(req.query.name);
+  ```
+
+  — is not attributed to the value at the sink, and the flow reads as **unsanitized**. Taint itself propagates through the return correctly (`SummaryCache`); only the sanitizer LABEL does not. Measured while writing the `bench/mutation` cases for PRD F12.5, and deliberately **not** added as a mutation case: it would make that gate permanently red, and a gate nobody can pass gets deleted. The error direction is precision (a clean flow reported at full confidence), never a missed vulnerability, which is why it is documented rather than treated as a release blocker.
+- **Sanitizer REVERSAL is modelled, but only for a named list.** `_UNSANITIZER_CALLEES` in `engine.js` carries the well-known inverses (`he.decode`, `unescape`, `html_entity_decode`, `decodeURIComponent`, …) and `sanitizer-gate.js` maps them to the family they reverse — percent-decoding does not undo HTML escaping, so the mapping is family-keyed rather than a flat list. A project-local decoder (`function unwrap(s) { … }`) is not recognised. Before this existed, `he.decode(escapeHtml(x))` reaching an HTML sink was reported as SANITIZED: a missed XSS, found by `bench/mutation`.
 
 ## Precision: centralized SSRF/path guard recognition
 

package/src/dataflow/engine.js

@@ -572,6 +572,62 @@ function _matchCallCatalog(calleeExpr, argExprs, state, callContext) {
 // labels the finding, and the proof gate demotes it. Recall-preserving, same
 // precedent as falsification.js / proof-gate.js: never removed, never
 // severity-touched.
+// Calls that UNDO an encoding. The catalog has no entry for these — it models
+// sanitizers, and a decoder is the opposite — so they would never be recorded
+// on the path and `sanitizer-gate.js` could not see them.
+//
+// Measured by bench/mutation: `he.decode(escapeHtml(req.query.name))` reaching
+// an HTML sink was labelled SANITIZED. The decode puts back exactly what the
+// escape removed, so that was a missed XSS reported as clean.
+//
+// Deliberately a NAME list rather than a catalog kind: these are not analysis
+// entries with families and effects, they are a short list of well-known
+// inverses, and the gate maps them to the family they reverse.
+const _UNSANITIZER_CALLEES = new Set([
+  'unescape', 'unescapeHtml', 'unescapeHtml3', 'unescapeHtml4',
+  'StringEscapeUtils.unescapeHtml3', 'StringEscapeUtils.unescapeHtml4',
+  'he.decode', 'entities.decode', 'html.decode', 'decodeHTML',
+  'decodeHTMLStrict', 'decodeEntities', 'html.unescape',
+  'html_entity_decode', 'htmlspecialchars_decode', '_.unescape', 'lodash.unescape',
+  'decodeURI', 'decodeURIComponent', 'unquote', 'unquote_plus',
+  'URLDecoder.decode', 'urldecode', 'querystring.unescape',
+]);
+
+// `callee` is an IR NODE, not a string: `{kind:'ident',name:'escapeHtml'}` or
+// `{kind:'member',object:{kind:'ident',name:'he'},prop:'decode'}`. Flattened to
+// the dotted form the name list is written in, plus the bare leaf so a call
+// through an alias (`const {decode} = he`) still matches on an unambiguous name.
+function _calleeNames(callee) {
+  if (!callee || typeof callee !== 'object') return [];
+  if (callee.kind === 'ident' && callee.name) return [callee.name];
+  if (callee.kind === 'member' && callee.prop) {
+    const obj = callee.object;
+    const base = obj && obj.kind === 'ident' && obj.name ? obj.name : null;
+    return base ? [`${base}.${callee.prop}`, callee.prop] : [callee.prop];
+  }
+  return [];
+}
+
+function _unsanitizersInExprTree(expr, out) {
+  if (!expr || typeof expr !== 'object') return;
+  if (expr.kind === 'call') {
+    for (const n of _calleeNames(expr.callee)) {
+      // The bare leaf is accepted only when it is unambiguous on its own.
+      // `decode` is not — jwt.decode, base64 decode, protobuf decode — and
+      // matching it would void correct sanitization claims all over the tree.
+      if (n === 'decode') continue;
+      if (_UNSANITIZER_CALLEES.has(n)) { out.add(n); break; }
+    }
+  }
+  for (const k of ['left', 'right', 'callee', 'object', 'property', 'value']) {
+    if (expr[k] && typeof expr[k] === 'object') _unsanitizersInExprTree(expr[k], out);
+  }
+  for (const k of ['args', 'parts', 'branches', 'elements']) {
+    if (Array.isArray(expr[k])) for (const e of expr[k]) _unsanitizersInExprTree(e, out);
+  }
+  if (Array.isArray(expr.props)) for (const p of expr.props) _unsanitizersInExprTree(p && p.value, out);
+}
+
 function _sanitizersInExprTree(expr, out) {
   if (!expr || typeof expr !== 'object') return;
   if (expr.kind === 'call') {
@@ -592,6 +648,26 @@ function _sanitizersInExprTree(expr, out) {
 }
 
 // Sanitizers applied to `expr`: those called inline within it, plus those
+// Un-sanitizers applied to `expr`, by the same rule: inline in the expression,
+// or inherited from a variable it reads. The inheritance half is what makes it
+// work at all — `const escaped = escapeHtml(x); const name = he.decode(escaped);
+// sink(name)` puts the decode on an ASSIGNMENT, so an expression-tree walk of
+// the sink argument sees only `name` and would never find it.
+function _unsanitizersForExpr(expr, callContext) {
+  const out = new Set();
+  _unsanitizersInExprTree(expr, out);
+  const byVar = callContext && callContext._unsanitizersByVar;
+  if (byVar && byVar.size) {
+    const vars = new Set();
+    _collectExprVars(expr, vars);
+    for (const v of vars) {
+      const s = byVar.get(v);
+      if (s) for (const n of s) out.add(n);
+    }
+  }
+  return out;
+}
+
 // recorded against any variable it reads (`const safe = escapeHtml(x); sink(safe)`).
 function _sanitizersForExpr(expr, callContext) {
   const out = new Set();
@@ -695,8 +771,10 @@ function _sinkFindingsForCall(calleeExpr, argExprs, cat, argTaints, state, callC
         // covers the finding's threat class — an xss escaper on a SQL sink
         // must not read as sanitised.
         const _sanNames = _sanitizersForExpr(taintedArgExpr, callContext);
+        const _unsanNames = _unsanitizersForExpr(taintedArgExpr, callContext);
         findings.push({
           ...(_sanNames.size ? { _sanitizersOnPath: [..._sanNames] } : {}),
+          ...(_unsanNames.size ? { _unsanitizersOnPath: [..._unsanNames] } : {}),
           kind: 'taint',
           sinkId: e.id,
           vuln: e.vuln?.name || 'Tainted Sink',
@@ -759,8 +837,10 @@ function _memberWriteSinkFindings(hits, sourceExpr, state, callContext, line, ta
     const reachingSources = _sourcesReachingExpr(sourceExpr, state, callContext._taintSources);
     const traceForThisFinding = reachingSources.length ? reachingSources.slice(0, 5) : [];
     const _sanNames = _sanitizersForExpr(sourceExpr, callContext);
+    const _unsanNames = _unsanitizersForExpr(sourceExpr, callContext);
     findings.push({
       ...(_sanNames.size ? { _sanitizersOnPath: [..._sanNames] } : {}),
+      ...(_unsanNames.size ? { _unsanitizersOnPath: [..._unsanNames] } : {}),
       kind: 'taint',
       sinkId: e.id,
       vuln: e.vuln?.name || 'Tainted Sink',
@@ -859,6 +939,13 @@ function step(node, stateIn, callContext) {
         const _byVar = (callContext._sanitizersByVar ||= new Map());
         if (_san.size) _byVar.set(target, _san);
         else _byVar.delete(target);
+        // The same bookkeeping for reversals, and for the same reason: a clean
+        // re-assignment must clear it, or a decode recorded once would void
+        // every later sanitization claim on that name.
+        const _unsan = _unsanitizersForExpr(node.source, callContext);
+        const _unByVar = (callContext._unsanitizersByVar ||= new Map());
+        if (_unsan.size) _unByVar.set(target, _unsan);
+        else _unByVar.delete(target);
       }
       // Constant propagation: track variables assigned from literals
       if (target && _activeConstantVars) {
@@ -1710,6 +1797,14 @@ export function runTaintEngine(perFileIR, callGraph, opts = {}) {
         // dropped — which is what previously left sanitizer-gate.js inert.
         ...(Array.isArray(f._sanitizersOnPath) && f._sanitizersOnPath.length
           ? { _sanitizersOnPath: f._sanitizersOnPath } : {}),
+        // The reversal half, and it hit the very trap this comment warns about:
+        // the walk collected `he.decode` correctly, the gate was wired to
+        // consume it, and the field was dropped HERE — so the fix looked inert
+        // through three rounds of debugging. An explicit allowlist is the right
+        // design and this is its standing cost: every new field must be added
+        // in two places, and the omission is silent.
+        ...(Array.isArray(f._unsanitizersOnPath) && f._unsanitizersOnPath.length
+          ? { _unsanitizersOnPath: f._unsanitizersOnPath } : {}),
         // _funcQid: the enclosing function's qid, set upstream during the walk
         // but silently dropped by this allowlist before backward.js's
         // annotateBackwardSlices ever saw it — the same class of omission

package/src/dataflow/sanitizer-gate.js

@@ -86,9 +86,60 @@ export function _sanitizerFamilies() {
 // ctx.sanitizersOnPath: { [findingId]: string[] } — callee names observed on the
 // flow that produced the finding. The engine supplies it; when absent the gate
 // is a no-op, which keeps this safe to call unconditionally.
+// Functions that UNDO an encoding, keyed by the family they reverse.
+//
+// The gate labelled a flow `sanitized` whenever a matching sanitizer appeared
+// on the path, with no notion that a later call could reverse it. Measured by
+// bench/mutation: `he.decode(escapeHtml(req.query.name))` reaching an HTML sink
+// was reported as SANITIZED — a missed XSS, because the decode puts back
+// exactly what the escape took out.
+//
+// Family-keyed, not a flat list, because reversal is family-specific:
+// `decodeURIComponent` undoes percent-encoding and does nothing at all to HTML
+// entities, so treating it as a universal un-sanitizer would throw away correct
+// sanitization claims.
+//
+// A match REFUSES the label rather than removing a finding. That is the safe
+// direction: the cost of being wrong here is a finding kept at full confidence
+// (a possible false positive), while the cost of the previous behaviour was a
+// real vulnerability reported as clean.
+const _UNSANITIZERS = {
+  xss: new Set([
+    'unescape', 'unescapeHtml', 'unescapeHtml3', 'unescapeHtml4',
+    'StringEscapeUtils.unescapeHtml3', 'StringEscapeUtils.unescapeHtml4',
+    'he.decode', 'entities.decode', 'html.decode', 'htmlparser2.decodeHTML',
+    'decodeHTML', 'decodeHTMLStrict', 'decodeEntities',
+    'html.unescape', 'html_entity_decode', 'htmlspecialchars_decode',
+    '_.unescape', 'lodash.unescape',
+  ]),
+  url: new Set([
+    'decodeURI', 'decodeURIComponent', 'unquote', 'unquote_plus',
+    'URLDecoder.decode', 'urldecode', 'querystring.unescape',
+  ]),
+  // sql / cmd / path have no encoding to reverse in the same sense: their
+  // sanitizers parameterise or canonicalise rather than encode, and there is no
+  // inverse call. Deliberately absent rather than guessed at.
+};
+
+/** Does any callee observed on this path undo the sanitization claimed for `fam`? */
+export function _reversedOnPath(observed, fam) {
+  const undoers = _UNSANITIZERS[fam];
+  if (!undoers) return null;
+  for (const name of observed) {
+    if (undoers.has(name)) return name;
+    // A member call may be recorded bare. Only accept a leaf that is
+    // unambiguous on its own — `decode` alone is not (jwt.decode, base64
+    // decode), and matching it would void correct claims.
+    const leaf = String(name).split('.').pop();
+    if (leaf !== name && undoers.has(leaf) && leaf !== 'decode') return name;
+  }
+  return null;
+}
+
 export function applySanitizerGate(findings, ctx) {
   const list = Array.isArray(findings) ? findings : [];
   const onPath = (ctx && ctx.sanitizersOnPath) || null;
+  const undoPath = (ctx && ctx.unsanitizersOnPath) || {};
   if (!onPath) return list;
   const index = _sanitizerIndex();
 
@@ -107,6 +158,16 @@ export function applySanitizerGate(findings, ctx) {
       return fams && (fams.has(fam) || fams.has('*'));
     });
     if (!matching.length) continue;
+    // A reversal anywhere on the path voids the claim. Order is not consulted:
+    // `sanitizersOnPath` is a set of observed callees, and a decode that
+    // precedes the escape is not a shape worth modelling separately when the
+    // conservative answer — refuse the label — is also the safe one.
+    const undone = undoPath[f.id] || undoPath[f.stableId] || [];
+    const reversedBy = _reversedOnPath(undone, fam);
+    if (reversedBy) {
+      f.sanitizerReversedBy = reversedBy;
+      continue;
+    }
     // Label only. The proof gate decides what to do with the label.
     f.sanitized = true;
     f.sanitizerProof = { sanitizers: matching, family: fam };

package/src/engine.js

@@ -6607,6 +6607,11 @@ function _annotateFunctionReachability(supplyChain, routes, callGraph, fc){
     if (!sites.length) { sc.functionReachable = 'unknown'; sc.routeReachable = false; continue; }
     let functionReachable = false;
     let routeReachable = false;
+    // Did ANY call site yield enough structure to reason about? If not, the
+    // honest answer is `unknown` — see the verdict assignment below.
+    let analysable = false;
+    // At least one call site sits inside an exported function — see below.
+    let publicApiSite = false;
     for (const site of sites) {
       // Classifier 1: site is inline inside a route handler (within 25 lines
       // of the route def, no intervening function declaration). This is the
@@ -6629,8 +6634,16 @@ function _annotateFunctionReachability(supplyChain, routes, callGraph, fc){
       // If any caller-chain hits a known route-handler function, the site
       // is route-reachable-via-function. If no caller at all, we keep
       // functionReachable=false for this site.
-      const enclosing = _enclosingFn(fc[site.file] || '', site.line);
+      const encInfo = _enclosingFnInfo(fc[site.file] || '', site.line);
+      const enclosing = encInfo && encInfo.name;
+      // Not being able to name the enclosing function is INCONCLUSIVE, not
+      // evidence of unreachability. Tracked so the verdict below can say so.
       if (!enclosing) continue;
+      // A public-API function with no in-tree caller is the NORMAL case, not
+      // dead code: its callers are its users. Only a private function can be
+      // shown unreachable by the absence of callers.
+      if (encInfo.exported) { publicApiSite = true; continue; }
+      analysable = true;
       const callers = _reverseCallGraphReachable(callGraph, enclosing, 4);
       if (callers.size > 1) functionReachable = true; // at least one caller exists
       for (const callerFn of callers) {
@@ -6642,18 +6655,76 @@ function _annotateFunctionReachability(supplyChain, routes, callGraph, fc){
       }
       if (routeReachable) break;
     }
-    sc.functionReachable = functionReachable ? 'reachable' : 'unreachable';
+    // ABSENCE OF PROOF IS NOT PROOF OF ABSENCE.
+    //
+    // This read `functionReachable ? 'reachable' : 'unreachable'`, so a site the
+    // analysis could not reason about — no recognisable enclosing function, no
+    // routes in the project at all — was reported as UNREACHABLE and the finding
+    // demoted to `info`. For a LIBRARY that is every site: express has no routes,
+    // so `cookie` and `send`, both required at the top of `lib/response.js` and
+    // called directly, were demoted out of the report.
+    //
+    // Measured by bench/sca-replay's reachability scorer (PRD F3.2): of the three
+    // demotions it could adjudicate against an import-level oracle, ALL THREE were
+    // false — express/cookie, express/send, poetry/requests, each genuinely
+    // imported. A false `unreachable` is a MISSED EXPLOIT, the expensive
+    // direction, so inconclusive now yields `unknown`: the finding keeps its
+    // severity and the analysis stops making a claim it cannot support.
+    // A project with NO ROUTES is a library, and "not reachable from any route"
+    // is not a claim that can be made about one: its callers are its users, who
+    // are not in this tree. express requires `cookie` and `send` at the top of
+    // lib/response.js and calls both directly — there is simply no route to
+    // trace them to, and reporting that as `unreachable` demoted two live
+    // dependencies to `info`. Same shape for poetry/requests.
+    //
+    // This is the library-vs-application distinction the PRD already flags for
+    // the taint engine (F2.3, "for a library the caller IS the attacker"),
+    // showing up here as a false demotion instead of a false negative.
+    const projectHasRoutes = Array.isArray(routes) && routes.length > 0;
+    sc.functionReachable = functionReachable
+      ? 'reachable'
+      : (analysable && projectHasRoutes && !publicApiSite ? 'unreachable' : 'unknown');
     sc.routeReachable = routeReachable;
   }
 }
-function _enclosingFn(content,line){
+// The declaration form of the function enclosing `line`, scanning backwards.
+//
+// Recognises four shapes, not one. The original matched only `function name(`
+// and `const name = (`, so an ANONYMOUS function assigned to a member —
+// `res.cookie = function (name, value, options) {`, which is how most of
+// express, and most of the JS ecosystem, defines a public method — was invisible.
+// The scan then walked past it and attributed the call site to whatever
+// unrelated function appeared further up the file.
+//
+// `exported` matters as much as the name: a function assigned to a member or to
+// module.exports is PUBLIC API, so having no caller inside this repository is
+// the normal case and says nothing about whether it can be reached. Treating it
+// as evidence of unreachability is what demoted express's live `cookie`
+// dependency to `info`.
+function _enclosingFnInfo(content,line){
   const lines=content.split('\n');
   for(let i=line-2;i>=0;i--){
-    const m=lines[i].match(/(?:function\s+(\w+)|(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?\()/);
-    if(m)return m[1]||m[2]||null;
+    const l=lines[i];
+    let m=l.match(/(?:^|\s)(?:async\s+)?function\s+(\w+)\s*\(/);
+    if(m)return {name:m[1],exported:/^\s*export\b/.test(l)};
+    m=l.match(/^\s*(?:export\s+)?(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?\(/);
+    if(m)return {name:m[1],exported:/^\s*export\b/.test(l)};
+    // `X.y = function (…)` / `X.y = async (…) => ` / `module.exports.y = …`
+    m=l.match(/^\s*(?:module\.)?(\w+)\.(\w+)\s*=\s*(?:async\s*)?(?:function\b|\()/);
+    if(m)return {name:m[2],exported:true};
+    // `module.exports = function name(…)`
+    m=l.match(/^\s*module\.exports\s*=\s*(?:async\s*)?function\s*(\w*)\s*\(/);
+    if(m)return {name:m[1]||'module.exports',exported:true};
+    // Object-literal method / class method: `cookie: function (` or `cookie(a) {`
+    m=l.match(/^\s*(\w+)\s*:\s*(?:async\s*)?(?:function\b|\()/);
+    if(m)return {name:m[1],exported:false};
   }
   return null;
 }
+function _enclosingFn(content,line){
+  const info=_enclosingFnInfo(content,line);
+  return info?info.name:null;
+}
 
 // 0.6.0 Feat-2: Toxic-combinations score — composes multi-signal risk into 0–100.
 // Composes existing per-finding signals into a 0–100 toxicity score with a
@@ -9067,13 +9138,24 @@ function _deterministicFileTimings(timings) {
     // sanitizer would then hide a real vulnerability outright, whereas a label
     // only demotes confidence here. Recall-preserving, on purpose.
     const sanitizersOnPath = {};
+    // The same shape for calls that UNDO an encoding. A sanitizer whose effect
+    // is reversed later on the path is not a sanitizer, and the gate could not
+    // see that before: the catalog only models sanitizers, so a decoder was
+    // never recorded at all and `he.decode(escapeHtml(x))` read as clean.
+    const unsanitizersOnPath = {};
     for (const f of finalFindings) {
       const names = f && f._sanitizersOnPath;
-      if (!Array.isArray(names) || !names.length) continue;
-      if (f.id) sanitizersOnPath[f.id] = names;
-      if (f.stableId) sanitizersOnPath[f.stableId] = names;
+      if (Array.isArray(names) && names.length) {
+        if (f.id) sanitizersOnPath[f.id] = names;
+        if (f.stableId) sanitizersOnPath[f.stableId] = names;
+      }
+      const undo = f && f._unsanitizersOnPath;
+      if (Array.isArray(undo) && undo.length) {
+        if (f.id) unsanitizersOnPath[f.id] = undo;
+        if (f.stableId) unsanitizersOnPath[f.stableId] = undo;
+      }
     }
-    _runAnnotator("applySanitizerGate", () => { applySanitizerGate(finalFindings, { sanitizersOnPath }); });
+    _runAnnotator("applySanitizerGate", () => { applySanitizerGate(finalFindings, { sanitizersOnPath, unsanitizersOnPath }); });
     _runAnnotator("annotateProofGate", () => { annotateProofGate(finalFindings); });
   }
   // Addition #1 — default falsification pass. Actively tries to DISPROVE each

package/src/report/index.js

@@ -736,6 +736,26 @@ export function toMarkdown(scan, meta={}){
   return lines.join('\n');
 }
 
+// The load-bearing caveats every machine-readable artifact must carry, in one
+// place. A consumer that ingests our output without seeing these will read an
+// ordinal priority score as a probability, and will read a benchmark-tuned F1
+// as a general-purpose quality claim. Both are wrong, and both are the kind of
+// wrong that only shows up in somebody else's risk-acceptance decision.
+export const TOOL_CAVEATS = Object.freeze([
+  {
+    id: 'scores-are-ordinal',
+    name: 'ScoresAreOrdinal',
+    shortDescription: 'priority/exploitability scores are ordinal, not calibrated probabilities',
+    fullDescription: 'The properties.exploitability and properties.confidence fields on each result are ORDINAL priority scores used to rank findings within a scan. They are NOT calibrated probabilities; do not render them as percentages or feed them into pricing / risk-acceptance decisions. Use the tier labels (critical/high/medium/low) for coarse bucketing. See bench/README.md for the open calibration work.',
+  },
+  {
+    id: 'owasp-benchmark-tuning',
+    name: 'OwaspBenchmarkTuning',
+    shortDescription: 'engine ships OWASP-Benchmark-shape precision lifters; F1 numbers do not generalize',
+    fullDescription: 'The engine includes precision lifters (sast/primary-cwe-java.js, sast/java-constant-fold.js) whose heuristics are tuned to OWASP Benchmark v1.2 file shape (servlet-style files <=300 LoC, canonical variable names). F1 numbers cited against OWASP Benchmark do NOT generalize to arbitrary Java code. Expect higher FP rates on real-world codebases until per-customer tuning lands. See bench/README.md.',
+  },
+]);
+
 export function toSARIF(scan, meta={}){
   const findings = normalizeFindings(scan);
   const ruleMap = new Map();
@@ -758,22 +778,18 @@ export function toSARIF(scan, meta={}){
   // SARIF run itself so machine consumers see them. Without these, a CI that
   // ingests SARIF treats "confidence: 0.9" as a probability and the
   // benchmark-tuned 0.907 number as quality evidence.
-  const SARIF_NOTIFICATIONS = [
-    {
-      id: 'scores-are-ordinal',
-      name: 'ScoresAreOrdinal',
-      shortDescription: { text: 'priority/exploitability scores are ordinal, not calibrated probabilities' },
-      defaultConfiguration: { level: 'note' },
-      fullDescription: { text: 'The properties.exploitability and properties.confidence fields on each result are ORDINAL priority scores used to rank findings within a scan. They are NOT calibrated probabilities; do not render them as percentages or feed them into pricing / risk-acceptance decisions. Use the tier labels (critical/high/medium/low) for coarse bucketing. See bench/README.md for the open calibration work.' },
-    },
-    {
-      id: 'owasp-benchmark-tuning',
-      name: 'OwaspBenchmarkTuning',
-      shortDescription: { text: 'engine ships OWASP-Benchmark-shape precision lifters; F1 numbers do not generalize' },
-      defaultConfiguration: { level: 'note' },
-      fullDescription: { text: 'The engine includes precision lifters (sast/primary-cwe-java.js, sast/java-constant-fold.js) whose heuristics are tuned to OWASP Benchmark v1.2 file shape (servlet-style files <=300 LoC, canonical variable names). F1 numbers cited against OWASP Benchmark do NOT generalize to arbitrary Java code. Expect higher FP rates on real-world codebases until per-customer tuning lands. See bench/README.md.' },
-    },
-  ];
+  //
+  // The texts live in TOOL_CAVEATS (module scope) because SARIF is no longer
+  // the only machine format that has to carry them: report/oscal.js emits the
+  // same list as back-matter resources. Two copies of a caveat is one copy
+  // that goes stale, and the stale one is always the one somebody reads.
+  const SARIF_NOTIFICATIONS = TOOL_CAVEATS.map(c => ({
+    id: c.id,
+    name: c.name,
+    shortDescription: { text: c.shortDescription },
+    defaultConfiguration: { level: 'note' },
+    fullDescription: { text: c.fullDescription },
+  }));
   return {
     $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
     version: '2.1.0',