@clear-capabilities/agentic-security-scanner 0.195.26 → 0.195.28

package/src/posture/rule-compiler/negative-corpus.js

@@ -0,0 +1,39 @@
+// The shared negative corpus shipped with the scanner (GA-07 §3, 0.195.27): safe, idiomatic code that no promoted rule may fire
+// on, the same on every machine and in every repository. `regression.js` puts it in front of the shared false-positive corpus, so
+// `rules evaluate`, `rules promote` and `rules regress` all hold a rule to it; a rule that fires on any entry is refused at
+// evaluation and reported as regressed later, wherever it runs.
+//
+// Each entry is the SAFE side of a pattern the compiler is likely to be asked to detect: a parameterised query beside the
+// concatenated one, an argument-vector process spawn beside the shell string, a constant-time comparison beside the plain one.
+// They are plain strings in a module (not files on disk) so the bundle carries them without a build step and the corpus is
+// identical wherever the scanner runs. Keep every entry free of the unsafe form: a vulnerable snippet here would make a correct
+// rule fail its gate.
+export const SHIPPED_NEGATIVE_CORPUS = Object.freeze([
+  { name: 'js-parameterised-query', language: 'javascript', code: 'const rows = await db.query("SELECT * FROM orders WHERE owner = $1", [ownerId]);\n' },
+  { name: 'js-placeholder-query', language: 'javascript', code: 'const [row] = await conn.execute("SELECT id FROM users WHERE email = ?", [email]);\n' },
+  { name: 'js-orm-where-object', language: 'javascript', code: 'const user = await User.findOne({ where: { id: req.params.id, tenantId: req.user.tenantId } });\n' },
+  { name: 'js-execfile-argv', language: 'javascript', code: 'const out = execFileSync("git", ["log", "--format=%H", "-1", ref], { encoding: "utf8" });\n' },
+  { name: 'js-spawn-argv', language: 'javascript', code: 'const child = spawn("convert", [inputPath, "-resize", "200x200", outputPath], { stdio: "ignore" });\n' },
+  { name: 'js-path-confined', language: 'javascript', code: 'const target = path.resolve(root, name);\nif (!target.startsWith(root + path.sep)) throw new Error("outside root");\nconst text = fs.readFileSync(target, "utf8");\n' },
+  { name: 'js-constant-time-compare', language: 'javascript', code: 'const ok = a.length === b.length && crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));\n' },
+  { name: 'js-password-hash', language: 'javascript', code: 'const hash = await bcrypt.hash(password, 12);\nawait store.save({ email, hash });\n' },
+  { name: 'js-random-token', language: 'javascript', code: 'const token = crypto.randomBytes(32).toString("hex");\n' },
+  { name: 'js-json-parse-validated', language: 'javascript', code: 'const body = schema.parse(JSON.parse(raw));\nres.json({ id: body.id });\n' },
+  { name: 'js-template-escaped', language: 'javascript', code: 'res.send(template.render({ name: escapeHtml(req.query.name) }));\n' },
+  { name: 'js-fetch-allowlist', language: 'javascript', code: 'if (!ALLOWED_HOSTS.has(new URL(target).host)) return res.status(400).end();\nconst r = await fetch(target, { signal: AbortSignal.timeout(5000) });\n' },
+  { name: 'ts-parameterised-query', language: 'typescript', code: 'const rows: Row[] = await db.query("SELECT * FROM t WHERE id = $1", [id]);\n' },
+  { name: 'py-parameterised-query', language: 'python', code: 'cur.execute("SELECT * FROM users WHERE email = %s", (email,))\n' },
+  { name: 'py-subprocess-argv', language: 'python', code: 'subprocess.run(["ls", "-l", directory], check=True, capture_output=True)\n' },
+  { name: 'py-safe-yaml', language: 'python', code: 'config = yaml.safe_load(text)\n' },
+  { name: 'py-path-confined', language: 'python', code: 'target = os.path.realpath(os.path.join(root, name))\nif not target.startswith(root + os.sep):\n    raise ValueError("outside root")\n' },
+  { name: 'py-password-hash', language: 'python', code: 'digest = hashlib.pbkdf2_hmac("sha256", password.encode(), salt, 200_000)\n' },
+  { name: 'go-parameterised-query', language: 'go', code: 'row := db.QueryRow("SELECT name FROM users WHERE id = $1", id)\n' },
+  { name: 'go-exec-argv', language: 'go', code: 'out, err := exec.Command("git", "rev-parse", ref).Output()\n' },
+  { name: 'rb-parameterised-query', language: 'ruby', code: 'User.where("email = ?", params[:email]).first\n' },
+  { name: 'rb-system-argv', language: 'ruby', code: 'system("convert", input_path, "-resize", "200x200", output_path)\n' },
+  { name: 'java-prepared-statement', language: 'java', code: 'PreparedStatement ps = conn.prepareStatement("SELECT * FROM t WHERE id = ?");\nps.setInt(1, id);\nResultSet rs = ps.executeQuery();\n' },
+  { name: 'java-processbuilder-argv', language: 'java', code: 'Process p = new ProcessBuilder("git", "log", "-1", ref).start();\n' },
+  { name: 'php-prepared-statement', language: 'php', code: '$stmt = $pdo->prepare("SELECT * FROM users WHERE id = :id");\n$stmt->execute([":id" => $id]);\n' },
+  { name: 'cs-parameterised-query', language: 'csharp', code: 'var cmd = new SqlCommand("SELECT * FROM t WHERE id = @id", conn);\ncmd.Parameters.AddWithValue("@id", id);\n' },
+  { name: 'rs-parameterised-query', language: 'rust', code: 'let row = client.query_one("SELECT name FROM users WHERE id = $1", &[&id]).await?;\n' },
+]);

package/src/posture/rule-compiler/promotion.js

@@ -69,5 +69,26 @@ export function gatePromotion({ ir, corpus, leakageCheck, thresholds } = {}) {
   else if (ind.detected < ind.positives) reasons.push(`misses ${ind.positives - ind.detected} of ${ind.positives} independent vulnerable example(s)`);
   if (ind.negatives < t.minIndependentClean) reasons.push(`${ind.negatives} independent safe example(s) (min ${t.minIndependentClean}): supply independentCleanCode`);
   else if (ind.falseAlarms > 0) reasons.push(`fires on ${ind.falseAlarms} of ${ind.negatives} independent safe example(s)`);
+  for (const dup of dependentExamples(corpus)) reasons.push(`${dup.label} is not independent: it is the same code as ${dup.sameAs} (the source finding, its patch or a generated mutation), so it grades nothing the source did not`);
   return { pass: reasons.length === 0, reasons, evaluation: evalResult, independent: ind };
 }
+
+// GA-07 §2 (0.195.27): an "independent" example that is the original snippet, its patch, or one of the compiler's own mutations
+// (whitespace aside) is circular grading, which the independent-example rule exists to prevent. Compared after collapsing
+// whitespace so a re-indented copy is caught; a genuinely different example with the same shape is not (that is what a rule is for).
+const squash = (s) => String(s ?? '').replace(/\s+/g, ' ').trim();
+export function dependentExamples(corpus) {
+  const known = new Map();
+  for (const item of [...(corpus?.positives ?? []), ...(corpus?.negatives ?? [])]) {
+    if (item.label.startsWith('independent-')) continue;
+    const k = squash(item.code);
+    if (k && !known.has(k)) known.set(k, item.label);
+  }
+  const out = [];
+  for (const item of [...(corpus?.positives ?? []), ...(corpus?.negatives ?? [])]) {
+    if (!item.label.startsWith('independent-')) continue;
+    const sameAs = known.get(squash(item.code));
+    if (sameAs) out.push({ label: item.label, sameAs });
+  }
+  return out;
+}

package/src/posture/rule-compiler/regression.js

@@ -15,18 +15,22 @@ import { statePath } from '../state-dir.js';
 import { buildCorpus, scoreRule } from './corpus.js';
 import { evaluateRule } from './promotion.js';
 import { runRule, normalizeCustomRule } from '../custom-rules.js';
+import { createHash } from 'node:crypto';
 import { compileToCustomRule } from './ir.js';
 import { loadIR, loadCorpus, loadProvenance } from './store.js';
 import { stateOf } from './lifecycle.js';
+import { SHIPPED_NEGATIVE_CORPUS } from './negative-corpus.js';
 
 const FP_DIR = 'rule-compiler/fp-corpus';
 const MAX_FP_FILE = 256 * 1024;
 const MAX_FP_FILES = 500;
 const EXT_OF = { '.js': 'javascript', '.mjs': 'javascript', '.cjs': 'javascript', '.ts': 'typescript', '.py': 'python', '.go': 'go', '.rb': 'ruby', '.java': 'java', '.rs': 'rust', '.cs': 'csharp', '.php': 'php' };
 
-/** Operator-supplied false positives (real code a rule should never flag). Plain files; symlinks and oversized files are ignored. */
-function operatorFalsePositives(root) {
-  const dir = statePath(root, ...FP_DIR.split('/'));
+// GA-07 §3 (0.195.27): one or more directories of safe code shared ACROSS repositories (a fleet's common false-positive corpus),
+// named by path-separator-joined entries in this variable. Same rules as the project directory: plain files, size and count caps.
+const SHARED_FP_ENV = 'AGENTIC_SECURITY_RULES_FP_CORPUS';
+
+function falsePositiveFiles(dir, prefix) {
   const out = [];
   let names = [];
   try { names = fs.readdirSync(dir).sort(); } catch { return out; }
@@ -35,19 +39,32 @@ function operatorFalsePositives(root) {
     try {
       const st = fs.lstatSync(f);
       if (!st.isFile() || st.isSymbolicLink() || st.size > MAX_FP_FILE) continue;
-      out.push({ label: `operator-fp:${n}`, file: n, language: EXT_OF[path.extname(n).toLowerCase()] ?? 'any', code: fs.readFileSync(f, 'utf8') });
+      out.push({ label: `${prefix}:${n}`, file: n, language: EXT_OF[path.extname(n).toLowerCase()] ?? 'any', code: fs.readFileSync(f, 'utf8') });
     } catch { /* unreadable: skipped */ }
   }
   return out;
 }
 
+/** Operator-supplied false positives (real code a rule should never flag): the project's own directory, then every shared directory. */
+function operatorFalsePositives(root, env = process.env) {
+  const out = falsePositiveFiles(statePath(root, ...FP_DIR.split('/')), 'operator-fp');
+  for (const dir of String(env[SHARED_FP_ENV] || '').split(path.delimiter).map((s) => s.trim()).filter(Boolean)) {
+    out.push(...falsePositiveFiles(path.resolve(dir), `shared-fp:${path.basename(dir)}`));
+  }
+  return out;
+}
+
 export function promotedRuleIds(ledger) {
   return [...new Set(ledger.entries.map((e) => e.ruleId))].filter((id) => stateOf(ledger, id) === 'PROMOTED');
 }
 
-/** The shared false-positive corpus as seen by `exceptId`: the safe code of every OTHER promoted rule, plus the operator's files. */
-export function sharedFalsePositiveCorpus(root, ledger, exceptId = null) {
-  const items = [];
+/**
+ * The shared false-positive corpus as seen by `exceptId`: the safe code shipped with the scanner (`negative-corpus.js`, the same on
+ * every machine and in every repository), the safe code of every OTHER promoted rule, the operator's project files, and any
+ * directories shared across repositories through AGENTIC_SECURITY_RULES_FP_CORPUS.
+ */
+export function sharedFalsePositiveCorpus(root, ledger, exceptId = null, env = process.env) {
+  const items = SHIPPED_NEGATIVE_CORPUS.map((s) => ({ label: `shipped-fp:${s.name}`, language: s.language, code: s.code }));
   for (const id of promotedRuleIds(ledger)) {
     if (id === exceptId) continue;
     const ir = loadIR(root, id); const spec = loadCorpus(root, id);
@@ -55,7 +72,12 @@ export function sharedFalsePositiveCorpus(root, ledger, exceptId = null) {
     let corpus; try { corpus = buildCorpus(ir, spec); } catch { continue; }
     for (const n of corpus.negatives) items.push({ label: `rule:${id}:${n.label}`, language: ir.languages[0] ?? 'any', code: n.code });
   }
-  return [...items, ...operatorFalsePositives(root)];
+  return [...items, ...operatorFalsePositives(root, env)];
+}
+
+/** The digest of a corpus half, as `rules evaluate` records it in the provenance record and `rules regress` re-derives it. */
+export function corpusHash(list) {
+  return createHash('sha256').update(JSON.stringify(list.map((x) => [x.label, x.code]).sort())).digest('hex');
 }
 
 const FILE_FOR_LANG = { javascript: 'x.js', typescript: 'x.ts', python: 'x.py', go: 'x.go', ruby: 'x.rb', java: 'x.java', rust: 'x.rs', csharp: 'x.cs', php: 'x.php', any: 'x.txt' };
@@ -85,8 +107,16 @@ export function regressRules(root, ledger, { only = null, thresholds } = {}) {
     let ev; let corpus;
     try { corpus = buildCorpus(ir, spec); ev = evaluateRule(ir, corpus, thresholds); } catch (e) { results.push({ id, status: 'broken', reasons: [`cannot be scored: ${String(e.message).slice(0, 120)}`] }); continue; }
     const fp = falsePositiveHits(ir, sharedFalsePositiveCorpus(root, ledger, id));
-    const baseline = loadProvenance(root, id)?.benchmarkResults ?? null;
+    const prov = loadProvenance(root, id);
+    const baseline = prov?.benchmarkResults ?? null;
     const reasons = [...ev.reasons];
+    // GA-07 §3 (0.195.27): the promotion was a review of ONE rule against ONE corpus, both digested into the promotion event. A
+    // corpus edited after the review (an independent example dropped, a protected variant softened) can still clear the gate, so
+    // the gate alone would not notice; the digests do. Such a rule is `review-stale`: not regressed, but no longer the reviewed one.
+    const reviewed = prov?.promotionEvent?.evidence ?? null;
+    if (reviewed) {
+      if (reviewed.positiveCorpusHash !== corpusHash(corpus.positives) || reviewed.negativeCorpusHash !== corpusHash(corpus.negatives)) reasons.push('the corpus changed since the reviewed promotion (its digests no longer match the promotion event); re-evaluate and promote again');
+    }
     if (fp.length) reasons.push(`fires on ${fp.length} item(s) of the shared false-positive corpus: ${fp.slice(0, 3).map((h) => h.label).join(', ')}${fp.length > 3 ? ', ...' : ''}`);
     if (baseline && ev.score.recall != null && baseline.recall != null && ev.score.recall < baseline.recall) reasons.push(`recall fell from ${(baseline.recall * 100).toFixed(1)}% to ${(ev.score.recall * 100).toFixed(1)}% since promotion`);
     results.push({ id, status: reasons.length ? 'regressed' : 'ok', reasons, precision: ev.score.precision, recall: ev.score.recall, protectedFailures: ev.score.protectedFailures, fpCorpusHits: fp.length });

package/src/posture/rule-compiler/store.js

@@ -5,6 +5,7 @@
 // using the SAME filename convention `runRuleTests` already reads (`vulnerable`/`clean` in the path).
 import fs from 'node:fs';
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { statePath, ensureStateDir, safeWriteState } from '../state-dir.js';
 import { newLedger, verifyLedger } from './lifecycle.js';
 import { signLastScan, verifyLastScan } from '../integrity.js';
@@ -35,20 +36,85 @@ export function loadLedger(scanRoot, env = process.env) {
   const v = verifyLedger(ledger);
   if (!v.ok) return { ...ledger, tampered: true, tamperReason: v.reason };
   const sig = verifyLastScan(text, `${f}.sig`);
-  if (sig === false) return { ...ledger, tampered: true, tamperReason: 'the ledger signature does not verify under this install key' };
+  if (sig === true) return { ...ledger, verifiedBy: 'install-key' };
+  // GA-07 §3 (0.195.27): the install key never leaves the machine that promoted the rule, so on a CI runner (or any other
+  // clone) the HMAC cannot verify. A ledger that `promote --sign-key` also signed with the operator's Ed25519 key is accepted
+  // when that signature verifies against a key the environment trusts: AGENTIC_SECURITY_RULES_PUBLIC_KEY (set outside the
+  // repository, a CI variable) or the trusted-keys store the rule packs already use. The chain check above still applies, and
+  // the signature covers the whole file, so a dropped last entry fails it like any other edit. A project-local key file alone
+  // is not trust (an author who can write .agentic-security/ could add one), which is why the env variable is the CI route.
+  const author = verifyAuthorSignature(text, `${f}${AUTHOR_SIG_SUFFIX}`, authorKeysFrom(scanRoot, env));
+  if (author.ok) return { ...ledger, verifiedBy: 'author-key', authorKeyId: author.keyId };
+  if (sig === false) return { ...ledger, tampered: true, tamperReason: `the ledger signature does not verify under this install key${author.present ? ` and its author signature does not verify against any trusted key (${author.reason})` : ' and it carries no author signature (promote with --sign-key to make it portable)'}` };
   if (sig === null && ledger.entries.length && env.AGENTIC_SECURITY_RULES_UNSIGNED !== '1') {
     return { ...ledger, tampered: true, tamperReason: 'the ledger is unsigned (written before 0.195.23 or by another tool); set AGENTIC_SECURITY_RULES_UNSIGNED=1 once to accept and re-sign it' };
   }
-  return ledger;
+  return { ...ledger, verifiedBy: sig === null ? 'unsigned-accepted' : 'install-key' };
 }
 
-export function saveLedger(scanRoot, ledger) {
+const AUTHOR_SIG_SUFFIX = '.author.sig';
+const PUBLIC_KEY_ENV = 'AGENTIC_SECURITY_RULES_PUBLIC_KEY';
+
+/** The Ed25519 public keys a ledger's author signature may verify against: the environment variable (one or more base64 raw keys,
+ * comma separated) first, then the rule-pack trust store (bundled keys, and the project file only when the operator honours it). */
+function authorKeysFrom(scanRoot, env) {
+  const keys = [];
+  for (const k of String(env[PUBLIC_KEY_ENV] || '').split(',').map((s) => s.trim()).filter(Boolean)) keys.push({ id: 'env', publicKey: k, alg: 'ed25519' });
+  const origErr = console.error; console.error = () => {};
+  try { keys.push(...loadTrustedKeys(scanRoot)); } catch { /* no trust store */ } finally { console.error = origErr; }
+  return keys;
+}
+
+function verifyAuthorSignature(text, sigPath, keys) {
+  let sig;
+  try { sig = fs.readFileSync(sigPath); } catch { return { ok: false, present: false, reason: 'no author signature' }; }
+  if (!keys.length) return { ok: false, present: true, reason: `no trusted key (set ${PUBLIC_KEY_ENV})` };
+  const body = Buffer.from(text, 'utf8');
+  for (const k of keys) {
+    try {
+      const keyBytes = Buffer.from(k.publicKey, 'base64');
+      if (keyBytes.length !== 32) continue;
+      const keyObj = crypto.createPublicKey({ key: { kty: 'OKP', crv: 'Ed25519', x: keyBytes.toString('base64url') }, format: 'jwk' });
+      if (crypto.verify(null, body, keyObj, sig)) return { ok: true, present: true, keyId: k.id || '(unnamed)' };
+    } catch { /* next key */ }
+  }
+  return { ok: false, present: true, reason: 'bad signature' };
+}
+
+function signWithAuthorKey(text, privateKeyB64) {
+  const privBytes = Buffer.from(privateKeyB64, 'base64');
+  if (privBytes.length !== 32) throw new Error('private key must be 32 bytes (raw ed25519)');
+  const keyObj = crypto.createPrivateKey({ key: Buffer.concat([Buffer.from('302e020100300506032b657004220420', 'hex'), privBytes]), format: 'der', type: 'pkcs8' });
+  return crypto.sign(null, Buffer.from(text, 'utf8'), keyObj);
+}
+
+/** The public key (base64 raw) that pairs with a raw Ed25519 private key; printed by `promote` so the operator can set it in CI. */
+export function publicKeyOf(privateKeyB64) {
+  const privBytes = Buffer.from(privateKeyB64, 'base64');
+  if (privBytes.length !== 32) return null;
+  const keyObj = crypto.createPrivateKey({ key: Buffer.concat([Buffer.from('302e020100300506032b657004220420', 'hex'), privBytes]), format: 'der', type: 'pkcs8' });
+  return Buffer.from(crypto.createPublicKey(keyObj).export({ format: 'jwk' }).x, 'base64url').toString('base64');
+}
+
+/**
+ * Write the ledger with its install-key signature and, when the operator's Ed25519 key is given, an author signature beside it
+ * (`ledger.json.author.sig`) that another machine can verify (see loadLedger). Without a key an existing author signature is
+ * removed rather than left stale: a signature that no longer matches the file would read as tampering on the next clone.
+ */
+export function saveLedger(scanRoot, ledger, { authorKey = null } = {}) {
   if (ledger?.tampered) return { ok: false, reason: `refusing to overwrite a ledger that failed its integrity check (${ledger.tamperReason})` };
   if (!ensureStateDir(scanRoot)) return { ok: false, reason: 'no safe state directory for this project' };
   const f = statePath(scanRoot, DIR, 'ledger.json');
-  const text = JSON.stringify(ledger, null, 2);
-  const ok = safeWriteState(f, text) && safeWriteState(`${f}.sig`, signLastScan(text));
-  return { ok };
+  const { verifiedBy, authorKeyId, ...body } = ledger;
+  const text = JSON.stringify(body, null, 2);
+  let ok = safeWriteState(f, text) && safeWriteState(`${f}.sig`, signLastScan(text));
+  let authorSigned = false;
+  if (ok && authorKey) {
+    try { ok = safeWriteState(`${f}${AUTHOR_SIG_SUFFIX}`, signWithAuthorKey(text, authorKey)); authorSigned = ok; } catch (e) { return { ok: false, reason: `cannot author-sign the ledger: ${String(e.message).slice(0, 120)}` }; }
+  } else if (ok) {
+    try { fs.unlinkSync(`${f}${AUTHOR_SIG_SUFFIX}`); } catch { /* none to remove */ }
+  }
+  return { ok, authorSigned };
 }
 
 export function saveIR(scanRoot, ir) {

package/src/posture/suppressions.js

@@ -39,6 +39,7 @@ import * as path from 'node:path';
 import * as yaml from '../util/yaml.js';
 import { statePath, safeWriteState } from './state-dir.js';
 import { loadApproverRegistry, verifyApprover, requiredRolesFor } from '../fix/approver-registry.js';
+import { contentFingerprint } from '../llm-validator/disposition.js';
 
 const MS_PER_DAY = 86400000;
 const SOFT_TTL_DAYS = 30;
@@ -63,6 +64,15 @@ export function saveSoftAccepted(scanRoot, items) {
   safeWriteState(fp, JSON.stringify({ accepted: items }, null, 2));
 }
 
+// Content fingerprint of a scanned file, or null when it cannot be read.
+function _diskFingerprint(scanRoot, file) {
+  try {
+    const abs = path.resolve(scanRoot, file);
+    if (abs !== path.resolve(scanRoot) && !abs.startsWith(path.resolve(scanRoot) + path.sep)) return null;
+    return contentFingerprint(fs.readFileSync(abs, 'utf8'));
+  } catch { return null; }
+}
+
 export function addSoftAcceptance(scanRoot, finding, reason) {
   const items = loadSoftAccepted(scanRoot);
   const expires = new Date(_now() + SOFT_TTL_DAYS * MS_PER_DAY).toISOString().slice(0, 10);
@@ -74,6 +84,8 @@ export function addSoftAcceptance(scanRoot, finding, reason) {
     reason: reason || 'vibecoded for now',
     accepted_at: new Date().toISOString().slice(0, 10),
     expires_at: expires,
+    // PRD FR 05: bind the acceptance to the code it was made on, so a changed file reopens it.
+    fingerprint: _diskFingerprint(scanRoot, finding.file),
   });
   saveSoftAccepted(scanRoot, items);
   return expires;
@@ -156,6 +168,15 @@ export function applySuppressions(findings, scanRoot, profile) {
         kept.push({ ...f, _suppressionExpired: true });
         continue;
       }
+      // PRD FR 05: an entry bound to a content fingerprint reopens when the
+      // file changes or disappears. Entries without one keep the legacy behaviour.
+      if (matched.fingerprint) {
+        const now_fp = _diskFingerprint(scanRoot, f.file);
+        if (now_fp !== matched.fingerprint) {
+          kept.push({ ...f, _suppressionReopened: now_fp ? 'source changed since the suppression was recorded' : 'suppressed source is no longer available' });
+          continue;
+        }
+      }
       // Pro: validate the entry still passes
       if (isPro) {
         // Same registry/category shape FR-307 already uses for high-impact

package/src/posture/watch-mode.js

@@ -25,6 +25,7 @@ import * as path from 'node:path';
 
 import { stateDir, statePath, stateWritesEnabled } from './state-dir.js';
 import { isLanguageSource, isLanguageManifest, isLanguageExcludedPath, isExplicitExport, impactedFiles } from '../language/discovery.js';
+import { buildScanInventory } from '../scope/inventory.js';
 const STATUS_MD   = 'watch-status.md';
 const STATUS_JSON = 'watch-status.json';
 const DEBOUNCE_MS = 350;
@@ -33,6 +34,25 @@ const MAX_BURST   = 50; // ignore beyond this # of rapid events
 const SCAN_EXT_RE = /\.(?:[jt]sx?|mjs|cjs|py|java|kt|go|rb|php|cs|c|cc|cpp|h|hpp|rs|sol|vy|swift|dart|toml|yml|yaml|json|tf|tfvars|bicep)$/i;
 const IGNORE_DIR_RE = /(?:^|\/)(?:\.git|node_modules|\.bench-cache|dist|build|\.next|coverage|\.agentic-security)(?:$|\/)/;
 
+// Under Git scope (PRD FR 01) the watcher asks the same inventory the scan uses, so a change to a Git-ignored file does not
+// trigger a rescan, and a tracked file under a directory the default list would skip (`dist/`, `build/`) still does. A change
+// to an ignore source rebuilds the inventory. A path the inventory has not seen (a new file) rebuilds it, at most once a second.
+const IGNORE_SOURCE = /(?:^|\/)\.gitignore$|^\.git\/info\/exclude$/;
+export function createScopeFilter(scanRoot, scope = {}, { build = buildScanInventory, now = Date.now } = {}) {
+  let included = null;
+  let builtAt = -Infinity;
+  const rebuild = () => { included = new Set(build(scanRoot, scope).included); builtAt = now(); };
+  rebuild();
+  return (rel) => {
+    if (!rel || /^\.agentic-security(?:\/|$)/.test(rel)) return false;
+    if (IGNORE_SOURCE.test(rel)) { rebuild(); return true; }
+    if (/^\.git(?:\/|$)/.test(rel)) return false;
+    if (included.has(rel)) return true;
+    if (now() - builtAt >= 1000) rebuild();
+    return included.has(rel);
+  };
+}
+
 function _isScanable(rel) {
   if (!rel) return false;
   // An explicit export is evidence even though it lives in a build directory.
@@ -162,6 +182,7 @@ export function readStatus(scanRoot) {
 export async function watchProject(scanRoot, onChange, opts = {}) {
   if (process.env.AGENTIC_SECURITY_NO_WATCH === '1') return { stop: async () => {}, _disabled: true };
   const recursive = opts.recursive !== false;
+  const eligible = typeof opts.isEligible === 'function' ? opts.isEligible : _isScanable;
   const ac = new AbortController();
   let timer = null;
   const pending = new Set();
@@ -183,7 +204,7 @@ export async function watchProject(scanRoot, onChange, opts = {}) {
       for await (const evt of fs.watch(scanRoot, { recursive, signal: ac.signal })) {
         if (stopped) break;
         const rel = String(evt.filename || '').replace(/\\/g, '/');
-        if (!_isScanable(rel)) continue;
+        if (!eligible(rel)) continue;
         pending.add(path.join(scanRoot, rel));
         if (timer) clearTimeout(timer);
         timer = setTimeout(flush, DEBOUNCE_MS);

package/src/report/disposition-view.js

@@ -0,0 +1,90 @@
+// Report view over dispositions (PRD FR 09). Display only: it reads a scan and
+// returns groups and counts, and never changes stored findings, so hiding a
+// category here cannot mark anything assessed or imply remediation. Raw and
+// displayed counts reconcile: raw = shown + every hidden bucket.
+
+import { DISPOSITIONS as D } from '../llm-validator/disposition.js';
+
+export const VIEW_SCHEMA = 'report-view/1';
+export const EXCLUDABLE_KINDS = Object.freeze(['sca', 'generated', 'secrets', 'logic']);
+
+const LANG_BY_EXT = { js: 'javascript', mjs: 'javascript', cjs: 'javascript', ts: 'typescript', tsx: 'typescript', jsx: 'javascript', py: 'python', java: 'java', go: 'go', rb: 'ruby', rs: 'rust', cs: 'csharp', kt: 'kotlin', php: 'php', hs: 'haskell', lhs: 'haskell', nix: 'nix', yml: 'yaml', yaml: 'yaml', tf: 'terraform' };
+export function languageOf(file) {
+  const m = /\.([A-Za-z0-9]+)$/.exec(String(file || ''));
+  return (m && LANG_BY_EXT[m[1].toLowerCase()]) || 'other';
+}
+
+const GENERATED = /(?:^|\/)(?:dist|build|buck-out|dist-newstyle|\.stack-work|generated|gen)\//i;
+
+function groupOf(f) {
+  const d = f.disposition;
+  if (d === D.CONFIRMED) return 'confirmed';
+  if (d === D.HARDENING) return 'hardening';
+  if (d === D.REFUTED) return 'history';
+  if (d === D.NEEDS_REVIEW) return 'needsReview';
+  return 'unvalidated';
+}
+
+/** Parse `--exclude-kind sca,generated` style values. Returns { kinds, errors }. */
+export function parseExcludeKinds(v) {
+  const kinds = []; const errors = [];
+  for (const k of String(v ?? '').split(',').map((s) => s.trim()).filter(Boolean)) {
+    if (EXCLUDABLE_KINDS.includes(k)) kinds.push(k); else errors.push(`--exclude-kind: unknown kind "${k}" (known: ${EXCLUDABLE_KINDS.join(', ')})`);
+  }
+  return { kinds, errors };
+}
+
+/**
+ * @param {object} scan
+ * @param {{excludeKinds?: string[], filters?: {category?: string, language?: string, package?: string, path?: string, disposition?: string, minConfidence?: number}}} [o]
+ */
+export function buildDispositionView(scan, { excludeKinds = [], filters = {} } = {}) {
+  const buckets = [
+    ['code', scan.findings || [], null],
+    ['secrets', scan.secrets || [], 'secrets'],
+    ['logic', scan.logicVulns || [], 'logic'],
+    ['sca', scan.supplyChain || [], 'sca'],
+  ];
+  const hidden = { byKind: {}, byFilter: 0 };
+  const groups = { confirmed: [], needsReview: [], unvalidated: [], hardening: [], history: [] };
+  let raw = 0;
+  for (const [bucket, items, kind] of buckets) {
+    for (const f of items) {
+      raw++;
+      const isSca = bucket === 'sca';
+      const k = kind || (GENERATED.test(String(f.file || '')) ? 'generated' : null);
+      if (k && excludeKinds.includes(k)) { hidden.byKind[k] = (hidden.byKind[k] || 0) + 1; continue; }
+      if (filters.category && String(f.family || f.category || '') !== filters.category) { hidden.byFilter++; continue; }
+      if (filters.language && languageOf(f.file) !== filters.language) { hidden.byFilter++; continue; }
+      if (filters.package && String(f.package || f.component || f.name || '') !== filters.package) { hidden.byFilter++; continue; }
+      if (filters.path && !String(f.file || '').startsWith(filters.path)) { hidden.byFilter++; continue; }
+      if (filters.disposition && (isSca ? 'unvalidated' : groupOf(f)) !== filters.disposition && f.disposition !== filters.disposition) { hidden.byFilter++; continue; }
+      if (typeof filters.minConfidence === 'number' && (typeof f.confidence === 'number' ? f.confidence : 1) < filters.minConfidence) { hidden.byFilter++; continue; }
+      groups[isSca ? 'unvalidated' : groupOf(f)].push(f);
+    }
+  }
+  // Refuted findings were moved to the suppression ledger by the engine; they appear as history.
+  for (const s of scan.suppressions || []) if (s && s.disposition === D.REFUTED) groups.history.push(s);
+  const counts = Object.fromEntries(Object.entries(groups).map(([k, v]) => [k, v.length]));
+  // History comes from the ledger, not from the live buckets, so it is outside the raw/shown reconciliation.
+  const shown = counts.confirmed + counts.needsReview + counts.unvalidated + counts.hardening;
+  const hiddenTotal = Object.values(hidden.byKind).reduce((a, b) => a + b, 0) + hidden.byFilter;
+  return {
+    schema: VIEW_SCHEMA,
+    excludeKinds: [...excludeKinds],
+    filters: { ...filters },
+    counts,
+    actionable: counts.confirmed + counts.needsReview,
+    raw, shown, hidden,
+    reconciles: raw === shown + hiddenTotal,
+    note: hiddenTotal ? 'Hidden items are still stored in the scan and are not assessed or remediated by hiding them.' : null,
+  };
+}
+
+export function viewLine(v) {
+  if (!v) return null;
+  const hid = Object.entries(v.hidden.byKind).map(([k, n]) => `${n} ${k}`);
+  if (v.hidden.byFilter) hid.push(`${v.hidden.byFilter} filtered`);
+  return `Findings: ${v.counts.confirmed} confirmed, ${v.counts.needsReview} needs review, ${v.counts.unvalidated} unvalidated, ${v.counts.hardening} hardening advice, ${v.counts.history} refuted history`
+    + (hid.length ? `; hidden from this view (still stored, not assessed): ${hid.join(', ')}` : '');
+}

package/src/report/index.js

@@ -1,4 +1,5 @@
 // Report writers — JSON / Markdown / SARIF.
+import { viewLine } from './disposition-view.js';
 import * as crypto from 'node:crypto';
 import { _isCustomSuppressed } from '../engine.js';
 import { alertFace, approveFace } from './mascot.js';
@@ -290,6 +291,14 @@ export function normalizeFindings(scan){
       blastRadius: f.blastRadius || null,
       // Sentinel-parity (FR-PREC, FR-L3) preserved fields.
       stableId: f.stableId || null,
+      // FR 05 / FR 10: the final disposition, why, and the evidence record. Present only when the engine computed them.
+      ...(f.disposition ? { disposition: f.disposition, dispositionDetail: f.dispositionDetail || null } : {}),
+      ...(Array.isArray(f.claims) && f.claims.length > 1 ? { claims: f.claims } : {}),
+      ...(f.record ? { record: f.record } : {}),
+      // FR 06: every workflow finding names the workflow, job, step, input origin, sensitive operation and privilege boundary.
+      ...(f.workflow ? { workflow: f.workflow, job: f.job ?? null, step: f.step ?? null, inputOrigin: f.inputOrigin ?? null, inputOriginKind: f.inputOriginKind ?? null, sensitiveOperation: f.sensitiveOperation ?? null, privilegeBoundary: f.privilegeBoundary ?? null, guards: f.guards ?? [], missingEvidence: f.missingEvidence ?? (f.dispositionDetail && f.dispositionDetail.missingEvidence) ?? [] } : {}),
+      ...(f.oidcTrust ? { oidcTrust: f.oidcTrust } : {}),
+      ...(f.validator_reject_retained ? { validator_reject_retained: true } : {}),
       confidenceTier: f.confidenceTier || null,
       exploitability: typeof f.exploitability === 'number' ? f.exploitability : null,
       exploitabilityTier: f.exploitabilityTier || null,
@@ -569,6 +578,8 @@ export function normalizeFindings(scan){
       version: sc.version,
       cveAliases: sc.cveAliases || [],
       osvId: sc.osvId || null,
+      ...(sc.basis ? { basis: sc.basis } : {}),
+      ...(sc.advisoryIds ? { advisoryIds: sc.advisoryIds, occurrences: sc.occurrences } : {}),
       advisory: sc.advisory || sc.description || sc.summary || '',
       // Hackage (and any matcher that decides from ranges): WHY the dependency matched. Without these a `possibly-affected` finding
       // (only a declared range is known) reads exactly like an `affected` one (the resolved version is inside the range).
@@ -764,6 +775,13 @@ export function toJSON(scan, meta={}, opts={}){
     // "analysis complete". Null when the engine did not compute one (e.g. a
     // hand-built `scan` object in a test), same convention as the S7 fields
     // above; a real scan always computes it.
+     ...(scan.scanRecord ? { scanRecord: scan.scanRecord } : {}),
+     ...(scan.reportView ? { reportView: scan.reportView } : {}),
+     ...(scan.dispositionCounts ? { dispositionCounts: scan.dispositionCounts } : {}),
+     // PRD FR 05: every candidate stays discoverable. Equivalent claims grouped under a primary are listed here, and the
+     // reconciliation shows raw, grouped, refuted and active counts with nothing counted twice.
+     ...(scan.candidateReconciliation ? { candidateReconciliation: scan.candidateReconciliation } : {}),
+     ...(Array.isArray(scan.groupedClaims) && scan.groupedClaims.length ? { groupedClaims: scan.groupedClaims.map((g) => ({ id: g.id ?? null, stableId: g.stableId ?? null, parser: g.parser ?? null, vuln: g.vuln ?? null, cwe: g.cwe ?? null, severity: g.severity ?? null, file: g.file ?? null, line: g.line ?? null, groupedInto: g.groupedInto ?? null, disposition: g.disposition ?? null })) } : {}),
     scanHealth: scan.scanHealth || null,
     // X-207: advisory hypotheses a caller put in the finding list; excluded from `findings`, listed here so it is never silent.
     ...(Array.isArray(scan.advisoryExcluded) && scan.advisoryExcluded.length ? { advisoryExcluded: scan.advisoryExcluded } : {}),
@@ -1079,6 +1097,29 @@ export const TOOL_CAVEATS = Object.freeze([
   },
 ]);
 
+// FR 02: one reading of the Haskell coverage record, shared by the CLI, HTML and SARIF outputs so they cannot disagree.
+export function haskellCoverageSummary(scan) {
+  const h = scan && scan.scanHealth && scan.scanHealth.languageCoverage && scan.scanHealth.languageCoverage.haskell;
+  if (!h || !h.present) return null;
+  const pct = (r) => (r == null ? 'n/a' : `${(r * 100).toFixed(1)}%`);
+  return {
+    status: h.capability.status,
+    discovered: h.totals.discovered, eligible: h.totals.eligible, eligibleHs: h.totals.eligibleHs,
+    parseRate: h.stages.parse.rate, semanticRate: h.stages.semantic.rate,
+    parseText: pct(h.stages.parse.rate), semanticText: pct(h.stages.semantic.rate),
+    functions: h.functions, unresolvedCalls: h.unresolvedCalls,
+    ruleFamilies: h.ruleFamilies.map((f) => ({ id: f.id, status: f.status, findings: f.findings })),
+    reasons: h.capability.reasons, limitations: h.capability.limitations,
+    incompleteEntries: h.incompleteEntries.length,
+  };
+}
+
+function haskellCoverageLine(scan) {
+  const h = haskellCoverageSummary(scan);
+  if (!h) return null;
+  return `Haskell coverage: ${h.status}; ${h.eligibleHs} eligible .hs file(s), parsed ${h.parseText}, semantic analysis completed ${h.semanticText}; ${h.functions.lowered}/${h.functions.discovered} function(s) analysed, ${h.unresolvedCalls == null ? 'n/a' : h.unresolvedCalls} unresolved call(s)`;
+}
+
 export function toSARIF(scan, meta={}){
   const findings = normalizeFindings(scan);
   const ruleMap = new Map();
@@ -1128,6 +1169,8 @@ export function toSARIF(scan, meta={}){
         // /security-trend regression analysis can attribute deltas to rule
         // changes vs. code changes.
         properties: {
+          ...(haskellCoverageSummary(scan) ? { haskellCoverage: haskellCoverageSummary(scan) } : {}),
+          ...(scan.reportView ? { reportView: scan.reportView } : {}),
           ...(scan && scan._rulesetVersion ? { rulesetVersion: scan._rulesetVersion } : {}),
           ...(scan && scan._rulesetVersionSource ? { rulesetVersionSource: scan._rulesetVersionSource } : {}),
           ...(scan && scan._rulesetVersionMismatch ? { rulesetVersionMismatch: scan._rulesetVersionMismatch } : {}),
@@ -1376,6 +1419,8 @@ export function toHTML(scan, meta = {}) {
     <div class="card"><h2>STRIDE coverage</h2><table><tbody>${strideRows}</tbody></table></div>
     <div class="card"><h2>Top files</h2><table><tbody>${hotRows}</tbody></table></div>
   </div>
+  ${(() => { const vl = viewLine(scan.reportView); return vl ? `<div class="card" style="margin-bottom:24px"><h2>Findings by disposition</h2><div class="meta">${_esc(vl)}</div></div>` : ''; })()}
+  ${(() => { const h = haskellCoverageSummary(scan); if (!h) return ''; return `<div class="card" style="margin-bottom:24px"><h2>Haskell coverage &mdash; ${_esc(h.status)}</h2><div class="meta">${_esc(haskellCoverageLine(scan))}</div><div class="meta">Rule families: ${h.ruleFamilies.map((f) => `${_esc(f.id)} (${_esc(f.status)})`).join(', ')}</div>${h.reasons.map((r) => `<div class="meta">&bull; ${_esc(r)}</div>`).join('')}${h.limitations.map((r) => `<div class="meta">&bull; ${_esc(r)}</div>`).join('')}</div>`; })()}
   <div class="filters">
     <input id="q" placeholder="Filter by file, vuln, CWE&hellip;" />
     <select id="sev"><option value="">All severities</option><option>critical</option><option>high</option><option>medium</option><option>low</option><option>info</option></select>
@@ -1688,6 +1733,8 @@ export function toShipVerdict(scan, options = {}) {
     const conditions = Array.isArray(scan.scanHealth.conditions) ? scan.scanHealth.conditions : [];
     lines.push(c(`  ${scan.scanHealth.status}: ${conditions[0] || 'analysis did not complete cleanly'}${conditions.length > 1 ? ` (+${conditions.length - 1} more)` : ''}`, SEV_COLOR.high));
   }
+  { const hl = haskellCoverageLine(scan); if (hl) lines.push(c(`  ${hl}`, DIM)); }
+  { const vl = viewLine(scan.reportView); if (vl) lines.push(c(`  ${vl}`, DIM)); }
   lines.push(`  • ${sev.critical} critical · ${sev.high} high · ${advisoryCount} advisory`);
   // Per-category 0..100 score bars — Secrets / Permissions / Hooks / MCP / Agents.
   // Only render when at least one category has been contributed to (skip the