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

package/dist/agentic-security.mjs.sha256

@@ -1 +1 @@
-a868fa3988608a5a5c0867774d870781a52d79924daf0956652c62fa1384d782  agentic-security.mjs
+c30ab141dd65e53a762c16c7683bfc3195b677107a838a83fcfae541f0fe5e0e  agentic-security.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clear-capabilities/agentic-security-scanner",
-  "version": "0.133.0",
+  "version": "0.134.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, SARIF ingest, pipeline integrity, compliance attestation, and more.",
   "type": "module",
   "main": "src/index.js",
@@ -58,17 +58,18 @@
     "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');\"",
     "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 && AGENTIC_SECURITY_CPP_DATAFLOW=1 node --test test/cpp-dataflow.test.js",
+    "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/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/attestation.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/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/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/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: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: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",
     "eval:independent:gate": "node ../bench/independent-eval/runner.mjs --gate default",
     "smoke": "node bin/agentic-security.js scan test/fixtures/vulnerable-js",
@@ -99,6 +100,9 @@
     "scorecard": "node ../scripts/scorecard.mjs",
     "corpus:enroll": "node ../scripts/enroll-proven-finding.mjs",
     "corpus:provenance": "node ../scripts/corpus-provenance-check.mjs",
+    "fleet": "node ../scripts/fleet.mjs",
+    "autopilot": "node ../scripts/autopilot.mjs",
+    "comparison": "node ../scripts/comparison.mjs",
     "determinism:attest": "node ../scripts/attest-fixture.mjs",
     "scorecard:check": "node ../scripts/scorecard-check.mjs",
     "release:check": "node ../scripts/release-check.mjs",

package/src/discovery/CLAUDE.md

@@ -0,0 +1,38 @@
+# scanner/src/discovery/
+
+LLM-driven candidate discovery, gated by the deterministic engine.
+
+User entry point: `agentic-security hunt --root <dir>` (`cmdHunt` in `bin/agentic-security.js`),
+documented in `commands/scan.md`. Advisory only — it never gates a build and its
+output does not enter `last-scan.json`.
+
+`partition.js` splits the call graph into disjoint focus areas · `lenses.js`
+holds the seven hunting lenses and the prompt builder · `hunter.js` runs one
+bounded (area × lens) pass · `confirm.js` routes each candidate back through
+the taint engine · `disprove.js` runs the three-angle majority-vote refutation
+panel · `judge.js` shapes findings and dedupes against the prior scan ·
+`llm-invoke.js` is the single injected LLM endpoint caller shared by
+`hunter.js` and `disprove.js` (no other module may talk to an LLM directly) ·
+`index.js` composes them.
+
+## Rules
+
+- **A hunter proposes; it never decides.** `confirm.js` sets a confirmation
+  tier and never filters — an `unconfirmed` candidate still proceeds, because
+  the taint engine models only a subset of the program and the absence of
+  corroboration must never be laundered into a false-positive verdict.
+  `disprove.js` is the only stage that removes a candidate: nothing reaches a
+  report without surviving refutation there.
+- **Every LLM call is an injected `llmInvoke`.** No module may import an SDK or
+  hard-code an endpoint. Absence of an LLM degrades to an empty, well-formed
+  result — it never throws and never blocks a scan.
+- **Silence never refutes.** A probe that says nothing lowers a candidate to
+  `unconfirmed`; only an argued majority refutes. A voter that errors is
+  excluded from the denominator, not counted as agreement.
+- **Severity comes from evidence, not from the model.** The confirmation tier
+  sets it: taint-confirmed → high, sink-adjacent → medium, unconfirmed → low.
+  This layer never emits `critical`.
+- **Ids are content digests.** No clock, no randomness, anywhere in an id, a
+  digest, or a sort key.
+- **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/confirm.js

@@ -0,0 +1,47 @@
+//
+// Route every model-proposed candidate back through the deterministic layer.
+//
+// WHY THIS EXISTS. A hunter's output is a hypothesis. The engine underneath it
+// can already decide, for a given file and line, whether tainted data reaches a
+// modelled sink there. Asking it turns "the model thinks so" into "the model
+// thinks so AND the taint engine agrees", which is a materially stronger claim
+// than either layer makes alone.
+//
+// THE ASYMMETRY IS DELIBERATE. Confirmation raises standing; the absence of
+// confirmation NEVER lowers it below `unconfirmed` and is never recorded as a
+// refutation. The taint engine models a subset of the program — an
+// unconfirmed candidate may be a real bug in a construct the engine does not
+// model, and calling that a false positive would launder a coverage gap into a
+// verdict. Refutation is `disprove.js`'s job, and it must be argued, not
+// inferred from silence.
+export const CONFIRMATION_TIERS = Object.freeze(['taint-confirmed', 'sink-adjacent', 'unconfirmed']);
+
+function unconfirmed(probedBy, reason) {
+  return { tier: 'unconfirmed', evidence: null, probedBy, reason: reason || null };
+}
+
+export async function confirmCandidate(candidate, opts = {}) {
+  const probe = typeof opts.taintProbe === 'function' ? opts.taintProbe : null;
+  if (!probe) return { ...candidate, confirmation: unconfirmed(null, 'no taintProbe supplied') };
+
+  let res;
+  try {
+    res = await probe(candidate);
+  } catch (err) {
+    return { ...candidate, confirmation: unconfirmed('taintProbe', `probe failed: ${err?.message || String(err)}`) };
+  }
+  if (!res) return { ...candidate, confirmation: unconfirmed('taintProbe', null) };
+  if (!CONFIRMATION_TIERS.includes(res.tier)) {
+    return { ...candidate, confirmation: unconfirmed('taintProbe', `unknown tier: ${res.tier}`) };
+  }
+  return {
+    ...candidate,
+    confirmation: { tier: res.tier, evidence: res.evidence ?? null, probedBy: 'taintProbe', reason: null },
+  };
+}
+
+export async function confirmAll(candidates, opts = {}) {
+  const out = [];
+  for (const c of candidates || []) out.push(await confirmCandidate(c, opts));
+  return out;
+}

package/src/discovery/disprove.js

@@ -0,0 +1,79 @@
+//
+// Adversarial refutation. Each voter is told to REFUTE the candidate, not to
+// assess it: a model asked "is this real?" agrees with the premise far more
+// often than one asked "show me why this cannot happen", and the second
+// question is the one that kills plausible-but-wrong findings.
+//
+// THREE ANGLES, NOT THREE COPIES. A candidate can fail in more than one way,
+// and three identical voters mostly measure sampling noise. Reachability,
+// attacker preconditions, and sanitization are the three ways these candidates
+// actually die.
+//
+// SILENCE NEVER REFUTES. A voter that errors or returns unparseable output did
+// not vote, and is excluded from the denominator rather than counted as
+// agreement. If nobody votes the panel is `undecided` and the candidate
+// SURVIVES — an outage must not quietly delete findings.
+import { resolveLlmInvoke } from './llm-invoke.js';
+
+const DEFAULT_ANGLES = ['reachability', 'preconditions', 'sanitization'];
+export const REFUTE_ANGLES = Object.freeze([...DEFAULT_ANGLES]);
+
+const ANGLE_BRIEF = {
+  reachability: 'Can attacker-controlled data actually reach this line at runtime? Name the caller chain or show there is none.',
+  preconditions: 'What must the attacker already have — a session, a role, a tenant, a race window? If the prerequisites exceed the impact, it is refuted.',
+  sanitization: 'Is the value validated, escaped, parameterised, or type-constrained anywhere on the path? A framework default counts.',
+};
+
+export function buildRefutePrompt(candidate, angle) {
+  return [
+    `Your job is to REFUTE the security finding below. Assume it is wrong and look for the reason.`,
+    `Refute it on this angle only: ${angle}. ${ANGLE_BRIEF[angle] || ''}`,
+    ``,
+    `Finding: ${candidate.title}`,
+    `Location: ${candidate.file}:${candidate.line}`,
+    `Claimed reason: ${candidate.rationale || '(none given)'}`,
+    `Deterministic confirmation: ${candidate.confirmation?.tier || 'unknown'}`,
+    ``,
+    `If you cannot refute it on this angle, say so honestly.`,
+    `Return JSON: {"refuted":true|false,"reason":"..."}`,
+  ].join('\n');
+}
+
+function parseVote(raw) {
+  if (typeof raw !== 'string') return null;
+  const s = raw.indexOf('{'), e = raw.lastIndexOf('}');
+  if (s < 0 || e <= s) return null;
+  let p;
+  try { p = JSON.parse(raw.slice(s, e + 1)); } catch { return null; }
+  if (typeof p?.refuted !== 'boolean') return null;
+  return { refuted: p.refuted, reason: typeof p.reason === 'string' ? p.reason : '' };
+}
+
+export async function disproveCandidate(candidate, opts = {}) {
+  const angles = Array.isArray(opts.angles) && opts.angles.length ? opts.angles : DEFAULT_ANGLES;
+  const llmInvoke = resolveLlmInvoke(opts);
+
+  const votes = [];
+  if (typeof llmInvoke === 'function') {
+    for (const angle of angles) {
+      let vote = null;
+      try { vote = parseVote(await llmInvoke(buildRefutePrompt(candidate, angle))); } catch { vote = null; }
+      if (vote) votes.push({ angle, ...vote });
+    }
+  }
+
+  const voterCount = votes.length;
+  const refuteCount = votes.filter(v => v.refuted).length;
+  const undecided = voterCount === 0;
+  const refuted = !undecided && refuteCount * 2 > voterCount;
+  return { ...candidate, refutation: { votes, voterCount, refuteCount, refuted, undecided } };
+}
+
+export async function disprovePanel(candidates, opts = {}) {
+  const survivors = [], refuted = [];
+  for (const c of candidates || []) {
+    const judged = await disproveCandidate(c, opts);
+    (judged.refutation.refuted ? refuted : survivors).push(judged);
+  }
+  return { survivors, refuted };
+}

package/src/discovery/hunter.js

@@ -0,0 +1,116 @@
+//
+// One bounded hunter run = one focus area seen through one lens.
+//
+// A hunter PROPOSES. Nothing here is a finding: every candidate must survive
+// `confirm.js` and `disprove.js` first. That separation is the whole design —
+// the model is allowed to be imaginative precisely because something
+// deterministic checks it afterwards.
+//
+// FAILURE IS ALWAYS DEGRADATION, NEVER AN EXCEPTION. A missing endpoint, a
+// rate limit, or unparseable output yields `degraded:true` with a reason. A
+// discovery pass that cannot run must leave the rest of the scan intact.
+import * as crypto from 'node:crypto';
+import { buildHunterPrompt } from './lenses.js';
+import { resolveLlmInvoke } from './llm-invoke.js';
+
+function appendEntry(transcript, entry) {
+  const prev = transcript.length ? transcript[transcript.length - 1].hash : null;
+  // Named `serialized`, not `body`: this is the canonical serialisation of a
+  // transcript entry being fed to a hash, and calling it `body` made the
+  // mass-assignment detector read it as a request payload. The name was simply
+  // wrong for what it holds, so this is a fix at the source rather than a
+  // suppression — and that detector's finding carries no line number, so a
+  // line-scoped ignore pragma could not have matched it anyway.
+  const serialized = JSON.stringify({ ...entry, prev });
+  const hash = crypto.createHash('sha256').update(serialized).digest('hex');
+  transcript.push({ ...entry, prev, hash });
+  return transcript;
+}
+
+function extractJsonWithFlag(raw) {
+  if (typeof raw !== 'string') return { parsed: null, found: false };
+  const start = raw.indexOf('{');
+  const end = raw.lastIndexOf('}');
+  if (start < 0 || end <= start) return { parsed: null, found: false };
+  try { return { parsed: JSON.parse(raw.slice(start, end + 1)), found: true }; } catch { return { parsed: null, found: false }; }
+}
+
+function candidateId(focusAreaId, lensKey, file, line, title) {
+  return crypto.createHash('sha256')
+    .update(`${focusAreaId}|${lensKey}|${file}|${line}|${title}`)
+    .digest('hex').slice(0, 12);
+}
+
+function candidatesFromParsed(parsed, focusArea, lens) {
+  const list = Array.isArray(parsed?.candidates) ? parsed.candidates : [];
+  const out = [];
+  for (const c of list) {
+    const file = typeof c?.file === 'string' ? c.file : null;
+    const line = Number.isInteger(c?.line) ? c.line : Number.parseInt(c?.line, 10);
+    if (!file || !Number.isInteger(line)) continue;      // no location, no candidate
+    const title = typeof c?.title === 'string' && c.title ? c.title : `${lens.title} candidate`;
+    out.push({
+      id: candidateId(focusArea.id, lens.key, file, line, title),
+      focusAreaId: focusArea.id,
+      lens: lens.key,
+      title,
+      file,
+      line,
+      family: lens.family,
+      cwe: lens.cwe,
+      rationale: typeof c?.rationale === 'string' ? c.rationale : '',
+      entryPoint: typeof c?.entryPoint === 'string' ? c.entryPoint : '',
+      sink: typeof c?.sink === 'string' ? c.sink : '',
+    });
+  }
+  return out;
+}
+
+export function parseCandidates(raw, focusArea, lens) {
+  const { parsed } = extractJsonWithFlag(raw);
+  return candidatesFromParsed(parsed, focusArea, lens);
+}
+
+export async function runHunter(focusArea, lens, ctx = {}, opts = {}) {
+  const transcript = [];
+  const lensKey = lens?.key || 'unknown';
+  const base = { focusAreaId: focusArea.id, lens: lensKey, transcript };
+  const llmInvoke = resolveLlmInvoke(opts);
+
+  if (typeof llmInvoke !== 'function') {
+    const reason = 'no llmInvoke supplied and AGENTIC_SECURITY_LLM_ENDPOINT not set';
+    appendEntry(transcript, { phase: 'init', reason });
+    return { ...base, candidates: [], degraded: true, reason };
+  }
+
+  let prompt;
+  try {
+    prompt = buildHunterPrompt(focusArea, lens, ctx);
+  } catch (err) {
+    const reason = `failed to build hunter prompt: ${err?.message || String(err)}`;
+    appendEntry(transcript, { phase: 'prompt_error', reason });
+    return { ...base, candidates: [], degraded: true, reason };
+  }
+
+  appendEntry(transcript, { phase: 'prompt', promptChars: prompt.length, files: focusArea.files.length });
+
+  let raw;
+  try {
+    raw = await llmInvoke(prompt);
+  } catch (err) {
+    const reason = `hunter llm call failed: ${err?.message || String(err)}`;
+    appendEntry(transcript, { phase: 'error', reason });
+    return { ...base, candidates: [], degraded: true, reason };
+  }
+
+  const { parsed, found } = extractJsonWithFlag(raw);
+  if (!found) {
+    const reason = 'hunter output was not parseable JSON';
+    appendEntry(transcript, { phase: 'parse_error', reason });
+    return { ...base, candidates: [], degraded: true, reason };
+  }
+
+  const candidates = candidatesFromParsed(parsed, focusArea, lens);
+  appendEntry(transcript, { phase: 'result', candidateCount: candidates.length });
+  return { ...base, candidates, degraded: false, reason: null };
+}

package/src/discovery/index.js

@@ -0,0 +1,159 @@
+//
+// Compose the discovery pipeline:
+//
+//   partition → (area × lens) hunters → confirm → disprove → judge
+//
+// COVERAGE IS PART OF THE OUTPUT. Every report states how many areas were
+// planned versus hunted and how many runs degraded, with reasons. A discovery
+// pass that half failed and reports "no findings" is indistinguishable from a
+// clean codebase unless it says so.
+import { partitionCallGraph } from './partition.js';
+import { LENSES, lensByKey } from './lenses.js';
+import { runHunter } from './hunter.js';
+import { confirmAll } from './confirm.js';
+import { disprovePanel } from './disprove.js';
+import { judgeCandidates } from './judge.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
+// without a full path is weaker corroboration ("sink-adjacent").
+//
+// NOTE: `runDeepAnalysis(perFileIR, callGraph, opts)` returns a BARE ARRAY of
+// findings (see scanner/src/dataflow/index.js), not an object with a
+// `.findings` property. Treat anything else defensively.
+export function makeTaintProbe(perFileIR, callGraph) {
+  let cache = null;
+  return async (candidate) => {
+    if (!callGraph || !perFileIR) return null;
+    try {
+      if (!cache) cache = runDeepAnalysisSafe(perFileIR, callGraph);
+      const deep = await cache;
+      if (!Array.isArray(deep)) return null;
+      const hits = deep.filter(f => f.file === candidate.file);
+      const exact = hits.find(f => Math.abs((f.line ?? -1) - candidate.line) <= 2);
+      if (exact) {
+        return { tier: 'taint-confirmed', evidence: { matchedFinding: exact.id ?? null, line: exact.line, vuln: exact.vuln ?? null } };
+      }
+      return hits.length ? { tier: 'sink-adjacent', evidence: { sameFileFindings: hits.length } } : null;
+    } catch {
+      return null;
+    }
+  };
+}
+
+async function runDeepAnalysisSafe(perFileIR, callGraph) {
+  try {
+    const { runDeepAnalysis } = await import('../dataflow/index.js');
+    return runDeepAnalysis(perFileIR, callGraph, {});
+  } catch {
+    return null;
+  }
+}
+
+// ctx = { perFileIR, callGraph, fileContents, priorScan, triageFeedback }
+// where { perFileIR, callGraph } come from buildProjectIR(fileContents),
+// which returns { perFile, callGraph } — callers must pass perFile as
+// perFileIR (see scanner/src/ir/index.js).
+export async function runDiscovery(ctx = {}, opts = {}) {
+  const areas = partitionCallGraph(ctx.callGraph, { maxAreas: opts.maxAreas ?? 8 });
+
+  const reasons = [];
+
+  // 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
+  // all seven. Only an absent/non-array value falls back to the full set.
+  const lensKeys = Array.isArray(opts.lenses) ? opts.lenses : LENSES.map(l => l.key);
+
+  const lenses = [];
+  for (const key of lensKeys) {
+    const lens = lensByKey(key);
+    // An unknown key must degrade visibly, not vanish via a silent filter.
+    if (lens) lenses.push(lens);
+    else reasons.push(`unresolved lens key: "${key}"`);
+  }
+  if (lenses.length === 0) {
+    reasons.push('no lenses resolved for this run (empty or fully-unresolved lens selection); nothing was hunted');
+  }
+
+  const runs = [];
+  let candidates = [];
+  // areasHunted: areas where AT LEAST ONE lens run completed without degrading.
+  const hunted = new Set();
+  // areasFullyHunted: areas where EVERY lens run completed without degrading.
+  // Distinct from areasHunted so a partially-degraded area (e.g. 6 of 7 lenses
+  // failed) cannot be read as fully covered from a single number.
+  const fullyHunted = new Set();
+
+  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 });
+      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;
+      else hunted.add(area.id);
+      candidates = candidates.concat(run.candidates);
+    }
+    if (lenses.length > 0 && areaDegradedCount === 0) fullyHunted.add(area.id);
+  }
+
+  const taintProbe = makeTaintProbe(ctx.perFileIR, ctx.callGraph);
+  const confirmed = await confirmAll(candidates, { taintProbe });
+  const { survivors, refuted } = await disprovePanel(confirmed, { llmInvoke: opts.llmInvoke });
+  const { fresh, duplicates, suppressed } = judgeCandidates(survivors, ctx.priorScan, ctx.triageFeedback);
+
+  // 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,
+  // but composed, a run where BOTH later stages died silently would still
+  // report clean hunter coverage while 100% of raw, uncorroborated model
+  // output landed in `fresh`. These counters and reasons make that visible.
+  const confirmedByTier = { 'taint-confirmed': 0, 'sink-adjacent': 0, 'unconfirmed': 0 };
+  for (const c of confirmed) {
+    const tier = c?.confirmation?.tier;
+    if (tier && Object.prototype.hasOwnProperty.call(confirmedByTier, tier)) confirmedByTier[tier] += 1;
+  }
+  if (confirmed.length > 0 && confirmedByTier['taint-confirmed'] === 0 && confirmedByTier['sink-adjacent'] === 0) {
+    reasons.push(`confirmation stage corroborated nothing for ${confirmed.length} candidate(s) — all remain "unconfirmed"; the deterministic gate may not have run, and the findings below are uncorroborated, not vetted`);
+  }
+
+  const panelled = [...survivors, ...refuted];
+  const panelsRun = panelled.length;
+  const undecidedPanels = panelled.filter(c => c?.refutation?.undecided === true).length;
+  if (panelsRun > 0 && undecidedPanels === panelsRun) {
+    reasons.push(`refutation panel returned no votes for any of ${panelsRun} candidate(s) — every finding below survived unrefuted, not because it withstood scrutiny`);
+  }
+
+  return {
+    schema: 'agentic-security/discovery@1',
+    focusAreas: areas.map(a => ({ id: a.id, label: a.label, files: a.files.length, size: a.size })),
+    runs,
+    fresh,
+    duplicates,
+    suppressed,
+    // `refutedCandidates` holds RAW candidates straight from `disprovePanel`,
+    // NOT findings — no `vuln`, `severity`, `parser`, or `stableId`. It is
+    // deliberately not run through `toFindingShape`: a refuted candidate is
+    // deliberately not promoted to a finding, and giving it finding shape
+    // would misrepresent it as one. Unlike `fresh`/`duplicates`/`suppressed`,
+    // do not iterate this array as if it were finding-shaped.
+    refutedCandidates: refuted,
+    coverage: {
+      areasPlanned: areas.length,
+      // At least one lens run completed for the area. Does NOT mean every
+      // lens succeeded there — see areasFullyHunted for that stronger claim.
+      areasHunted: hunted.size,
+      // Every lens run for the area completed without degrading.
+      areasFullyHunted: fullyHunted.size,
+      lensesPerArea: lenses.length,
+      degradedRuns: runs.filter(r => r.degraded).length,
+      // Per-tier count of every candidate that went through confirm.js.
+      confirmedByTier,
+      // How many candidates went through the refutation panel, and how many
+      // of those came back with no votes at all (undecided, not refuted).
+      panelsRun,
+      undecidedPanels,
+      reasons,
+    },
+  };
+}

package/src/discovery/judge.js

@@ -0,0 +1,97 @@
+//
+// Turn surviving candidates into findings, then decide which are actually new.
+//
+// SEVERITY IS DRIVEN BY EVIDENCE, NOT BY THE MODEL'S ADJECTIVES. A hunter has
+// no calibrated view of impact and will call everything critical. What we can
+// defend is how well-evidenced the candidate is, so the confirmation tier sets
+// the ceiling: taint-confirmed → high, sink-adjacent → medium, unconfirmed →
+// low. A human or the existing triage path can raise it; the discovery layer
+// never claims critical on its own.
+//
+// A PRIOR TRUE POSITIVE IS NOT A DUPLICATE. Triage feedback suppresses only
+// `fp` verdicts. A `tp` verdict means the finding was real, and re-reporting it
+// while it is still in the code is correct behaviour.
+//
+// STABLE IDS ARE LOCATION-FUZZY BY DESIGN, AND THAT MATTERS HERE. `stable-id.js`
+// hashes ruleId, snippet, path shape, and BASENAME — deliberately not the line,
+// so an id survives code moving down a file. The consequence for this layer:
+// two different candidates of the same lens in the same file collide on one
+// stableId. That is why file+line+family is the PRIMARY duplicate key and the
+// stableId check is only a secondary net. It also means an `fp` verdict
+// suppresses the whole (lens, file) pair rather than one line — the same
+// breadth the rest of the engine already has, kept rather than silently
+// diverged from. `ruleId` is set explicitly so ids partition by lens rather
+// than falling back to the CWE.
+import { computeStableId } from '../posture/stable-id.js';
+
+const SEVERITY_BY_TIER = { 'taint-confirmed': 'high', 'sink-adjacent': 'medium', 'unconfirmed': 'low' };
+
+// Guards against a malformed candidate producing a schema-invalid finding
+// (root CLAUDE.md requires { id, severity, file, line, vuln, cwe, ... } on
+// every finding). `hunter.js` already filters out candidates with no usable
+// file/line before they reach here, so this should never trigger in the
+// normal pipeline — but toFindingShape is exported and callable directly, and
+// degrading with `null` (rather than throwing) matches this subsystem's
+// degrade-don't-throw style everywhere else. Callers must skip a `null`.
+export function toFindingShape(candidate) {
+  const file = typeof candidate?.file === 'string' && candidate.file ? candidate.file : null;
+  const line = Number.isInteger(candidate?.line) ? candidate.line : null;
+  if (!file || line === null) return null;
+
+  const tier = candidate?.confirmation?.tier || 'unconfirmed';
+  const lensTitle = candidate?.lens ? `${candidate.lens} candidate` : 'discovery candidate';
+  const title = typeof candidate?.title === 'string' && candidate.title ? candidate.title : lensTitle;
+  const base = {
+    id: `discovery-${candidate.lens}-${candidate.id}`,
+    severity: SEVERITY_BY_TIER[tier] || 'low',
+    file,
+    line,
+    vuln: title,
+    cwe: candidate.cwe || 'CWE-710',
+    description: candidate.rationale
+      ? `${candidate.rationale} (entry point: ${candidate.entryPoint || 'unstated'}; sink: ${candidate.sink || 'unstated'})`
+      : `Proposed by the ${candidate.lens} lens; no rationale supplied.`,
+    remediation: `Review ${candidate.file}:${candidate.line}. Confirm whether ${candidate.entryPoint || 'attacker-controlled input'} can reach ${candidate.sink || 'this operation'}, and constrain it at the boundary if so.`,
+    parser: 'DISCOVERY',
+    family: candidate.family || 'other',
+    ruleId: `discovery:${candidate.lens}`,
+    // snippet discriminates findings so computeStableId has material to hash. An empty
+    // snippet collapses distinct findings of the same lens in the same file onto one id.
+    snippet: candidate.sink || candidate.entryPoint || candidate.title || '',
+  };
+  return {
+    ...base,
+    stableId: computeStableId(base),
+    discovery: {
+      lens: candidate.lens,
+      focusAreaId: candidate.focusAreaId,
+      confirmation: candidate.confirmation || null,
+      refutation: candidate.refutation || null,
+    },
+  };
+}
+
+export function judgeCandidates(candidates, priorScan, triageFeedback) {
+  const prior = Array.isArray(priorScan?.findings) ? priorScan.findings : [];
+  const priorByLoc = new Map();
+  const priorIds = new Set();
+  for (const p of prior) {
+    if (p?.stableId) priorIds.add(p.stableId);
+    priorByLoc.set(`${p?.file}|${p?.line}|${p?.family}`, p?.stableId || null);
+  }
+  const feedback = triageFeedback && typeof triageFeedback === 'object' ? triageFeedback : {};
+
+  const fresh = [], duplicates = [], suppressed = [];
+  for (const c of candidates || []) {
+    const f = toFindingShape(c);
+    if (!f) continue; // malformed candidate (no usable file/line) — degrade by skipping, never throw
+    if (feedback[f.stableId] === 'fp') { suppressed.push({ ...f, suppressedBy: 'triage-fp' }); continue; }
+    const locKey = `${f.file}|${f.line}|${f.family}`;
+    // Location key is PRIMARY: same file, line, and family match existing findings.
+    if (priorByLoc.has(locKey)) { duplicates.push({ ...f, duplicateOf: priorByLoc.get(locKey) }); continue; }
+    // stableId is SECONDARY: same lens, file, and sink at a moved line is likely the same bug.
+    if (priorIds.has(f.stableId)) { duplicates.push({ ...f, duplicateOf: f.stableId }); continue; }
+    fresh.push(f);
+  }
+  return { fresh, duplicates, suppressed };
+}