@clear-capabilities/agentic-security-scanner 0.171.0 → 0.172.1

package/src/context-intelligence/evaluation/runner.js

@@ -0,0 +1,139 @@
+//
+// Runs the frozen synthetic suite through the compared systems and tallies per-case outcomes.
+//
+// Systems (each answers one question per case variant: "is a defect reported at the labeled sink?"):
+//   deterministic  the default scanner (`runScan`) with state writes disabled; no model, no spend
+//   hunt           the existing discovery pipeline (partition, lens hunters, confirm, panel, judge)
+//   dci            DCI bundles + governed review + verified citations -> candidates (model hypotheses, pre-confirmation)
+//   dci-compiler   dci with imported compiler metadata; BLOCKED unless the case ships a `hie-export.json`
+// Both model-backed systems get the SAME injected reader, so the only thing that differs is the text put in front of it.
+//
+// The reader here is the scripted one, so every number is a statement about the machinery on synthetic cases.
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { runScan } from '../../runScan.js';
+import { withStateWritesDisabled } from '../../posture/state-dir.js';
+import { buildProjectIR } from '../../ir/index.js';
+import { runDiscovery } from '../../discovery/index.js';
+import { makeTaintProbe } from '../../discovery/index.js';
+import { buildContext } from '../build.js';
+import { loadConfig } from '../config.js';
+import { planJobs, runQueue } from '../queue.js';
+import { packById } from '../prompts/packs.js';
+import { describeModel } from '../review.js';
+import { reviewsToCandidates, adjudicate } from '../candidates.js';
+import { scriptedReader } from './scripted-reader.js';
+import { readSnapshot } from '../files.js';
+
+export const SYSTEMS = Object.freeze(['deterministic', 'hunt', 'dci', 'dci-compiler']);
+export const LINE_TOLERANCE = 5;
+
+/** Line (1-based) of the first line containing `contains`, or null. */
+export function locate(text, contains) {
+  const lines = String(text).split('\n');
+  for (let i = 0; i < lines.length; i++) if (lines[i].includes(contains)) return i + 1;
+  return null;
+}
+
+function copyTree(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const e of fs.readdirSync(src, { withFileTypes: true })) {
+    const s = path.join(src, e.name); const d = path.join(dest, e.name);
+    if (e.isDirectory()) copyTree(s, d); else if (e.isFile()) fs.copyFileSync(s, d);
+  }
+}
+
+function recorder(inner) {
+  const prompts = [];
+  const fn = async (prompt) => { prompts.push(prompt); return inner(prompt); };
+  fn.tokenizerName = inner.tokenizerName;
+  return { invoke: fn, prompts };
+}
+
+function hit(found, sink) {
+  return found.some(f => f.file === sink.file && Number.isInteger(f.line) && Math.abs(f.line - sink.line) <= LINE_TOLERANCE);
+}
+
+async function runDeterministic(dir, sink) {
+  const { scan } = await withStateWritesDisabled(() => runScan(dir, { deep: true, deepInCi: true }));
+  const findings = [...(scan.findings || []), ...(scan.logicVulns || [])].filter(f => f && f.severity !== 'info');
+  return { flagged: hit(findings, sink), calls: 0, promptChars: 0, detail: { findings: findings.length }, prompts: [] };
+}
+
+async function runHuntSystem(dir, sink, reader) {
+  const snap = await readSnapshot(dir, { maxFiles: 2000 });
+  const fileContents = snap.fileContents;
+  const ir = buildProjectIR(fileContents);
+  const rec = recorder(reader);
+  const res = await withStateWritesDisabled(() => runDiscovery({ perFileIR: ir.perFile, callGraph: ir.callGraph, fileContents }, { llmInvoke: rec.invoke, lenses: ['authz', 'business-logic'], maxAreas: 8 }));
+  const reported = [...res.fresh, ...res.duplicates];
+  const found = reported.map(f => ({ file: f.file, line: f.line }));
+  return { flagged: hit(found, sink), calls: rec.prompts.length, promptChars: rec.prompts.reduce((n, p) => n + p.length, 0), detail: { reported: reported.length, areas: res.focusAreas.length }, prompts: rec.prompts };
+}
+
+async function runDciSystem(dir, sink, reader, { packIds, withCompiler }) {
+  const { config } = loadConfig(dir);
+  if (withCompiler) config.semanticMetadata = { mode: 'import', haskellHieDir: '.' };
+  const built = await buildContext(dir, { config });
+  if (!built.ok) return { flagged: false, calls: 0, promptChars: 0, detail: { buildFailed: built.reason }, prompts: [] };
+  const packs = packIds.map(packById).filter(Boolean);
+  const model = describeModel();
+  const { jobs } = planJobs({ bundles: built.bundles, packs, model });
+  const byEp = new Map(built.bundles.map(b => [b.entrypoint.id, b]));
+  const packMap = new Map(packs.map(p => [p.id, p]));
+  const loadJob = (job) => {
+    const bundles = job.entrypointIds.map(id => byEp.get(id));
+    if (bundles.some(b => !b || !b.manifest)) return { error: 'no bundle' };
+    return { pack: packMap.get(job.packId), entrypoints: bundles.map(b => b.entrypoint), manifests: bundles.map(b => b.manifest), packageTexts: bundles.map((b, i) => (b.pack.packages.find(p => p.index === job.packageIndexes[i]) || b.pack.packages[0]).text) };
+  };
+  const rec = recorder(reader);
+  const result = await runQueue(jobs, { root: built.root, fileContents: built.fileContents, model, invoker: { ok: true, invoke: rec.invoke }, loadJob, retryFailed: false, limits: { concurrency: 1, maxCalls: 500, maxWallSeconds: 300, maxTokensPerJob: 40000, maxRetries: 0, jobTimeoutMs: 30000, maxCostUsd: null, costPerCallUsd: null } });
+  const records = [];
+  for (const [, res] of result.results) {
+    if (res.state === 'succeeded' && res.review) { const lj = loadJob(res.job); if (!lj.error) records.push({ review: res.review, entrypoints: lj.entrypoints.map(e => ({ id: e.id, label: e.label })), pack: lj.pack }); }
+  }
+  const candidates = reviewsToCandidates(records);
+  const adj = await adjudicate(candidates, { taintProbe: makeTaintProbe(built.ir.perFile, built.ir.callGraph), scanRoot: built.root });
+  const found = candidates.map(c => ({ file: c.file, line: c.line }));
+  const tiers = {};
+  for (const f of adj.findings) { const t = (f.discovery && f.discovery.confirmation && f.discovery.confirmation.tier) || 'unknown'; tiers[t] = (tiers[t] || 0) + 1; }
+  return {
+    flagged: hit(found, sink), calls: rec.prompts.length, promptChars: rec.prompts.reduce((n, p) => n + p.length, 0),
+    detail: { jobs: jobs.length, candidates: candidates.length, coverage: { eligible: result.coverage.eligible, succeeded: result.coverage.succeeded, missing: result.coverage.missingCoverage }, confirmationTiers: tiers, bundles: { complete: built.summary.complete, partial: built.summary.partialBundles, unavailable: built.summary.unavailable } },
+    prompts: rec.prompts,
+  };
+}
+
+/**
+ * Run one system over one case variant in a throwaway copy. Never touches the source fixture.
+ * Returns { flagged, calls, promptChars, detail, prompts, status } where status is 'ok' or 'blocked'/'error'.
+ */
+export async function runCase({ system, caseDef, variant, suiteDir, variantName = 'dci' }) {
+  const v = caseDef.variants[variant.key];
+  const srcDir = path.join(suiteDir, 'corpus', caseDef.id, variant.key);
+  if (system === 'dci-compiler' && !fs.existsSync(path.join(srcDir, 'hie-export.json'))) {
+    return { status: 'blocked', reason: 'no compiler metadata export is shipped for this case (the exporter needs a build toolchain and is not run by DCI)', flagged: null, calls: 0, promptChars: 0, detail: {}, prompts: [] };
+  }
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'dci-eval-'));
+  try {
+    copyTree(srcDir, tmp);
+    const sinkText = fs.readFileSync(path.join(tmp, v.sink.file), 'utf8');
+    const line = locate(sinkText, v.sink.contains);
+    if (line === null) return { status: 'error', reason: `sink text not found in ${v.sink.file}`, flagged: null, calls: 0, promptChars: 0, detail: {}, prompts: [] };
+    const sink = { file: v.sink.file, line };
+    const reader = scriptedReader();
+    let r;
+    if (system === 'deterministic') r = await runDeterministic(tmp, sink);
+    else if (system === 'hunt') r = await runHuntSystem(tmp, sink, reader);
+    else if (system === 'dci' || system === 'dci-compiler') {
+      const packIds = variantName === 'dci-all-packs' ? ['authz-idor', 'authz-function', 'transaction-integrity'] : [caseDef.pack];
+      r = await runDciSystem(tmp, sink, reader, { packIds, withCompiler: system === 'dci-compiler' });
+    } else return { status: 'error', reason: `unknown system ${system}`, flagged: null, calls: 0, promptChars: 0, detail: {}, prompts: [] };
+    return { status: 'ok', sink, ...r };
+  } catch (e) {
+    return { status: 'error', reason: String(e && e.message || e).slice(0, 200), flagged: null, calls: 0, promptChars: 0, detail: {}, prompts: [] };
+  } finally {
+    try { fs.rmSync(tmp, { recursive: true, force: true }); } catch { /* best effort */ }
+  }
+}

package/src/context-intelligence/evaluation/scripted-reader.js

@@ -0,0 +1,289 @@
+//
+// A deterministic, rule-based "reader" that stands in for a model in the SYNTHETIC evaluation suite.
+//
+// WHAT IT IS. A small text analyser that answers the same two prompt formats a model would see (the DCI review prompt
+// and the `hunt` prompt) using only what is literally written in the prompt. Because it is deterministic, a suite run
+// is reproducible bit for bit and needs no network, key or spend, which is what lets the evaluation HARNESS be tested.
+//
+// WHAT IT IS NOT. It is not a language model and its results are not evidence about any model's ability. It was
+// written by the same people who wrote the fixtures, so it is good at exactly the shapes those fixtures contain. Any
+// score produced with it measures the context-construction and verification machinery on synthetic cases, never
+// vulnerability-finding skill. The scorecard says so on its face.
+//
+// It reads ONLY the prompt. That is the point of the comparison: two systems differ in what text they put in front of
+// the same reader, so a difference in outcome is a difference in context.
+import * as crypto from 'node:crypto';
+
+const ROUTE_CALL = /\b(?:app|router|server|api)\.(get|post|put|patch|delete|all)\s*\(\s*(['"`])([^'"`]+)\2/;
+const FLASK_ROUTE = /@\w+\.route\(\s*(['"])([^'"]+)\1/;
+const SCOTTY_ROUTE = /^\s*(get|post|put|patch|delete)\s+"([^"]+)"/;
+const UNTRUSTED = /\b(?:req|request)\.(?:params|query|body|args|form)\b|\bparam\s+"|<int:\w+>|<\w+>|\bnote_id\b|\bitem_id\b/;
+const DATA = /\b(?:db|tx|conn|pool|client|repo)\.(?:query|execute|run)\s*\(|\bquery\s+conn\b|\bexecute\s+conn\b|\bdb\.execute\(/;
+const WRITE = /\b(?:UPDATE|DELETE|INSERT)\b/i;
+const QUALIFIED_PRINCIPAL = /\b(?:req\.user|request\.user|current_user|session\.user|principal|ctx\.user|userId\s+u)\b/;
+const OWNER_COL = /\b(?:owner|owner_id|org_id|tenant_id|user_id|account_id)\b|\bowner\s*=/i;
+const ROLE_GUARD = /\b(?:requireAdmin|isAdmin|role\s*!==?\s*['"]admin['"]|hasRole|requireRole)\b/;
+
+function numbered(text) {
+  // "  12| code" lines, as the DCI packer renders them
+  const out = [];
+  for (const raw of text.split('\n')) {
+    const m = /^\s*(\d+)\| ?(.*)$/.exec(raw);
+    if (m) out.push({ n: +m[1], text: m[2] });
+  }
+  return out;
+}
+
+/** Blocks from a DCI review prompt: [{file, lines:[{n,text}]}] plus metadata the packer wrote into the header. */
+export function blocksFromReviewPrompt(prompt) {
+  const blocks = [];
+  const re = /^=== SOURCE (\S+):(\d+)-(\d+) \|[^\n]*===\n/gm;
+  const marks = [];
+  let m;
+  while ((m = re.exec(prompt))) marks.push({ file: m[1], at: m.index, bodyAt: re.lastIndex });
+  marks.forEach((mk, i) => {
+    const end = i + 1 < marks.length ? marks[i + 1].at : prompt.length;
+    blocks.push({ file: mk.file, lines: numbered(prompt.slice(mk.bodyAt, end)) });
+  });
+  return { blocks, unresolved: /^UNRESOLVED:/m.test(prompt), notIncluded: /^NOT INCLUDED:/m.test(prompt), limit: /^LIMIT:/m.test(prompt) };
+}
+
+/** Blocks from a `hunt` prompt: whole files, which the reader numbers itself. */
+export function blocksFromHuntPrompt(prompt) {
+  const blocks = [];
+  const re = /--- SOURCE FILE \(untrusted data\): (\S+?)(?: \(truncated\))? ---\n([\s\S]*?)\n--- END SOURCE FILE: /g;
+  let m;
+  while ((m = re.exec(prompt))) blocks.push({ file: m[1], lines: m[2].split('\n').map((text, i) => ({ n: i + 1, text })) });
+  return blocks;
+}
+
+function allLines(blocks) { return blocks.flatMap(b => b.lines.map(l => ({ ...l, file: b.file }))); }
+
+/** Lines from a registration to the end of its handler within one block. */
+function handlerRange(block, startIdx) {
+  const L = block.lines;
+  const first = L[startIdx].text;
+  if (/^\s*@/.test(first)) { // decorator style: until the next top-level line after the def body
+    let i = startIdx + 1;
+    while (i < L.length && /^\s*@/.test(L[i].text)) i++;
+    const base = /^\s*/.exec(L[i] ? L[i].text : '')[0].length;
+    let j = i + 1;
+    while (j < L.length && (L[j].text.trim() === '' || /^\s*/.exec(L[j].text)[0].length > base)) j++;
+    return L.slice(startIdx, j);
+  }
+  if (SCOTTY_ROUTE.test(first)) {
+    const base = /^\s*/.exec(first)[0].length;
+    let j = startIdx + 1;
+    while (j < L.length && (L[j].text.trim() === '' || /^\s*/.exec(L[j].text)[0].length > base)) j++;
+    return L.slice(startIdx, j);
+  }
+  let depth = 0; let opened = false; let j = startIdx;
+  for (; j < L.length; j++) {
+    for (const c of L[j].text) { if (c === '{') { depth++; opened = true; } else if (c === '}') depth--; }
+    if (opened && depth <= 0) break;
+  }
+  return L.slice(startIdx, Math.min(L.length, j + 1));
+}
+
+function findRoutes(blocks) {
+  const routes = [];
+  for (const b of blocks) {
+    b.lines.forEach((l, i) => {
+      let m = ROUTE_CALL.exec(l.text);
+      if (m) { routes.push({ block: b, idx: i, method: m[1].toUpperCase(), path: m[3], file: b.file, line: l.n }); return; }
+      m = FLASK_ROUTE.exec(l.text);
+      if (m) { routes.push({ block: b, idx: i, method: 'GET', path: m[2], file: b.file, line: l.n }); return; }
+      m = SCOTTY_ROUTE.exec(l.text);
+      if (m) routes.push({ block: b, idx: i, method: m[1].toUpperCase(), path: m[2], file: b.file, line: l.n });
+    });
+  }
+  return routes;
+}
+
+/** Find the body of a function named `name` anywhere in the blocks (one level of helper). */
+function functionBody(blocks, name) {
+  for (const b of blocks) {
+    for (let i = 0; i < b.lines.length; i++) {
+      if (new RegExp(`(?:function\\s+${name}\\b|\\b${name}\\s*=\\s*(?:async\\s*)?\\(|^\\s*${name}\\s*::|\\bdef\\s+${name}\\b)`).test(b.lines[i].text)) {
+        const range = handlerRange(b, i);
+        return range.map(l => ({ ...l, file: b.file }));
+      }
+    }
+  }
+  return null;
+}
+
+function statement(lines, i) {
+  let text = lines[i].text; let depth = 0;
+  for (const c of text) { if (c === '(') depth++; else if (c === ')') depth--; }
+  let j = i;
+  while (depth > 0 && j + 1 < lines.length && j - i < 6) { j++; text += ' ' + lines[j].text; for (const c of lines[j].text) { if (c === '(') depth++; else if (c === ')') depth--; } }
+  return text;
+}
+
+function stripUntrusted(t) {
+  return t.replace(/\b(?:req|request)\.(?:params|query|body|args|form)\b(?:\.\w+)?/g, ' ').replace(/(["'`])(?:\\.|(?!\1).)*\1/g, '""');
+}
+
+/**
+ * Analyse ONE route: returns the observations a reader can make from the text it was given.
+ */
+export function analyseRoute(route, blocks, { dynamicUnresolved = false } = {}) {
+  const handler = handlerRange(route.block, route.idx).map(l => ({ ...l, file: route.file }));
+  const all = allLines(blocks);
+  const obs = { route, handler, untrusted: false, data: [], writes: [], scoping: [], capability: null, roleGuards: [], roleGuardDefined: false, lateScoping: [], dynamic: false, transaction: false, helperScoping: [] };
+  const regLine = handler[0] ? handler[0].text : '';
+
+  obs.untrusted = handler.some(l => UNTRUSTED.test(l.text)) || UNTRUSTED.test(regLine);
+  handler.forEach((l, i) => {
+    if (DATA.test(l.text)) {
+      const st = statement(handler, i);
+      obs.data.push({ ...l, stmt: st });
+      if (WRITE.test(st)) obs.writes.push({ ...l, stmt: st });
+      if (OWNER_COL.test(st) && QUALIFIED_PRINCIPAL.test(stripUntrustedKeepUser(st))) obs.scoping.push({ ...l, kind: 'query-filter' });
+    }
+    if (/\btoken\s*=\s*\$1/.test(l.text) && /\b(?:req|request)\.params\.token\b/.test(statement(handler, i))) obs.capability = { ...l };
+    if (/!==|!=|==/.test(l.text) && OWNER_COL.test(l.text) && QUALIFIED_PRINCIPAL.test(stripUntrustedKeepUser(l.text))) obs.lateScoping.push({ ...l });
+    if (/\bactions\[|\[[^\]]*(?:params|query|body)[^\]]*\]/.test(l.text) || /\breturn\s+run\(/.test(l.text)) obs.dynamic = true;
+    if (/\btransaction\b/.test(l.text)) obs.transaction = true;
+    if (/\bisAdmin\b|\brole\s*!==?\s*['"]admin['"]/.test(l.text)) obs.roleGuards.push({ ...l, where: 'handler' });
+  });
+
+  // middleware named on the registration line
+  const mwNames = [...regLine.matchAll(/\b(require[A-Z]\w*)\b/g)].map(m => m[1]);
+  for (const name of mwNames) {
+    if (ROLE_GUARD.test(name)) {
+      const body = functionBody(blocks, name);
+      if (body) { obs.roleGuardDefined = true; obs.roleGuards.push({ ...body[0], where: 'middleware', name }); }
+      else obs.roleGuards.push({ file: route.file, n: route.line, text: regLine, where: 'middleware-undefined', name });
+    }
+  }
+  // router-level / app-level `use` lines in the provided blocks
+  for (const l of all) {
+    const m = /\b(?:router|app)\.use\(\s*(require[A-Z]\w*)\s*\)/.exec(l.text);
+    if (m && ROLE_GUARD.test(m[1]) && l.n < route.line + 0 && l.file === route.file) {
+      const body = functionBody(blocks, m[1]);
+      obs.roleGuards.push({ ...l, where: 'use', name: m[1], defined: !!body });
+      if (body) obs.roleGuardDefined = true;
+    }
+  }
+  // one level of helper: a call whose definition is in the blocks and which scopes by the principal
+  for (const l of handler) {
+    for (const m of l.text.matchAll(/\b(find\w+|get\w+|load\w+)\s*\(/g)) {
+      const body = functionBody(blocks, m[1]);
+      if (!body) continue;
+      body.forEach((bl, i) => {
+        if (DATA.test(bl.text)) {
+          const st = statement(body, i);
+          obs.helperData = { ...bl, stmt: st };
+          if (OWNER_COL.test(st) && /\buser\.id\b|\bcurrent_user\b|\buser\.orgId\b/.test(st)) obs.helperScoping.push({ ...bl });
+        }
+      });
+    }
+  }
+  void dynamicUnresolved;
+  return obs;
+}
+
+function stripUntrustedKeepUser(t) { return stripUntrusted(t).replace(/""/g, '""'); }
+
+function cite(l, role, claim) { return { role, file: l.file, startLine: l.n, endLine: l.n, claim }; }
+
+/** A reader that cites a line says what is on it: the claim quotes the cited text, as a careful model would. */
+function quoteCited(obj, blocks) {
+  const text = (c) => {
+    for (const b of blocks) if (b.file === c.file) { const l = b.lines.find(x => x.n === c.startLine); if (l) return l.text.trim().slice(0, 100); }
+    return '';
+  };
+  const fix = (list) => (Array.isArray(list) ? list.map(c => ({ ...c, claim: `${c.claim}: ${text(c)}` })) : list);
+  return { ...obj, evidence: fix(obj.evidence), observedMitigations: fix(obj.observedMitigations) };
+}
+
+/** The decision for a pack, from the observations. Returns the review JSON object. */
+export function decide(packId, obs, ctx) {
+  const base = { observedMitigations: [], attackerControl: [], uncertainties: [], likelihood: 'low' };
+  if (packId === 'authz-idor') {
+    if (obs.capability) {
+      return { ...base, evidence: [cite(obs.capability, 'data-access', 'looked up by an unguessable token')], observedMitigations: [{ kind: 'other', file: obs.capability.file, startLine: obs.capability.n, endLine: obs.capability.n, claim: 'capability token lookup' }], conclusion: ctx.complete ? 'no_issue_observed' : 'insufficient_evidence', invariant: 'object selected by identifier must be scoped', narrative: 'access is by capability token', uncertainties: ctx.complete ? [] : ['context incomplete'] };
+    }
+    const data = obs.data[0] || (obs.helperData ? { ...obs.helperData } : null);
+    if (!obs.untrusted || !data) return { ...base, evidence: [], conclusion: 'insufficient_evidence', invariant: 'object selected by identifier must be scoped', uncertainties: ['no identifier-to-data path visible'] };
+    const scoped = obs.scoping.length || obs.helperScoping.length;
+    if (obs.writes.length && obs.lateScoping.length) {
+      const w = obs.writes[0]; const g = obs.lateScoping[0];
+      if (g.n > w.n) return { ...base, evidence: [cite(w, 'state-change', 'the write happens first'), cite(g, 'guard', 'the ownership check comes after it')], conclusion: 'potential_issue', invariant: 'object selected by identifier must be scoped before it is changed', narrative: 'the change is made before the owner is checked', attackerControl: ['req.params.id'], likelihood: 'high' };
+    }
+    if (obs.lateScoping.length && !obs.writes.length && obs.lateScoping[0].n >= data.n) {
+      return { ...base, evidence: [cite(data, 'data-access', 'fetch'), cite(obs.lateScoping[0], 'guard', 'owner check')], observedMitigations: [{ kind: 'ownership', file: obs.lateScoping[0].file, startLine: obs.lateScoping[0].n, endLine: obs.lateScoping[0].n, claim: 'owner compared with the principal and rejected before use' }], conclusion: ctx.complete ? 'no_issue_observed' : 'insufficient_evidence', invariant: 'object selected by identifier must be scoped', narrative: 'fetched, then checked before use' };
+    }
+    if (scoped) {
+      const s = obs.scoping[0] || obs.helperScoping[0];
+      return { ...base, evidence: [cite(data, 'data-access', 'query'), cite(s, 'guard', 'filter by principal')], observedMitigations: [{ kind: 'ownership', file: s.file, startLine: s.n, endLine: s.n, claim: 'query is filtered by the authenticated principal' }], conclusion: ctx.complete ? 'no_issue_observed' : 'insufficient_evidence', invariant: 'object selected by identifier must be scoped', narrative: 'id is combined with the principal in the query', uncertainties: ctx.complete ? [] : ['context incomplete'] };
+    }
+    if (ctx.unresolved) return { ...base, evidence: [], conclusion: 'insufficient_evidence', invariant: 'object selected by identifier must be scoped', uncertainties: ['an unresolved call could contain the scoping'] };
+    return { ...base, evidence: [cite(data, 'data-access', 'object fetched by a caller-controlled identifier')], conclusion: 'potential_issue', invariant: 'object selected by identifier must be scoped to the principal', narrative: 'the identifier flows into the query and nothing ties it to the caller', attackerControl: ['identifier'], likelihood: 'high' };
+  }
+  if (packId === 'authz-function') {
+    if (obs.dynamic && ctx.unresolved) return { ...base, evidence: [], conclusion: 'insufficient_evidence', invariant: 'privileged action needs a role check', uncertainties: ['the action is chosen at runtime'] };
+    if (obs.dynamic) return { ...base, evidence: [], conclusion: 'insufficient_evidence', invariant: 'privileged action needs a role check', uncertainties: ['the action is chosen at runtime'] };
+    const act = obs.writes[0] || obs.data[0];
+    if (!act) return { ...base, evidence: [], conclusion: 'insufficient_evidence', invariant: 'privileged action needs a role check', uncertainties: ['no privileged action visible'] };
+    const defined = obs.roleGuards.find(g => g.where === 'handler' || g.where === 'middleware' || (g.where === 'use' && g.defined));
+    if (defined) return { ...base, evidence: [cite(act, 'state-change', 'privileged change')], observedMitigations: [{ kind: 'role-check', file: defined.file, startLine: defined.n, endLine: defined.n, claim: 'role check precedes the action' }], conclusion: ctx.complete ? 'no_issue_observed' : 'insufficient_evidence', invariant: 'privileged action needs a role check', narrative: 'role check then action' };
+    if (obs.roleGuards.length) return { ...base, evidence: [], conclusion: 'insufficient_evidence', invariant: 'privileged action needs a role check', uncertainties: ['a role guard is named but its body is not shown'] };
+    if (ctx.unresolved) return { ...base, evidence: [], conclusion: 'insufficient_evidence', invariant: 'privileged action needs a role check', uncertainties: ['an unresolved call could contain the check'] };
+    return { ...base, evidence: [cite(act, 'state-change', 'privileged change with no role check')], conclusion: 'potential_issue', invariant: 'privileged action needs a role check', narrative: 'only authentication stands in front of the action', likelihood: 'high' };
+  }
+  if (packId === 'transaction-integrity') {
+    if (obs.writes.length >= 2 && !obs.transaction) return { ...base, evidence: [cite(obs.writes[0], 'state-change', 'first write'), cite(obs.writes[1], 'state-change', 'second write')], conclusion: 'potential_issue', invariant: 'dependent writes must be atomic', narrative: 'a failure between the two writes leaves them inconsistent' };
+    if (obs.writes.length >= 2 && obs.transaction) return { ...base, evidence: [cite(obs.writes[0], 'state-change', 'write')], observedMitigations: [{ kind: 'other', file: obs.writes[0].file, startLine: obs.writes[0].n, endLine: obs.writes[0].n, claim: 'writes run inside a transaction' }], conclusion: ctx.complete ? 'no_issue_observed' : 'insufficient_evidence', invariant: 'dependent writes must be atomic' };
+    return { ...base, evidence: [], conclusion: 'insufficient_evidence', invariant: 'dependent writes must be atomic' };
+  }
+  return { ...base, evidence: [], conclusion: 'insufficient_evidence', invariant: 'unspecified' };
+}
+
+/** The reader as an `llmInvoke`: prompt in, JSON text out. Handles both prompt formats. */
+export function scriptedReader() {
+  const invoke = async (prompt) => {
+    if (/^QUESTION PACK: /m.test(prompt)) {
+      const packId = /^QUESTION PACK: ([\w-]+)\//m.exec(prompt)[1];
+      const label = (/^ENTRY POINT LABEL \(data\): (.*)$/m.exec(prompt) || [])[1] || '';
+      const { blocks, unresolved, notIncluded, limit } = blocksFromReviewPrompt(prompt);
+      const routes = findRoutes(blocks);
+      const [method, ...rest] = label.split(' ');
+      const wantPath = rest.join(' ');
+      const route = routes.find(r => r.path === wantPath && (r.method === method || r.method === 'ALL')) || routes.find(r => r.path === wantPath) || routes[0];
+      if (!route) return JSON.stringify({ evidence: [], observedMitigations: [], conclusion: 'insufficient_evidence', invariant: 'unspecified', uncertainties: ['the registration is not in the provided context'] });
+      const obs = analyseRoute(route, blocks);
+      const complete = !unresolved && !notIncluded && !limit;
+      return JSON.stringify(quoteCited(decide(packId, obs, { complete, unresolved }), blocks));
+    }
+    // hunt prompt: report the candidates for the lens, with a location
+    const lens = /Your lens is ([\w ]+)\./.exec(prompt);
+    const lensTitle = lens ? lens[1].trim() : '';
+    const packId = lensTitle === 'Authorization' ? 'authz-idor' : lensTitle === 'Business logic' ? 'transaction-integrity' : null;
+    const blocks = blocksFromHuntPrompt(prompt);
+    const candidates = [];
+    if (packId) {
+      for (const route of findRoutes(blocks)) {
+        const obs = analyseRoute(route, blocks);
+        let d = decide(packId, obs, { complete: true, unresolved: false });
+        if (packId === 'authz-idor' && /(?:role|admin|users\/:id\/role|purge|jobs)/.test(route.path + obs.handler.map(l => l.text).join(' '))) {
+          const f = decide('authz-function', obs, { complete: true, unresolved: false });
+          if (f.conclusion === 'potential_issue') d = f;
+        }
+        if (d.conclusion === 'potential_issue' && d.evidence.length) {
+          const e = d.evidence[0];
+          candidates.push({ title: `${route.method} ${route.path}: ${d.invariant}`, file: e.file, line: e.startLine, rationale: d.narrative || '', entryPoint: `${route.method} ${route.path}`, sink: e.claim });
+        }
+      }
+    }
+    return JSON.stringify({ candidates });
+  };
+  invoke.tokenizerName = 'chars/4-estimate';
+  return invoke;
+}
+
+export function readerIdentity() {
+  return { kind: 'scripted-reader', version: 1, digest: crypto.createHash('sha256').update(scriptedReader.toString() + decide.toString() + analyseRoute.toString()).digest('hex').slice(0, 16), synthetic: true };
+}

package/src/context-intelligence/files.js

@@ -0,0 +1,80 @@
+//
+// Which files DCI analyses, and how they are read. Reading goes through `readRepoFile`, so a symlink, a file that
+// resolves outside the repository, or an oversized file is skipped with a counted reason, never followed.
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { listFiles } from '../util/glob.js';
+import { STATE_DIR_NAME } from '../posture/state-dir.js';
+import { readRepoFile, snapshotHashOf, normalizeText, safeRelPath } from './canonical.js';
+
+export const SOURCE_EXTS = /\.(?:js|jsx|mjs|cjs|ts|tsx|py|java|cs|kt|go|php|rb|rs|c|cc|cpp|h|hpp|l?hs|nix)$/i;
+export const IGNORE_GLOBS = ['node_modules/**', '.git/**', 'dist/**', 'build/**', 'vendor/**', '**/.agentic-security/**', 'dist-newstyle/**', '.stack-work/**', '.direnv/**', 'coverage/**', '**/*.min.js'];
+
+/** Read the analysable source set. Returns { ok, fileContents, skipped, snapshotHash } or { ok:false, reason }. */
+export async function readSnapshot(root, { maxFiles = 3000 } = {}) {
+  let rootReal;
+  try { rootReal = fs.realpathSync(root); } catch { return { ok: false, reason: 'root-not-found' }; }
+  const rels = (await listFiles(rootReal, { ignore: IGNORE_GLOBS })).filter(f => SOURCE_EXTS.test(f)).sort();
+  if (rels.length > maxFiles) return { ok: false, reason: 'too-many-files', count: rels.length, limit: maxFiles };
+  const fileContents = {};
+  const skipped = [];
+  for (const rel of rels) {
+    const r = readRepoFile(rootReal, rel);
+    if (r.ok) fileContents[rel] = r.text;
+    else skipped.push({ file: rel, reason: r.reason });
+  }
+  for (const l of findSymlinks(rootReal)) skipped.push({ file: l, reason: 'symlink' });
+  skipped.sort((a, b) => (a.file < b.file ? -1 : a.file > b.file ? 1 : 0));
+  return { ok: true, rootReal, fileContents, skipped, snapshotHash: snapshotHashOf(fileContents) };
+}
+
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'build', 'vendor', STATE_DIR_NAME, 'dist-newstyle', '.stack-work', '.direnv', 'coverage']);
+
+/** Symlinked source files and directories (never followed), so they are counted as skipped instead of vanishing. */
+function findSymlinks(rootReal, limit = 5000) {
+  const found = [];
+  let seen = 0;
+  const walk = (abs, rel) => {
+    let entries;
+    try { entries = fs.readdirSync(abs, { withFileTypes: true }); } catch { return; }
+    for (const e of entries) {
+      if (++seen > limit) return;
+      const r = rel ? `${rel}/${e.name}` : e.name;
+      if (e.isSymbolicLink()) { if (e.name.indexOf('.') === -1 || SOURCE_EXTS.test(e.name)) found.push(r); continue; }
+      if (e.isDirectory() && !SKIP_DIRS.has(e.name)) walk(path.join(abs, e.name), r);
+    }
+  };
+  walk(rootReal, '');
+  return found;
+}
+
+/**
+ * Read the analysable source set as it was at a git ref, without touching the working tree. `ref` is passed to git as a
+ * single argv element after `--end-of-options`-style validation, never through a shell. Returns the same shape as
+ * `readSnapshot`, or { ok:false, reason }.
+ */
+export function readGitSnapshot(root, ref, { maxFiles = 3000 } = {}) {
+  if (typeof ref !== 'string' || !/^[A-Za-z0-9._\/~^@{}:-]{1,200}$/.test(ref) || ref.startsWith('-')) return { ok: false, reason: 'bad-ref' };
+  let rootReal;
+  try { rootReal = fs.realpathSync(root); } catch { return { ok: false, reason: 'root-not-found' }; }
+  const git = (args, max = 64 * 1024 * 1024) => execFileSync('git', ['-C', rootReal, ...args], { encoding: 'utf8', timeout: 30000, maxBuffer: max, stdio: ['ignore', 'pipe', 'ignore'] });
+  let commit;
+  try { commit = git(['rev-parse', '--verify', `${ref}^{commit}`]).trim(); } catch { return { ok: false, reason: 'unknown-ref' }; }
+  let names;
+  try { names = git(['ls-tree', '-r', '--name-only', '-z', commit]).split('\0').filter(Boolean); } catch { return { ok: false, reason: 'ls-tree-failed' }; }
+  const ignore = IGNORE_GLOBS.map(g => new RegExp('^' + g.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*\*\//g, '(?:.*/)?').replace(/\*\*/g, '.*').replace(/\*/g, '[^/]*') + '$'));
+  const rels = names.filter(f => SOURCE_EXTS.test(f) && safeRelPath(f) === f && !ignore.some(re => re.test(f))).sort();
+  if (rels.length > maxFiles) return { ok: false, reason: 'too-many-files', count: rels.length, limit: maxFiles };
+  const fileContents = {};
+  const skipped = [];
+  for (const rel of rels) {
+    try {
+      const mode = git(['ls-tree', commit, '--', rel]).split(' ')[0];
+      if (mode === '120000' || mode === '160000') { skipped.push({ file: rel, reason: 'symlink-or-submodule' }); continue; }
+      const text = git(['show', `${commit}:${rel}`], 2 * 1024 * 1024);
+      fileContents[rel] = normalizeText(text);
+    } catch { skipped.push({ file: rel, reason: 'unreadable-at-ref' }); }
+  }
+  return { ok: true, rootReal, fileContents, skipped, snapshotHash: snapshotHashOf(fileContents), commit };
+}