@clear-capabilities/agentic-security-scanner 0.175.0 → 0.177.0

package/src/mcp/proof-tools.js

@@ -0,0 +1,132 @@
+// proof-tools.js: the MCP surface for execution-backed exploit proof (PRD 1).
+//
+// Two tools, both of which RUN CODE in the proof fabric's confined environment, so both are classified `mutating` and both require
+// `confirm: true`:
+//   prove_finding   execute a reproducer (supplied, stored, or generated from the finding) and report the evidence state
+//   prove_fix       overlay a patch on a COPY of the sources, replay the original exploit against it, run the static verification,
+//                   and search for sibling exposures; the patch is never written to the project
+//
+// Guarantees, each with a test:
+//   - nothing runs without `confirm: true`, without a verified (HMAC-checked) last scan, or for a shadow finding;
+//   - a reproducer an agent supplies is validated as untrusted input (closed schema, argv only, bounded files, safe paths) before
+//     it reaches the runner, and it runs under the same sandbox, limits, network policy and 3-of-3 plus independent replay as any other;
+//   - patch paths are confined to the session root and the reserved write paths are refused, though nothing is written;
+//   - the result carries evidence STATE and counts, never the target's output, and is scrubbed before it is returned;
+//   - a model decides nothing: the oracle does.
+// The factory shape (rather than importing helpers from tools.js) avoids a cycle between this file and the registry.
+import { proveFinding } from '../posture/proof-fabric/orchestrator.js';
+import { verifyFixWithProof, formatFixProof } from '../posture/proof-fabric/fix-proof.js';
+import { resolveReproducer } from '../posture/proof-fabric/cli.js';
+import { saveProof, scrubDeep } from '../posture/proof-fabric/store.js';
+import { validateReproducer } from '../posture/proof-fabric/reproducer.js';
+import { findSiblings } from '../posture/proof-fabric/siblings.js';
+import { verifyFix } from '../posture/fix-verify.js';
+
+const MAX_RESPONSE_BYTES = 200_000;
+
+export function makeProofTools({ confine, META, readLastScanVerified, findById, isReservedWritePath, redactString }) {
+  const refuse = (reason, extra = {}) => ({ _meta: META, ok: false, reason, ...extra });
+
+  async function load(args, ctx) {
+    if (args.confirm !== true) return { error: refuse('this tool executes code in the proof environment and requires confirm: true.') };
+    const { scan, status } = readLastScanVerified(ctx.sessionRoot, { allowUnsigned: false });
+    if (!scan) return { error: refuse(`last-scan.json failed integrity check: ${status}. Run a fresh scan.`) };
+    const finding = findById(scan, args.finding_id);
+    if (!finding) return { error: refuse(`Finding not found: ${args.finding_id}`) };
+    if (finding._shadow === true) return { error: refuse('shadow findings cannot be proven') };
+    let reproducer = null; let generated = null;
+    if (args.reproducer) {
+      const errs = validateReproducer(args.reproducer);
+      if (errs.length) return { error: refuse(`the reproducer is not acceptable: ${errs.slice(0, 5).join('; ')}`) };
+      reproducer = args.reproducer;
+    } else {
+      const r = resolveReproducer(ctx.sessionRoot, finding, null);
+      if (!r.reproducer) return { error: refuse(`no reproducer was supplied or stored, and none could be generated: ${r.reason}`) };
+      reproducer = r.reproducer; generated = r.generated;
+    }
+    return { scan, finding, reproducer, generated };
+  }
+
+  const finish = (obj) => {
+    const safe = scrubDeep(obj);
+    const text = redactString(JSON.stringify(safe));
+    if (text.length > MAX_RESPONSE_BYTES) return refuse('the result is too large for one response');
+    return { _meta: META, ...JSON.parse(text) };
+  };
+
+  const prove_finding = {
+    name: 'prove_finding',
+    description: 'Execute a reproducer for a finding in the confined proof environment and report its evidence state (CANDIDATE ... EXPLOIT_CONFIRMED). The reproducer is supplied, stored, or generated from the finding; EXPLOIT_CONFIRMED needs 3 of 3 reproductions and an independent replay, decided by a deterministic oracle, never by a model. Runs code: requires confirm: true. Returns state and counts, never the target\'s output.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        finding_id: { type: 'string', minLength: 1, maxLength: 256 },
+        confirm: { type: 'boolean' },
+        reproducer: { type: 'object' },
+        attempts: { type: 'integer', minimum: 1, maximum: 10 },
+        required: { type: 'integer', minimum: 1, maximum: 10 },
+        require_container: { type: 'boolean' },
+      },
+      required: ['finding_id', 'confirm'],
+    },
+    async handler(args, ctx) {
+      const l = await load(args, ctx);
+      if (l.error) return l.error;
+      const policy = {};
+      if (args.attempts) policy.attempts = args.attempts;
+      if (args.required) policy.required = Math.min(args.required, args.attempts ?? 10);
+      if (args.require_container) policy.requireContainer = true;
+      let result;
+      try { result = await proveFinding({ finding: l.finding, reproducer: l.reproducer, policy, sourceRoot: ctx.sessionRoot }); } catch (e) { return refuse(`the proof could not run: ${String(e.message).slice(0, 200)}`); }
+      const saved = saveProof(ctx.sessionRoot, { ...result, reproducer: l.reproducer, ...(l.generated ? { generatedFrom: l.generated } : {}) });
+      return finish({
+        ok: true, findingId: result.findingId, state: result.state, outcome: result.outcome, oracle: result.oracle, completeness: result.completeness,
+        attempts: result.attempts, independentReplay: result.independentReplay?.status ?? 'not-run', environment: result.environment ? { mode: result.environment.mode, assurance: result.environment.assurance } : null,
+        degradation: result.degradation, durationMs: result.timing?.proofMs ?? null, generated: l.generated, stored: saved.ok,
+        note: 'Not reproduced is not proof of safety.',
+      });
+    },
+  };
+
+  const prove_fix = {
+    name: 'prove_fix',
+    description: 'Check a proposed patch against the original exploit: confirm the exploit before the patch, overlay the patch on a COPY of the sources, replay the exploit, run the static verification, and search for sibling exposures. Reports FIX_VERIFIED only when the exploit is blocked in every replay and nothing was skipped. Nothing is written to the project. Runs code (and the project tests): requires confirm: true.',
+    inputSchema: {
+      type: 'object',
+      additionalProperties: false,
+      properties: {
+        finding_id: { type: 'string', minLength: 1, maxLength: 256 },
+        confirm: { type: 'boolean' },
+        patch: { type: 'object', additionalProperties: { type: 'string', maxLength: 500_000 }, minProperties: 1, maxProperties: 8 },
+        reproducer: { type: 'object' },
+      },
+      required: ['finding_id', 'confirm', 'patch'],
+    },
+    async handler(args, ctx) {
+      const l = await load(args, ctx);
+      if (l.error) return l.error;
+      const files = {};
+      for (const [rel, content] of Object.entries(args.patch)) {
+        let abs;
+        try { abs = confine(ctx.sessionRoot, rel, 'patch key'); } catch (e) { return refuse(`path-escape refused: ${String(e.message).replace(ctx.sessionRoot, '<root>')}`); }
+        if (isReservedWritePath(ctx.sessionRoot, abs)) return refuse(`reserved path refused: ${rel}`);
+        files[rel] = String(content);
+      }
+      let staticVerification = null;
+      try { staticVerification = l.finding.stableId ? await verifyFix({ scanRoot: ctx.sessionRoot, originalFindingStableId: l.finding.stableId, files, recordMetrics: false }) : null; } catch { staticVerification = null; }
+      const sib = findSiblings({ root: ctx.sessionRoot, finding: l.finding, scanFindings: l.scan.findings || [] });
+      let fp;
+      try {
+        fp = await verifyFixWithProof({ finding: l.finding, reproducer: l.reproducer, files, scanRoot: ctx.sessionRoot, staticVerification, siblings: sib.siblings.map((x) => ({ file: x.file, line: x.line, source: x.source })), siblingSearchTruncated: sib.truncated });
+      } catch (e) { return refuse(`the fix proof could not run: ${String(e.message).slice(0, 200)}`); }
+      return finish({
+        ok: true, findingId: fp.findingId, state: fp.state, verified: fp.verified, completeness: fp.completeness, degradedLegs: fp.degradedLegs ?? [], legs: fp.legs,
+        reason: fp.reason ?? null, incompleteStep: fp.incompleteStep ?? null, siblings: sib.siblings.slice(0, 20), siblingSearchTruncated: sib.truncated, report: formatFixProof(fp), generated: l.generated,
+        note: 'The patch was not written. Apply it with apply_fix once it is verified.',
+      });
+    },
+  };
+
+  return { prove_finding, prove_fix };
+}

package/src/mcp/server.js

@@ -45,7 +45,7 @@ const TOOLS_BY_NAME = Object.fromEntries(ALL_TOOLS.map(t => [t.name, t]));
 function _codeFingerprint() {
   try {
     const here = path.dirname(fileURLToPath(import.meta.url));
-    const files = ['server.js', 'tools.js', 'dataflow-tools.js', 'invariant-tools.js', 'portfolio-tools.js', 'stdio.js', 'audit.js', 'validate.js', 'redact.js'];
+    const files = ['server.js', 'tools.js', 'dataflow-tools.js', 'invariant-tools.js', 'portfolio-tools.js', 'proof-tools.js', 'stdio.js', 'audit.js', 'validate.js', 'redact.js'];
     const h = crypto.createHash('sha256');
     for (const f of files) {
       try { h.update(f); h.update(fs.readFileSync(path.join(here, f))); } catch {}

package/src/mcp/tools.js

@@ -37,6 +37,7 @@ import { redactFindingProvenance } from '../posture/provenance/schema.js';
 import { dataflow_get_graph, dataflow_get_node, dataflow_get_edge, dataflow_get_flow } from './dataflow-tools.js';
 import { makeInvariantTools } from './invariant-tools.js';
 import { makePortfolioTools } from './portfolio-tools.js';
+import { makeProofTools } from './proof-tools.js';
 
 // Lazy-loaded: these transitively pull in npm packages (@babel/core and
 // friends) that aren't available in the plugin-cache install path
@@ -1701,6 +1702,7 @@ export const apply_sca_upgrade = {
 // X-407: read-only scenario export; the factory takes this file's confinement so the two modules do not import each other.
 const { invariant_scenario_export } = makeInvariantTools({ confine: _confine, META });
 // X-707: read-only portfolio progress view, same factory shape.
+const { prove_finding, prove_fix } = makeProofTools({ confine: _confine, META, readLastScanVerified: _readLastScanVerified, findById: _findById, isReservedWritePath: _isReservedWritePath, redactString });
 const { portfolio_progress } = makePortfolioTools({ confine: _confine, META });
 
-export const ALL_TOOLS = [scan_diff, query_taint, explain_finding, apply_fix, verify_fix, synthesize_fix, find_rule_module, append_scratchpad, read_scratchpad, append_agents_memory, read_agents_memory, lookup_cve, synthesize_sca_upgrade, apply_sca_upgrade, query_triage_memory, query_findings_memory, query_cache_telemetry, dataflow_get_graph, dataflow_get_node, dataflow_get_edge, dataflow_get_flow, invariant_scenario_export, portfolio_progress];
+export const ALL_TOOLS = [scan_diff, query_taint, explain_finding, apply_fix, verify_fix, synthesize_fix, find_rule_module, append_scratchpad, read_scratchpad, append_agents_memory, read_agents_memory, lookup_cve, synthesize_sca_upgrade, apply_sca_upgrade, query_triage_memory, query_findings_memory, query_cache_telemetry, dataflow_get_graph, dataflow_get_node, dataflow_get_edge, dataflow_get_flow, invariant_scenario_export, portfolio_progress, prove_finding, prove_fix];

package/src/posture/CLAUDE.md

@@ -996,6 +996,29 @@ reading the cache; it does not defeat root or the same OS user. See
 `cache.js`'s own header for the full tradeoff writeup, including why
 encryption-at-rest was considered and deferred.
 
+## Detection and response: `dnr/` (PRD 7)
+
+Turns a PROVEN finding into a validated detection, hunts local historical logs for the exploit's shape, scopes the observable exposure window, and shows Find, Prove, Hunt, Fix, Verify and Detect for one finding. Entry point `dnr/cli.js` (`cmdDnr`); guide `docs/guides/detection-and-response.md`; tests `test/dnr/`, `test/cli/dnr-cli.test.js`.
+
+* **No network, no model.** Nothing in `dnr/` imports an HTTP module or the LLM/egress layers (a test pins it). Production logs stay on the machine, so the model-egress policy has nothing to gate here. Do not add a model call to "improve" a detection: the point is that every fact has a source.
+* **The IR is closed-world** (`detection-ir.js`, `attack-facts.js`). There is no field for an attacker address, domain, file hash or user agent, and `validateDetectionIR` refuses unknown keys. Request facts come from the optional `attack` block on the reproducer, which the proof runner never reads. A missing fact is `null` plus a stated limitation, never a guess.
+* **One evaluator** (`matchers.js` `evaluateEvent`) serves validation, hunting and the descriptions of the rendered rules. A rule that validates is the rule that searches. Keep it that way: a second matcher would let a tested rule and a shipped rule drift apart.
+* **A negative needs evidence** (`hunt.js`). `NOT_OBSERVED` is returned only when the logs parsed cleanly, carried every field the detection needs, were read to the end, and had timestamps. Anything less is `INCONCLUSIVE`. `notExploitedClaim` is always `false`. The exit code per verdict differs so automation cannot read an unanswered question as clean.
+* **Bounded reads** (`log-reader.js`): file count, depth, file size, total size, line length, line count, wall clock, abort signal; symlinks and compressed files are skipped and reported. Every limit hit is disclosed and blocks a `NOT_OBSERVED`.
+* **Redaction before persistence or display** (`redact.js`), on top of the proof store's secret scrubber. Records live under `.agentic-security/dnr/` (registered in `artifact-registry.js`, evidence class, encrypted by policy, tamper-evident).
+* **Names:** a detection is not a finding rule. `rule-compiler/` promotes DETECTION rules for the scanner; `dnr/` produces RESPONSE rules for a SIEM, a WAF or a log search. Do not merge them.
+
+## Eval Lab and the policy router: `evaluation/lab/`, `routing/policy-router.js` (PRD 6)
+
+Measures a deterministic baseline and model arms, and routes tasks from the measurements. Entry points `evaluation/lab/cli.js` (`cmdEval`, `cmdModelsLab`) and `routing/policy-router.js`; guide `docs/guides/eval-lab.md`; tests `test/eval-lab/`, `test/cli/eval-lab-cli.test.js`.
+
+* **Lives inside `evaluation/` on purpose.** It reuses the custody audit (`auditWorkspace`, `protectedTermsFrom`, `guardPrompt`) and `defaultScanFn`. The isolation test keeps the custody, label, runner, score, gates and protocol modules unreachable from outside `evaluation/`, so the lab's CLI is the only door and it imports nothing the engine imports back. Do not move the lab out to "tidy" it.
+* **Mechanical evidence decides.** The lab never believes an arm's claim that a PoC works or a patch holds: it executes the reproducer (`proveFinding`) and replays the exploit against the patch (`verifyFixWithProof`). An attempt that does not complete is recorded and scored as a no-result (a miss for a positive, `unscored` for a negative), never dropped.
+* **Labels never reach an arm.** Labels live only in the manifest; workspaces are staged under neutral names, neutralized (`neutralize.js`) and audited, and every request is guarded. A hit quarantines the entry and marks the run incomplete. Dataset `leakagePolicy.mode` accepts only `enforce`.
+* **No provider client.** Models attach through the `command` adapter (request in a file, answer on stdout, scrubbed env, timeout, whole-tree cleanup). A non-local arm is checked against `evaluateEgress` before it runs and there is no fallback between arms. Do not add a direct HTTP client here.
+* **The router is the policy layer, `routing/decide.js` is the calibrated one.** `policy-router.js` selects from measured scoreboard entries (quality, median cost, median latency, run count) under four policies; `decide.js` keeps quality LOWER bounds on held-out outcomes per stratum. They do not call each other. The router refuses to guess: too few runs, unknown cost under a cost policy, an egress denial or a dataset mismatch excludes a model with the reason, and `threat-model` is blocked because it has no evaluation task.
+* **Digest-checked state.** Runs and the scoreboard live under `.agentic-security/eval-lab/` (registered in `artifact-registry.js`); a record that no longer matches its digest is reported and never used for routing.
+
 ## Gotchas
 
 - The seed `calibration-seed.json` is small (n < 30 for several families). Don't treat it as a held-out set — that's `holdout-eval.js`'s job, against an externally-supplied JSONL.

package/src/posture/artifact-registry.js

@@ -133,6 +133,7 @@ export const ARTIFACT_REGISTRY = [
   { name: 'proofs', kind: 'dir', classification: 'generated', retentionClass: 'evidence', confidential: true, source: 'src/posture/proof-fabric/store.js (saveProof)', note: 'Universal Exploit Proof Fabric evidence: hashed records of exploit reproductions. Never holds plaintext credentials, per-run nonces or raw secrets (the runner redacts before persisting). Encrypted per the encryption policy via maybeEncryptForWrite, and purged by retention like any evidence-class artifact; a legal hold on `proofs` blocks the purge.' },
   { name: 'fleet-state.json', kind: 'file', classification: 'generated', retentionClass: 'scan', source: 'src/posture/fleet/cli.js, src/posture/fleet.js (loadFleetState/_saveFleetState)', note: 'Per-repository resume checkpoint for `fleet scan` — which fleet repositories are already complete, so a resumed run skips them. Scanner-managed; a plain reset may delete it.' },
   { name: 'fleet-rollup.json', kind: 'file', classification: 'generated', retentionClass: 'scan', source: 'src/posture/fleet/cli.js', note: 'The last fleet rollup (rollupFleet output), kept only so the NEXT `fleet scan` can compute a delta against it and so `fleet status` has something to read without re-scanning.' },
+  { name: 'fleet', kind: 'dir', classification: 'generated', retentionClass: 'scan', source: 'src/posture/fleet/cli.js, src/posture/fleet/job-store.js, src/posture/fleet/job-runner.js, src/posture/fleet/scan-cache.js', note: 'Distributed scan fabric state: the SQLite job store (fleet.db with its WAL files: runs, jobs, leases, heartbeats, retry counts, result hashes), per-run scan artifacts (a slim copy of each repository\'s findings, verified against the recorded hash before use), the content-addressed scan cache (reused only when commit, lockfiles, configuration and scanner build are unchanged) and the stored enterprise graph with the evidence for every edge. Holds finding locations, never source content or secrets. Safe to delete: the next scan rebuilds it, at the cost of rescanning.' },
   { name: 'fleet-graph.json', kind: 'file', classification: 'generated', retentionClass: 'scan', source: 'src/posture/fleet/cli.js, src/posture/fleet/fleet-graph.js', note: 'The cross-repository dependency graph built from each fleet repository\'s own manifest, consumed by `fleet query --depends-on`. Rebuilt on every `fleet scan`.' },
   { name: 'mcp-audit.log', kind: 'file', classification: 'generated', retentionClass: 'evidence' },
   { name: 'egress-audit.log', kind: 'file', classification: 'generated', retentionClass: 'evidence', note: "FR-604 per-call egress audit log — hash-chained NDJSON written by egress/audit.js's recordEgressCall, never read as config" },
@@ -240,6 +241,9 @@ export const ARTIFACT_REGISTRY = [
   { name: 'rules.yml', kind: 'file', classification: 'operator-config' },
   { name: 'rules', kind: 'dir', classification: 'operator-config' },
   { name: 'rules-proposed', kind: 'dir', classification: 'operator-config', note: 'proposed rules awaiting human review — not yet approved config, but not scanner-regenerable either' },
+  { name: 'eval-lab', kind: 'dir', classification: 'generated', retentionClass: 'evidence', confidential: true, source: 'src/posture/evaluation/lab/store.js (saveRun, saveScoreboard)', note: 'Eval Lab: digest-chained run records (per-attempt outcomes, scores, leakage-audit result, machine profile) and the model scoreboard the policy router reads. Runs keep digests of model patches, never their contents; secrets are scrubbed before writing. A run or scoreboard that no longer matches its own digest is reported as failed and never used for routing. Encrypted per the encryption policy and purged by retention like other evidence-class artifacts; a legal hold on `eval-lab` blocks the purge.' },
+  { name: 'runtime-explorer.html', kind: 'file', classification: 'generated', retentionClass: 'cache', confidential: true, source: 'bin/agentic-security.js (cmdRuntimeExplorer)', note: 'The static runtime-twin page written by `explore . --runtime`: edge states, destinations and counts from imported telemetry, with identities only as keyed-hash tokens. Regenerable from the signed graph and the observation store, so it is a cache; it can reveal internal hostnames and service names, so it is treated as confidential.' },
+  { name: 'dnr', kind: 'dir', classification: 'generated', retentionClass: 'evidence', confidential: true, source: 'src/posture/dnr/store.js (saveRecord)', note: 'Detection-and-response loop: per-finding detection IR with its validation result, historical-hunt results and exposure windows. Hunt samples are redacted and truncated before they are written (a value fingerprint stands in for the value), so production request contents are not stored. Encrypted per the encryption policy and purged by retention like other evidence-class artifacts; a legal hold on `dnr` blocks the purge.' },
   { name: 'rule-compiler', kind: 'dir', classification: 'generated', retentionClass: 'evidence', source: 'src/posture/rule-compiler/store.js', note: 'Self-Learning Finding-to-Rule Compiler: per-rule lifecycle ledger, IR, evaluation score and regression fixtures. The PROMOTED custom-rule document it publishes lives separately under `rules/` (operator-config, unaffected by reset) once promoted; this directory holds only the scanner-managed provenance and corpus behind that decision.' },
   { name: 'license-policy.yml', kind: 'file', classification: 'operator-config' },
   { name: 'trusted-keys.json', kind: 'file', classification: 'operator-config' },

package/src/posture/custom-rules.js

@@ -23,6 +23,13 @@
 //   match.allOf: [regex…] — every regex must match somewhere in the file
 //   match.notMatch: regex — kill if this regex matches
 //   match.window: N       — when allOf is set, all matches must fall within N lines
+//   match.fileRequires: [regex…]: file-level preconditions (e.g. a framework marker); every one must match somewhere in the file
+//   match.guardedBy: regex : a sanitizer or dominating guard: a hit is dropped when this matches within `guardWindow` lines BEFORE
+//                             (or on) the hit's line. Unlike notMatch it is local to the hit, not the whole file.
+//   match.guardWindow: N   : how far back guardedBy looks (default: the rule's window, else 5)
+//   match.excludeLine: [regex…]: a hit is dropped when its own line matches any of these
+//   (the last four are the structural vocabulary the rule compiler's IR compiles to; a rule that uses any of them is evaluated
+//    against EVERY anchor and reports the first that survives, not only the first anchor in the file)
 //
 // `agentic-security rule test <fixture-glob>` runs every rule against every
 // file and prints PASS/FAIL.
@@ -153,6 +160,10 @@ function _isSafePattern(p) {
   return !_REDOS_NESTED_RE.test(p);
 }
 
+/** The loader's own rule normalizer, exported so anything that scores or validates a rule uses the SAME one the scanner loads
+ * with (and so a rule the loader would reject is never reported as working). Returns null for a rule the loader refuses. */
+export function normalizeCustomRule(r, fp = '(compiled)') { return normalizeRule(r, fp); }
+
 function normalizeRule(r, fp) {
   if (!r || !r.id || !r.match) return null;
   const m = r.match;
@@ -177,6 +188,22 @@ function normalizeRule(r, fp) {
   let notMatch = null;
   if (m.notMatch) { try { notMatch = new RegExp(m.notMatch, 'm'); } catch {} }
 
+  // Structural vocabulary (rule compiler IR): every regex passes the same ReDoS guard as the main patterns, and a rule that
+  // cannot be compiled is rejected whole rather than loaded with a constraint silently missing.
+  const compileAll = (list) => {
+    const out = [];
+    for (const p of list) {
+      if (typeof p !== 'string' || !p || !_isSafePattern(p)) { console.error(`agentic-security: rejected unsafe or non-string structural regex in ${r.id}`); return null; }
+      try { out.push(new RegExp(p, 'm')); } catch (e) { console.error(`agentic-security: invalid structural regex in ${r.id}: ${e.message}`); return null; }
+    }
+    return out;
+  };
+  let fileRequires = null; let guardedBy = null; let excludeLine = null;
+  if (m.fileRequires != null) { if (!Array.isArray(m.fileRequires)) return null; fileRequires = compileAll(m.fileRequires); if (!fileRequires) return null; }
+  if (m.guardedBy != null) { const g = compileAll([m.guardedBy]); if (!g) return null; guardedBy = g[0]; }
+  if (m.excludeLine != null) { if (!Array.isArray(m.excludeLine)) return null; excludeLine = compileAll(m.excludeLine); if (!excludeLine) return null; }
+  const guardWindow = Number.isInteger(m.guardWindow) && m.guardWindow > 0 && m.guardWindow <= 200 ? m.guardWindow : (m.window || 5);
+
   // SentQL extensions (Sentinel-parity FR-DSL-1):
   //   llm_validate: { prompt, min_confidence }
   //   path: { must_traverse: [...], must_not_traverse: [...] }
@@ -208,6 +235,8 @@ function normalizeRule(r, fp) {
     notMatch,
     requireAll: Array.isArray(m.allOf),
     windowLines: m.window || 50,
+    fileRequires, guardedBy, guardWindow, excludeLine,
+    structural: !!(fileRequires || guardedBy || excludeLine),
     sourceFile: fp,
     llmValidate,
     pathConstraints,
@@ -260,17 +289,34 @@ export function runRule(rule, file, content) {
   });
 
   const findings = [];
+  // structural preconditions and per-hit filters (see the header): file-level requirements first
+  if (rule.fileRequires && !rule.fileRequires.every((rx) => rx.test(content))) return [];
+  const lineText = (n) => lines[n - 1] ?? '';
+  const guardLines = [];
+  if (rule.guardedBy) {
+    const g = new RegExp(rule.guardedBy.source, 'gm');
+    let gm; const deadline = Date.now() + EXEC_TIMEOUT_MS;
+    while ((gm = g.exec(content)) !== null) { guardLines.push(offsetToLine(gm.index)); if (gm.index === g.lastIndex) g.lastIndex++; if (Date.now() > deadline) break; }
+  }
+  const survives = (hit) => {
+    if (rule.excludeLine && rule.excludeLine.some((rx) => rx.test(lineText(hit.line)))) return false;
+    if (rule.guardedBy && guardLines.some((gl) => gl <= hit.line && hit.line - gl <= rule.guardWindow)) return false;
+    return true;
+  };
   if (rule.requireAll) {
     if (matches.some(l => l.length === 0)) return [];
-    // Pick the earliest match in the first list, verify the others fall within window.
-    const anchor = matches[0][0];
-    const close = matches.slice(1).every(list =>
-      list.some(x => Math.abs(x.line - anchor.line) <= rule.windowLines)
-    );
-    if (!close) return [];
-    findings.push(toFinding(rule, file, anchor));
+    // Pick the earliest match in the first list, verify the others fall within window. A structural rule tries every anchor in order.
+    const anchors = rule.structural ? matches[0] : [matches[0][0]];
+    for (const anchor of anchors) {
+      const close = matches.slice(1).every(list =>
+        list.some(x => Math.abs(x.line - anchor.line) <= rule.windowLines)
+      );
+      if (!close || !survives(anchor)) continue;
+      findings.push(toFinding(rule, file, anchor));
+      break;
+    }
   } else {
-    for (const m of matches[0]) findings.push(toFinding(rule, file, m));
+    for (const m of matches[0]) if (survives(m)) findings.push(toFinding(rule, file, m));
   }
   return findings;
 }

package/src/posture/dnr/attack-facts.js

@@ -0,0 +1,31 @@
+// The request-level facts a proof can carry about HOW the vulnerable operation is reached: `POST /api/export`, parameter
+// `filename`, sink `exec()`. They are optional and ride on the reproducer (as `reproducer.attack`) because only the person or
+// agent who wrote the reproducer knows them; the runner never reads them, so adding them cannot change a proof's result.
+//
+// Closed-world on purpose. There is no field for an attacker address, a domain, a file hash or a user agent: a detection that
+// is built only from these facts cannot contain an invented indicator, because there is nowhere to put one.
+import { PAYLOAD_CLASS_NAMES } from './payload-classes.js';
+
+const ATTACK_FACT_KEYS = Object.freeze(['method', 'path', 'parameter', 'location', 'payloadClass', 'sink']);
+export const HTTP_METHODS = Object.freeze(['GET', 'POST', 'PUT', 'PATCH', 'DELETE', 'HEAD', 'OPTIONS']);
+export const PARAM_LOCATIONS = Object.freeze(['query', 'body', 'header', 'path', 'cookie']);
+
+const PATH_RE = /^\/[A-Za-z0-9/_\-.:{}~%]{0,199}$/;
+const PARAM_RE = /^[A-Za-z_][A-Za-z0-9_.\-[\]]{0,63}$/;
+const SINK_RE = /^[A-Za-z0-9_.()\- /$]{1,80}$/;
+
+/** Returns a list of problems; empty means the facts are acceptable. Unknown keys are refused, never ignored. */
+export function validateAttackFacts(a) {
+  if (a == null) return [];
+  if (typeof a !== 'object' || Array.isArray(a)) return ['attack must be an object'];
+  const errs = [];
+  for (const k of Object.keys(a)) if (!ATTACK_FACT_KEYS.includes(k)) errs.push(`attack.${k} is not a recognised fact`);
+  if (a.method != null && !HTTP_METHODS.includes(a.method)) errs.push('attack.method must be an HTTP method in upper case');
+  if (a.path != null && (typeof a.path !== 'string' || !PATH_RE.test(a.path) || a.path.includes('..'))) errs.push('attack.path must be an absolute URL path without a query string');
+  if (a.parameter != null && (typeof a.parameter !== 'string' || !PARAM_RE.test(a.parameter))) errs.push('attack.parameter must be a plain parameter name');
+  if (a.location != null && !PARAM_LOCATIONS.includes(a.location)) errs.push(`attack.location must be one of ${PARAM_LOCATIONS.join(', ')}`);
+  if (a.payloadClass != null && !PAYLOAD_CLASS_NAMES.includes(a.payloadClass)) errs.push(`attack.payloadClass must be one of ${PAYLOAD_CLASS_NAMES.join(', ')}`);
+  if (a.sink != null && (typeof a.sink !== 'string' || !SINK_RE.test(a.sink))) errs.push('attack.sink must be a short operation name');
+  if ((a.parameter != null) !== (a.location != null)) errs.push('attack.parameter and attack.location go together');
+  return errs;
+}

package/src/posture/dnr/cli.js

@@ -0,0 +1,138 @@
+// CLI surface for the detection-and-response loop: `dnr generate|validate|hunt|window|show|status`.
+// Non-interactive by construction (no command reads stdin), bounded (log reads have size, line and time budgets), and local:
+// nothing here contacts a network or a model, so production logs never leave the machine.
+//
+// Exit codes: 0 completed and clean, 4 usage or precondition, 1 a stored/produced result failed its own check (validation),
+// and for `hunt` a distinct code per verdict so automation cannot read an unanswered question as a clean one:
+//   0 NOT_OBSERVED   10 OBSERVED   11 INCONCLUSIVE   12 TELEMETRY_UNAVAILABLE
+import fs from 'node:fs';
+import path from 'node:path';
+import { latestProof } from '../proof-fabric/store.js';
+import { buildDetectionIR, validateDetectionIR } from './detection-ir.js';
+import { renderDetection, renderAll, FORMATS } from './outputs.js';
+import { validateDetection } from './validate.js';
+import { huntLogs } from './hunt.js';
+import { computeExposureWindow, loadDeployments, formatExposureWindow } from './exposure-window.js';
+import { saveRecord, latestRecord, listRecords } from './store.js';
+import { buildLifecycleView, formatLifecycleView, loadFindingFromLastScan } from './view.js';
+
+const HUNT_EXIT = Object.freeze({ NOT_OBSERVED: 0, OBSERVED: 10, INCONCLUSIVE: 11, TELEMETRY_UNAVAILABLE: 12 });
+const EXT = { sigma: 'yml', http: 'json', waf: 'conf', 'log-query': 'json', yara: 'yar', spl: 'spl', kql: 'kql', cloudwatch: 'txt', elastic: 'json', yaral: 'yaral', datadog: 'json' };
+
+const usage = () => { console.error('usage: dnr generate <finding-id> [--format sigma|http|waf|log-query|yara|spl|kql|cloudwatch|elastic|yaral|datadog|all] [--out dir] [--allow-unproven]\n       dnr validate <finding-id>\n       dnr hunt <finding-id> --logs <file-or-dir> [--since ISO] [--until ISO]\n       dnr window <finding-id> --deployments <file> [--fix-commit sha] [--environment name]\n       dnr show <finding-id>\n       dnr status <finding-id>'); return 4; };
+
+function ensureDetection(root, id, flags) {
+  const existing = latestRecord(root, id, 'detection');
+  if (existing && !flags.regenerate) return { ok: true, saved: existing.record };
+  const finding = loadFindingFromLastScan(root, id);
+  if (!finding) return { ok: false, reason: `Finding ${id} not found in the last scan.` };
+  const proofRec = latestProof(root, id);
+  const built = buildDetectionIR({ finding, proof: proofRec?.record ?? null, allowUnproven: !!flags['allow-unproven'] });
+  if (!built.ok) return { ok: false, reason: built.reason };
+  const validation = validateDetection(built.ir);
+  const record = { ir: built.ir, validation: { status: validation.status, counts: validation.counts, failures: validation.failures ?? [], reason: validation.reason ?? null }, enabled: validation.status === 'VALIDATED', proof: proofRec?.record ? { recordDigest: proofRec.record.recordDigest ?? null, state: proofRec.record.state ?? null } : null };
+  const saved = saveRecord(root, id, 'detection', record);
+  if (!saved.ok) return { ok: false, reason: `could not store the detection: ${saved.reason}` };
+  return { ok: true, saved: { ...record, recordDigest: saved.digest }, fresh: true };
+}
+
+function writeOut(dir, id, ir, formats) {
+  // the id names a file: it must be the digest-derived form, never text that arrived from a record on disk
+  if (!/^det-[0-9a-f]{12}$/.test(String(ir.id))) { console.error('refusing to write: the detection id is not in its derived form'); return []; }
+  fs.mkdirSync(dir, { recursive: true });
+  const written = [];
+  for (const f of formats) {
+    const r = renderDetection(ir, f);
+    if (!r.applicable) continue;
+    const file = path.join(dir, `${ir.id}.${f === 'log-query' ? 'query' : f}.${EXT[f]}`);
+    try { if (fs.lstatSync(file).isSymbolicLink()) { console.error(`refusing to write through a symlink: ${file}`); continue; } } catch { /* does not exist */ }
+    fs.writeFileSync(file, r.content);
+    written.push(file);
+  }
+  return written;
+}
+
+export async function cmdDnr(args, root) {
+  const sub = args._[1];
+  const id = String(args._[2] ?? '');
+  const flags = args.flags || {};
+  if (!sub || !id) return usage();
+
+  if (sub === 'generate') {
+    const r = ensureDetection(root, id, { ...flags, regenerate: true });
+    if (!r.ok) { console.error(r.reason); return 4; }
+    const { ir, validation } = r.saved;
+    const want = flags.format ? String(flags.format) : null;
+    if (want && want !== 'all' && !FORMATS.includes(want)) { console.error(`unknown format "${want}"; choose one of ${FORMATS.join(', ')}, or all`); return 4; }
+    if (flags.json) { console.log(JSON.stringify({ ir, validation, outputs: want && want !== 'all' ? { [want]: renderDetection(ir, want) } : renderAll(ir) }, null, 2)); return validation.status === 'VALIDATED' ? 0 : 1; }
+    console.log(`Detection ${ir.id} for ${ir.findingId}: ${ir.payloadClass} (${ir.grounding}, confidence ${ir.confidence})`);
+    console.log(`Validation: ${validation.status} (${validation.counts.passed}/${validation.counts.positives + validation.counts.negatives} synthetic cases)${validation.status === 'VALIDATED' ? '; recurrence rule enabled' : '; NOT enabled'}`);
+    for (const l of ir.limitations) console.log(`  limitation: ${l}`);
+    if (flags.out) { const w = writeOut(path.resolve(String(flags.out)), id, ir, want && want !== 'all' ? [want] : FORMATS); console.log(`Wrote ${w.length} file(s) to ${path.resolve(String(flags.out))}`); }
+    else if (want && want !== 'all') { const o = renderDetection(ir, want); console.log(''); console.log(o.applicable ? o.content : `(${want} not applicable: ${o.reason})`); }
+    else console.log(`Formats: ${FORMATS.filter((f) => renderDetection(ir, f).applicable).join(', ')} (use --format <name> to print one, --out <dir> to write them)`);
+    return validation.status === 'VALIDATED' ? 0 : 1;
+  }
+
+  if (sub === 'validate') {
+    const rec = latestRecord(root, id, 'detection');
+    if (!rec) { console.error(`No detection for ${id}. Run: dnr generate ${id}`); return 4; }
+    const errs = validateDetectionIR(rec.record.ir);
+    if (errs.length) { console.error(`The stored detection is invalid: ${errs.join('; ')}`); return 1; }
+    const v = validateDetection(rec.record.ir);
+    if (flags.json) console.log(JSON.stringify(v, null, 2));
+    else { console.log(`Validation: ${v.status} (${v.counts.passed}/${v.cases.length} cases)`); for (const c of v.cases.filter((x) => !x.ok)) console.log(`  FAILED: ${c.kind} "${c.name}" ${c.kind === 'positive' ? 'did not fire' : 'fired'}`); if (v.reason) console.log(`  ${v.reason}`); }
+    return v.status === 'VALIDATED' ? 0 : 1;
+  }
+
+  if (sub === 'hunt') {
+    if (!flags.logs) { console.error('dnr hunt needs --logs <file-or-directory>. Nothing was searched.'); return 4; }
+    const det = ensureDetection(root, id, flags);
+    if (!det.ok) { console.error(det.reason); return 4; }
+    const ac = new AbortController();
+    const onSig = () => ac.abort();
+    process.once('SIGINT', onSig);
+    let result;
+    try { result = await huntLogs({ ir: det.saved.ir, logsPath: path.resolve(String(flags.logs)), since: flags.since ?? null, until: flags.until ?? null, signal: ac.signal }); } finally { process.off('SIGINT', onSig); }
+    const saved = saveRecord(root, id, 'hunt', result);
+    if (flags.json) console.log(JSON.stringify({ ...result, stored: saved.ok ? saved.file : null }, null, 2));
+    else {
+      console.log(`Hunt: ${result.verdict}`);
+      console.log(`Logs: ${result.logs.files} file(s), ${result.logs.parsed}/${result.logs.lines} lines parsed${result.window.start ? `, ${result.window.start.slice(0, 10)} to ${result.window.end.slice(0, 10)}` : ', no timestamps'}`);
+      if (result.matches.count) console.log(`Matches: ${result.matches.count}${result.matches.firstSeen ? ` (first ${result.matches.firstSeen}, last ${result.matches.lastSeen})` : ''}`);
+      for (const s of result.matches.samples.slice(0, 5)) console.log(`  ${s.time ?? 'undated'} ${s.method} ${s.path} [${s.matchedOn}] ${s.valuePreview}`);
+      for (const c of result.caveats) console.log(`Caveat: ${c}`);
+      console.log(result.statement);
+      if (!saved.ok) console.log(`(result not stored: ${saved.reason})`);
+    }
+    return HUNT_EXIT[result.verdict] ?? 11;
+  }
+
+  if (sub === 'window') {
+    if (!flags.deployments) { console.error('dnr window needs --deployments <file> (a JSON list of {commit, deployedAt, environment?}). Nothing was computed.'); return 4; }
+    const finding = loadFindingFromLastScan(root, id);
+    if (!finding) { console.error(`Finding ${id} not found in the last scan.`); return 4; }
+    const { deployments, problems } = loadDeployments(path.resolve(String(flags.deployments)), { environment: flags.environment ?? null });
+    const hunt = latestRecord(root, id, 'hunt')?.record ?? null;
+    const telemetry = flags['telemetry-start'] && flags['telemetry-end'] ? { start: flags['telemetry-start'], end: flags['telemetry-end'] } : hunt?.window ?? null;
+    const w = computeExposureWindow({ finding, repo: root, deployments, deploymentProblems: problems, fixCommit: flags['fix-commit'] ?? null, telemetry });
+    saveRecord(root, id, 'window', w);
+    if (flags.json) console.log(JSON.stringify(w, null, 2)); else console.log(`${formatExposureWindow(w)}\n\n${w.statement}`);
+    return w.status === 'complete' ? 0 : 1;
+  }
+
+  if (sub === 'show') {
+    const rec = latestRecord(root, id, 'detection');
+    if (!rec) { console.error(`No detection for ${id}.`); return 4; }
+    if (listRecords(root, id, 'detection').some((r) => r.tampered)) console.error('WARNING: a stored detection record failed its integrity check and was not used.');
+    console.log(JSON.stringify(flags.json ? rec.record : { id: rec.record.ir.id, payloadClass: rec.record.ir.payloadClass, grounding: rec.record.ir.grounding, endpoint: rec.record.ir.endpoint, enabled: rec.record.enabled, validation: rec.record.validation.status, proof: rec.record.proof }, null, 2));
+    return 0;
+  }
+
+  if (sub === 'status') {
+    const v = buildLifecycleView(root, id);
+    if (flags.json) console.log(JSON.stringify(v, null, 2)); else console.log(formatLifecycleView(v));
+    return 0;
+  }
+  return usage();
+}

package/src/posture/dnr/detection-ir.js

@@ -0,0 +1,123 @@
+// Detection intermediate representation (PRD 7, requirement 1). One IR per confirmed finding; every rendered rule, every
+// hunt and every validation is derived from it, so there is exactly one place where the claim "what the exploit looks like"
+// is made.
+//
+// Evidence grounding (requirement 3) is enforced structurally:
+//   * the IR is CLOSED-WORLD: `validateDetectionIR` refuses any key it does not list, and none of them can carry an attacker
+//     address, a domain, a file hash or a user agent;
+//   * every fact that came from somewhere records where (`facts[field] = {source, ref}`), and a fact with no source is not
+//     put in the IR at all (it is `null`, and the limitation is stated);
+//   * the confidence is computed from the evidence state, never asserted.
+import { canonicalize, sha256 } from '../proof-fabric/reproducer.js';
+import { stateRank } from '../proof-fabric/states.js';
+import { PAYLOAD_CLASSES, classForCwe } from './payload-classes.js';
+import { validateAttackFacts, HTTP_METHODS, PARAM_LOCATIONS } from './attack-facts.js';
+
+const DETECTION_IR_SCHEMA = 'agentic-security/detection-ir';
+const DETECTION_IR_VERSION = 1;
+
+const IR_KEYS = Object.freeze(['schema', 'version', 'id', 'findingId', 'cwe', 'family', 'attackBehavior', 'endpoint', 'parameter', 'payloadClass', 'affectedOperation', 'processEffect', 'networkEffect', 'dbEffect', 'confidence', 'grounding', 'evidence', 'facts', 'limitations', 'digest']);
+const GROUNDING = Object.freeze(['exploit-confirmed', 'reproduced', 'static-only']);
+
+/** "POST /api/export" -> {method, path}; anything else -> null. A finding's own route text is a fact source like any other. */
+export function parseRouteText(text) {
+  const m = /^\s*(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\s+(\/[A-Za-z0-9/_\-.:{}~%]{0,199})\s*$/.exec(String(text ?? ''));
+  return m ? { method: m[1], path: m[2] } : null;
+}
+
+function groundingFor(proof) {
+  const state = proof?.state ?? null;
+  if (state && stateRank(state) >= stateRank('EXPLOIT_CONFIRMED')) return 'exploit-confirmed';
+  if (state && stateRank(state) >= stateRank('REPRODUCED')) return 'reproduced';
+  return 'static-only';
+}
+
+/**
+ * Build the IR for one finding. Returns {ok:true, ir} or {ok:false, reason}.
+ * A finding with no proof is refused unless `allowUnproven` is set, in which case the IR says so (`grounding: static-only`)
+ * and carries a lower confidence. A finding with no recognisable payload class is refused: there is nothing to detect.
+ */
+export function buildDetectionIR({ finding, proof = null, allowUnproven = false } = {}) {
+  if (!finding || typeof finding !== 'object') return { ok: false, reason: 'no finding' };
+  const findingId = String(finding.stableId ?? finding.id ?? '');
+  if (!findingId) return { ok: false, reason: 'the finding has no stable id' };
+  const grounding = groundingFor(proof);
+  if (grounding === 'static-only' && !allowUnproven) {
+    return { ok: false, reason: `no exploit proof for ${findingId}: prove it first (triage exploit ${findingId} --prove), or pass --allow-unproven to build a lower-confidence detection from the static finding alone` };
+  }
+  const attack = proof?.reproducer?.attack ?? null;
+  const attackErrs = validateAttackFacts(attack);
+  if (attackErrs.length) return { ok: false, reason: `the reproducer's attack facts are invalid: ${attackErrs.join('; ')}` };
+
+  const facts = {};
+  const evidence = [];
+  const limitations = [];
+  if (finding.file) evidence.push({ kind: 'finding', ref: `${finding.file}:${finding.line ?? '?'}`, id: findingId });
+  if (proof?.recordDigest) evidence.push({ kind: 'proof', ref: `proof:${proof.recordDigest}`, state: proof.state ?? null, oracle: proof.oracle ?? null });
+  if (attack) evidence.push({ kind: 'reproducer', ref: `reproducer:${String(proof?.reproducer ? sha256(canonicalize(proof.reproducer)) : '').slice(0, 16)}` });
+
+  // payload class: the reproducer's explicit statement wins, then the finding's CWE
+  let payloadClass = null;
+  if (attack?.payloadClass) { payloadClass = attack.payloadClass; facts.payloadClass = { source: 'reproducer', ref: 'attack.payloadClass' }; }
+  else if (classForCwe(finding.cwe)) { payloadClass = classForCwe(finding.cwe); facts.payloadClass = { source: 'finding', ref: `cwe:${finding.cwe}` }; }
+  if (!payloadClass) return { ok: false, reason: `no payload class describes ${finding.cwe || 'this finding'}; a detection would have to guess, and a guessed detection is not generated` };
+  const def = PAYLOAD_CLASSES[payloadClass];
+
+  // endpoint: the reproducer's facts, else the finding's own route text
+  let endpoint = null;
+  if (attack?.method && attack?.path) { endpoint = { method: attack.method, path: attack.path }; facts.endpoint = { source: 'reproducer', ref: 'attack.method+attack.path' }; }
+  else {
+    const fromFinding = parseRouteText(finding.route ?? finding.endpoint);
+    if (fromFinding) { endpoint = fromFinding; facts.endpoint = { source: 'finding', ref: finding.route ? 'route' : 'endpoint' }; }
+  }
+  if (!endpoint) limitations.push('no endpoint is known for this finding, so no request-level rule is generated; only the payload class is described');
+
+  let parameter = null;
+  if (attack?.parameter) { parameter = { name: attack.parameter, location: attack.location }; facts.parameter = { source: 'reproducer', ref: 'attack.parameter' }; }
+  else if (payloadClass !== 'auth-bypass') limitations.push('no vulnerable parameter is known, so the payload test is applied to every query and body value of the endpoint');
+
+  let sink = null;
+  if (attack?.sink) { sink = attack.sink; facts.sink = { source: 'reproducer', ref: 'attack.sink' }; }
+  const affectedOperation = { sink, file: finding.file ? String(finding.file) : null, line: Number.isInteger(finding.line) ? finding.line : null };
+
+  const confidence = Math.max(0.1, Math.min(0.95,
+    (grounding === 'exploit-confirmed' ? 0.9 : grounding === 'reproduced' ? 0.7 : 0.4) - (endpoint ? 0 : 0.2) - (parameter || payloadClass === 'auth-bypass' ? 0 : 0.1)));
+  if (grounding !== 'exploit-confirmed') limitations.push(grounding === 'reproduced' ? 'the exploit was reproduced but not independently confirmed' : 'the exploit was not executed; this detection rests on static analysis only');
+
+  const ir = {
+    schema: DETECTION_IR_SCHEMA, version: DETECTION_IR_VERSION,
+    id: '', findingId,
+    cwe: finding.cwe ? String(finding.cwe) : null,
+    family: finding.family ? String(finding.family) : payloadClass,
+    attackBehavior: def.behavior,
+    endpoint, parameter, payloadClass, affectedOperation,
+    processEffect: def.effects.process ?? 'none', networkEffect: def.effects.network ?? 'none', dbEffect: def.effects.db ?? 'none',
+    confidence: Number(confidence.toFixed(2)), grounding, evidence, facts, limitations, digest: '',
+  };
+  ir.digest = sha256(canonicalize({ ...ir, id: '', digest: '' }));
+  ir.id = `det-${ir.digest.slice(0, 12)}`;
+  return { ok: true, ir };
+}
+
+/** Structural validation of an IR read back from disk or supplied by a caller. Returns a list of problems. */
+export function validateDetectionIR(ir) {
+  if (!ir || typeof ir !== 'object' || Array.isArray(ir)) return ['detection IR must be an object'];
+  const errs = [];
+  for (const k of Object.keys(ir)) if (!IR_KEYS.includes(k)) errs.push(`unknown IR field: ${k}`);
+  if (ir.schema !== DETECTION_IR_SCHEMA || ir.version !== DETECTION_IR_VERSION) errs.push('unsupported schema or version');
+  if (typeof ir.findingId !== 'string' || !ir.findingId) errs.push('findingId required');
+  if (!PAYLOAD_CLASSES[ir.payloadClass]) errs.push(`unknown payload class: ${String(ir.payloadClass)}`);
+  if (!GROUNDING.includes(ir.grounding)) errs.push('unknown grounding');
+  if (ir.endpoint != null) {
+    if (!HTTP_METHODS.includes(ir.endpoint.method) || typeof ir.endpoint.path !== 'string') errs.push('endpoint must be {method, path}');
+    else if (validateAttackFacts({ method: ir.endpoint.method, path: ir.endpoint.path }).length) errs.push('endpoint path is not a plain URL path');
+  }
+  if (ir.parameter != null) {
+    if (!PARAM_LOCATIONS.includes(ir.parameter.location) || typeof ir.parameter.name !== 'string') errs.push('parameter must be {name, location}');
+    else if (validateAttackFacts({ parameter: ir.parameter.name, location: ir.parameter.location }).length) errs.push('parameter name is not a plain name');
+  }
+  if (typeof ir.confidence !== 'number' || ir.confidence < 0 || ir.confidence > 1) errs.push('confidence must be between 0 and 1');
+  if (!Array.isArray(ir.evidence) || !Array.isArray(ir.limitations)) errs.push('evidence and limitations must be lists');
+  if (ir.digest && ir.digest !== sha256(canonicalize({ ...ir, id: '', digest: '' }))) errs.push('digest does not match the content');
+  return errs;
+}