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

package/src/pipeline/evidence-record.js

@@ -0,0 +1,112 @@
+// Evidence contract (PRD FR 10): additive scan-record and finding-record fields. Nothing here replaces an existing
+// field; every field is derived from data the scan already holds or from read-only git queries on the scan root.
+
+import * as crypto from 'node:crypto';
+import * as cp from 'node:child_process';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { hardenGitArgs, hardenGitEnv } from '../util/git-hardening.js';
+
+export const SCAN_RECORD_SCHEMA = 'scan-record/1';
+export const FINDING_RECORD_SCHEMA = 'finding-record/1';
+const DIRTY_CAP = 200;
+
+const sha = (s) => crypto.createHash('sha256').update(s).digest('hex');
+
+function git(root, args) {
+  const r = cp.spawnSync('git', hardenGitArgs(args), { cwd: root, env: hardenGitEnv({}), encoding: 'buffer', maxBuffer: 64 * 1024 * 1024 });
+  return r.status === 0 ? r.stdout.toString('utf8') : null;
+}
+
+/** Source commit and digests of the files that differ from it, so a result is tied to the exact code scanned. */
+export function sourceState(root) {
+  const inside = git(root, ['rev-parse', '--is-inside-work-tree']);
+  if (!inside || inside.trim() !== 'true') return { vcs: 'none', commit: null, dirty: null, dirtyFiles: [], dirtyFilesTruncated: false };
+  const commit = (git(root, ['rev-parse', 'HEAD']) || '').trim() || null;
+  const status = git(root, ['status', '--porcelain=v1', '-z', '--untracked-files=normal']);
+  const entries = (status || '').split('\0').filter(Boolean).map((e) => ({ code: e.slice(0, 2), file: e.slice(3) }));
+  const dirtyFiles = entries.slice(0, DIRTY_CAP).map((e) => {
+    let digest = null;
+    try { const abs = path.join(root, e.file); if (fs.lstatSync(abs).isFile()) digest = sha(fs.readFileSync(abs)); } catch { /* deleted */ }
+    return { file: e.file, status: e.code.trim() || '?', sha256: digest };
+  });
+  return { vcs: 'git', commit, dirty: entries.length > 0, dirtyFiles, dirtyFilesTruncated: entries.length > DIRTY_CAP, dirtyCount: entries.length };
+}
+
+/** Flags that shaped the run, with values that could carry secrets or local paths reduced to their names. */
+export function invocationSummary(argv) {
+  const out = [];
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (!a.startsWith('--')) continue;
+    let [k, v] = a.split(/=(.*)/s, 2);
+    // `--flag value`: keep a short non-path value so the record shows the format and mode that were chosen.
+    if (v === undefined && argv[i + 1] !== undefined && !argv[i + 1].startsWith('-') && /^[A-Za-z0-9_.,:-]{1,40}$/.test(argv[i + 1]) && !argv[i + 1].includes('/')) v = argv[i + 1];
+    out.push(/key|token|secret|password/i.test(k) ? `${k}=<redacted>` : (v !== undefined ? `${k}=${v}` : k));
+  }
+  return out;
+}
+
+export function buildScanRecord({ root, scan, meta, argv = [], engineVersion, mode }) {
+  const h = scan.scanHealth || {};
+  const model = scan.aiAssistance || null;
+  return {
+    schema: SCAN_RECORD_SCHEMA,
+    tool: { name: 'agentic-security', version: engineVersion || null },
+    source: sourceState(root),
+    invocation: { flags: invocationSummary(argv), mode: mode || (meta && meta.mode) || 'full' },
+    ignorePolicy: scan.scope ? { mode: scan.scope.policy.mode, ruleDigest: scan.scope.policy.ruleDigest, trackedFileSemantics: scan.scope.policy.trackedFileSemantics } : { mode: 'legacy-walk', ruleDigest: null, trackedFileSemantics: false },
+    rules: { rulesetVersion: scan._rulesetVersion || null, rulesetSource: scan._rulesetVersionSource || null },
+    model: model ? { provider: model.provider, model: model.model, egress: model.egress, stages: model.stages } : { configured: false },
+    capability: { status: h.status || null, conditions: Array.isArray(h.conditions) ? h.conditions.length : 0 },
+    fileCounts: { scanned: scan.filesScanned ?? null, skipped: scan.scope ? scan.scope.skippedCount : null, included: scan.scope ? scan.scope.includedCount : null },
+    // Wall-clock time differs on every run, so deterministic mode leaves it out and the record stays byte-identical.
+    elapsedMs: process.env.AGENTIC_SECURITY_DETERMINISTIC === '1' ? null : (meta && meta.durationMs != null ? meta.durationMs : null),
+  };
+}
+
+/** The span a finding occupies: source line through sink line when both are known, else its own line. */
+function spanOf(f) {
+  const lines = [f.line, f.source && f.source.line, f.sink && f.sink.line].filter((n) => Number.isInteger(n));
+  if (!lines.length) return null;
+  return { startLine: Math.min(...lines), endLine: Math.max(...lines) };
+}
+
+/** Finding record. `fileContents` maps scan-relative path to text. Existing fields are untouched. */
+export function annotateFindingRecords(findings, fileContents, { engineVersion = null } = {}) {
+  for (const f of findings || []) {
+    if (!f || f.record) continue;
+    const text = fileContents && (fileContents instanceof Map ? fileContents.get(f.file) : fileContents[f.file]);
+    f.record = {
+      schema: FINDING_RECORD_SCHEMA,
+      stableId: f.stableId || null,
+      path: f.file || null,
+      sourceHash: typeof text === 'string' ? sha(text) : null,
+      span: spanOf(f),
+      ruleFamily: f.family || null,
+      ruleVersion: engineVersion,
+      originalSeverity: f.originalSeverity || f.severity || null,
+      confidence: typeof f.confidence === 'number' ? f.confidence : null,
+      disposition: f.disposition || null,
+      evidence: {
+        sourceToSink: f.source || f.sink ? { source: f.source || null, sink: f.sink || null } : null,
+        guards: f.falsification ? [f.falsification] : [],
+        missingEvidence: (f.dispositionDetail && f.dispositionDetail.missingEvidence) || [],
+      },
+      reviewerVerdicts: Array.isArray(f.reviewerVerdicts) ? f.reviewerVerdicts : [],
+      modelOpinion: f.validator_verdict ? { verdict: f.validator_verdict, confidence: f.llm_confidence ?? null } : null,
+      remediation: f.fix || f.remediation || null,
+    };
+  }
+  return findings;
+}
+
+/**
+ * Raw and displayed findings must reconcile: every raw item is either displayed or accounted for by a named reason.
+ * Returns { ok, raw, displayed, accounted, gap }.
+ */
+export function reconcileFindings({ raw, displayed, hidden = {} }) {
+  const accounted = Object.values(hidden).reduce((a, b) => a + b, 0);
+  const gap = raw - displayed - accounted;
+  return { ok: gap === 0, raw, displayed, accounted, gap };
+}

package/src/pipeline/scan-health.js

@@ -42,6 +42,17 @@ export const SCAN_HEALTH_SCHEMA_VERSION = 1;
  *   never a fabricated all-zero summary.
  * @returns {object} scanHealth per PRD §10.3, additive fields only.
  */
+// The per-file table travels with the record up to this many files; beyond it only the count is kept
+// (the aggregate stages, rates and incomplete lists above are always present).
+const HASKELL_BYFILE_INLINE_MAX = 2000;
+function summarizeHaskellCoverage(h) {
+  if (!h) return null;
+  const n = h.byFile ? Object.keys(h.byFile).length : 0;
+  if (n <= HASKELL_BYFILE_INLINE_MAX) return { ...h, byFileCount: n };
+  const { byFile, ...rest } = h;
+  return { ...rest, byFileCount: n, byFileOmitted: true };
+}
+
 export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engineErrors = null, deepStatus = null, analyzerCoverage = null, lineageStatus = null, languageCoverage = null, supplyChain = null } = {}) {
   const conditions = [];
   const safeAnnotatorErrors = Array.isArray(annotatorErrors) ? annotatorErrors : [];
@@ -130,7 +141,7 @@ export function computeScanHealth({ scanMeta = null, annotatorErrors = [], engin
     schemaVersion: SCAN_HEALTH_SCHEMA_VERSION,
     status,
     ...(trustFindings.length ? { buildTrust: { findings: trustFindings.length, uncertain: trustUncertain } } : {}),
-    ...(languageCoverage ? { languageCoverage: { totals: languageCoverage.totals ?? null, byKind: languageCoverage.byKind ?? null, ...(languageCoverage.limitations ? { limitations: languageCoverage.limitations } : {}), ...(languageCoverage.capabilities ? { capabilities: languageCoverage.capabilities } : {}), ...(languageCoverage.optionalModes ? { optionalModes: languageCoverage.optionalModes } : {}) } } : {}),
+    ...(languageCoverage ? { languageCoverage: { totals: languageCoverage.totals ?? null, byKind: languageCoverage.byKind ?? null, ...(languageCoverage.limitations ? { limitations: languageCoverage.limitations } : {}), ...(languageCoverage.capabilities ? { capabilities: languageCoverage.capabilities } : {}), ...(languageCoverage.optionalModes ? { optionalModes: languageCoverage.optionalModes } : {}), ...(languageCoverage.haskell ? { haskell: summarizeHaskellCoverage(languageCoverage.haskell) } : {}) } } : {}),
     files: {
       expected: scanMeta?.checkpoint?.total ?? null,
       scanned: scanMeta?.filesScanned ?? null,

package/src/posture/artifact-registry.js

@@ -253,6 +253,8 @@ export const ARTIFACT_REGISTRY = [
   { name: 'integrations.yml', kind: 'file', classification: 'operator-config' },
   { name: 'profile.yml', kind: 'file', classification: 'operator-config' },
   { name: 'sca-policy.yml', kind: 'file', classification: 'operator-config' },
+  { name: 'haskell-budget.json', kind: 'file', classification: 'generated', retentionClass: 'scan', source: 'src/language/haskell-budget-state.js (saveBudgetState)', note: 'Haskell parse budgets in effect and every file left unanalysed when one was hit, with a content digest, so the next scan can say what finished since. Rewritten by every scan that has Haskell work left.' },
+  { name: 'haskell-models.json', kind: 'file', classification: 'operator-config', note: 'reviewed project models for Haskell wrappers; only ever loaded by language/haskell-project-models.js' },
   { name: 'suppressions.yml', kind: 'file', classification: 'operator-config', note: 'audit-tier suppression config; only ever loaded, never saved, by posture/suppressions.js' },
   { name: 'network-policy.json', kind: 'file', classification: 'operator-config', note: 'documented as an Inputs-section artifact in posture/network-policy-import.js, not a scanner-written digest' },
   { name: 'privacy-taxonomy.json', kind: 'file', classification: 'operator-config', note: 'FR-402 privacy data-classification taxonomy overrides/additions — read by dataflow/privacy-taxonomy.js, never written by the scanner' },

package/src/posture/drift.js

@@ -78,7 +78,21 @@ export function driftBetween(scanA, scanB) {
   // Findings — use kind+file+line+vuln as the stable key.
   const allFindingsA = [...(scanA.findings || []), ...(scanA.logicVulns || [])];
   const allFindingsB = [...(scanB.findings || []), ...(scanB.logicVulns || [])];
-  const findings = _diffSets(allFindingsA, allFindingsB, _findingKey);
+  // A claim grouped under an equivalent primary (llm-validator/claim-groups.js) is still present: it keeps its identity for drift,
+  // so grouping never shows a finding as fixed, and ungrouping never shows one as new.
+  const findings = _diffSets([...allFindingsA, ...(scanA.groupedClaims || [])], [...allFindingsB, ...(scanB.groupedClaims || [])], _findingKey);
+  // PRD FR 01: a finding that disappeared because the newer scan did not cover its file is out of scope, never fixed.
+  const outOfScope = [];
+  if (scanB.scope && Array.isArray(scanB.scope.included)) {
+    const inB = new Set(scanB.scope.included);
+    const keep = [];
+    for (const f of findings.removed) (f && f.file && !inB.has(f.file) ? outOfScope : keep).push(f);
+    findings.removed = keep;
+    findings.outOfScope = outOfScope;
+  } else {
+    findings.outOfScope = [];
+    findings.scopeUnknown = !!(scanB.scope && scanB.scope.includedOmitted);
+  }
   const severity = _severityDelta(allFindingsA, allFindingsB);
   const authBoundaries = _authBoundaryDelta(scanA.routes || [], scanB.routes || []);
   const dataClasses = _dataClassDelta(scanA.routes || [], scanB.routes || []);
@@ -163,6 +177,10 @@ export function driftToMarkdown(drift) {
     lines.push(`**Findings fixed: ${drift.findings.removed.length}**`);
     lines.push('');
   }
+  if (drift.findings.outOfScope && drift.findings.outOfScope.length) {
+    lines.push(`**Findings not covered by this scan (out of scope, not fixed): ${drift.findings.outOfScope.length}**`);
+    lines.push('');
+  }
   if (drift.dataClasses.newlyExposed.length) {
     lines.push(`**Newly exposed data classes: ${drift.dataClasses.newlyExposed.join(', ')}**`);
     lines.push('');

package/src/posture/reachability-filter.js

@@ -25,12 +25,12 @@ const SEVERITY_DEMOTE = {
 // keeps full severity. route-reachable-via-function and function-reachable
 // both keep full severity because the vulnerable function is provably
 // called; import-reachable also keeps full severity (imported = uncertain
-// but plausible). The lower three tiers get demoted.
+// but plausible). manifest-only and transitive-only record only that no use was
+// observed, which is unknown reachability, and unknown reachability cannot lower
+// severity (PRD FR 08). Only positive evidence (unreachable, build-only) demotes.
 const DEMOTE_SCA_TIERS = new Set([
   'unreachable',       // function never called from project
   'build-only',        // dev/build-time dependency only
-  'manifest-only',     // declared, but no use observed
-  'transitive-only',   // transitive dep, scope unclear
 ]);
 
 export function demoteUnreachable(findings, opts = {}) {

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

package/src/runScan.js

@@ -3,12 +3,16 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import * as cp from 'node:child_process';
+import * as fsSync from 'node:fs';
 import { listFiles } from './util/glob.js';
+import { buildScanInventory } from './scope/inventory.js';
 import { hardenGitArgs, hardenGitEnv } from './util/git-hardening.js';
 import { runFullScan, shouldScan, isKubernetesManifest, isCloudFormationTemplate, isInstructionFile } from './engine.js';
 import { appendScanSnapshot } from './posture/security-trend.js';
 import { recover as recoverFixHistory } from './posture/fix-history.js';
 import { stampScan } from './posture/ruleset-version.js';
+import { annotateFindingRecords, buildScanRecord } from './pipeline/evidence-record.js';
+import { SCANNER_VERSION } from './posture/version.js';
 import { isLanguageManifest, isLanguageExcludedPath, isLanguageSource, readExplicitExports, WALK_IGNORE_GLOBS, impactedFiles, buildImportGraph, importClosure } from './language/discovery.js';
 
 const DEP_FILE_NAMES = new Set([
@@ -77,8 +81,23 @@ const DEFAULT_IGNORE = [
   ...WALK_IGNORE_GLOBS,
 ];
 
-export async function readTree(root, { ignore = [] } = {}) {
-  const entries = await listFiles(root, { ignore: [...DEFAULT_IGNORE, ...ignore] });
+// Directory names a Git-scoped scan still refuses regardless of Git state:
+// dependency trees and Git's own metadata. The broader DEFAULT_IGNORE list
+// (vendor, test, bin, ...) does NOT apply in Git-scoped mode: tracked code is
+// not discarded because of its folder name (PRD FR 01).
+const GIT_SCOPE_SAFETY_IGNORE = ['**/node_modules/**', '**/.git/**'];
+
+export async function readTree(root, { ignore = [], gitScope = process.env.AGENTIC_SECURITY_GIT_SCOPE === '1', scope = {} } = {}) {
+  let entries;
+  let inventory = null;
+  if (gitScope) {
+    // One inventory decides eligibility before any content is read.
+    inventory = buildScanInventory(root, scope);
+    const drop = [...GIT_SCOPE_SAFETY_IGNORE, ...ignore];
+    entries = inventory.included.filter((rel) => !drop.some((g) => path.matchesGlob(rel, g)));
+  } else {
+    entries = await listFiles(root, { ignore: [...DEFAULT_IGNORE, ...ignore] });
+  }
   const fileContents = {};
   const depFileContents = {};
   const oversize = [];
@@ -104,6 +123,7 @@ export async function readTree(root, { ignore = [] } = {}) {
     else if (/\.proto$/i.test(base)) depFileContents[rel] = content;
     else if (/\.(?:graphql|gql)$/i.test(base)) depFileContents[rel] = content;
     else if (/\.tf$/i.test(base)) depFileContents[rel] = content;
+    else if (/^(?:BUCK|TARGETS)(?:\.v2)?$/.test(base) && /\bhaskell_|prebuilt_haskell_library/.test(content)) depFileContents[rel] = content;
     // A Kubernetes manifest is admitted on CONTENT, not on living under a
     // directory named k8s/ — see isKubernetesManifest. Without this the
     // k8s-admission detector is wired into the dispatch and never invoked by it.
@@ -113,7 +133,7 @@ export async function readTree(root, { ignore = [] } = {}) {
     // A CloudFormation template is a `.yaml`/`.json` that no path predicate can
     // recognise — same problem as a Kubernetes manifest, same fix, and the same
     // requirement that BOTH gates open: runFullScan re-filters this exact list.
-    if (shouldScan(rel) || isKubernetesManifest(rel, content) || isCloudFormationTemplate(rel, content) || isInstructionFile(rel)) fileContents[rel] = content;
+    if (shouldScan(rel, !!gitScope) || isKubernetesManifest(rel, content) || isCloudFormationTemplate(rel, content) || isInstructionFile(rel)) fileContents[rel] = content;
     // Auxiliary files: .properties files are referenced by Java rules
     // (e.g. OWASP Benchmark's benchmark.properties resolves algorithm
     // aliases). They are not scannable for vulns themselves, but the
@@ -127,7 +147,7 @@ export async function readTree(root, { ignore = [] } = {}) {
     const { contents } = readExplicitExports(root, manifests);
     for (const [rel, text] of Object.entries(contents)) depFileContents[rel] = text;
   } catch { /* exports are best-effort evidence */ }
-  return { fileContents, depFileContents, oversize };
+  return { fileContents, depFileContents, oversize, inventory };
 }
 
 // Feat-10: incremental scan via `--changed-since <git-ref>`. Returns the set of
@@ -174,6 +194,16 @@ export async function languageFilesIgnoredByPolicy(root, fileContents, depFileCo
   return all.filter((rel) => (isLanguageSource(rel) || isLanguageManifest(rel)) && !isLanguageExcludedPath(rel) && !seen.has(rel)).sort().slice(0, 500);
 }
 
+// FR 02: an explicit package layout for Buck or custom builds, `{ "packages": { "name": ["dir", ...] } }`.
+// Read as data only; nothing in the map is executed and the build is not run.
+function loadHaskellSourceMap(file, root) {
+  if (!file) return null;
+  const abs = path.resolve(root, file);
+  const doc = JSON.parse(fsSync.readFileSync(abs, 'utf8'));
+  if (!doc || typeof doc !== 'object' || !doc.packages || typeof doc.packages !== 'object') throw new Error(`Haskell source map ${file} must be {"packages": {"<name>": ["<dir>", ...]}}`);
+  return { packages: doc.packages, file: path.relative(root, abs) };
+}
+
 export async function runScan(rootDir, opts = {}) {
   const root = path.resolve(rootDir);
   const startedAt = new Date().toISOString();
@@ -202,6 +232,7 @@ export async function runScan(rootDir, opts = {}) {
   // false claim of coverage.
   let completeScan = true;
   let sizeSkipped = [];
+  let scopeInventory = null;
   if (opts.fileContents) {
     // Caller-supplied file list (MCP `scan_diff`, the LSP's on-save scan): by
     // construction a subset of the tree, not a scan of it.
@@ -209,7 +240,7 @@ export async function runScan(rootDir, opts = {}) {
     depFileContents = opts.depFileContents || {};
     completeScan = false;
   } else {
-    ({ fileContents, depFileContents, oversize: sizeSkipped } = await readTree(root, opts));
+    ({ fileContents, depFileContents, oversize: sizeSkipped, inventory: scopeInventory } = await readTree(root, opts));
   }
 
   // Haskell/Nix sources under a default-ignored directory (tests, specs, mocks, bin, build, dist, vendor) are not
@@ -254,10 +285,33 @@ export async function runScan(rootDir, opts = {}) {
 
   // R8: `resume` is opt-in. Left undefined here, runFullScan falls back to the
   // AGENTIC_SECURITY_RESUME=1 env var, which is off by default.
-  const scan = await runFullScan({ fileContents, depFileContents, scanRoot: root, resume: opts.resume, deep: opts.deep, deepInCi: opts.deepInCi, completeScan, policyExcluded, sizeSkipped }, opts.onProgress || (()=>{}));
+  const scan = await runFullScan({ fileContents, depFileContents, scanRoot: root, resume: opts.resume, deep: opts.deep, deepInCi: opts.deepInCi, completeScan, policyExcluded, sizeSkipped, haskellSourceMap: loadHaskellSourceMap(opts.haskellSourceMap, root), gitScope: !!scopeInventory }, opts.onProgress || (()=>{}));
   // Premortem 2R4.2: stamp ruleset version + source on the scan result, and
   // notify if the operator pinned a different version than what's installed.
   try { stampScan(root, scan); } catch {}
+  // FR 01: additive scope record (never replaces an existing field). Skipped paths are
+  // capped; the counts are exact.
+  if (scopeInventory) {
+    const reasons = {};
+    for (const x of scopeInventory.skipped) reasons[x.reason] = (reasons[x.reason] || 0) + 1;
+    scan.scope = {
+      schema: 1,
+      policy: scopeInventory.policy,
+      includedCount: scopeInventory.included.length,
+      // The included list itself lets a later comparison tell "no longer reported because it was fixed" from "no longer reported
+      // because a narrower scan did not look". Kept only when small enough not to bloat the record.
+      ...(scopeInventory.included.length <= 5000 ? { included: scopeInventory.included } : { includedOmitted: true }),
+      skippedCount: scopeInventory.skipped.length,
+      skippedByReason: reasons,
+      skipped: scopeInventory.skipped.slice(0, 500),
+      overrides: scopeInventory.overrides,
+      coverageConditions: scopeInventory.skipped.filter((x) => x.coverageCondition).slice(0, 100),
+    };
+  }
+  // FR 10: additive evidence contract. Finding records carry the source hash and span; the scan record ties the run to a commit,
+  // dirty-file digests, the ignore-policy digest and the invocation. Neither replaces an existing field.
+  try { annotateFindingRecords(scan.findings, fileContents, { engineVersion: SCANNER_VERSION }); } catch {}
+  try { scan.scanRecord = buildScanRecord({ root, scan, meta: { mode: opts.changedSince ? 'incremental' : 'full', durationMs: Date.now() - t0 }, argv: opts.invocation || [], engineVersion: SCANNER_VERSION }); } catch {}
   // Append snapshot to history for /security-trend (non-blocking, never throws)
   try { appendScanSnapshot(scan, root); } catch {}
   return {