@clear-capabilities/agentic-security-scanner 0.174.0 → 0.176.0

package/src/posture/dnr/exposure-window.js

@@ -0,0 +1,134 @@
+// Vulnerability exposure window (PRD 7, requirement 5): combine WHEN the flaw entered the code, WHEN a build containing it
+// first ran, WHEN the fix was committed and deployed, and WHAT telemetry exists, into the span that can actually be hunted.
+//
+// Every date is sourced (provenance, a deployment record, a git commit, a hunt's own telemetry window). A date that has no
+// source is reported as unknown and listed under `unknowns`; the window that depends on it is then `partial`, or
+// `unavailable`, and the output never fills a gap with an assumption. Part of the exposure that predates the telemetry is
+// reported as `unobservableBefore`: it happened, and nothing here can say whether it was exploited.
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+
+export const MAX_DEPLOYMENTS = 1000;
+const SHA_RE = /^[0-9a-f]{7,64}$/i;
+const ts = (v) => { if (v == null) return null; const t = Date.parse(v); return Number.isNaN(t) ? null : t; };
+const iso = (t) => (t == null ? null : new Date(t).toISOString());
+
+/** Parse a deployment-history file. Returns {deployments, problems}. Unusable entries are listed, never silently dropped. */
+export function loadDeployments(file, { environment = null } = {}) {
+  const problems = [];
+  let raw;
+  try { raw = JSON.parse(fs.readFileSync(file, 'utf8')); } catch (e) { return { deployments: [], problems: [`could not read deployment history: ${e.code || e.message}`] }; }
+  const list = Array.isArray(raw) ? raw : Array.isArray(raw?.deployments) ? raw.deployments : null;
+  if (!list) return { deployments: [], problems: ['deployment history must be a list, or an object with a "deployments" list'] };
+  if (list.length > MAX_DEPLOYMENTS) problems.push(`only the first ${MAX_DEPLOYMENTS} of ${list.length} deployments were read`);
+  const deployments = [];
+  list.slice(0, MAX_DEPLOYMENTS).forEach((d, i) => {
+    if (!d || typeof d !== 'object') { problems.push(`deployment ${i}: not an object`); return; }
+    if (typeof d.commit !== 'string' || !SHA_RE.test(d.commit)) { problems.push(`deployment ${i}: commit must be a hex sha`); return; }
+    if (ts(d.deployedAt) == null) { problems.push(`deployment ${i}: deployedAt is not a date`); return; }
+    if (environment && d.environment !== environment) return;
+    deployments.push({ commit: d.commit.toLowerCase(), deployedAt: iso(ts(d.deployedAt)), environment: typeof d.environment === 'string' ? d.environment.slice(0, 40) : null, artifactDigest: typeof d.artifactDigest === 'string' ? d.artifactDigest.slice(0, 80) : null });
+  });
+  return { deployments, problems };
+}
+
+function git(repo, args, timeoutMs = 15000) {
+  const r = spawnSync('git', args, { cwd: repo, encoding: 'utf8', timeout: timeoutMs, killSignal: 'SIGKILL', stdio: ['ignore', 'pipe', 'ignore'], maxBuffer: 1 << 20 });
+  return r.error || r.status === null ? { ok: false, status: null, out: '' } : { ok: true, status: r.status, out: r.stdout.trim() };
+}
+/** true / false / null (null: git could not answer, e.g. an unknown commit or a shallow clone). */
+export function isAncestor(repo, ancestor, descendant) {
+  const r = git(repo, ['merge-base', '--is-ancestor', ancestor, descendant]);
+  if (!r.ok) return null;
+  return r.status === 0 ? true : r.status === 1 ? false : null;
+}
+export function commitDate(repo, sha) {
+  const r = git(repo, ['show', '-s', '--format=%cI', sha]);
+  return r.ok && r.status === 0 && r.out ? iso(ts(r.out)) : null;
+}
+
+/** True only when the NEWEST recorded deployment is one that contains the flaw: a statement about the record, not about today. */
+function stillExposed(deployments, vulnerable) {
+  if (!deployments.length || !vulnerable.length) return false;
+  const newest = [...deployments].sort((a, b) => Date.parse(b.deployedAt) - Date.parse(a.deployedAt))[0];
+  return vulnerable.some((d) => d.commit === newest.commit && d.deployedAt === newest.deployedAt);
+}
+
+export function computeExposureWindow({ finding, repo, deployments: rawDeployments = [], deploymentProblems = [], fixCommit = null, telemetry = null, deps = {} } = {}) {
+  // callers may pass records that did not come through loadDeployments; normalise dates so every output is comparable
+  const deployments = rawDeployments.filter((d) => d && ts(d.deployedAt) != null).map((d) => ({ ...d, deployedAt: iso(ts(d.deployedAt)) }));
+  const anc = deps.isAncestor ?? ((a, d) => isAncestor(repo, a, d));
+  const cdate = deps.commitDate ?? ((sha) => commitDate(repo, sha));
+  const unknowns = [];
+  const origin = finding?.findingProvenance?.findingOrigin ?? null;
+  const introCommit = origin?.commit ?? null;
+  const introducedAt = iso(ts(origin?.authorDate ?? origin?.committerDate));
+  if (!introCommit) unknowns.push('introduction commit (the finding has no resolved origin)');
+  else if (!introducedAt) unknowns.push('introduction date');
+
+  const fixAt = fixCommit ? cdate(fixCommit) : null;
+  if (!fixCommit) unknowns.push('fix commit (not supplied)');
+  else if (!fixAt) unknowns.push('fix commit date (the commit could not be read)');
+
+  const unresolved = [];
+  const vulnerable = []; const fixed = [];
+  if (!deployments.length) unknowns.push('deployment history (none supplied)');
+  for (const d of deployments) {
+    if (!introCommit) break;
+    const hasBug = anc(introCommit, d.commit);
+    if (hasBug === null) { unresolved.push({ commit: d.commit, deployedAt: d.deployedAt, reason: 'ancestry could not be determined' }); continue; }
+    const hasFix = fixCommit ? anc(fixCommit, d.commit) : false;
+    if (fixCommit && hasFix === null) { unresolved.push({ commit: d.commit, deployedAt: d.deployedAt, reason: 'fix ancestry could not be determined' }); continue; }
+    if (hasBug && !hasFix) vulnerable.push(d);
+    if (hasFix) fixed.push(d);
+  }
+  if (unresolved.length) unknowns.push(`${unresolved.length} deployment(s) whose contents could not be resolved against the introduction/fix commits`);
+  const byTime = (a, b) => Date.parse(a.deployedAt) - Date.parse(b.deployedAt);
+  const firstVulnerable = [...vulnerable].sort(byTime)[0] ?? null;
+  const fixDeployedAt = [...fixed].sort(byTime)[0] ?? null;
+  if (introCommit && deployments.length && !firstVulnerable && !unresolved.length) unknowns.push('no recorded deployment contains the vulnerable code');
+  if (fixCommit && deployments.length && !fixDeployedAt && !unresolved.length) unknowns.push('the fix has not been deployed according to the deployment history');
+
+  const exposureStart = ts(firstVulnerable?.deployedAt);
+  const exposureEnd = ts(fixDeployedAt?.deployedAt);
+  const telStart = ts(telemetry?.start); const telEnd = ts(telemetry?.end);
+  if (telStart == null || telEnd == null) unknowns.push('telemetry window (no dated telemetry)');
+
+  let observable = null; let unobservableBefore = null;
+  if (exposureStart != null) {
+    const end = exposureEnd ?? telEnd;
+    if (telStart != null && telEnd != null && end != null) {
+      const s = Math.max(exposureStart, telStart); const e = Math.min(end, telEnd);
+      if (s <= e) observable = { start: iso(s), end: iso(e), openEnded: exposureEnd == null };
+      if (exposureStart < telStart) unobservableBefore = { start: iso(exposureStart), end: iso(Math.min(telStart, end ?? telStart)) };
+    }
+  }
+  const status = exposureStart == null ? 'unavailable' : (unknowns.length || !observable) ? 'partial' : 'complete';
+  return {
+    schema: 'agentic-security/exposure-window', version: 1, findingId: finding?.stableId ?? finding?.id ?? null, status,
+    vulnerabilityIntroduced: introducedAt ? { at: introducedAt, commit: introCommit, source: 'finding-provenance' } : null,
+    firstVulnerableDeployment: firstVulnerable ? { at: firstVulnerable.deployedAt, commit: firstVulnerable.commit, environment: firstVulnerable.environment, artifactDigest: firstVulnerable.artifactDigest } : null,
+    fixCommitted: fixAt ? { at: fixAt, commit: fixCommit } : null,
+    fixDeployed: fixDeployedAt ? { at: fixDeployedAt.deployedAt, commit: fixDeployedAt.commit, environment: fixDeployedAt.environment, artifactDigest: fixDeployedAt.artifactDigest } : null,
+    stillExposed: stillExposed(deployments, vulnerable),
+    telemetryWindow: telStart != null && telEnd != null ? { start: iso(telStart), end: iso(telEnd) } : null,
+    observableWindow: observable, unobservableBefore, unresolvedDeployments: unresolved, deploymentProblems, unknowns,
+    statement: 'The observable window is the part of the exposure that telemetry covers. Exposure outside it is unobserved, which is not the same as unexploited.',
+  };
+}
+
+export function formatExposureWindow(w) {
+  const day = (x) => (x ? x.at.slice(0, 10) : 'unknown');
+  const lines = [
+    `Vulnerability introduced: ${day(w.vulnerabilityIntroduced)}`,
+    `First vulnerable deployment: ${day(w.firstVulnerableDeployment)}`,
+    `Fix committed: ${day(w.fixCommitted)}`,
+    `Fix deployed: ${w.fixDeployed ? day(w.fixDeployed) : w.stillExposed ? 'not deployed (still exposed)' : 'unknown'}`,
+    `Telemetry available: ${w.telemetryWindow ? `${w.telemetryWindow.start.slice(0, 10)} to ${w.telemetryWindow.end.slice(0, 10)}` : 'unknown'}`,
+    '',
+    `Observable exposure window: ${w.observableWindow ? `${w.observableWindow.start.slice(0, 10)} to ${w.observableWindow.openEnded ? 'present (fix not deployed)' : w.observableWindow.end.slice(0, 10)}` : 'cannot be determined'}`,
+  ];
+  if (w.unobservableBefore) lines.push(`Exposed but not observable: ${w.unobservableBefore.start.slice(0, 10)} to ${w.unobservableBefore.end.slice(0, 10)} (before telemetry began)`);
+  if (w.unknowns.length) lines.push('', `Status: ${w.status}. Unknown: ${w.unknowns.join('; ')}`);
+  return lines.join('\n');
+}

package/src/posture/dnr/hunt.js

@@ -0,0 +1,84 @@
+// Historical hunting (PRD 7, requirement 4): search local logs for requests that have the shape of the proven exploit.
+//
+// Four outcomes, and the rules for reaching each are deliberately asymmetric:
+//   OBSERVED              at least one event matches. A match is a lead, not a verdict of compromise.
+//   NOT_OBSERVED          nothing matched AND the evidence was good enough to look: logs readable and parsed cleanly, every
+//                         field the detection needs present on the events, the read not cut short, timestamps available.
+//   INCONCLUSIVE          nothing matched but one of those conditions failed. This is the honest answer, never NOT_OBSERVED.
+//   TELEMETRY_UNAVAILABLE no readable request records at all.
+//
+// NOT_OBSERVED never means NOT_EXPLOITED, and the result says so in a field a consumer can test (`notExploitedClaim: false`)
+// and in a sentence a person reads.
+import path from 'node:path';
+import { readLogs } from './log-reader.js';
+import { evaluateEvent, requiredFields } from './matchers.js';
+import { redactValue, fingerprint } from './redact.js';
+
+export const HUNT_VERDICTS = Object.freeze(['OBSERVED', 'NOT_OBSERVED', 'INCONCLUSIVE', 'TELEMETRY_UNAVAILABLE']);
+const MAX_SAMPLES = 20;
+const MAX_PARSE_FAILURE_RATIO = 0.05;
+
+const STATEMENTS = {
+  OBSERVED: (n) => `${n} request(s) have the shape of this exploit. A match is a lead to investigate, not proof of compromise: a scanner or a test could produce the same request.`,
+  NOT_OBSERVED: () => 'No matching request was found in the searched logs. This does not establish that the vulnerability was not exploited: exploitation could have used a route, encoding or time these logs do not cover.',
+  INCONCLUSIVE: () => 'No matching request was found, but the logs could not support a negative answer. See the caveats; do not read this as "not exploited".',
+  TELEMETRY_UNAVAILABLE: () => 'There were no readable request records to search, so nothing can be said about past exploitation.',
+};
+
+const FIELD_COUNT_KEY = { method: 'method', path: 'path', query: 'query', body: 'body', headers: 'headers', status: 'status', auth: 'auth' };
+
+export async function huntLogs({ ir, logsPath, since = null, until = null, signal, limits } = {}) {
+  const base = { schema: 'agentic-security/hunt-result', version: 1, findingId: ir.findingId, detectionId: ir.id, detectionDigest: ir.digest, notExploitedClaim: false, egress: 'none' };
+  const sinceMs = since ? Date.parse(since) : null;
+  const untilMs = until ? Date.parse(until) : null;
+  if ((since && Number.isNaN(sinceMs)) || (until && Number.isNaN(untilMs))) {
+    return { ...base, verdict: 'INCONCLUSIVE', caveats: ['the --since/--until value is not a valid date, so nothing was searched'], matches: { count: 0, samples: [] }, statement: STATEMENTS.INCONCLUSIVE() };
+  }
+  const sampleList = [];
+  let matchCount = 0; let firstSeen = null; let lastSeen = null;
+  let undecidable = 0; const undecidableFields = new Set();
+  let endpointEvents = 0; let outOfWindow = 0; let undated = 0;
+
+  const stats = await readLogs(logsPath, {
+    signal, limits,
+    onEvent(ev) {
+      if (sinceMs != null || untilMs != null) {
+        if (!ev.time) { undated++; return; }
+        const t = Date.parse(ev.time);
+        if ((sinceMs != null && t < sinceMs) || (untilMs != null && t > untilMs)) { outOfWindow++; return; }
+      }
+      const r = evaluateEvent(ir, ev);
+      if (r.undecidable) { undecidable++; r.missing.forEach((m) => undecidableFields.add(m)); return; }
+      if (ir.endpoint && ev.method === ir.endpoint.method) endpointEvents++;
+      if (!r.match) return;
+      matchCount++;
+      if (ev.time) { if (!firstSeen || ev.time < firstSeen) firstSeen = ev.time; if (!lastSeen || ev.time > lastSeen) lastSeen = ev.time; }
+      if (sampleList.length < MAX_SAMPLES) sampleList.push({ time: ev.time, method: ev.method, path: redactValue(ev.path, 160), matchedOn: r.matchedOn, valueFingerprint: fingerprint(r.value), valuePreview: redactValue(r.value, 80), status: ev.status });
+    },
+  });
+
+  const logs = { source: path.basename(String(logsPath)), files: stats.files.length, filesSkipped: stats.filesSkipped, lines: stats.lines, parsed: stats.parsed, failed: stats.failed, truncated: stats.truncated };
+  const window = { start: stats.windowStart, end: stats.windowEnd, datedEvents: stats.eventsWithTime };
+  const caveats = [];
+  const result = (verdict) => ({ ...base, verdict, logs, window, coverage: { requestedWindow: { since, until }, outOfWindow, undated, endpointEvents, requiredFields: requiredFields(ir), fieldAvailability: Object.fromEntries(Object.entries(FIELD_COUNT_KEY).map(([k, key]) => [k, stats.parsed ? Number((stats.fieldCounts[key] / stats.parsed).toFixed(3)) : 0])) }, matches: { count: matchCount, firstSeen, lastSeen, samples: sampleList }, caveats, statement: STATEMENTS[verdict](matchCount) });
+
+  if (stats.unreadable || stats.parsed === 0) {
+    caveats.push(stats.unreadable ? 'the log path could not be read' : stats.lines === 0 ? 'the logs contain no lines' : 'no line was recognised as a request record (supported: common/combined access logs, JSON lines)');
+    return result('TELEMETRY_UNAVAILABLE');
+  }
+  if (matchCount > 0) {
+    if (stats.truncated.length || stats.aborted) caveats.push(`the read was cut short (${[...stats.truncated, ...(stats.aborted ? ['aborted'] : [])].join(', ')}); more matches may exist`);
+    return result('OBSERVED');
+  }
+  // nothing matched: decide whether a negative answer is supportable
+  const failRatio = stats.lines ? stats.failed / stats.lines : 0;
+  if (failRatio > MAX_PARSE_FAILURE_RATIO) caveats.push(`${(failRatio * 100).toFixed(1)}% of lines could not be parsed (limit ${MAX_PARSE_FAILURE_RATIO * 100}%)`);
+  if (stats.truncated.length || stats.aborted || stats.budgetExhausted) caveats.push(`the read was cut short (${[...stats.truncated, ...(stats.aborted ? ['aborted'] : [])].join(', ') || 'budget'})`);
+  if (undecidable > 0) caveats.push(`${undecidable} event(s) lacked a field this detection needs (${[...undecidableFields].join(', ')}), so they could not be judged`);
+  if (!stats.eventsWithTime) caveats.push('no event carries a timestamp, so the searched time window is unknown');
+  if (stats.filesSkipped.some((f) => f.reason !== 'not-a-log-extension')) caveats.push(`${stats.filesSkipped.filter((f) => f.reason !== 'not-a-log-extension').length} file(s) were skipped (${[...new Set(stats.filesSkipped.map((f) => f.reason))].join(', ')})`);
+  if (undated > 0) caveats.push(`${undated} event(s) had no timestamp and were excluded by the requested window`);
+  if (!caveats.length && ir.endpoint && endpointEvents === 0) caveats.push('no request to the endpoint appears in the logs at all (informational: nothing to exploit was seen either)');
+  const blocking = caveats.some((c) => !c.startsWith('no request to the endpoint'));
+  return result(blocking ? 'INCONCLUSIVE' : 'NOT_OBSERVED');
+}

package/src/posture/dnr/log-reader.js

@@ -0,0 +1,189 @@
+// Bounded, streaming reader for historical HTTP logs (PRD 7, requirement 4). Logs are hostile input: a file may be huge,
+// binary, symlinked, line-less or crafted to blow up a parser. Everything here has a cap and a clock, and every cap that is
+// reached is REPORTED (`truncated`, `budgetExhausted`, skipped-file reasons) so the hunt can answer INCONCLUSIVE rather than
+// pretend it searched everything.
+//
+// Production logs stay local: this module reads files and calls a callback. It imports no network module, and a test pins
+// that. Understood shapes: Apache/nginx common and combined access logs, JSON lines (including Envoy and generic structured
+// loggers). Anything else on a line is a parse failure, counted, never guessed at.
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+
+export const LIMITS = Object.freeze({ maxFiles: 500, maxDepth: 4, maxFileBytes: 256 * 1024 * 1024, maxTotalBytes: 2 * 1024 * 1024 * 1024, maxLines: 20_000_000, maxLineChars: 32 * 1024, maxParams: 200, budgetMs: 10 * 60 * 1000 });
+const TEXT_EXT = /\.(?:log|txt|json|jsonl|ndjson|access|out)$|^[^.]+$/i;
+const MONTHS = { Jan: 0, Feb: 1, Mar: 2, Apr: 3, May: 4, Jun: 5, Jul: 6, Aug: 7, Sep: 8, Oct: 9, Nov: 10, Dec: 11 };
+const CLF = /^(\S+) \S+ (\S+) \[([^\]]+)\] "([A-Z]{3,8}) (\S+)(?: HTTP\/[\d.]+)?" (\d{3}|-) (?:\d+|-)/;
+
+const decode = (s) => { try { return decodeURIComponent(String(s).replace(/\+/g, ' ')); } catch { return String(s); } };
+
+export function parseQuery(qs, cap = LIMITS.maxParams) {
+  const out = {};
+  let n = 0;
+  for (const part of String(qs ?? '').split('&')) {
+    if (!part) continue;
+    if (++n > cap) break;
+    const i = part.indexOf('=');
+    const k = decode(i === -1 ? part : part.slice(0, i));
+    const v = i === -1 ? '' : decode(part.slice(i + 1));
+    if (k.length > 128) continue;
+    (out[k] ??= []).push(v);
+  }
+  return out;
+}
+
+function parseTime(v) {
+  if (v == null || v === '') return null;
+  if (typeof v === 'number' && Number.isFinite(v)) { const ms = v > 1e12 ? v : v * 1000; const d = new Date(ms); return Number.isNaN(d.getTime()) ? null : d.toISOString(); }
+  const s = String(v);
+  const clf = /^(\d{1,2})\/([A-Za-z]{3})\/(\d{4}):(\d{2}):(\d{2}):(\d{2}) ([+-]\d{4})$/.exec(s);
+  if (clf && clf[2] in MONTHS) {
+    const off = clf[7];
+    const sign = off[0] === '-' ? -1 : 1;
+    const offMin = sign * (Number(off.slice(1, 3)) * 60 + Number(off.slice(3, 5)));
+    return new Date(Date.UTC(Number(clf[3]), MONTHS[clf[2]], Number(clf[1]), Number(clf[4]), Number(clf[5]), Number(clf[6])) - offMin * 60000).toISOString();
+  }
+  if (/^\d{9,13}(?:\.\d+)?$/.test(s)) return parseTime(Number(s));
+  const d = new Date(s);
+  return Number.isNaN(d.getTime()) ? null : d.toISOString();
+}
+
+function flatten(obj, prefix = '', depth = 0, out = {}) {
+  for (const [k, v] of Object.entries(obj)) {
+    const key = prefix ? `${prefix}.${k}` : k;
+    if (v && typeof v === 'object' && !Array.isArray(v) && depth < 3) flatten(v, key, depth + 1, out);
+    else out[key.toLowerCase()] = v;
+  }
+  return out;
+}
+const pick = (flat, names) => { for (const n of names) if (flat[n] !== undefined && flat[n] !== null && flat[n] !== '') return flat[n]; return undefined; };
+
+function fromRequestTarget(target) {
+  const t = String(target);
+  const i = t.indexOf('?');
+  const p = i === -1 ? t : t.slice(0, i);
+  return { path: p.startsWith('http') ? (() => { try { return new URL(p).pathname; } catch { return null; } })() : p, query: i === -1 ? {} : parseQuery(t.slice(i + 1)) };
+}
+
+/** One log line -> normalized event, or null when it is not a request record in a shape this reader understands. */
+export function parseLine(line) {
+  const text = line.trim();
+  if (!text) return undefined; // blank: neither parsed nor failed
+  if (text[0] === '{') {
+    let obj;
+    try { obj = JSON.parse(text); } catch { return null; }
+    if (!obj || typeof obj !== 'object' || Array.isArray(obj)) return null;
+    const f = flatten(obj);
+    const method = pick(f, ['method', 'request_method', 'http.request.method', 'http.method', 'req.method', 'request.method', 'httpmethod', 'verb']);
+    let target = pick(f, ['path', 'uri', 'url', 'request_uri', ':path', 'url.path', 'request.path', 'req.url', 'http.url', 'request.uri', 'url.original', 'requesturi']);
+    const requestLine = pick(f, ['request']); // "GET /x HTTP/1.1" in some structured loggers
+    let m = method;
+    if (!target && typeof requestLine === 'string') { const rl = /^([A-Z]{3,8}) (\S+)/.exec(requestLine); if (rl) { m = m ?? rl[1]; target = rl[2]; } }
+    if (typeof target !== 'string' && typeof m !== 'string') return null;
+    // `flatten` dissolves nested objects, so a structured body or query is read from the original object
+    const nested = (...chain) => chain.reduce((acc, k) => (acc && typeof acc === 'object' ? acc[k] : undefined), obj);
+    const qsField = pick(f, ['query', 'query_string', 'url.query', 'request.query', 'querystring']) ?? nested('query') ?? nested('request', 'query') ?? nested('url', 'query');
+    const tgt = typeof target === 'string' ? fromRequestTarget(target) : { path: undefined, query: undefined };
+    let query = tgt.query;
+    if (typeof qsField === 'string') query = { ...(query ?? {}), ...parseQuery(qsField.replace(/^\?/, '')) };
+    else if (qsField && typeof qsField === 'object') query = { ...(query ?? {}), ...Object.fromEntries(Object.entries(qsField).slice(0, LIMITS.maxParams).map(([k, v]) => [k, [].concat(v).map(String)])) };
+    const bodyRaw = pick(f, ['body', 'request_body', 'request.body', 'http.request.body.content', 'req.body', 'payload']) ?? nested('body') ?? nested('request', 'body') ?? nested('req', 'body') ?? nested('http', 'request', 'body', 'content') ?? nested('payload');
+    let bodyParams = null;
+    if (typeof bodyRaw === 'string') {
+      try { const j = JSON.parse(bodyRaw); bodyParams = j && typeof j === 'object' && !Array.isArray(j) ? Object.fromEntries(Object.entries(flatten(j)).slice(0, LIMITS.maxParams).map(([k, v]) => [k, [String(v)]])) : { '': [bodyRaw] }; } catch { bodyParams = bodyRaw.includes('=') ? parseQuery(bodyRaw) : { '': [bodyRaw] }; }
+    } else if (bodyRaw && typeof bodyRaw === 'object') bodyParams = Object.fromEntries(Object.entries(flatten(bodyRaw)).slice(0, LIMITS.maxParams).map(([k, v]) => [k, [String(v)]]));
+    const headers = {};
+    let sawHeaders = false;
+    for (const [k, v] of Object.entries(f)) {
+      const hm = /^(?:request\.)?headers?\.(.+)$/.exec(k) || /^http\.request\.headers\.(.+)$/.exec(k);
+      if (hm) { headers[hm[1]] = String(v); sawHeaders = true; }
+    }
+    const authHeader = headers.authorization ?? pick(f, ['authorization']);
+    const authFlag = pick(f, ['authenticated', 'is_authenticated', 'auth.present']);
+    const authPresent = authHeader != null ? true : typeof authFlag === 'boolean' ? authFlag : (sawHeaders ? false : null);
+    const statusRaw = pick(f, ['status', 'status_code', 'response_code', 'http.response.status_code', 'sc-status', 'response.status', 'res.statuscode']);
+    const status = Number.isInteger(Number(statusRaw)) && statusRaw !== undefined ? Number(statusRaw) : null;
+    return { time: parseTime(pick(f, ['@timestamp', 'timestamp', 'time', 'ts', 'start_time', 'datetime', 'date'])), method: typeof m === 'string' ? m.toUpperCase() : null, path: tgt.path ?? null, query: query ?? null, bodyParams, headers: sawHeaders ? headers : null, status, authPresent };
+  }
+  const c = CLF.exec(text);
+  if (c) {
+    const { path: p, query } = fromRequestTarget(c[5]);
+    return { time: parseTime(c[3]), method: c[4], path: p, query, bodyParams: null, headers: null, status: c[6] === '-' ? null : Number(c[6]), authPresent: null };
+  }
+  return null;
+}
+
+function collectFiles(root, limits, skipped) {
+  const out = [];
+  const walk = (p, depth) => {
+    let st;
+    try { st = fs.lstatSync(p); } catch { skipped.push({ file: path.basename(p), reason: 'unreadable' }); return; }
+    if (st.isSymbolicLink()) { skipped.push({ file: path.basename(p), reason: 'symlink' }); return; }
+    if (st.isDirectory()) {
+      if (depth > limits.maxDepth) { skipped.push({ file: path.basename(p), reason: 'too-deep' }); return; }
+      let names = [];
+      try { names = fs.readdirSync(p).sort(); } catch { skipped.push({ file: path.basename(p), reason: 'unreadable' }); return; }
+      for (const n of names) walk(path.join(p, n), depth + 1);
+      return;
+    }
+    if (!st.isFile()) return;
+    if (/\.(?:gz|zip|bz2|xz|zst|tgz)$/i.test(p)) { skipped.push({ file: path.basename(p), reason: 'compressed-unsupported' }); return; }
+    if (!TEXT_EXT.test(path.basename(p))) { skipped.push({ file: path.basename(p), reason: 'not-a-log-extension' }); return; }
+    if (out.length >= limits.maxFiles) { skipped.push({ file: path.basename(p), reason: 'file-count-limit' }); return; }
+    out.push({ file: p, size: st.size });
+  };
+  walk(root, 0);
+  return out;
+}
+
+/**
+ * Stream every request record under `target` through `onEvent(event)`. Never throws on bad content.
+ * @returns stats: files, lines, parsed/failed counts, time window, per-field availability, and every limit that was hit.
+ */
+export async function readLogs(target, { onEvent, signal, limits: over = {} } = {}) {
+  const limits = { ...LIMITS, ...over };
+  const stats = { files: [], filesSkipped: [], lines: 0, parsed: 0, failed: 0, oversizeLines: 0, windowStart: null, windowEnd: null, eventsWithTime: 0, fieldCounts: { method: 0, path: 0, query: 0, body: 0, headers: 0, status: 0, auth: 0 }, truncated: [], budgetExhausted: false, aborted: false, unreadable: false };
+  let st;
+  try { st = fs.lstatSync(target); } catch { stats.unreadable = true; return stats; }
+  if (st.isSymbolicLink()) { stats.unreadable = true; stats.filesSkipped.push({ file: path.basename(target), reason: 'symlink' }); return stats; }
+  const base = st.isDirectory() ? target : path.dirname(target);
+  const files = st.isDirectory() ? collectFiles(target, limits, stats.filesSkipped) : collectFiles(target, limits, stats.filesSkipped);
+  const deadline = Date.now() + limits.budgetMs;
+  let totalBytes = 0;
+  for (const { file, size } of files) {
+    if (signal?.aborted) { stats.aborted = true; break; }
+    if (Date.now() > deadline) { stats.budgetExhausted = true; stats.truncated.push('time-budget'); break; }
+    if (size > limits.maxFileBytes) { stats.filesSkipped.push({ file: path.relative(base, file), reason: 'file-too-large' }); stats.truncated.push('file-too-large'); continue; }
+    if (totalBytes + size > limits.maxTotalBytes) { stats.filesSkipped.push({ file: path.relative(base, file), reason: 'total-size-limit' }); stats.truncated.push('total-size-limit'); continue; }
+    totalBytes += size;
+    const fstat = { name: path.relative(base, file) || path.basename(file), bytes: size, lines: 0, parsed: 0, failed: 0 };
+    stats.files.push(fstat);
+    const stream = fs.createReadStream(file, { encoding: 'utf8', highWaterMark: 1 << 20 });
+    const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+    try {
+      for await (const line of rl) {
+        if (signal?.aborted) { stats.aborted = true; break; }
+        if ((fstat.lines & 0x3ff) === 0 && Date.now() > deadline) { stats.budgetExhausted = true; stats.truncated.push('time-budget'); break; }
+        if (stats.lines >= limits.maxLines) { stats.truncated.push('line-limit'); break; }
+        stats.lines++; fstat.lines++;
+        if (line.length > limits.maxLineChars) { stats.oversizeLines++; stats.failed++; fstat.failed++; continue; }
+        const ev = parseLine(line);
+        if (ev === undefined) continue;
+        if (ev === null) { stats.failed++; fstat.failed++; continue; }
+        stats.parsed++; fstat.parsed++;
+        if (ev.method) stats.fieldCounts.method++;
+        if (ev.path != null) stats.fieldCounts.path++;
+        if (ev.query != null) stats.fieldCounts.query++;
+        if (ev.bodyParams != null) stats.fieldCounts.body++;
+        if (ev.headers != null) stats.fieldCounts.headers++;
+        if (ev.status != null) stats.fieldCounts.status++;
+        if (ev.authPresent != null) stats.fieldCounts.auth++;
+        if (ev.time) { stats.eventsWithTime++; if (!stats.windowStart || ev.time < stats.windowStart) stats.windowStart = ev.time; if (!stats.windowEnd || ev.time > stats.windowEnd) stats.windowEnd = ev.time; }
+        onEvent?.(ev);
+      }
+    } catch { stats.filesSkipped.push({ file: fstat.name, reason: 'read-error' }); } finally { rl.close(); stream.destroy(); }
+    if (stats.aborted || stats.budgetExhausted || stats.truncated.includes('line-limit')) break;
+  }
+  stats.truncated = [...new Set(stats.truncated)];
+  return stats;
+}

package/src/posture/dnr/matchers.js

@@ -0,0 +1,90 @@
+// The one evaluator behind every detection output. Validation (synthetic events), hunting (historical logs) and the
+// rendered rules' described behavior all call `evaluateEvent`, so a rule that passes validation is the same rule that
+// searches the logs. An event is the NORMALIZED request record produced by log-reader.js or by the validator.
+//
+//   event = { time, method, path, query: {name: [values]}, bodyParams: {name: [values]} | null, headers: {name: value} | null,
+//             status, authPresent: boolean | null }
+//
+// A missing field is `undefined`/`null`, never an empty string: "the log did not record this" and "the value was empty" are
+// different facts, and only the first makes an event undecidable.
+import { PAYLOAD_CLASSES, matchesClass } from './payload-classes.js';
+
+const norm = (p) => (p.length > 1 ? p.replace(/\/+$/, '') : p);
+
+/** `/api/users/:id` and `/api/users/{id}` match any single non-empty segment in that position. */
+export function pathMatches(template, actual) {
+  if (typeof actual !== 'string' || !actual.startsWith('/')) return false;
+  const t = norm(template).split('/');
+  const a = norm(actual.split('?')[0]).split('/');
+  if (t.length !== a.length) return false;
+  return t.every((seg, i) => (/^(?::[A-Za-z_]\w*|\{[A-Za-z_]\w*\})$/.test(seg) ? a[i].length > 0 : seg === a[i]));
+}
+
+/** Fields an event must have for a detection to be able to say "no" about it. */
+export function requiredFields(ir) {
+  const need = new Set();
+  if (ir.endpoint) { need.add('method'); need.add('path'); }
+  if (ir.payloadClass === 'auth-bypass') { need.add('status'); need.add('auth'); return [...need]; }
+  const loc = ir.parameter?.location;
+  if (loc === 'body') need.add('body');
+  else if (loc === 'header' || loc === 'cookie') need.add('headers');
+  else if (loc === 'path') need.add('path');
+  else need.add('query');
+  if (!ir.endpoint) need.add('path');
+  return [...need];
+}
+
+function candidateValues(ir, event) {
+  const out = [];
+  const p = ir.parameter;
+  const take = (bag, name) => { for (const v of (bag?.[name] ?? [])) out.push([`${name}`, v]); };
+  if (!p) {
+    for (const [k, vs] of Object.entries(event.query ?? {})) for (const v of vs) out.push([`query:${k}`, v]);
+    for (const [k, vs] of Object.entries(event.bodyParams ?? {})) for (const v of vs) out.push([`body:${k}`, v]);
+    return { values: out, decidable: event.query != null };
+  }
+  if (p.location === 'query') { take(event.query, p.name); return { values: out.map(([k, v]) => [`query:${k}`, v]), decidable: event.query != null }; }
+  if (p.location === 'body') { take(event.bodyParams, p.name); return { values: out.map(([k, v]) => [`body:${k}`, v]), decidable: event.bodyParams != null }; }
+  if (p.location === 'header' || p.location === 'cookie') {
+    const v = event.headers?.[p.name.toLowerCase()];
+    return { values: v == null ? [] : [[`${p.location}:${p.name}`, v]], decidable: event.headers != null };
+  }
+  // path parameter: the segment where the template has the parameter
+  if (p.location === 'path' && ir.endpoint) {
+    const t = norm(ir.endpoint.path).split('/');
+    const a = norm(String(event.path).split('?')[0]).split('/');
+    t.forEach((seg, i) => { if (seg === `:${p.name}` || seg === `{${p.name}}`) out.push([`path:${p.name}`, a[i] ?? '']); });
+  }
+  return { values: out, decidable: typeof event.path === 'string' };
+}
+
+/**
+ * @returns {{match: boolean, undecidable: boolean, missing: string[], matchedOn: string|null, value: string|null}}
+ * `undecidable` means "this event lacks a field the detection needs", which is different from "this event does not match".
+ */
+export function evaluateEvent(ir, event) {
+  const res = { match: false, undecidable: false, missing: [], matchedOn: null, value: null };
+  if (ir.endpoint) {
+    if (!event.method) res.missing.push('method');
+    if (typeof event.path !== 'string') res.missing.push('path');
+    if (res.missing.length) { res.undecidable = true; return res; }
+    if (String(event.method).toUpperCase() !== ir.endpoint.method) return res;
+    if (!pathMatches(ir.endpoint.path, event.path)) return res;
+  } else if (typeof event.path !== 'string') { res.missing.push('path'); res.undecidable = true; return res; }
+
+  if (ir.payloadClass === 'auth-bypass') {
+    if (event.status == null) res.missing.push('status');
+    if (event.authPresent == null) res.missing.push('auth');
+    if (res.missing.length) { res.undecidable = true; return res; }
+    if (event.status >= 200 && event.status < 300 && event.authPresent === false) { res.match = true; res.matchedOn = 'unauthenticated-success'; res.value = `${event.status}`; }
+    return res;
+  }
+
+  if (!PAYLOAD_CLASSES[ir.payloadClass]) { res.undecidable = true; res.missing.push('payload-class'); return res; }
+  const { values, decidable } = candidateValues(ir, event);
+  for (const [where, v] of values) {
+    if (matchesClass(ir.payloadClass, v)) { res.match = true; res.matchedOn = where; res.value = String(v).slice(0, 200); return res; }
+  }
+  if (!decidable) { res.undecidable = true; res.missing.push(ir.parameter?.location === 'body' ? 'body' : ir.parameter?.location === 'header' || ir.parameter?.location === 'cookie' ? 'headers' : 'query'); }
+  return res;
+}