@clear-capabilities/agentic-security-scanner 0.127.0 → 0.128.1

package/dist/agentic-security.mjs.sha256

@@ -1 +1 @@
-424585bd11f792465c48ad4fcf7bcb61be3b3351b80f3fdb500eb7f89cb6755c  agentic-security.mjs
+2d630902bbb9bebbd5557bce1c7db106cd81fdf975cf18c5273b1e46716103a7  agentic-security.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clear-capabilities/agentic-security-scanner",
-  "version": "0.127.0",
+  "version": "0.128.1",
   "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, SARIF ingest, pipeline integrity, compliance attestation, and more.",
   "type": "module",
   "main": "src/index.js",
@@ -61,13 +61,13 @@
     "test": "npm run test:smoke && npm run test:sast && npm run test:posture && npm run test:dataflow && npm run test:mcp && npm run test:report && npm run test:bench-modules && npm run test:lifecycle && npm run test:eval && AGENTIC_SECURITY_CPP_DATAFLOW=1 node --test test/cpp-dataflow.test.js",
     "test:smoke": "node --test test/smoke.test.js",
     "test:sast": "node --test test/llm.test.js test/llm-cost-advisor.test.js test/llm-owasp.test.js test/logic.test.js test/authz.test.js test/model-load.test.js test/prompt-template.test.js test/business-logic.test.js test/python-sinks.test.js test/phase1-detectors.test.js test/phase2-detectors.test.js test/phase3-v3.test.js test/phase7-extensions.test.js test/phase8-extensions.test.js test/new-cwe-detectors.test.js test/file-upload.test.js test/llmsecops-detectors.test.js test/db-taint.test.js test/dart-swift.test.js test/redos-nfa.test.js test/weak-randomness.test.js test/csharp-pipeline.test.js test/post-quantum-crypto.test.js test/web3-advanced.test.js test/cloud-iam-k8s.test.js test/crypto-protocol.test.js test/ml-supply-chain.test.js test/wrong-context-sanitizer.test.js test/sanitizer-context.test.js test/frontend-hygiene.test.js test/csv-injection.test.js test/stored-taint.test.js test/tree-sitter-sinks.test.js test/kotlin-structural.test.js test/ruby-php-structural.test.js test/java-csharp-structural.test.js test/guard-recognition.test.js test/js-python-framework-structural.test.js test/go-structural.test.js test/secret-concat.test.js test/xss-reflected-multilang.test.js test/code-injection-multilang.test.js test/xxe-multilang.test.js test/xpath-injection-multilang.test.js test/gapfill-batch13.test.js test/agent-untrusted-flow.test.js test/api-authz.test.js test/event-entrypoint.test.js test/iac-terraform.test.js test/cross-service.test.js test/rbac-consistency.test.js",
-    "test:posture": "node --test test/material-change.test.js test/drift.test.js test/scorecard.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/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/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-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/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:posture": "node --test test/material-change.test.js test/drift.test.js test/scorecard.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/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/fix-honesty-gate.test.js test/model-routing.test.js test/root-cause-sweep.test.js test/entrypoint-inventory.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-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/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:dataflow": "node --test 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-go.test.js test/parser-php-rb.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/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:mcp": "node --test test/mcp.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:report": "node --test test/sarif-ingest.test.js 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:bench-modules": "node --test test/phase4-harness.test.js test/pipeline.test.js",
     "test:lifecycle": "node --test test/dead-code.test.js test/no-dead-modules.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 && node ../scripts/lint-command-descriptions.mjs",
-    "test:eval": "node --test test/independent-eval.test.js",
+    "test:eval": "node --test test/independent-eval.test.js test/realworld-recall.test.js",
     "eval:independent": "node ../bench/independent-eval/runner.mjs",
     "eval:independent:gate": "node ../bench/independent-eval/runner.mjs --gate default",
     "smoke": "node bin/agentic-security.js scan test/fixtures/vulnerable-js",

package/src/engine.js

@@ -174,6 +174,10 @@ import { applyLearnedCalibration } from './posture/triage-learning.js';
 import { annotateFormalVerification } from './dataflow/formal-verify.js';
 import { annotatePathFeasibility } from './dataflow/smt-feasibility.js';
 import { annotateProofGate } from './dataflow/proof-gate.js';
+import { annotateFalsification } from './posture/falsification.js';
+import { routeModelForFinding } from './posture/model-routing.js';
+import { buildEntrypointInventory } from './posture/entrypoint-inventory.js';
+import { sweepRootCauses } from './posture/root-cause-sweep.js';
 import { computeAnalysisTiers, countUnmodeledSinkCandidates } from './posture/coverage-report.js';
 import { annotatePrivacyTaint, emitDpiaArtifact } from './dataflow/privacy-taint.js';
 import { buildThreatModel as buildAutoThreatModel, persistThreatModel as persistAutoThreatModel } from './posture/threat-model-auto.js';
@@ -7912,6 +7916,23 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null},
   if (process.env.AGENTIC_SECURITY_NO_PROOF_GATE !== '1') {
     _runAnnotator("annotateProofGate", () => { annotateProofGate(finalFindings); });
   }
+  // Addition #1 — default falsification pass. Actively tries to DISPROVE each
+  // taint-style finding by locating a context-matched control on the path, and
+  // demotes + quarantines the ones it can block. Recall-preserving (never
+  // removes a finding, never touches severity — like the proof gate). Runs
+  // AFTER proof-gate so it layers on the same demotion channel. Deterministic by
+  // default; the LLM tier is only wired when an endpoint is configured. Opt out
+  // with AGENTIC_SECURITY_NO_FALSIFICATION=1.
+  if (process.env.AGENTIC_SECURITY_NO_FALSIFICATION !== '1') {
+    _runAnnotator("annotateFalsification", () => { annotateFalsification(finalFindings, fc); });
+  }
+  // Addition #5 — capability-based model routing. Stamp each finding with the
+  // model tier a cost-sensitive fixer/triager/PoC subagent should be dispatched
+  // on for THIS vuln class (crypto/auth/critical → strongest; injection → mid;
+  // low-sev hardening → cheapest). Advisory metadata consumed at dispatch time.
+  _runAnnotator("annotateDispatchModel", () => {
+    for (const f of finalFindings) { try { f.dispatchModel = routeModelForFinding(f).model; } catch { /* advisory only */ } }
+  });
   // v3 next-gen: production-aware context ingest (Pillar 9). Must run BEFORE
   // the mitigation composite, persona prioritization, and final why-fired
   // record so those see the demotion signals.
@@ -8542,7 +8563,12 @@ async function runFullScan({fileContents={}, depFileContents={}, scanRoot=null},
   try { _analysisTier = computeAnalysisTiers(Object.keys(fc)); } catch {}
   try { _unmodeledSinks = countUnmodeledSinkCandidates(fc, finalFindings); } catch {}
   const _scanMeta={filesScanned:files.length,filesSkipped:_filesSkipped,filesDenseSkipped:_filesDenseSkipped,filesTimedOut:_filesTimedOut,analysisTier:_analysisTier,unmodeledSinkCandidates:_unmodeledSinks,fileTimings:_fileTimings.sort((a,b)=>b.ms-a.ms).slice(0,20),findingsBySeverity:{critical:finalFindings.filter(f=>f.severity==='critical').length,high:finalFindings.filter(f=>f.severity==='high').length,medium:finalFindings.filter(f=>f.severity==='medium').length,low:finalFindings.filter(f=>f.severity==='low').length,info:finalFindings.filter(f=>f.severity==='info').length}};
-  return{routes:dd(aR,r=>`${r.method}:${r.path}:${r.file}:${r.line}`),findings:finalFindings,sources:aSrc,sinks:aSink,sanitizers:aSan,filesScanned:files.length,crossFileCount:cf.length,logicVulns:aLogic,supplyChain,components:annotatedComponents,secrets:aSecrets,ciphers:{atRest:aCiphersRest,inTransit:aCiphersTransit},pfr,fc,suppressions:_getSuppressions(),_v3,_scanMeta,_engineErrors:{cppDataflowParseErrors:_cppDataflowParseErrors.value},annotatorErrors:_annotatorErrors,threatModel:_threatModel,sbomDiff:_sbomDiff,complianceReport:_complianceReport,exploitBundles:_exploitBundles,pqcPlan:_pqcPlan,licenseGraph:_licenseGraph,attributions:_attributions,attackTaxonomy:_taxonomySummary};}
+  // Addition #2 — attack-surface completeness inventory (entry points → dispositions).
+  let _entrypointInventory = {}; try { _entrypointInventory = buildEntrypointInventory(fc, { routes: aR, findings: finalFindings }); } catch { _entrypointInventory = {}; }
+  // Addition #3 — root-cause sweep: from confirmed findings, find sibling instances
+  // detectors missed, with total-count accounting. Confirmed-only (cheap by default).
+  let _rootCauseSweep = null; try { _rootCauseSweep = sweepRootCauses(finalFindings, fc); } catch { _rootCauseSweep = null; }
+  return{entrypointInventory:_entrypointInventory,rootCauseSweep:_rootCauseSweep,routes:dd(aR,r=>`${r.method}:${r.path}:${r.file}:${r.line}`),findings:finalFindings,sources:aSrc,sinks:aSink,sanitizers:aSan,filesScanned:files.length,crossFileCount:cf.length,logicVulns:aLogic,supplyChain,components:annotatedComponents,secrets:aSecrets,ciphers:{atRest:aCiphersRest,inTransit:aCiphersTransit},pfr,fc,suppressions:_getSuppressions(),_v3,_scanMeta,_engineErrors:{cppDataflowParseErrors:_cppDataflowParseErrors.value},annotatorErrors:_annotatorErrors,threatModel:_threatModel,sbomDiff:_sbomDiff,complianceReport:_complianceReport,exploitBundles:_exploitBundles,pqcPlan:_pqcPlan,licenseGraph:_licenseGraph,attributions:_attributions,attackTaxonomy:_taxonomySummary};}
 
 // Post-aggregation classification: every source becomes "unsafe"|"safe"; every sink becomes "confirmed"|"safe".
 // Orphans (no finding linkage) are bucketed by file-local heuristic so the UI shows binary states only.

package/src/integrations/tickets.js

@@ -17,6 +17,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as cp from 'node:child_process';
 import { buildJiraIssue } from './index.js';
+import { escapeMarkdown } from '../util/untrusted.js';
 
 function statePath(scanRoot) {
   return path.join(scanRoot, '.agentic-security', 'tickets.json');
@@ -32,7 +33,10 @@ function writeState(scanRoot, state) {
 }
 
 function findingTitle(f) {
-  return `[${(f.severity || 'medium').toUpperCase()}] ${f.vuln || f.title || 'security finding'} at ${f.file}:${f.line}`;
+  // vuln/title are lifted from the (untrusted) scanned code — escape before
+  // they land in an issue title. See docs/AGENT_THREAT_MODEL.md path #1.
+  const label = escapeMarkdown(f.vuln) || escapeMarkdown(f.title) || 'security finding';
+  return `[${(f.severity || 'medium').toUpperCase()}] ${label} at ${f.file}:${f.line}`;
 }
 function findingBody(f) {
   const br = f.blastRadius;
@@ -43,9 +47,11 @@ function findingBody(f) {
     f.cwe ? `**CWE:** ${f.cwe}` : null,
     f.epss != null ? `**EPSS:** ${f.epss.toFixed(4)} (percentile ${(f.epssPercentile * 100).toFixed(1)}%)` : null,
     exploited,
-    f.description ? `\n${f.description}` : null,
+    f.description ? `\n${escapeMarkdown(f.description)}` : null,
     br?.narrative ? `\n**Blast radius:** ${br.narrative}` : null,
-    f.snippet ? `\n\`\`\`\n${f.snippet}\n\`\`\`` : null,
+    // snippet is attacker-authored code; escape so a crafted ``` fence or
+    // <img>/[x](url) inside it cannot break out of the code block.
+    f.snippet ? `\n\`\`\`\n${escapeMarkdown(f.snippet)}\n\`\`\`` : null,
     f.remediation ? `\n**Remediation:** ${f.remediation}` : null,
     `\n---\n_Surfaced by agentic-security · finding id: ${f.id}_`,
   ].filter(Boolean).join('\n');

package/src/mcp/tools.js

@@ -549,12 +549,23 @@ export const apply_fix = {
       // Inline re-verify — the load-bearing gate. Must pass to write.
       let verdict;
       try {
-        const verifyFixCore = await getVerifyFixCore();
-        verdict = await verifyFixCore({
-          scanRoot: ctx.sessionRoot,
-          originalFindingStableId: f.stableId,
-          files: Object.fromEntries(Object.entries(confinedAbs).map(([rel, v]) => [rel, v.content])),
-        });
+        const _files = Object.fromEntries(Object.entries(confinedAbs).map(([rel, v]) => [rel, v.content]));
+        if (process.env.AGENTIC_SECURITY_FIX_RUN_TESTS === '1') {
+          // Addition #7 — connect the closed-loop verifier: add the project test
+          // suite as a fourth verification leg (scan + lint + tests). Opt-in
+          // because many repos have no runner and we must not fail-closed by
+          // default. Normalized to the scan+lint verdict shape used below.
+          const { verifyFixWithTests } = await import('../posture/fix-verify-loop.js');
+          const t = await verifyFixWithTests({ scanRoot: ctx.sessionRoot, originalFindingStableId: f.stableId, files: _files });
+          verdict = { ok: t.ok, summary: t.summary, rescan: t.legs?.scan?.detail, lint: t.legs?.lint?.detail, tests: t.legs?.tests, testVerdict: t.verdict };
+        } else {
+          const verifyFixCore = await getVerifyFixCore();
+          verdict = await verifyFixCore({
+            scanRoot: ctx.sessionRoot,
+            originalFindingStableId: f.stableId,
+            files: _files,
+          });
+        }
       } catch (e) {
         return { _meta: META, applied: false, reason: `patch verification failed: ${e.message}` };
       }

package/src/posture/CLAUDE.md

@@ -21,6 +21,13 @@ Annotators that run **after** every detector has emitted, plus state stores read
 
 **Agentic verification** — `verifier.js`, `verifier-target.js`, `verifier-ephemeral.js`, `harness-discovery.js`, `adversary-agent.js`, `defender-agent.js`, `auditor-agent.js`, `three-agent-pipeline.js`.
 
+**Methodology additions (`docs/AGENTIC_METHODOLOGY_PRD.md`)** — default-on annotators/artifacts that layer the agentic-hunter methodology on the deterministic engine:
+- `falsification.js` — default falsification pass. For each taint-style finding, tries to DISPROVE it (locate a context-matched control on the path, reusing `dataflow/sanitizer-proof.js`'s shape rules read-only); a blocked finding is demoted + `quarantined`, never removed and never severity-touched (recall-preserving, like `proof-gate`). Wired after `annotateProofGate`. Opt out: `AGENTIC_SECURITY_NO_FALSIFICATION=1`. Optional LLM tier over survivors when an endpoint is configured.
+- `entrypoint-inventory.js` — attack-surface completeness ledger. Enumerates every entry point (HTTP/queue/cron/CLI/env/upload/webhook) with a disposition each; on `scan.entrypointInventory`.
+- `root-cause-sweep.js` — from confirmed findings, finds sibling instances detectors missed with total-count accounting (`found === candidates + mitigated`); on `scan.rootCauseSweep`.
+- `model-routing.js` — capability-based CWE/severity→model policy; stamps `finding.dispatchModel` (strongest for crypto/auth/critical, mid for injection, cheapest for low-sev hardening) for cost-sensitive subagent dispatch.
+- `fix-honesty-gate.js` — deterministic honesty gates on fix output: a residual-risk hand-wave guard, a cited-file:line requirement for any FP/safe verdict, and FULL/MITIGATION/WORKAROUND completeness tiers. Consumed by `fix-verify.js` when the caller supplies fix metadata; the closed-loop test leg (`fix-verify-loop.js`) is wired into `mcp/apply_fix` behind `AGENTIC_SECURITY_FIX_RUN_TESTS=1`.
+
 **Integrity + signing** — `integrity.js` (per-install HMAC for `last-scan.json`), `rule-pack-signing.js`. The HMAC key lives at `$XDG_CONFIG_HOME/agentic-security/scan-key`; override via `$AGENTIC_SECURITY_HMAC_KEY`. Premortem-derived; do not regress to hostname-derived.
 
 **Rule lifecycle** — `custom-rules.js` (YAML pattern DSL), `rule-overrides.js` (`disable:` gated on signature), `rule-packs.js`, `rule-synthesis.js` (proposes suppressions from triage feedback), `ruleset-version.js`.

package/src/posture/entrypoint-inventory.js

@@ -0,0 +1,248 @@
+// Attack-surface completeness inventory (addition #2).
+//
+// Enumerates every attacker-reachable entry point across a codebase and
+// assigns each a disposition, producing an auditable coverage ledger. The
+// point is completeness: rather than only reporting where a finding fired,
+// this lists every surface an attacker can *reach* (HTTP routes, queue
+// consumers, cron jobs, CLI arg parsing, environment reads, file uploads,
+// webhooks) and states, for each, whether it was traced clean, has an open
+// finding, or otherwise. A reviewer can then audit the coverage rather than
+// trust that "no finding == safe."
+//
+// Entry-point types (7):
+//   http     — inbound HTTP routes (from opts.routes; one entry per route)
+//   queue    — message-queue consumers (Kafka / SQS / RabbitMQ / pub-sub)
+//   cron     — scheduled jobs (@Scheduled, cron.schedule, setInterval, celery)
+//   cli      — command-line argument parsing (argv / argparse / commander / …)
+//   env      — environment-variable reads (process.env / getenv)
+//   upload   — file-upload sinks (multer / req.files / MultipartFile)
+//   webhook  — inbound webhook handlers (route path or /webhook literal)
+//
+// Granularity: HTTP/webhook routes are enumerated per route. The regex-
+// discovered surfaces are enumerated per (type, file) — a source file that
+// exposes a surface is counted once for that surface, recording the first
+// matching line. This avoids double-counting an import line plus its use
+// site (e.g. `import multer` + `multer(...)`) while still distinguishing
+// distinct surface types that share a file.
+//
+// No throwing: every public entry degrades to an empty/zeroed ledger.
+
+// ── Entry-point type order (fixed — drives byType key order) ────────────────
+const ENTRY_TYPES = ['http', 'queue', 'cron', 'cli', 'env', 'upload', 'webhook'];
+
+// ── Regex-discovered surface patterns ──────────────────────────────────────
+// Non-global regexes (no /g) so repeated .test()/.exec() calls are stateless.
+// Ordered roughly most-specific → most-generic within each type.
+const SURFACE_PATTERNS = {
+  queue: [
+    /@KafkaListener\b/,
+    /@SqsListener\b/,
+    /@RabbitListener\b/,
+    /\b(?:sqs|kafka|rabbit)\w*\s*\.\s*(?:consume|subscribe|receiveMessage|poll|on)\b/i,
+    /new\s+(?:Kafka)?Consumer\s*\(/,
+    /\.consume\s*\(/,
+    /\.subscribe\s*\(/,
+  ],
+  cron: [
+    /@Scheduled\b/,
+    /cron\.schedule\s*\(/,
+    /\bnode-cron\b/,
+    /@shared_task\b/,
+    /@periodic_task\b/,
+    /@(?:app\.)?task\b/,          // celery
+    /setInterval\s*\(/,           // interval used as a recurring job
+  ],
+  cli: [
+    /process\.argv\b/,
+    /\bargparse\b/,
+    /\bcommander\b/,
+    /\byargs\b/,
+    /\bcobra\.Command\b/,
+    /\bflag\.Parse\s*\(/,
+  ],
+  env: [
+    /process\.env\.\w+/,
+    /os\.getenv\s*\(/,
+    /System\.getenv\s*\(/,
+  ],
+  upload: [
+    /\bmulter\b/,
+    /\breq\.files?\b/,
+    /\brequest\.files?\b/,
+    /multipart\/form-data/i,
+    /\bMultipartFile\b/,
+  ],
+  webhook: [
+    /['"`][^'"`]*\/webhook[^'"`]*['"`]/i,   // a "/webhook…" string literal
+  ],
+};
+
+// Auth tokens — presence near an entry point in the same file promotes its
+// trust boundary from unauthenticated → authenticated. `\bauth\b` matches the
+// bare token only (not "author" / "oauth", which retain their word chars).
+const AUTH_TOKEN = /(?:@PreAuthorize|requireAuth|require_auth|login_required|isAuthenticated|authenticate\w*|authorize\w*|authMiddleware|authGuard|\bauth\b)/i;
+
+const AUTH_WINDOW = 8;   // lines above/below the entry point to scan for auth
+
+// ── Input normalization ─────────────────────────────────────────────────────
+// Accept either a Map<filepath,string> or a plain object {path: source}.
+function _entries(fileContents) {
+  if (!fileContents) return [];
+  if (fileContents instanceof Map) {
+    return [...fileContents.entries()].filter(([, v]) => typeof v === 'string');
+  }
+  if (typeof fileContents === 'object') {
+    return Object.entries(fileContents).filter(([, v]) => typeof v === 'string');
+  }
+  return [];
+}
+
+function _emptyCoverage() {
+  const byType = {};
+  for (const t of ENTRY_TYPES) byType[t] = 0;
+  return { total: 0, byType, tracedSafe: 0, finding: 0, notReachable: 0, noInput: 0 };
+}
+
+function _authNear(lines, line) {
+  const lo = Math.max(0, line - 1 - AUTH_WINDOW);
+  const hi = Math.min(lines.length, line + AUTH_WINDOW);
+  return AUTH_TOKEN.test(lines.slice(lo, hi).join('\n'));
+}
+
+function _routeHasInput(route) {
+  if (Array.isArray(route.params) && route.params.length) return true;
+  const p = typeof route.path === 'string' ? route.path : '';
+  // :id (Express/Koa), {id} (FastAPI/Spring), <id> (Flask/Django) → has input.
+  return /[:{<]\w/.test(p);
+}
+
+function _clip(s, n = 80) {
+  const str = String(s == null ? '' : s).trim();
+  return str.length > n ? str.slice(0, n) : str;
+}
+
+// ── Core ─────────────────────────────────────────────────────────────────────
+
+export function buildEntrypointInventory(fileContents, opts = {}) {
+  const coverage = _emptyCoverage();
+  const entrypoints = [];
+  try {
+    const routes = Array.isArray(opts && opts.routes) ? opts.routes : [];
+    const findings = Array.isArray(opts && opts.findings) ? opts.findings : [];
+    const findingFiles = new Set(
+      findings.map(f => (f && typeof f.file === 'string' ? f.file : null)).filter(Boolean),
+    );
+
+    // 1) HTTP / webhook entry points — one per route.
+    for (const route of routes) {
+      if (!route || typeof route !== 'object') continue;
+      const file = typeof route.file === 'string' && route.file ? route.file : '(unknown)';
+      const line = Number.isInteger(route.line) ? route.line : 0;
+      const method = typeof route.method === 'string' ? route.method : 'GET';
+      const path = typeof route.path === 'string' ? route.path : '';
+      const isWebhook = /webhook/i.test(path) || /webhook/i.test(String(route.handler || ''));
+      const type = isWebhook ? 'webhook' : 'http';
+      const name = _clip(route.handler || `${method} ${path}`.trim() || type);
+
+      // Trust: an authenticated route (hasAuth) or a nearby auth token wins.
+      let trust = route.hasAuth === true ? 'authenticated' : 'unauthenticated';
+      if (trust === 'unauthenticated' && fileContents) {
+        const src = _srcOf(fileContents, file);
+        if (src && _authNear(src.split(/\r?\n/), line)) trust = 'authenticated';
+      }
+
+      let disposition;
+      if (findingFiles.has(file)) disposition = 'finding';
+      else if (type === 'http' && !_routeHasInput(route)) disposition = 'no-input';
+      else disposition = 'traced-safe';
+
+      entrypoints.push({ type, file, line, name, trust, disposition });
+    }
+
+    // 2) Regex-discovered surfaces — one per (type, file), first matching line.
+    for (const [file, source] of _entries(fileContents)) {
+      const lines = source.split(/\r?\n/);
+      for (const type of ENTRY_TYPES) {
+        const pats = SURFACE_PATTERNS[type];
+        if (!pats) continue;   // http has no file-scan pattern (routes-only)
+        let hitLine = -1;
+        let hitText = '';
+        outer:
+        for (let i = 0; i < lines.length; i++) {
+          for (const re of pats) {
+            const m = re.exec(lines[i]);
+            if (m) { hitLine = i + 1; hitText = _clip(m[0] || type); break outer; }
+          }
+        }
+        if (hitLine < 0) continue;
+
+        const trust = _authNear(lines, hitLine) ? 'authenticated' : 'unauthenticated';
+        // Regex surfaces inherently carry attacker-controlled input (a queue
+        // message, an env value, a CLI arg, an upload). Only HTTP routes get
+        // the optional 'no-input' disposition.
+        const disposition = findingFiles.has(file) ? 'finding' : 'traced-safe';
+        entrypoints.push({ type, file, line: hitLine, name: hitText || type, trust, disposition });
+      }
+    }
+
+    // 3) Roll up the coverage ledger.
+    coverage.total = entrypoints.length;
+    for (const e of entrypoints) {
+      if (coverage.byType[e.type] != null) coverage.byType[e.type]++;
+      if (e.disposition === 'finding') coverage.finding++;
+      else if (e.disposition === 'not-reachable') coverage.notReachable++;
+      else if (e.disposition === 'no-input') coverage.noInput++;
+      else coverage.tracedSafe++;
+    }
+  } catch (_) {
+    // Degrade to whatever we accumulated before the error (or empty).
+    return { entrypoints, coverage: _recount(entrypoints) };
+  }
+  return { entrypoints, coverage };
+}
+
+// Defensive re-count used only on the error path.
+function _recount(entrypoints) {
+  const coverage = _emptyCoverage();
+  coverage.total = entrypoints.length;
+  for (const e of entrypoints) {
+    if (coverage.byType[e.type] != null) coverage.byType[e.type]++;
+    if (e.disposition === 'finding') coverage.finding++;
+    else if (e.disposition === 'not-reachable') coverage.notReachable++;
+    else if (e.disposition === 'no-input') coverage.noInput++;
+    else coverage.tracedSafe++;
+  }
+  return coverage;
+}
+
+function _srcOf(fileContents, file) {
+  if (!fileContents) return null;
+  if (fileContents instanceof Map) {
+    const v = fileContents.get(file);
+    return typeof v === 'string' ? v : null;
+  }
+  const v = fileContents[file];
+  return typeof v === 'string' ? v : null;
+}
+
+// ── Engine wiring helper ─────────────────────────────────────────────────────
+// Annotates a scan object in place with scan.entrypointInventory. Never throws;
+// absent inputs yield an empty ledger.
+export function annotateEntrypointCoverage(scan) {
+  if (!scan || typeof scan !== 'object') return scan;
+  try {
+    const fileContents = scan.fileContents || scan._fileContents || null;
+    const routes = Array.isArray(scan.routes) ? scan.routes : [];
+    const findings = Array.isArray(scan.findings) ? scan.findings : [];
+    if (!fileContents && routes.length === 0) {
+      scan.entrypointInventory = { entrypoints: [], coverage: _emptyCoverage() };
+      return scan;
+    }
+    scan.entrypointInventory = buildEntrypointInventory(fileContents || {}, { routes, findings });
+  } catch (_) {
+    scan.entrypointInventory = { entrypoints: [], coverage: _emptyCoverage() };
+  }
+  return scan;
+}
+
+export const _internals = { SURFACE_PATTERNS, ENTRY_TYPES, AUTH_TOKEN, _entries };

package/src/posture/falsification.js

@@ -0,0 +1,121 @@
+// Addition #1 — Default falsification pass ("prove it can't be blocked, or demote").
+//
+// For each taint-style finding we actively try to DISPROVE it: locate a
+// context-matched control (a sanitizer whose shape actually neutralizes THIS
+// CWE family) on the path between source and sink. A finding that is blocked by
+// such a control is "falsified" — demoted and quarantined. A finding with no
+// blocking control "survives" and stands.
+//
+// This is recall-preserving, exactly like `dataflow/proof-gate.js`: a falsified
+// finding is DEMOTED (confidence + tiers) and flagged `quarantined`, never
+// removed and never severity-touched. Genuine vulnerabilities have no valid
+// control on the path, so they survive — the corpus `pre:TP` fixtures stay TP.
+//
+// An OPTIONAL LLM tier (`opts.llmReview`, wired only when an LLM endpoint is
+// configured) argues the opposing case over survivors; it is never required and
+// the deterministic core runs fully offline.
+
+import { isValidSanitizerFor } from '../dataflow/sanitizer-proof.js';
+
+const DEMOTE_FACTOR = 0.4;               // mirror proof-gate.js
+const TIERS = ['low', 'medium', 'high']; // confidence / exploitability tier order
+
+function _dropTier(tier) {
+  const i = TIERS.indexOf(tier);
+  if (i <= 0) return tier;               // unknown or already lowest → unchanged
+  return TIERS[i - 1];
+}
+
+function _fileText(fileContents, file) {
+  if (!fileContents || !file) return '';
+  if (fileContents instanceof Map) return fileContents.get(file) || '';
+  return fileContents[file] || '';
+}
+
+// Reconstruct the path window: the source line, the sink line, and the lines
+// between/around the sink, plus whatever snippets the finding already carries.
+function _pathWindow(finding, fileContents) {
+  const parts = [];
+  if (finding.source?.snippet) parts.push(String(finding.source.snippet));
+  if (finding.sink?.snippet) parts.push(String(finding.sink.snippet));
+  const text = _fileText(fileContents, finding.file);
+  if (text) {
+    const lines = text.split('\n');
+    const sinkLine = Number(finding.sink?.line) || 0;
+    const srcLine = Number(finding.source?.line) || 0;
+    const lo = Math.max(0, Math.min(sinkLine, srcLine) - 3);
+    const hi = Math.min(lines.length, Math.max(sinkLine, srcLine) + 3);
+    for (let i = lo; i < hi; i++) parts.push(lines[i]);
+  }
+  return parts.join('\n');
+}
+
+/**
+ * Pure classifier. Returns `{ verdict, reasons }` with verdict ∈
+ *   'blocked'  — a context-matched control for this CWE family sits on the path
+ *   'survived' — no blocking control found; the finding stands
+ *   'unproven' — not enough context to attempt falsification
+ */
+export function classifyFinding(finding, fileContents) {
+  if (!finding || !finding.cwe || !finding.source || !finding.sink) {
+    return { verdict: 'unproven', reasons: ['not a taint-style finding'] };
+  }
+  // A sanitizer that doesn't match the sink context does NOT block the flow —
+  // the finding survives (this is a real bug, not a mitigation).
+  if (finding.sanitizerMismatch === true) {
+    return { verdict: 'survived', reasons: ['wrong-context sanitizer does not neutralize this sink'] };
+  }
+  const window = _pathWindow(finding, fileContents);
+  if (!window || !window.trim()) {
+    return { verdict: 'unproven', reasons: ['no source context available to attempt falsification'] };
+  }
+  const v = isValidSanitizerFor(window, finding.cwe);
+  if (v.trusted) {
+    return { verdict: 'blocked', reasons: [`context-matched control on path — ${v.reason}`] };
+  }
+  return { verdict: 'survived', reasons: ['no context-matched control found between source and sink'] };
+}
+
+/**
+ * Default-on annotator. Adds `finding.falsification = { verdict, reasons }` to
+ * every taint-style finding; demotes + quarantines the ones falsified as blocked.
+ * NEVER removes a finding and NEVER mutates severity (recall-preserving).
+ *
+ * @param opts.llmReview  optional (survivor) => { verdict, reason } — the LLM tier.
+ *                        Wired only when an LLM endpoint is configured; run over
+ *                        survivors, and its result is attached at .falsification.llm.
+ */
+export function annotateFalsification(findings, fileContents, opts = {}) {
+  if (!Array.isArray(findings)) return findings;
+  const survivors = [];
+  for (const f of findings) {
+    if (!f || !f.source || !f.sink || !f.cwe) continue; // only taint-style findings
+    let res;
+    try { res = classifyFinding(f, fileContents); }
+    catch { res = { verdict: 'unproven', reasons: ['classification error'] }; }
+    f.falsification = { verdict: res.verdict, reasons: res.reasons };
+
+    if (res.verdict === 'blocked') {
+      f.quarantined = true;
+      if (typeof f.confidence === 'number') {
+        f.confidence = Math.max(0, Math.round(f.confidence * DEMOTE_FACTOR * 1000) / 1000);
+      }
+      if (f.confidenceTier) f.confidenceTier = _dropTier(f.confidenceTier);
+      if (f.exploitabilityTier) f.exploitabilityTier = _dropTier(f.exploitabilityTier);
+      // severity intentionally untouched.
+    } else if (res.verdict === 'survived') {
+      survivors.push(f);
+    }
+  }
+
+  // Optional LLM tier — only over survivors, only when a reviewer is supplied.
+  if (typeof opts.llmReview === 'function') {
+    for (const f of survivors) {
+      try {
+        const llm = opts.llmReview(f);
+        if (llm) f.falsification.llm = llm;
+      } catch { /* the LLM tier is advisory; never let it break the scan */ }
+    }
+  }
+  return findings;
+}