@clear-capabilities/agentic-security-scanner 0.195.27 → 0.195.29

package/src/language/haskell-project-models.js

@@ -0,0 +1,107 @@
+// Declarative project models for Haskell wrappers (PRD FR 03).
+//
+// A wrapper the shipped registry does not know (a project's own `runQuery`, a vendored HTTP helper) can be declared in
+// `.agentic-security/haskell-models.json`. A suggestive function name is never enough: every model must carry provenance (who
+// reviewed it and why), the argument position it concerns, and a paired positive and negative test that exist in the scanned
+// source. A model that lacks any of these is rejected, with the reason, and has no effect on the scan.
+//
+// File shape:
+//   { "schema": "haskell-project-models/1",
+//     "models": [ { "id": "app-runquery", "role": "sink", "module": "App.Db", "name": "runQuery",
+//                   "family": "sql", "cwe": "CWE-89", "argIndex": 0,
+//                   "provenance": { "reviewer": "…", "reviewedAt": "2026-11-01", "reason": "…" },
+//                   "tests": { "positive": "test/RunQueryVuln.hs", "negative": "test/RunQuerySafe.hs" } } ] }
+//
+// Roles: `source` (its result is untrusted input), `sink` (argument `argIndex` is dangerous for `family`), `sanitizer`
+// (its result is safe for the families in `appliesTo`, and only those; `*` is not accepted).
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { statePath } from '../posture/state-dir.js';
+
+export const PROJECT_MODEL_SCHEMA = 'haskell-project-models/1';
+
+const FAMILIES = Object.freeze({
+  sql: 'CWE-89', cmd: 'CWE-78', path: 'CWE-22', ssrf: 'CWE-918', xss: 'CWE-79', log: 'CWE-532', code: 'CWE-94', redirect: 'CWE-601',
+});
+const SEVERITY = { sql: 'high', cmd: 'high', path: 'high', ssrf: 'high', xss: 'high', log: 'medium', code: 'critical', redirect: 'medium' };
+const MODULE_RE = /^[A-Z][A-Za-z0-9_']*(?:\.[A-Z][A-Za-z0-9_']*)*$/;
+const NAME_RE = /^[a-z_][A-Za-z0-9_']*$/;
+
+function check(m, exists) {
+  if (!m || typeof m !== 'object') return 'not an object';
+  if (!m.id || typeof m.id !== 'string') return 'missing id';
+  if (!['source', 'sink', 'sanitizer'].includes(m.role)) return `role must be source, sink or sanitizer, got ${JSON.stringify(m.role)}`;
+  if (!MODULE_RE.test(String(m.module || ''))) return 'module must be a qualified module name such as App.Db';
+  if (!NAME_RE.test(String(m.name || ''))) return 'name must be a function name';
+  const pv = m.provenance;
+  if (!pv || !pv.reviewer || !pv.reviewedAt || !pv.reason) return 'provenance needs reviewer, reviewedAt and reason: a function name alone is not a model';
+  const t = m.tests;
+  if (!t || !t.positive || !t.negative) return 'a paired positive and negative test is required';
+  if (t.positive === t.negative) return 'the positive and negative tests must be different files';
+  for (const k of ['positive', 'negative']) {
+    if (!exists(String(t[k]))) return `${k} test "${t[k]}" does not exist inside the project`;
+  }
+  if (m.role === 'sink') {
+    if (!FAMILIES[m.family]) return `family must be one of ${Object.keys(FAMILIES).join(', ')}`;
+    if (!(Number.isInteger(m.argIndex) && m.argIndex >= 0) && m.argIndex !== 'all') return 'a sink needs argIndex (a non-negative integer or "all")';
+  }
+  if (m.role === 'sanitizer') {
+    if (!Array.isArray(m.appliesTo) || !m.appliesTo.length) return 'a sanitizer needs appliesTo, the families it neutralises';
+    if (m.appliesTo.includes('*')) return 'a project sanitizer may not claim every family';
+    const bad = m.appliesTo.find((f) => !FAMILIES[f]);
+    if (bad) return `unknown family in appliesTo: ${bad}`;
+  }
+  if (m.role === 'source' && !m.label) return 'a source needs a label saying what it returns';
+  return null;
+}
+
+/** A predicate for 'this relative path is a regular file inside the project root'. */
+export function projectFileExists(scanRoot) {
+  const root = path.resolve(scanRoot);
+  return (rel) => {
+    try {
+      if (path.isAbsolute(rel)) return false;
+      const abs = path.resolve(root, rel);
+      if (abs !== root && !abs.startsWith(root + path.sep)) return false;
+      return fs.lstatSync(abs).isFile();
+    } catch { return false; }
+  };
+}
+
+/** Read the model file from the scan root (an exact path, never a traversal). Returns the parsed document or null. */
+export function readProjectModelFile(scanRoot) {
+  try {
+    const fp = statePath(scanRoot, 'haskell-models.json');
+    return JSON.parse(fs.readFileSync(fp, 'utf8'));
+  } catch { return null; }
+}
+
+/**
+ * @returns {{present: boolean, accepted: object[], rejected: {id: string, reason: string}[], catalog: object[]}}
+ */
+export function loadProjectModels(doc, exists = () => false) {
+  if (!doc) return { present: false, accepted: [], rejected: [], catalog: [] };
+  if (doc.schema !== PROJECT_MODEL_SCHEMA || !Array.isArray(doc.models)) {
+    return { present: true, accepted: [], rejected: [{ id: '(file)', reason: `expected schema ${PROJECT_MODEL_SCHEMA} with a models array` }], catalog: [] };
+  }
+  const accepted = []; const rejected = []; const seen = new Set();
+  for (const m of doc.models) {
+    const id = String(m && m.id || '(no id)');
+    const why = seen.has(id) ? 'duplicate id' : check(m, exists);
+    seen.add(id);
+    if (why) rejected.push({ id, reason: why }); else accepted.push(m);
+  }
+  const catalog = accepted.map((m) => {
+    const callee = `${m.module}.${m.name}`;
+    const base = { id: `hs-project-${m.id}`.toLowerCase(), language: 'hs', framework: 'haskell', match: { type: 'call', callee }, projectModel: m.id };
+    if (m.role === 'source') return { ...base, kind: 'source', label: m.label, provenance: 'project-model' };
+    if (m.role === 'sink') return {
+      ...base, kind: 'sink', argIndex: m.argIndex,
+      vuln: { name: m.vuln || `${m.family} sink (project model ${m.id})`, severity: SEVERITY[m.family], cwe: m.cwe || FAMILIES[m.family], remediation: m.remediation || 'See the project model that declares this wrapper.' },
+      hs: { family: m.family, shell: m.shell === true, argv: false, package: 'project', htmlSkeleton: false },
+    };
+    return { ...base, kind: 'sanitizer', effect: 'strip', appliesTo: m.appliesTo, note: `project model ${m.id}` };
+  });
+  return { present: true, accepted, rejected, catalog };
+}

package/src/language/nix-eval-isolation.js

@@ -69,7 +69,7 @@ const real = (p) => { try { return realpathSync(p); } catch { return resolve(p);
  * The sandboxed command for a backend. Reads are an ALLOWLIST (the listed roots, system library paths and the
  * evaluator); writes are an allowlist of one scratch directory; network and process creation are denied.
  * @param {{backend:string, path?:string}} sb
- * @param {{execFile:string, args:string[], readOnly:string[], readFiles?:string[], writable:string[], cwd:string}} spec
+ * @param {{execFile:string, args:string[], readOnly:string[], readFiles?:string[], writable:string[], cwd:string, env?:Record<string,string>}} spec
  */
 export function sandboxCommand(sb, spec) {
   const ro = [...new Set(spec.readOnly.map(real))];
@@ -92,34 +92,94 @@ export function sandboxCommand(sb, spec) {
     for (const p of ro) a.push('--ro-bind', p, p);
     for (const p of files) a.push('--ro-bind', p, p);
     for (const p of rw) a.push('--bind', p, p);
+    // --clearenv empties the environment bwrap itself was given, so the clean one is set explicitly inside.
+    for (const [k, v] of Object.entries(spec.env || {})) a.push('--setenv', k, String(v));
+    // Namespaces do not stop process creation; the seccomp filter does. Before it, a sandboxed process could spawn anything the
+    // read-only binds expose (found the first time a CI runner had bwrap installed). On an architecture with no filter there is
+    // none, and the probe then reports the spawn and refuses to evaluate.
+    const seccomp = seccompNoProcesses(sb.arch || process.arch);
+    if (seccomp) a.push('--seccomp', '3');
     a.push('--chdir', spec.cwd, exec, ...spec.args);
-    return { file: sb.path, args: a, profile: null };
+    return { file: sb.path, args: a, profile: null, fd3: seccomp };
   }
   return null;
 }
 
+// ── seccomp: threads yes, processes no ──────────────────────────────────────
+// A classic-BPF seccomp program, as `bwrap --seccomp FD` reads it (struct sock_filter, native little-endian). It denies fork and vfork,
+// denies clone unless CLONE_THREAD is set (so pthread_create works and posix_spawn, fork and vfork through clone do not), answers clone3
+// with ENOSYS (its flags are behind a pointer a filter cannot read; glibc then falls back to clone), denies x32 syscalls, and kills a
+// process that switches to another syscall ABI.
+const SECCOMP_ARCH = {
+  x64: { audit: 0xc000003e, clone: 56, clone3: 435, deny: [57, 58], x32: true },
+  arm64: { audit: 0xc00000b7, clone: 220, clone3: 435, deny: [], x32: false },
+};
+const CLONE_THREAD = 0x10000;
+export function seccompNoProcesses(arch) {
+  const A = SECCOMP_ARCH[arch];
+  if (!A) return null;
+  const LD = 0x20, JEQ = 0x15, JGE = 0x35, JSET = 0x45, RET = 0x06;
+  const ALLOW = 0x7fff0000, EPERM = 0x00050000 | 1, ENOSYS = 0x00050000 | 38, KILL = 0x80000000;
+  // Instructions with symbolic jump targets, resolved to relative offsets below.
+  const prog = [
+    [LD, 0, 0, 4],                                         // arch
+    [JEQ, null, 'kill', A.audit],
+    [LD, 0, 0, 0],                                         // syscall number
+    ...(A.x32 ? [[JGE, 'eperm', null, 0x40000000]] : []),
+    [JEQ, 'enosys', null, A.clone3],
+    ...A.deny.map((nr) => [JEQ, 'eperm', null, nr]),
+    [JEQ, null, 'allow', A.clone],
+    [LD, 0, 0, 16],                                        // clone flags, args[0] low word
+    [JSET, 'allow', 'eperm', CLONE_THREAD],
+    ['allow', RET, ALLOW], ['eperm', RET, EPERM], ['enosys', RET, ENOSYS], ['kill', RET, KILL],
+  ];
+  const at = {};
+  prog.forEach((ins, i) => { if (typeof ins[0] === 'string') at[ins[0]] = i; });
+  const buf = Buffer.alloc(prog.length * 8);
+  prog.forEach((ins, i) => {
+    const [code, jt, jf, k] = typeof ins[0] === 'string' ? [ins[1], 0, 0, ins[2]] : ins;
+    const rel = (t) => (t === null || t === 0 ? 0 : at[t] - i - 1);
+    buf.writeUInt16LE(code, i * 8); buf.writeUInt8(rel(jt), i * 8 + 2); buf.writeUInt8(rel(jf), i * 8 + 3); buf.writeUInt32LE(k >>> 0, i * 8 + 4);
+  });
+  return buf;
+}
+
 // ── process supervisor ───────────────────────────────────────────────────────
-function rssOfGroup(pgid) {
-  const r = spawnSync('/bin/ps', ['-o', 'rss=', '-g', String(pgid)], { encoding: 'utf8', timeout: 2000 });
+// The memory of the whole process tree under `root`, in MB. Not the process group: bwrap's --new-session puts the sandboxed process in
+// a session and group of its own, so a group sum never saw the evaluator on Linux.
+function rssOfTree(root) {
+  const r = spawnSync('/bin/ps', ['-A', '-o', 'pid=,ppid=,rss='], { encoding: 'utf8', timeout: 2000 });
   if (r.status !== 0) return 0;
-  return r.stdout.split('\n').map((x) => parseInt(x, 10)).filter(Number.isFinite).reduce((a, b) => a + b, 0) / 1024;
+  const kids = new Map(); const rss = new Map();
+  for (const line of r.stdout.split('\n')) {
+    const [pid, ppid, kb] = line.trim().split(/\s+/).map((x) => parseInt(x, 10));
+    if (!Number.isFinite(pid) || !Number.isFinite(ppid)) continue;
+    rss.set(pid, Number.isFinite(kb) ? kb : 0);
+    if (!kids.has(ppid)) kids.set(ppid, []);
+    kids.get(ppid).push(pid);
+  }
+  let total = 0; const seen = new Set(); const stack = [root];
+  while (stack.length) { const p = stack.pop(); if (seen.has(p)) continue; seen.add(p); total += rss.get(p) || 0; stack.push(...(kids.get(p) || [])); }
+  return total / 1024;
 }
 function killGroup(pid, sig) { try { process.kill(-pid, sig); } catch { try { process.kill(pid, sig); } catch { /* gone */ } } }
 
 /** Run a command to completion under a deadline, an output cap and a memory ceiling. Never throws. */
-export function supervise(file, args, { env, cwd, deadlineMs, maxOutputBytes, maxRssMb, killGraceMs = 1500 }) {
+export function supervise(file, args, { env, cwd, deadlineMs, maxOutputBytes, maxRssMb, killGraceMs = 1500, fd3 = null }) {
   return new Promise((resolveP) => {
     const t0 = Date.now();
     let child;
-    try { child = spawn(file, args, { env, cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe'] }); }
+    try { child = spawn(file, args, { env, cwd, detached: true, stdio: ['ignore', 'pipe', 'pipe', ...(fd3 ? ['pipe'] : [])] }); }
     catch (e) { return resolveP({ status: 'failed', reason: `could not start: ${e.message}`, stdout: '', stderr: '', exitCode: null, signal: null, ms: 0 }); }
+    // fd 3 carries the seccomp program to bwrap; a child that exits before reading it closes the pipe, which is not an error here.
+    if (fd3) { child.stdio[3].on('error', () => {}); child.stdio[3].end(fd3); }
     let out = ''; let err = ''; let bytes = 0; let state = null; let done = false;
     const finish = (extra = {}) => { if (done) return; done = true; clearInterval(poll); clearTimeout(dl); resolveP({ stdout: out, stderr: err.slice(0, 4000), ms: Date.now() - t0, ...extra }); };
     const stop = (why) => { if (state) return; state = why; killGroup(child.pid, 'SIGTERM'); setTimeout(() => killGroup(child.pid, 'SIGKILL'), killGraceMs).unref(); };
     child.stdout.on('data', (d) => { bytes += d.length; if (bytes > maxOutputBytes) { stop('output-limit'); return; } out += d.toString('utf8'); });
     child.stderr.on('data', (d) => { if (err.length < 8000) err += d.toString('utf8'); });
     const dl = setTimeout(() => stop('timed-out'), deadlineMs);
-    const poll = setInterval(() => { if (!state && maxRssMb && rssOfGroup(child.pid) > maxRssMb) stop('resource-limit'); }, 250);
+    const poll = setInterval(() => { if (!state && maxRssMb && rssOfTree(child.pid) > maxRssMb) stop('resource-limit'); }, 250);
     child.on('error', (e) => finish({ status: 'failed', reason: e.message, exitCode: null, signal: null }));
     child.on('close', (code, signal) => {
       killGroup(child.pid, 'SIGKILL');                                          // reap any descendants
@@ -197,8 +257,8 @@ export async function probeSandbox(sb, opts = {}) {
   const port = tcp.address().port;
   try {
     const exe = opts.nodePath || process.execPath;
-    const cmd = sandboxCommand(sb, { execFile: exe, args: [script, join(allowed, 'a.txt'), join(outside, 'secret.txt'), join(outside, 'w.txt'), join(scratch, 'w.txt'), String(port), sockPath], readOnly: [allowed, dirname(dirname(real(exe)))], readFiles: [script], writable: [scratch], cwd: scratch });
-    const r = await supervise(cmd.file, cmd.args, { env: cleanEnv(scratch), cwd: scratch, deadlineMs: limits.probeDeadlineMs, maxOutputBytes: 64 * 1024, maxRssMb: limits.maxRssMb, killGraceMs: limits.killGraceMs });
+    const cmd = sandboxCommand(sb, { env: cleanEnv(scratch), execFile: exe, args: [script, join(allowed, 'a.txt'), join(outside, 'secret.txt'), join(outside, 'w.txt'), join(scratch, 'w.txt'), String(port), sockPath], readOnly: [allowed, dirname(dirname(real(exe)))], readFiles: [script], writable: [scratch], cwd: scratch });
+    const r = await supervise(cmd.file, cmd.args, { fd3: cmd.fd3, env: cleanEnv(scratch), cwd: scratch, deadlineMs: limits.probeDeadlineMs, maxOutputBytes: 64 * 1024, maxRssMb: limits.maxRssMb, killGraceMs: limits.killGraceMs });
     let attempts = null;
     try { attempts = JSON.parse(r.stdout.trim()); } catch { /* unparseable: not verified */ }
     if (!attempts) return { verified: false, backend: sb.backend, reason: `the probe did not complete inside the sandbox (${r.reason || r.stderr.slice(0, 120) || 'no output'})`, attempts: {} };
@@ -221,8 +281,8 @@ export async function probeSandbox(sb, opts = {}) {
 /** @param {{file:string, prefixArgs?:string[]}} nix  the evaluator command (a stand-in in tests) */
 export async function detectEvaluator(nix, sb, ctx) {
   const run = async (args) => {
-    const cmd = sandboxCommand(sb, { execFile: nix.file, args: [...(nix.prefixArgs || []), ...args], readOnly: ctx.readOnly, readFiles: [...(ctx.readFiles || []), ...(nix.prefixArgs || []).filter((a) => !a.startsWith('-'))], writable: [ctx.work], cwd: ctx.work });
-    return supervise(cmd.file, cmd.args, { env: cleanEnv(ctx.work), cwd: ctx.work, deadlineMs: 10_000, maxOutputBytes: 64 * 1024, maxRssMb: ctx.limits.maxRssMb, killGraceMs: ctx.limits.killGraceMs });
+    const cmd = sandboxCommand(sb, { env: cleanEnv(ctx.work), execFile: nix.file, args: [...(nix.prefixArgs || []), ...args], readOnly: ctx.readOnly, readFiles: [...(ctx.readFiles || []), ...(nix.prefixArgs || []).filter((a) => !a.startsWith('-'))], writable: [ctx.work], cwd: ctx.work });
+    return supervise(cmd.file, cmd.args, { fd3: cmd.fd3, env: cleanEnv(ctx.work), cwd: ctx.work, deadlineMs: 10_000, maxOutputBytes: 64 * 1024, maxRssMb: ctx.limits.maxRssMb, killGraceMs: ctx.limits.killGraceMs });
   };
   const v = await run(['--version']);
   const ver = (/(\d+\.\d+(?:\.\d+)?)/.exec(v.stdout) || [])[1] || null;
@@ -276,8 +336,8 @@ export async function runIsolatedEval(o) {
     const feat = await detectEvaluator(o.nix, sb, ctx);
     if (!feat.ok) return stopBefore('unsupported', `${feat.reason}; the project's Nix code was NOT evaluated`, { sandbox: sb, probe: { verified: true }, evaluator: feat });
     const args = [...(o.nix.prefixArgs || []), ...buildEvalArgs(target)];
-    const cmd = sandboxCommand(sb, { execFile: o.nix.file, args, readOnly: ctx.readOnly, readFiles: nixFiles, writable: [ctx.work], cwd: ctx.work });
-    const r = await supervise(cmd.file, cmd.args, { env: cleanEnv(ctx.work, o.env || {}), cwd: ctx.work, deadlineMs: limits.deadlineMs, maxOutputBytes: limits.maxOutputBytes, maxRssMb: limits.maxRssMb, killGraceMs: limits.killGraceMs });
+    const cmd = sandboxCommand(sb, { env: cleanEnv(ctx.work, o.env || {}), execFile: o.nix.file, args, readOnly: ctx.readOnly, readFiles: nixFiles, writable: [ctx.work], cwd: ctx.work });
+    const r = await supervise(cmd.file, cmd.args, { fd3: cmd.fd3, env: cleanEnv(ctx.work, o.env || {}), cwd: ctx.work, deadlineMs: limits.deadlineMs, maxOutputBytes: limits.maxOutputBytes, maxRssMb: limits.maxRssMb, killGraceMs: limits.killGraceMs });
     const base = { ...keep, projectCodeEvaluated: true, sandbox: { backend: sb.backend }, evaluator: { version: feat.version }, ms: r.ms, target: { attribute: target.attribute, system: target.system, installable: target.installable } };
     if (r.status !== 'ok') return { ...base, status: r.status === 'failed' ? 'failed' : r.status, reason: r.reason || r.stderr.slice(0, 200) };
     let data;

package/src/llm-validator/bounded-context.js

@@ -0,0 +1,193 @@
+// Bounded context for model-assisted validation (PRD FR 05 "required validation flow").
+//
+// The model is shown numbered spans, each with an id (S1, S2, ...), a role and exact file and line bounds: the code around the
+// finding, the source and sink when they lie outside it, each traced path step, and the related files on a Haskell/Nix evidence
+// chain. It is asked to cite the span lines its verdict rests on. A citation is checked against the spans actually sent:
+//
+//   valid    every citation names a span and a line inside it
+//   none     the reply cited nothing (recorded; the verdict is kept, and the disposition lists the missing citation)
+//   invalid  a citation names a span or a line that was not sent: the model reasoned about code it was not shown, so the reply
+//            is not used (the caller turns it into `escalate`)
+//
+// Callers and configuration are collected by name, and the prompt says so:
+//
+//   callers        the nearest function definition above the finding, then call sites of that name in scanned files of the same
+//                  language. Matched by name, not resolved through imports or dispatch: a same-named function can appear, and
+//                  calls through aliases, callbacks or dynamic dispatch are missed.
+//   configuration  environment keys read in the finding's span, then the scanned configuration files that set them. Dotenv files
+//                  other than examples are never read, and the value of a secret-like key is masked before redaction.
+//
+// What is not collected is stated in `gaps`, never implied.
+
+import { languagePromptExtras } from '../language/context.js';
+
+const lineOf = (x) => (x && Number.isInteger(x.line) && x.line > 0 ? x.line : null);
+
+/**
+ * @returns {{spans:{id:string, role:string, file:string, start:number, end:number, text:string}[], gaps:string[]}}
+ */
+export function collectBoundedContext(finding, fileContents, { window = 20, stepWindow = 3, maxSpans = 10, maxCallers = 3, maxConfig = 2 } = {}) {
+  const raw = [];
+  const gaps = [];
+  const add = (role, file, line, w, mask = null) => {
+    const code = fileContents && typeof fileContents[file] === 'string' ? fileContents[file] : null;
+    if (code === null) { gaps.push(`${role} file ${file} was not available`); return; }
+    const lines = mask ? code.split('\n').map(mask) : code.split('\n');
+    const start = Math.max(1, line - w);
+    const end = Math.min(lines.length, line + w);
+    if (start > end) return;
+    raw.push({ role, file, start, end, lines });
+  };
+  if (finding && finding.file && lineOf(finding)) add('finding', finding.file, finding.line, window);
+  const src = finding && finding.source; const snk = finding && finding.sink;
+  if (lineOf(src)) add('source', src.file || finding.file, src.line, stepWindow);
+  if (lineOf(snk)) add('sink', snk.file || finding.file, snk.line, stepWindow);
+  for (const step of Array.isArray(finding && finding.path) ? finding.path : []) {
+    if (lineOf(step)) add('path-step', step.file || finding.file, step.line, stepWindow);
+  }
+  if (finding && finding.file && lineOf(finding) && typeof (fileContents || {})[finding.file] === 'string') {
+    collectCallers(finding, fileContents, { maxCallers, stepWindow, add, gaps });
+    collectConfiguration(finding, fileContents, { window, maxConfig, add, gaps });
+  } else {
+    gaps.push('the finding has no readable source line, so callers and configuration were not collected');
+  }
+  // Merge spans that overlap or touch in the same file; the first role stays, the others are kept as `alsoRoles`.
+  const merged = [];
+  for (const s of raw) {
+    const hit = merged.find((m) => m.file === s.file && s.start <= m.end + 1 && s.end >= m.start - 1);
+    if (hit) { hit.start = Math.min(hit.start, s.start); hit.end = Math.max(hit.end, s.end); if (hit.role !== s.role && !hit.alsoRoles.includes(s.role)) hit.alsoRoles.push(s.role); continue; }
+    merged.push({ ...s, alsoRoles: [] });
+  }
+  const spans = merged.slice(0, maxSpans).map((m, i) => ({
+    id: `S${i + 1}`, role: m.role, ...(m.alsoRoles.length ? { alsoRoles: m.alsoRoles } : {}), file: m.file, start: m.start, end: m.end,
+    text: m.lines.slice(m.start - 1, m.end).map((l, k) => `${m.start + k}: ${l}`).join('\n'),
+  }));
+  if (merged.length > maxSpans) gaps.push(`${merged.length - maxSpans} span(s) beyond the first ${maxSpans} were not sent`);
+  try {
+    for (const x of languagePromptExtras(finding, fileContents)) {
+      const n = x.text.split('\n').length;
+      spans.push({ id: `S${spans.length + 1}`, role: 'related', file: x.file, start: x.startLine, end: x.startLine + n - 1, text: x.text });
+    }
+  } catch { /* related excerpts are advisory */ }
+  if (!spans.length) gaps.push('no source text was available for the finding');
+  gaps.push('deployment configuration outside the repository (environment, secrets stores, cloud policy) was not collected');
+  return { spans, gaps };
+}
+
+// ── callers ─────────────────────────────────────────────────────────────────
+const NOT_A_NAME = new Set(['if', 'for', 'while', 'switch', 'catch', 'return', 'function', 'else', 'do', 'try', 'new', 'typeof', 'await',
+  'with', 'sizeof', 'elif', 'except', 'when', 'match', 'case', 'super', 'this', 'self', 'import', 'require', 'where', 'let', 'in']);
+// Lines carrying a CWE-1333 pragma: bounded by MAX_DEF_LINE below, so the polynomial worst case is capped per line.
+const LANGS = [
+  { ext: /\.(?:js|jsx|ts|tsx|mjs|cjs)$/i, defs: [/\bfunction\s*\*?\s*([A-Za-z_$][\w$]*)\s*\(/, /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:function\b|\([^)]*\)\s*=>|[A-Za-z_$][\w$]*\s*=>)/, /^\s*(?:(?:public|private|protected|static|async|get|set)\s+)*([A-Za-z_$][\w$]*)\s*\([^)]*\)\s*\{/] }, // agentic-security-ignore: CWE-1333
+  { ext: /\.py$/i, defs: [/^\s*(?:async\s+)?def\s+([A-Za-z_]\w*)\s*\(/] },
+  { ext: /\.rb$/i, defs: [/^\s*def\s+(?:self\.)?([A-Za-z_]\w*[?!]?)/] },
+  { ext: /\.go$/i, defs: [/^func\s+(?:\([^)]*\)\s*)?([A-Za-z_]\w*)\s*[[(]/] },
+  { ext: /\.rs$/i, defs: [/\bfn\s+([A-Za-z_]\w*)/] },
+  { ext: /\.php$/i, defs: [/\bfunction\s+([A-Za-z_]\w*)\s*\(/] },
+  { ext: /\.(?:java|kt|kts|cs|scala)$/i, defs: [/^\s*(?:(?:public|private|protected|internal|static|final|override|suspend|async|virtual|abstract|synchronized|open)\s+)*(?:fun\s+|def\s+)?(?:[\w<>\[\],.?]+\s+)?([A-Za-z_]\w*)\s*\([^;]*$/] }, // agentic-security-ignore: CWE-1333
+  { ext: /\.hs$/i, defs: [/^([a-z_][\w']*)\s*::/, /^([a-z_][\w']*)\b[^=\n]*=/], bare: true },
+];
+const langOf = (file) => LANGS.find((l) => l.ext.test(file)) || null;
+const escapeRe = (x) => x.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+// The definition patterns run over scanned (untrusted) source. None backtracks exponentially, but the modifier and type groups can go
+// quadratic on a long line, so a line longer than any real definition header is never matched.
+const MAX_DEF_LINE = 400;
+const defName = (lang, line) => {
+  if (line.length > MAX_DEF_LINE) return null;
+  for (const re of lang.defs) { const m = re.exec(line); if (m && !NOT_A_NAME.has(m[1])) return m[1]; }
+  return null;
+};
+
+/** The nearest function definition at or above `line` (1-based), within 400 lines. */
+export function enclosingFunction(file, code, line) {
+  const lang = langOf(file);
+  if (!lang) return null;
+  const lines = code.split('\n');
+  for (let i = Math.min(line, lines.length) - 1; i >= 0 && i >= line - 400; i--) {
+    const name = defName(lang, lines[i]);
+    if (name) return { name, line: i + 1 };
+  }
+  return null;
+}
+
+function collectCallers(finding, fileContents, { maxCallers, stepWindow, add, gaps }) {
+  const lang = langOf(finding.file);
+  const fn = lang ? enclosingFunction(finding.file, fileContents[finding.file], finding.line) : null;
+  if (!fn) { gaps.push('the enclosing function could not be determined, so callers were not collected'); return; }
+  const call = lang.bare ? new RegExp(`(?<![\\w'.])${escapeRe(fn.name)}(?![\\w'])`) : new RegExp(`(?<![\\w$])${escapeRe(fn.name)}\\s*\\(`);
+  const sites = [];
+  for (const [file, code] of Object.entries(fileContents)) {
+    if (typeof code !== 'string' || code.length > 1_000_000 || !lang.ext.test(file) || !code.includes(fn.name)) continue;
+    code.split('\n').forEach((text, i) => {
+      if (!call.test(text) || defName(lang, text) === fn.name) return;               // the definition (or a signature) is not a call
+      if (file === finding.file && i + 1 >= fn.line && i + 1 <= finding.line) return;  // recursion inside the finding's own function
+      sites.push({ file, line: i + 1 });
+    });
+  }
+  if (!sites.length) {
+    gaps.push(`no call site of ${fn.name} was found by name in the scanned files of the same language (it may be an entry point, exported, or called dynamically)`);
+    return;
+  }
+  for (const s of sites.slice(0, maxCallers)) add('caller', s.file, s.line, stepWindow);
+  gaps.push(`callers of ${fn.name} were matched by name, not resolved: a same-named function can appear, and calls through aliases, callbacks or dynamic dispatch are missed`);
+  if (sites.length > maxCallers) gaps.push(`${sites.length - maxCallers} further call site(s) of ${fn.name} were not sent`);
+}
+
+// ── configuration ───────────────────────────────────────────────────────────
+const ENV_READS = [
+  /process\.env\.([A-Za-z_][\w]*)/g, /process\.env\[\s*['"]([^'"]+)['"]\s*\]/g, /os\.environ(?:\.get)?\s*[[(]\s*['"]([^'"]+)['"]/g,
+  /\bgetenv\(\s*['"]([^'"]+)['"]/g, /\b(?:getEnv|lookupEnv)\s+"([^"]+)"/g, /System\.getenv\(\s*"([^"]+)"/g,
+  /\bENV(?:\.fetch\(\s*|\[\s*)['"]([^'"]+)['"]/g, /os\.(?:Getenv|LookupEnv)\(\s*"([^"]+)"/g, /env::var\(\s*"([^"]+)"/g,
+];
+const CONFIG_FILE = /(?:^|\/)(?:\.env\.(?:example|sample|template|dist)|[^/]+\.(?:ya?ml|toml|ini|conf|cfg|properties|nix)|docker-compose[^/]*|Dockerfile[^/]*|app\.json)$/i;
+const SECRET_KEY = /secret|token|passw|pwd|credential|private|api[_-]?key|auth/i;
+// Masks the value of a secret-like key; the generic redaction then runs over the whole span.
+const maskSecretValues = (text) => text.replace(/^(\s*(?:export\s+|-\s+)?["']?([\w.-]+)["']?\s*[:=]\s*)(.+)$/, (all, head, key) => (SECRET_KEY.test(key) ? `${head}<masked>` : all));
+
+function collectConfiguration(finding, fileContents, { window, maxConfig, add, gaps }) {
+  const lines = fileContents[finding.file].split('\n');
+  const span = lines.slice(Math.max(0, finding.line - 1 - window), finding.line + window).join('\n');
+  const keys = new Set();
+  for (const re of ENV_READS) for (const m of span.matchAll(re)) keys.add(m[1]);
+  if (!keys.size) { gaps.push("no configuration key is read near the finding, so no configuration file was collected"); return; }
+  const found = new Set(); let sent = 0; let more = 0;
+  for (const [file, code] of Object.entries(fileContents)) {
+    if (typeof code !== 'string' || !CONFIG_FILE.test(file) || code.length > 500_000) continue;
+    const cl = code.split('\n');
+    for (const key of keys) {
+      const re = new RegExp(`(?<![\\w])${escapeRe(key)}(?![\\w])`);
+      const i = cl.findIndex((t) => re.test(t));
+      if (i < 0) continue;
+      found.add(key);
+      if (sent < maxConfig) { add('configuration', file, i + 1, 1, maskSecretValues); sent++; } else more++;
+    }
+  }
+  const missing = [...keys].filter((k) => !found.has(k)).sort();
+  if (missing.length) gaps.push(`configuration key(s) ${missing.join(', ')} read near the finding are set in no scanned configuration file (they may be set at deploy time)`);
+  if (more) gaps.push(`${more} further configuration match(es) were not sent`);
+}
+
+/** Render spans as the untrusted excerpt block. */
+export function renderSpans(spans) {
+  return spans.map((s) => `[${s.id} ${s.role}${s.alsoRoles ? `+${s.alsoRoles.join('+')}` : ''}] ${s.file}:${s.start}-${s.end}\n${s.text}`).join('\n\n');
+}
+
+/** Check a reply's citations against the spans that were sent. */
+export function checkCitations(citations, spans) {
+  if (citations === undefined || citations === null || (Array.isArray(citations) && citations.length === 0)) return { status: 'none', resolved: [], invalid: [] };
+  if (!Array.isArray(citations)) return { status: 'invalid', resolved: [], invalid: [String(citations).slice(0, 40)] };
+  const byId = new Map(spans.map((s) => [s.id, s]));
+  const resolved = []; const invalid = [];
+  for (const c of citations.slice(0, 20)) {
+    const m = /^\s*(S\d+)\s*:\s*(\d+)\s*$/.exec(String(c));
+    const s = m && byId.get(m[1]);
+    const line = m ? Number(m[2]) : NaN;
+    if (s && line >= s.start && line <= s.end) resolved.push({ span: s.id, file: s.file, line });
+    else invalid.push(String(c).slice(0, 40));
+  }
+  return { status: invalid.length ? 'invalid' : 'valid', resolved, invalid };
+}
+
+/** The span list as recorded on a finding: bounds and roles, never the text. */
+export const spanRecord = (spans) => spans.map(({ text, ...rest }) => rest);

package/src/llm-validator/claim-groups.js

@@ -0,0 +1,105 @@
+// Equivalent detector claims (PRD FR 05 validation flow, FR 07 "group multiple detector claims without merging independent sinks").
+//
+// Two detectors often report the same weakness at the same place: a regex rule and a language analyzer both see `pickle.loads(x)`,
+// a structural rule and a password-hash rule both see `createHash('md5')` on a password. Shown twice, one weakness is counted twice
+// and reviewed twice. Grouped, it is one actionable result that names every detector that found it.
+//
+// Claims are equivalent only when ALL of these hold:
+//   - same report category (kind), same file, same integer line, same CWE
+//   - neither is a composite (chain) claim
+//   - different detectors (parser). Two claims from ONE detector at one line are two findings it chose to emit (two calls, two
+//     sources), so they are never merged here.
+//   - neither names a sink line the other contradicts (independent sinks stay apart)
+//   - neither is a dependency finding
+// The primary is the claim that locates the most of the path (source and sink, then the sink alone), then one the IR taint engine
+// produced over a lexical rule, then the highest severity, then the lowest id, so the choice is deterministic. Nothing is deleted: every grouped claim is returned for the raw export, pointing at its primary.
+
+const SEV = { critical: 4, high: 3, medium: 2, low: 1, info: 0 };
+
+// A composite claim (an attack chain, an agent chain) asserts that several weaknesses combine; it is never the same claim as one of
+// its hops, even where it is anchored on that hop's line.
+const isComposite = (f) => Array.isArray(f.chain) || f.parser === 'CHAIN' || /chain/i.test(String(f.family || ''));
+
+function groupKey(f) {
+  if (!f || typeof f !== 'object' || f.kind === 'sca' || f.type === 'vulnerable_dep' || isComposite(f)) return null;
+  if (!Number.isInteger(f.line) || f.line <= 0 || !f.file || !f.cwe) return null;
+  return `${f.kind || 'sast'}\0${f.file}\0${f.line}\0${f.cwe}`;
+}
+
+// How much of the path a claim locates (both ends, the sink alone, or neither), then whether the IR taint engine located it
+// (semantic) or a lexical rule did. A reviewer starts from the claim that points at the most code.
+const IR_TRACED = new Set(['IR-TAINT', 'MULTI-SINK', 'IR-PRIVACY-TAINT']);
+const located = (f) => (f.source && f.sink ? 2 : f.sink ? 1 : 0);
+
+function rank(a, b) {
+  const l = located(b) - located(a);
+  if (l) return l;
+  const p = (IR_TRACED.has(b.parser) ? 1 : 0) - (IR_TRACED.has(a.parser) ? 1 : 0);
+  if (p) return p;
+  const s = (SEV[b.severity] ?? -1) - (SEV[a.severity] ?? -1);
+  if (s) return s;
+  return String(a.stableId || a.id || '').localeCompare(String(b.stableId || b.id || ''));
+}
+
+const sinkLine = (f) => (f.sink && Number.isInteger(f.sink.line) ? f.sink.line : null);
+
+const claimOf = (f) => ({ id: f.id ?? null, stableId: f.stableId ?? null, parser: f.parser ?? null, vuln: f.vuln ?? null, severity: f.severity ?? null });
+
+/**
+ * Group equivalent claims. Returns { kept, grouped, groups } where `kept` is the input order with grouped members removed, `grouped`
+ * holds each removed claim (annotated `groupedInto`), and `groups` counts the groups formed. The primary gains `claims` (every
+ * claim in its group, itself first). Severity and confidence are never changed.
+ */
+export function groupEquivalentClaims(findings) {
+  const list = Array.isArray(findings) ? findings : [];
+  const byKey = new Map();
+  for (const f of list) {
+    const k = groupKey(f);
+    if (k === null) continue;
+    if (!byKey.has(k)) byKey.set(k, []);
+    byKey.get(k).push(f);
+  }
+  const drop = new Set();
+  const grouped = [];
+  let groups = 0;
+  for (const members of byKey.values()) {
+    if (members.length < 2) continue;
+    const sorted = [...members].sort(rank);
+    const primary = sorted[0];
+    const taken = [primary];
+    const seenParsers = new Set([primary.parser]);
+    for (const m of sorted.slice(1)) {
+      if (seenParsers.has(m.parser)) continue;
+      const a = sinkLine(primary); const b = sinkLine(m);
+      if (a !== null && b !== null && a !== b) continue;
+      seenParsers.add(m.parser);
+      taken.push(m);
+    }
+    if (taken.length < 2) continue;
+    groups++;
+    primary.claims = taken.map(claimOf);
+    for (const m of taken.slice(1)) {
+      m.groupedInto = primary.stableId || primary.id || null;
+      drop.add(m);
+      grouped.push(m);
+    }
+  }
+  return { kept: list.filter((f) => !drop.has(f)), grouped, groups };
+}
+
+/**
+ * One reconciliation of the candidate counts, so no candidate is counted twice:
+ *   raw = grouped + refuted + (confirmed + needs-review + hardening + unvalidated)
+ * `suppressed` counts candidates removed before this stage (pragmas, rules, accepted risk); it is reported beside raw, not inside it.
+ */
+export function reconcileCounts({ raw, grouped, refuted, dispositionCounts, suppressed = 0 }) {
+  const d = dispositionCounts || {};
+  const active = ['confirmed', 'needs-review', 'hardening', 'unvalidated'].reduce((n, k) => n + (d[k] || 0), 0);
+  const out = {
+    raw, grouped, refuted, deduplicated: raw - grouped,
+    confirmed: d.confirmed || 0, needsReview: d['needs-review'] || 0, hardening: d.hardening || 0, unvalidated: d.unvalidated || 0,
+    suppressedBeforeValidation: suppressed,
+  };
+  out.balanced = raw === grouped + refuted + active;
+  return out;
+}