@clear-capabilities/agentic-security-scanner 0.134.0 → 0.136.2

package/dist/compliance-frameworks/owasp-asvs-5.json

@@ -0,0 +1,79 @@
+{
+  "id": "owasp-asvs-5",
+  "name": "OWASP Application Security Verification Standard 5.0",
+  "publisher": "OWASP Foundation",
+  "license": "Creative Commons Attribution-ShareAlike 4.0",
+  "url": "https://owasp.org/www-project-application-security-verification-standard/",
+  "controls": [
+    {
+      "id": "V2.1",
+      "category": "Authentication",
+      "summary": "Verify that authentication is performed for protected functions.",
+      "evidence": ["Zero open critical findings in family auth-missing on the current scan."],
+      "mapsTo": ["family:auth-missing"]
+    },
+    {
+      "id": "V2.7",
+      "category": "Authentication",
+      "summary": "Verify that MFA / secondary authentication is used for high-value operations.",
+      "evidence": ["aws-no-mfa-condition zero findings (if AWS in scope)."],
+      "mapsTo": ["family:aws-no-mfa"]
+    },
+    {
+      "id": "V4.1",
+      "category": "Access Control",
+      "summary": "Verify that authorization is enforced for every resource access.",
+      "evidence": ["Zero idor / authz findings."],
+      "mapsTo": ["family:idor", "family:authz"]
+    },
+    {
+      "id": "V5.1",
+      "category": "Input Validation",
+      "summary": "Verify input validation for type, length, and content.",
+      "evidence": ["Zero open critical findings in sqli/xss/command-injection/ldap-injection/xpath-injection."],
+      "mapsTo": ["family:sqli", "family:xss", "family:command-injection", "family:ldap-injection", "family:xpath-injection", "family:nosql-injection"]
+    },
+    {
+      "id": "V6.1",
+      "category": "Cryptography",
+      "summary": "Verify use of strong cryptography per a documented policy.",
+      "evidence": ["Zero open findings in crypto-weak-cipher / crypto-weak-hash / crypto-ecb / crypto-static-iv."],
+      "mapsTo": ["family:crypto-weak-cipher", "family:crypto-weak-hash", "family:crypto-ecb", "family:crypto-static-iv", "family:crypto-kdf-weak"]
+    },
+    {
+      "id": "V6.2",
+      "category": "Cryptography",
+      "summary": "Verify all transit data uses TLS ≥ 1.2.",
+      "evidence": ["Zero findings in crypto-tls-version / crypto-tls-no-verify."],
+      "mapsTo": ["family:crypto-tls-version", "family:crypto-tls-no-verify"]
+    },
+    {
+      "id": "V7.1",
+      "category": "Error Handling & Logging",
+      "summary": "Verify that error handling does not disclose sensitive information.",
+      "evidence": ["No findings in family data-exposure."],
+      "mapsTo": ["family:data-exposure"]
+    },
+    {
+      "id": "V8.1",
+      "category": "Data Protection",
+      "summary": "Verify that personal data is protected at rest and in transit.",
+      "evidence": ["DPIA artifact at .agentic-security/dpia.md.", "Zero pii-exposure findings."],
+      "mapsTo": ["family:pii-exposure", "family:training-data-pii"]
+    },
+    {
+      "id": "V10.1",
+      "category": "Malicious Code",
+      "summary": "Verify the application does not include known-malicious or compromised dependencies.",
+      "evidence": [".agentic-security/sbom-history snapshots clean.", "No dependency-confusion or dependency-drift findings."],
+      "mapsTo": ["family:vulnerable-dependency", "family:dependency-confusion", "family:dependency-drift"]
+    },
+    {
+      "id": "V14.1",
+      "category": "Configuration",
+      "summary": "Verify that build, deployment, and configuration are secure.",
+      "evidence": ["No findings in family iam-overpermissive / k8s-rbac-cluster-admin / k8s-pod-security-privileged."],
+      "mapsTo": ["family:iam-overpermissive", "family:k8s-rbac-cluster-admin", "family:k8s-pod-security-privileged"]
+    }
+  ]
+}

package/dist/compliance-frameworks/owasp-llm-top-10.json

@@ -0,0 +1,69 @@
+{
+  "id": "owasp-llm-top-10",
+  "name": "OWASP Top 10 for LLM Applications 2025",
+  "publisher": "OWASP Foundation",
+  "license": "Creative Commons Attribution-ShareAlike 4.0",
+  "url": "https://owasp.org/www-project-top-10-for-large-language-model-applications/",
+  "controls": [
+    {
+      "id": "LLM01",
+      "summary": "Prompt Injection — controls preventing injected instructions from overriding the system prompt.",
+      "evidence": ["Zero open findings in family prompt-injection / llm-app-security.", "Prompt-template integrity check passing."],
+      "mapsTo": ["family:prompt-injection", "family:llm-app-security", "family:prompt-integrity"]
+    },
+    {
+      "id": "LLM02",
+      "summary": "Insecure Output Handling — LLM output is not directly piped to dangerous sinks (eval/shell/SQL/HTML).",
+      "evidence": ["Zero open findings in subfamily llm-output-untrusted-sink."],
+      "mapsTo": ["family:llm-app-security:llm-output-untrusted-sink"]
+    },
+    {
+      "id": "LLM03",
+      "summary": "Training Data Poisoning — provenance and integrity controls on training/fine-tuning data.",
+      "evidence": ["No streaming-dataset-url findings.", "datasets.load_dataset uses pinned revisions."],
+      "mapsTo": ["family:streaming-dataset-url", "family:hf-datasets-rce"]
+    },
+    {
+      "id": "LLM04",
+      "summary": "Model Denial of Service — rate-limit / token-cap controls.",
+      "evidence": ["LLM API calls in source carry an explicit max_tokens cap (bodyguard rule no-max-tokens)."],
+      "mapsTo": ["rule:no-max-tokens"]
+    },
+    {
+      "id": "LLM05",
+      "summary": "Supply Chain — model & dataset supply-chain integrity.",
+      "evidence": ["No mlflow-untrusted-uri / model-format / hf-endpoint-override findings.", "Sigstore provenance verification configured if opt-in."],
+      "mapsTo": ["family:mlflow-untrusted-uri", "family:model-format", "family:hf-endpoint-override"]
+    },
+    {
+      "id": "LLM06",
+      "summary": "Sensitive Information Disclosure — output filters prevent leakage.",
+      "evidence": ["Zero findings in subfamily llm-credential-in-prompt.", "Redact module covers prompt + response."],
+      "mapsTo": ["family:llm-app-security:llm-credential-in-prompt"]
+    },
+    {
+      "id": "LLM07",
+      "summary": "Insecure Plugin / Tool Design — tools the LLM can invoke are narrowly scoped.",
+      "evidence": ["Zero llm-app-security:llm-tool-exec findings.", "Agent tool definitions reviewed for excessive agency."],
+      "mapsTo": ["family:agent-tool-exec", "family:llm-app-security:llm-tool-exec"]
+    },
+    {
+      "id": "LLM08",
+      "summary": "Excessive Agency — agent autonomy is bounded by explicit guards.",
+      "evidence": ["MCP server config limits write-tools to confirm:true + reserved-write-path refusal.", "Apply-fix path requires HMAC-verified scan."],
+      "mapsTo": ["module:mcp-tools", "module:apply-fix"]
+    },
+    {
+      "id": "LLM09",
+      "summary": "Overreliance — human review checkpoints exist.",
+      "evidence": ["security-fixer agent has Stop-on-verify-fail loop.", "PreToolUse bodyguard exists."],
+      "mapsTo": ["module:security-fixer", "module:pre-edit-bodyguard"]
+    },
+    {
+      "id": "LLM10",
+      "summary": "Model Theft — model access controls.",
+      "evidence": ["No private-key-in-frontend or rpc-key-inline findings in client code."],
+      "mapsTo": ["family:private-key-in-frontend", "family:rpc-key-inline"]
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clear-capabilities/agentic-security-scanner",
-  "version": "0.134.0",
+  "version": "0.136.2",
   "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",
@@ -55,19 +55,19 @@
     "lodash-es": "^4.18.1"
   },
   "scripts": {
-    "build": "ncc build bin/agentic-security.js -o dist --minify -e web-tree-sitter -e tree-sitter-wasms && mv dist/index.js dist/agentic-security.mjs && rm -f dist/package.json && chmod +x dist/agentic-security.mjs && node -e \"const fs=require('fs');const p='dist/agentic-security.mjs';const c=fs.readFileSync(p,'utf8');if(!c.startsWith('#!'))fs.writeFileSync(p,'#!/usr/bin/env node\\n'+c);\" && node -e \"const fs=require('fs');const c=require('crypto');const h=c.createHash('sha256').update(fs.readFileSync('dist/agentic-security.mjs')).digest('hex');fs.writeFileSync('dist/agentic-security.mjs.sha256',h+'  agentic-security.mjs\\n');\"",
+    "build": "ncc build bin/agentic-security.js -o dist --minify -e web-tree-sitter -e tree-sitter-wasms && rm -rf dist/compliance-frameworks && mkdir -p dist/compliance-frameworks && cp src/posture/compliance-frameworks/*.json dist/compliance-frameworks/ && mv dist/index.js dist/agentic-security.mjs && rm -f dist/package.json && chmod +x dist/agentic-security.mjs && node -e \"const fs=require('fs');const p='dist/agentic-security.mjs';const c=fs.readFileSync(p,'utf8');if(!c.startsWith('#!'))fs.writeFileSync(p,'#!/usr/bin/env node\\n'+c);\" && node -e \"const fs=require('fs');const c=require('crypto');const h=c.createHash('sha256').update(fs.readFileSync('dist/agentic-security.mjs')).digest('hex');fs.writeFileSync('dist/agentic-security.mjs.sha256',h+'  agentic-security.mjs\\n');\"",
     "prepare": "node ../scripts/pre-push-gate.mjs --install-hook",
     "prepublishOnly": "npm run build && node ../scripts/sync-scanner-changelog.mjs && node ../scripts/release-check.mjs",
     "test": "npm run test:smoke && npm run test:glob && 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 && npm run test:discovery && AGENTIC_SECURITY_CPP_DATAFLOW=1 node --test test/cpp-dataflow.test.js",
     "test:smoke": "node --test test/smoke.test.js",
     "test:glob": "node --test test/glob-compat.test.js",
     "test:sast": "node --test test/crypto-specialist.test.js 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/accuracy-scorecard.test.js test/scorecard-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/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/verification-separation.test.js test/logic-claims.test.js test/attestation.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: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/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/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/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/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: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/ir-stats.test.js test/parser-cpp.test.js test/parser-js-decorators.test.js test/cpp-integration.test.js test/engine-reconnect.test.js test/phase2-scoping.test.js test/engine-recall.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/proof-corpus-lib.test.js test/proof-corpus-runner.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 test/sandbox.test.js test/sandbox-escape.test.js && node ../scripts/lint-command-descriptions.mjs",
+    "test:lifecycle": "node --test test/dead-code.test.js test/no-dead-modules.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 && node ../scripts/lint-command-descriptions.mjs",
     "test:eval": "node --test test/independent-eval.test.js test/realworld-recall.test.js",
     "test:discovery": "node --test test/discovery-partition.test.js test/discovery-lenses.test.js test/discovery-hunter.test.js test/discovery-confirm.test.js test/discovery-disprove.test.js test/discovery-judge.test.js test/discovery-run.test.js test/discovery-wiring.test.js test/discovery-llm-invoke.test.js",
     "eval:independent": "node ../bench/independent-eval/runner.mjs",
@@ -108,7 +108,11 @@
     "release:check": "node ../scripts/release-check.mjs",
     "release:check:fast": "node ../scripts/release-check.mjs --fast",
     "gate:prepush": "node ../scripts/pre-push-gate.mjs",
-    "gate:prepush:install": "node ../scripts/pre-push-gate.mjs --install-hook"
+    "gate:prepush:install": "node ../scripts/pre-push-gate.mjs --install-hook",
+    "bench:independent": "node ../bench/independent/runner.mjs",
+    "bench:independent:fetch": "node ../bench/independent/fetch.mjs",
+    "bench:independent:mine": "node ../bench/independent/mine.mjs",
+    "bench:independent:materialise": "node ../bench/independent/materialise-cli.mjs"
   },
   "author": "Ross Young <ross@clearcapabilities.com>",
   "license": "PolyForm-Internal-Use-1.0.0"

package/src/badge.js

@@ -28,6 +28,7 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+import { statePath } from './posture/state-dir.js';
 const COLORS = {
   critical:    '#e05d44',  // red
   high:        '#fe7d37',  // orange
@@ -42,7 +43,7 @@ const SEVERITIES = ['critical', 'high', 'medium', 'low', 'info'];
 
 function _readLastScan(scanRoot) {
   if (!scanRoot) return null;
-  const fp = path.join(scanRoot, '.agentic-security', 'last-scan.json');
+  const fp = statePath(scanRoot, 'last-scan.json');
   if (!fs.existsSync(fp)) return null;
   try { return JSON.parse(fs.readFileSync(fp, 'utf8')); }
   catch { return null; }

package/src/dataflow/cross-service-taint.js

@@ -44,12 +44,13 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as yaml from '../util/yaml.js';
 
+import { statePath } from '../posture/state-dir.js';
 const SERVICES_FILE_NAMES = ['services.yml', 'services.yaml'];
 
 export function loadServiceGraph(scanRoot) {
   if (!scanRoot) return null;
   for (const name of SERVICES_FILE_NAMES) {
-    const fp = path.join(scanRoot, '.agentic-security', name);
+    const fp = statePath(scanRoot, name);
     if (!fs.existsSync(fp)) continue;
     try {
       const raw = fs.readFileSync(fp, 'utf8');

package/src/dataflow/ifds-precise.js

@@ -24,6 +24,7 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 
+import { statePath, safeWriteState, stateWritesEnabled } from '../posture/state-dir.js';
 // ── Per-call-site refined summaries ────────────────────────────────────────
 
 /**
@@ -160,7 +161,7 @@ export function backwardSlice(callGraph, finding, opts = {}) {
 // ── Persistent cross-scan summary cache ────────────────────────────────────
 
 function _cachePath(scanRoot) {
-  return path.join(scanRoot, '.agentic-security', 'ifds-summaries.json');
+  return statePath(scanRoot, 'ifds-summaries.json');
 }
 
 function _fileHash(content) {
@@ -190,8 +191,9 @@ export function loadPersistedCache(scanRoot) {
  * skip re-analysis of functions whose file hash hasn't changed.
  */
 export function persistCache(scanRoot, cache, perFileIR) {
-  const dir = path.join(scanRoot, '.agentic-security');
-  try { fs.mkdirSync(dir, { recursive: true }); } catch {}
+  // A read-only scan still ANALYSES; it just may not persist the cache. The
+  // next scan simply recomputes, which is slower and identical. (PRD M1)
+  if (!stateWritesEnabled()) return;
   const fileHashes = {};
   for (const [filePath, ir] of (perFileIR || new Map())) {
     if (ir && typeof ir._content === 'string') fileHashes[filePath] = _fileHash(ir._content);
@@ -203,7 +205,7 @@ export function persistCache(scanRoot, cache, perFileIR) {
     if (sum.has('∅')) summaries[qid] = sum.get('∅');
   }
   const out = { scanTs: new Date().toISOString(), summaries, fileHashes };
-  try { fs.writeFileSync(_cachePath(scanRoot), JSON.stringify(out, null, 2)); }
+  try { safeWriteState(_cachePath(scanRoot), JSON.stringify(out, null, 2)); }
   catch { /* best-effort */ }
 }
 

package/src/dataflow/incremental.js

@@ -31,7 +31,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import * as crypto from 'node:crypto';
 
-const STATE_DIR = '.agentic-security/incremental';
+import { statePath, stateWritesEnabled } from '../posture/state-dir.js';
+
 const FILES_PATH = 'files.json';
 const SUMMARIES_PATH = 'summaries.json';
 const VERSION_PATH = 'version.json';
@@ -44,7 +45,7 @@ export function hashFileContent(stripped) {
 
 /** Read the persisted state. Returns a fresh empty state on any error. */
 export function readIncrementalState(projectRoot) {
-  const dir = path.join(projectRoot, STATE_DIR);
+  const dir = statePath(projectRoot, 'incremental');
   try {
     const versionFp = path.join(dir, VERSION_PATH);
     if (!fs.existsSync(versionFp)) return _emptyState();
@@ -197,9 +198,10 @@ export function serializeSummaries(summaryCache) {
  */
 export function commitIncrementalState(projectRoot, state, currentVersion) {
   if (!projectRoot) return false;
-  const dir = path.join(projectRoot, STATE_DIR);
+  const dir = statePath(projectRoot, 'incremental');
   try {
-    fs.mkdirSync(dir, { recursive: true });
+    if (!stateWritesEnabled()) return;
+  fs.mkdirSync(dir, { recursive: true });
     fs.writeFileSync(path.join(dir, VERSION_PATH), JSON.stringify(currentVersion, null, 2));
     fs.writeFileSync(path.join(dir, FILES_PATH), JSON.stringify(state.files || {}, null, 2));
     const payload = {
@@ -215,7 +217,7 @@ export function commitIncrementalState(projectRoot, state, currentVersion) {
 
 /** Drop persisted state — used when a version mismatch is detected. */
 export function dropIncrementalState(projectRoot) {
-  const dir = path.join(projectRoot, STATE_DIR);
+  const dir = statePath(projectRoot, 'incremental');
   try {
     if (!fs.existsSync(dir)) return true;
     for (const fn of [VERSION_PATH, FILES_PATH, SUMMARIES_PATH]) {

package/src/discovery/CLAUDE.md

@@ -34,5 +34,15 @@ panel · `judge.js` shapes findings and dedupes against the prior scan ·
   This layer never emits `critical`.
 - **Ids are content digests.** No clock, no randomness, anywhere in an id, a
   digest, or a sort key.
+- **Bounded by default.** The pipeline is multiplicative — areas × lenses
+  hunter calls, then three refutation votes per surviving candidate. Six
+  files produced 168 LLM calls before C3. `makeBudget` in `index.js` wraps
+  `llmInvoke` so every call is counted against a ceiling, and `maxCandidates`
+  caps what reaches the panel. Never remove a bound without replacing it:
+  an unbounded run's cost is a function of repository size.
+- **An exhausted budget means INCOMPLETE, not clean.** Exhaustion arrives
+  through the same degradation path as a dead endpoint and lands in
+  `coverage.reasons`. A capped candidate is neither a finding nor cleared —
+  it was not examined, and the report says so.
 - **Coverage is reported.** Degraded runs and their reasons appear in every
   report. A half-failed pass must never read as a clean one.

package/src/discovery/index.js

@@ -13,6 +13,7 @@ import { runHunter } from './hunter.js';
 import { confirmAll } from './confirm.js';
 import { disprovePanel } from './disprove.js';
 import { judgeCandidates } from './judge.js';
+import { loadMemory, saveMemory, rememberRun, previouslyRefuted, nextWavePlan } from './memory.js';
 
 // Bridge a candidate to the deterministic layer. A taint finding at or within
 // two lines of the candidate corroborates it; a modelled sink on the line
@@ -54,10 +55,91 @@ async function runDeepAnalysisSafe(perFileIR, callGraph) {
 // where { perFileIR, callGraph } come from buildProjectIR(fileContents),
 // which returns { perFile, callGraph } — callers must pass perFile as
 // perFileIR (see scanner/src/ir/index.js).
+/**
+ * PRD Phase 0 / C3 — the run budget.
+ *
+ * This pipeline is multiplicative and was, until now, unbounded. Eight focus
+ * areas × seven lenses is 56 hunter calls before a single candidate exists, and
+ * every surviving candidate then costs three more calls in the refutation
+ * panel. Nothing capped any of it, so the cost of a run was a function of how
+ * large the repository happened to be — which is not a property you want to
+ * discover from an invoice.
+ *
+ * ENFORCED AT THE ONE SEAM EVERY CALL PASSES THROUGH. Rather than thread checks
+ * through the hunter and the panel, the budget wraps `llmInvoke` itself. When
+ * it is spent the wrapper throws, and both callers already treat a throwing
+ * llmInvoke as ordinary degradation with a stated reason. So exhaustion arrives
+ * through the same path as a rate limit or a dead endpoint, and lands in
+ * `coverage.reasons` like any other coverage gap. No new failure mode.
+ *
+ * CALLS AND WALL CLOCK, NOT TOKENS. `llmInvoke` is an injected callback that
+ * returns a string; it carries no usage metadata, so counting tokens here would
+ * mean inventing a number. Calls are exactly countable and wall clock is
+ * exactly observable. A caller who knows their per-call cost can pass
+ * `costPerCallUsd` and get a `maxCostUsd` ceiling expressed in calls, which is
+ * honest about being an estimate derived from their figure rather than ours.
+ */
+// Internal, not exported: the dead-module guard treats an export with no
+// external call site as shipped dead code, and these are read only by
+// makeBudget below. A consumer sets a ceiling by passing opts, not by importing
+// a constant.
+const DEFAULT_MAX_LLM_CALLS = 200;
+const DEFAULT_MAX_WALL_MS = 15 * 60 * 1000;
+const DEFAULT_MAX_CANDIDATES = 50;
+
+export function makeBudget(opts = {}, now = Date.now) {
+  const startedAt = now();
+  let maxCalls = Number.isInteger(opts.maxLlmCalls) && opts.maxLlmCalls >= 0
+    ? opts.maxLlmCalls : DEFAULT_MAX_LLM_CALLS;
+  // A dollar ceiling is only meaningful with a caller-supplied per-call cost.
+  // Converting it to a call count keeps one enforcement mechanism rather than
+  // two that can disagree.
+  if (Number.isFinite(opts.maxCostUsd) && Number.isFinite(opts.costPerCallUsd) && opts.costPerCallUsd > 0) {
+    maxCalls = Math.min(maxCalls, Math.floor(opts.maxCostUsd / opts.costPerCallUsd));
+  }
+  const maxWallMs = Number.isInteger(opts.maxWallMs) && opts.maxWallMs > 0
+    ? opts.maxWallMs : DEFAULT_MAX_WALL_MS;
+
+  let calls = 0;
+  let exhaustedReason = null;
+
+  const check = () => {
+    if (exhaustedReason) return exhaustedReason;
+    if (calls >= maxCalls) return (exhaustedReason = `LLM call budget spent (${calls}/${maxCalls} calls)`);
+    if (now() - startedAt >= maxWallMs) {
+      return (exhaustedReason = `wall-clock budget spent (${Math.round(maxWallMs / 1000)}s)`);
+    }
+    return null;
+  };
+
+  return {
+    get calls() { return calls; },
+    get maxCalls() { return maxCalls; },
+    get exhaustedReason() { return exhaustedReason; },
+    spent: () => check() !== null,
+    /** Wrap an llmInvoke so every call is counted and the ceiling is enforced. */
+    wrap(llmInvoke) {
+      if (typeof llmInvoke !== 'function') return llmInvoke;
+      return async (prompt) => {
+        const stop = check();
+        if (stop) throw new Error(`discovery budget exhausted: ${stop}`);
+        calls += 1;
+        return llmInvoke(prompt);
+      };
+    },
+  };
+}
+
 export async function runDiscovery(ctx = {}, opts = {}) {
   const areas = partitionCallGraph(ctx.callGraph, { maxAreas: opts.maxAreas ?? 8 });
 
   const reasons = [];
+  const budget = makeBudget(opts);
+  // PRD C4 — what previous runs already judged. scanRoot absent => no memory,
+  // which is the correct default for a library call with nowhere to persist.
+  const memory = opts.scanRoot ? loadMemory(opts.scanRoot) : null;
+  // Every LLM call in this pipeline goes through this one wrapped callback.
+  const llmInvoke = budget.wrap(opts.llmInvoke);
 
   // An explicit array (including an empty one) is honoured exactly — a caller
   // narrowing a run to no lenses must get no lenses, not a silent fallback to
@@ -87,7 +169,7 @@ export async function runDiscovery(ctx = {}, opts = {}) {
   for (const area of areas) {
     let areaDegradedCount = 0;
     for (const lens of lenses) {
-      const run = await runHunter(area, lens, { fileContents: ctx.fileContents || {} }, { llmInvoke: opts.llmInvoke });
+      const run = await runHunter(area, lens, { fileContents: ctx.fileContents || {} }, { llmInvoke });
       runs.push({ focusAreaId: run.focusAreaId, lens: run.lens, degraded: run.degraded, reason: run.reason, candidateCount: run.candidates.length });
       if (run.degraded && run.reason) reasons.push(`${area.label} × ${lens.key}: ${run.reason}`);
       if (run.degraded) areaDegradedCount += 1;
@@ -97,11 +179,69 @@ export async function runDiscovery(ctx = {}, opts = {}) {
     if (lenses.length > 0 && areaDegradedCount === 0) fullyHunted.add(area.id);
   }
 
-  const taintProbe = makeTaintProbe(ctx.perFileIR, ctx.callGraph);
+  // PRD Phase 0 / C3.2 — the candidate cap.
+  //
+  // Every candidate that reaches the panel costs three more LLM calls, so an
+  // unusually productive hunt multiplies straight into spend. Cap it, and
+  // REPORT the cap rather than applying it silently: a run that quietly
+  // examined the first N candidates and said nothing would look identical to a
+  // run that found only N. Same precedent as prove-findings.js's `capped`.
+  // PRD C4 — drop what a previous run already refuted, BEFORE spending the
+  // panel's three calls per candidate on it again. Only refutals suppress: a
+  // candidate previously judged fresh is re-reported, because it was never
+  // fixed, which is the same asymmetry judge.js applies to tp/fp triage.
+  let rememberedRefutals = 0;
+  if (memory) {
+    const before = candidates.length;
+    candidates = candidates.filter(c => !previouslyRefuted(memory, c));
+    rememberedRefutals = before - candidates.length;
+    if (rememberedRefutals > 0) {
+      reasons.push(`${rememberedRefutals} candidate(s) were refuted by an earlier run and not re-examined ` +
+        '(clear with --forget-refuted if a model, ruleset or the code has changed since)');
+    }
+  }
+
+  const maxCandidates = Number.isInteger(opts.maxCandidates) && opts.maxCandidates >= 0
+    ? opts.maxCandidates : DEFAULT_MAX_CANDIDATES;
+  let candidatesCapped = 0;
+  if (candidates.length > maxCandidates) {
+    candidatesCapped = candidates.length - maxCandidates;
+    // Deterministic: candidates arrive in a stable (area, lens) order, so the
+    // cap keeps the same prefix on every run over the same inputs.
+    candidates = candidates.slice(0, maxCandidates);
+    reasons.push(`candidate cap: ${candidatesCapped} candidate(s) were NOT confirmed or refuted ` +
+      `(cap ${maxCandidates}); they are neither findings nor cleared — they were not examined`);
+  }
+
+  // PRD D3 — the hybrid-loop uplift measurement.
+  //
+  // `confirm: false` runs the pipeline with the deterministic gate switched OFF,
+  // so every candidate reaches the panel as `unconfirmed`. Running a population
+  // both ways and diffing the result isolates what the taint engine contributes
+  // on top of the model — a number no surveyed competitor can compute, because
+  // none of them has a deterministic layer to switch off.
+  //
+  // It exists ONLY to be measured against. It is not a performance switch, and
+  // a run with it disabled is strictly weaker: severity collapses to `low` for
+  // everything, since the confirmation tier is what sets it.
+  const confirmationEnabled = opts.confirm !== false;
+  const taintProbe = confirmationEnabled ? makeTaintProbe(ctx.perFileIR, ctx.callGraph) : null;
+  if (!confirmationEnabled) {
+    reasons.push('deterministic confirmation was DISABLED for this run (uplift measurement); ' +
+      'every candidate is reported unconfirmed and severity is not evidence-derived');
+  }
   const confirmed = await confirmAll(candidates, { taintProbe });
-  const { survivors, refuted } = await disprovePanel(confirmed, { llmInvoke: opts.llmInvoke });
+  const { survivors, refuted } = await disprovePanel(confirmed, { llmInvoke });
   const { fresh, duplicates, suppressed } = judgeCandidates(survivors, ctx.priorScan, ctx.triageFeedback);
 
+  // A spent budget is a coverage gap, stated once at the top level rather than
+  // left to be inferred from N identical per-run degradation reasons.
+  if (budget.exhaustedReason) {
+    reasons.push(`RUN INCOMPLETE — ${budget.exhaustedReason}. Work remained when the budget ran ` +
+      'out, so absence of a finding below is not evidence of absence. Raise maxLlmCalls / ' +
+      'maxWallMs, or narrow the scope with --root or --lens, and re-run.');
+  }
+
   // Coverage must not stop at the hunter stage. `confirm.js` correctly never
   // lowers a candidate below `unconfirmed`, and `disprove.js` correctly lets
   // a candidate survive when no voter votes — each rule is right on its own,
@@ -124,6 +264,16 @@ export async function runDiscovery(ctx = {}, opts = {}) {
     reasons.push(`refutation panel returned no votes for any of ${panelsRun} candidate(s) — every finding below survived unrefuted, not because it withstood scrutiny`);
   }
 
+  // PRD C4 — fold this run into the memory so the next one can be additive
+  // rather than a repeat. Persistence failure is non-fatal: the report is still
+  // valid, it just will not inform the next run.
+  if (memory && opts.scanRoot) {
+    saveMemory(opts.scanRoot, rememberRun(memory, {
+      fresh, refutedCandidates: refuted,
+      areas: areas.map(a => ({ id: a.id, label: a.label, files: a.files.length, hunted: hunted.has(a.id) })),
+    }));
+  }
+
   return {
     schema: 'agentic-security/discovery@1',
     focusAreas: areas.map(a => ({ id: a.id, label: a.label, files: a.files.length, size: a.size })),
@@ -153,6 +303,28 @@ export async function runDiscovery(ctx = {}, opts = {}) {
       // of those came back with no votes at all (undecided, not refuted).
       panelsRun,
       undecidedPanels,
+      // PRD Phase 0 / C3 — what the run cost and whether the budget stopped it.
+      // `budgetExhausted` true means the report is INCOMPLETE by construction:
+      // work remained and was not done. Reading it as a clean result is the
+      // exact misreading the coverage block exists to prevent.
+      // PRD C4 — what history contributed, and what to hunt next. A coverage
+      // report says what happened; `nextWave` says what to do about it.
+      rememberedRefutals,
+      priorRuns: memory ? memory.runs : null,
+      nextWave: memory ? nextWavePlan(memory, areas.map(a => ({ id: a.id, label: a.label }))) : null,
+      llmCalls: budget.calls,
+      maxLlmCalls: budget.maxCalls,
+      // PRD N4 — the standing cost metric. C3 bounded the worst case and C4
+      // moved the typical case by 4x, so cost is a property that drifts across
+      // several workstreams rather than one that a phase finishes. A number
+      // that only appears when somebody goes looking regresses silently, so it
+      // is reported every run and carries its denominator like every other rate
+      // in this engine. `null` when nothing was found — dividing by zero
+      // findings would print Infinity and read as a catastrophe rather than as
+      // "there is nothing to divide".
+      callsPerFinding: fresh.length > 0 ? Number((budget.calls / fresh.length).toFixed(1)) : null,
+      budgetExhausted: Boolean(budget.exhaustedReason),
+      candidatesCapped,
       reasons,
     },
   };