@clear-capabilities/agentic-security-scanner 0.130.0 → 0.133.0

package/src/posture/prove-findings.js

@@ -0,0 +1,148 @@
+// Promote findings to `execution-proven` during a scan (R2 — the automatic half).
+//
+// Before this, `proveFinding` existed and was tested but had no call site in a
+// scan, so `last-scan.json` could never contain an execution-proven finding and
+// corpus auto-enrolment had to be driven by hand. This annotator closes that:
+// it synthesizes a sandbox-runnable PoC for eligible findings, runs it inside
+// R1's sandbox, and lets the sandbox decide the tier.
+//
+// OPT-IN, AND IT STAYS OPT-IN. This executes code derived from the scanned
+// project. That is a different risk class from static analysis, and it is slow
+// — one sandboxed process per candidate. Making it default-on would change
+// what `scan` means. Enable with `AGENTIC_SECURITY_PROVE=1`.
+//
+// FAIL-CLOSED IN BOTH DIRECTIONS:
+//   - No sandbox → nothing is executed and no tier is promoted. An
+//     unavailable sandbox disables the feature, it never bypasses it.
+//   - A PoC that could not run leaves the finding at its static tier. Only a
+//     PoC that RAN and produced the marker yields `execution-proven`;
+//     `attachProofTier` enforces that independently of anything here.
+//
+// BOUNDED TWICE, BECAUSE ONE BOUND WAS NOT ENOUGH. `maxCandidates` caps how
+// many findings are proved in one scan, and the cap is REPORTED rather than
+// applied silently — a scan that quietly proved the first N findings and said
+// nothing would look like a scan that found only N provable ones.
+//
+// A count cap alone bounds nothing in time, though, and a per-run timeout is
+// only as good as the backend's ability to enforce it — which CI proved is not
+// something to take on faith (the namespace backend's timeout did not stop a
+// payload at all until `killSignal: 'SIGKILL'` landed). So there is also an
+// AGGREGATE wall-clock budget checked between candidates. It cannot interrupt a
+// call already in flight (`spawnSync` blocks the thread), but it bounds the
+// total and stops the loop rather than letting a slow host multiply one bad
+// case by `maxCandidates`.
+//
+// WHAT THIS ACTUALLY EXECUTES, STATED PLAINLY. The generated PoC does
+// `import handler from './<target file>'`, and an ES module import runs the
+// target file's ENTIRE TOP-LEVEL BODY before any handler is called. So enabling
+// this on a repository you do not trust executes that repository's top-level
+// code. Confinement contains what it can — no filesystem writes outside the
+// sandbox root, no network egress, both verified by executing tests on each
+// backend — but CPU and wall-clock are bounded only by the budgets here. Do not
+// enable this on untrusted code without accepting that.
+
+import { synthesizeInProcessPoc } from './poc-inprocess.js';
+import { proveFinding } from './execution-proof.js';
+import { sandboxAvailable } from '../sandbox/index.js';
+
+const DEFAULT_MAX = 25;
+// Aggregate wall-clock across all candidates in one scan.
+const DEFAULT_TOTAL_BUDGET_MS = 120000;
+
+export function proveEnabled(env = process.env) {
+  return env.AGENTIC_SECURITY_PROVE === '1';
+}
+
+/**
+ * @param {object[]} findings   annotated findings (mutated in place)
+ * @param {object}   opts
+ * @param {Map|object} opts.fileContents  file -> source, as the engine already carries
+ * @returns {object} a summary suitable for surfacing on the scan
+ */
+export async function annotateExecutionProofs(findings, {
+  fileContents = null, maxCandidates = DEFAULT_MAX, timeoutMs = 10000,
+  totalBudgetMs = DEFAULT_TOTAL_BUDGET_MS, env = process.env, now = Date.now,
+} = {}) {
+  const summary = {
+    enabled: false, attempted: 0, proven: 0, failed: 0, inconclusive: 0,
+    skipped: 0, capped: 0, budgetExhausted: 0, reason: null,
+  };
+  if (!Array.isArray(findings) || !findings.length) return summary;
+  if (!proveEnabled(env)) {
+    summary.reason = 'not enabled (set AGENTIC_SECURITY_PROVE=1)';
+    return summary;
+  }
+  if (!sandboxAvailable()) {
+    // Deliberately not an error: an unavailable confinement primitive means
+    // execution features switch OFF, per R1's constraint.
+    summary.reason = 'no confinement backend available; execution proof disabled';
+    return summary;
+  }
+  summary.enabled = true;
+
+  const read = (file) => {
+    if (!fileContents) return null;
+    if (typeof fileContents.get === 'function') return fileContents.get(file) ?? null;
+    return fileContents[file] ?? null;
+  };
+
+  const candidates = [];
+  for (const f of findings) {
+    if (!f || typeof f !== 'object') continue;
+    const content = read(f.file);
+    const syn = synthesizeInProcessPoc(f, content);
+    if (!syn.ok) { summary.skipped++; continue; }
+    candidates.push({ finding: f, poc: syn.poc, content });
+  }
+
+  if (candidates.length > maxCandidates) {
+    summary.capped = candidates.length - maxCandidates;
+    candidates.length = maxCandidates;
+  }
+
+  const startedAt = now();
+  for (const c of candidates) {
+    // Checked BEFORE each call, since a call in flight cannot be interrupted.
+    // Reported, never silent: findings left unproven because the budget ran out
+    // are a different statement from findings that could not be proved.
+    if (now() - startedAt >= totalBudgetMs) {
+      summary.budgetExhausted = candidates.length - summary.attempted;
+      break;
+    }
+    summary.attempted++;
+    // The PoC imports the vulnerable file, so it must exist in the sandbox
+    // root alongside it.
+    const files = {};
+    for (const rel of c.poc.requires || []) files[rel] = c.content;
+    let proved;
+    try {
+      proved = await proveFinding({ ...c.finding, poc: c.poc }, { files, timeoutMs });
+    } catch (e) {
+      summary.inconclusive++;
+      continue;
+    }
+    c.finding.poc = c.poc;
+    c.finding.proofTier = proved.proofTier;
+    c.finding.proofEvidence = proved.proofEvidence;
+    if (proved.proofTier === 'execution-proven') summary.proven++;
+    else if (proved.proofTier === 'proof-failed') summary.failed++;
+    else summary.inconclusive++;
+  }
+  return summary;
+}
+
+/** One-line human summary; null when the feature did not run. */
+export function renderProofSummary(s) {
+  if (!s || !s.enabled) return null;
+  const bits = [`${s.proven} execution-proven of ${s.attempted} attempted`];
+  if (s.failed) bits.push(`${s.failed} ran without demonstrating the bug (triage signal, NOT a false-positive verdict)`);
+  if (s.inconclusive) bits.push(`${s.inconclusive} inconclusive`);
+  if (s.capped) bits.push(`${s.capped} eligible finding(s) NOT attempted (per-scan cap)`);
+  if (s.budgetExhausted) {
+    bits.push(`${s.budgetExhausted} eligible finding(s) NOT attempted (aggregate time budget exhausted) — `
+      + 'unproven here means unattempted, not unprovable');
+  }
+  return bits.join('; ') + '.';
+}
+
+export const _internals = { DEFAULT_MAX, DEFAULT_TOTAL_BUDGET_MS };

package/src/posture/rule-overrides.js

@@ -120,11 +120,72 @@ export function applyOverrides(findings, scanRoot) {
     disable = new Set();
   }
   const sevMap = o.severityOverrides || {};
-  return findings
-    .filter(f => !disable.has(f.vuln) && !disable.has(f.id))
-    .map(f => sevMap[f.vuln] ? { ...f, severity: sevMap[f.vuln] } : f);
+  const kept = [];
+  for (const f of findings) {
+    const key = disable.has(f.vuln) ? f.vuln : (disable.has(f.id) ? f.id : null);
+    if (key !== null) {
+      // RECORD the suppression. A `disable:` that takes effect otherwise
+      // produces findings that are simply absent — indistinguishable, in the
+      // artifact a human reads, from a clean scan. Coverage reduction must be
+      // visible where the results are, not only on a stderr line nobody keeps.
+      _recordSuppression(scanRoot, key, f);
+      continue;
+    }
+    kept.push(sevMap[f.vuln] ? { ...f, severity: sevMap[f.vuln] } : f);
+  }
+  return kept;
+}
+
+// Per-scanRoot ledger of what `disable:` removed, and under what authority.
+// Read by the CLI and attached to the scan output.
+const _suppressions = new Map();
+
+function _recordSuppression(scanRoot, key, finding) {
+  const root = String(scanRoot || '');
+  let e = _suppressions.get(root);
+  if (!e) { e = { rules: new Map(), total: 0 }; _suppressions.set(root, e); }
+  let r = e.rules.get(key);
+  if (!r) { r = { rule: key, count: 0, severities: {}, examples: [] }; e.rules.set(key, r); }
+  r.count++;
+  e.total++;
+  const sev = finding?.severity || 'unknown';
+  r.severities[sev] = (r.severities[sev] || 0) + 1;
+  // A bounded sample so a reader can see WHAT was removed, not just how much.
+  if (r.examples.length < 5 && finding?.file) {
+    r.examples.push(`${finding.file}${finding.line ? ':' + finding.line : ''}`);
+  }
 }
 
+/**
+ * What `disable:` removed from this scan, and under what authority.
+ *
+ * Returns null when nothing was suppressed — callers omit the section rather
+ * than rendering an empty one. `authority` is the reason the gate allowed it,
+ * so a reader can tell a signed suppression from an env-var opt-out.
+ */
+export function suppressionReport(scanRoot) {
+  const e = _suppressions.get(String(scanRoot || ''));
+  if (!e || !e.total) return null;
+  const gate = _disableAllowed(scanRoot);
+  return {
+    total: e.total,
+    authority: gate.reason,
+    rules: [...e.rules.values()].sort((a, b) => b.count - a.count || (a.rule < b.rule ? -1 : 1)),
+    note: 'These findings were REMOVED from the report by `disable:` in '
+      + '.agentic-security/rules.yml. They are not absent because the code is clean.',
+  };
+}
+
+/** One-line human summary; null when nothing was suppressed. */
+export function renderSuppressionSummary(rep) {
+  if (!rep) return null;
+  const top = rep.rules.slice(0, 3).map(r => `${r.rule} (${r.count})`).join(', ');
+  return `${rep.total} finding(s) SUPPRESSED by rules.yml disable: [${top}${rep.rules.length > 3 ? ', …' : ''}] `
+    + `— authority: ${rep.authority}. These are removed results, not clean code.`;
+}
+
+export function _resetSuppressionsForTests() { _suppressions.clear(); }
+
 // Cache: compiled custom rules per scanRoot. Validated at first call;
 // subsequent calls for the same scan reuse the compiled regexes.
 const _compiledCustomRules = new Map();   // scanRoot → { compiled[], errors[] }

package/src/posture/state-dir.js

@@ -16,6 +16,8 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 
+const STATE_DIR_NAME = '.agentic-security';
+
 const PROJECT_MARKERS = [
   '.git',
   'package.json',
@@ -83,6 +85,29 @@ export function isSafeStateDir(dir) {
       if (fs.existsSync(path.join(parent, m))) return true;
     } catch { /* ignore */ }
   }
+  // A directory NESTED inside an already-valid state root is safe too.
+  //
+  // Without this the check only ever accepted `<project>/.agentic-security`
+  // itself, because it looks for a project marker in the immediate parent and
+  // `.agentic-security` deliberately does not count as one. Every nested state
+  // directory — `llm-cache/`, `fix-history/`, `sbom-history/` — therefore
+  // failed, and `safeWriteState` silently refused to write there.
+  //
+  // The consequence was not theoretical: `llm-validator`'s `writeCache` goes
+  // through `safeWriteState`, so the validator cache never persisted a single
+  // entry. Every scan re-queried the model for every finding, while a
+  // `validator-cache stats|gc` subcommand existed to manage a cache that was
+  // always empty. Found by a positive-control test asserting that a
+  // legitimately written entry round-trips.
+  //
+  // This does not weaken the guard. Its purpose is to stop `.agentic-security/`
+  // being created in unrelated directories; a subdirectory of a state root that
+  // has already been validated is exactly the case it was never meant to catch.
+  const segments = path.resolve(dir).split(path.sep);
+  const idx = segments.lastIndexOf(STATE_DIR_NAME);
+  if (idx > 0 && idx < segments.length - 1) {
+    return isSafeStateDir(segments.slice(0, idx + 1).join(path.sep));
+  }
   return false;
 }
 

package/src/posture/vuln-archaeology.js

@@ -0,0 +1,231 @@
+// R14 — vulnerability archaeology.
+//
+// The engine scores the CURRENT tree, and `material-change.js` scores a diff.
+// Neither reads history. But a repository's history holds a signal nothing in
+// the present tree does: WHERE this team has introduced security bugs before,
+// and how often those places needed fixing again.
+//
+// The output is not a finding. It is a per-file risk prior — "this file has
+// been security-fixed four times in the last two years" — that ranks where
+// attention is worth spending. Emitting archaeology as findings would be
+// wrong twice over: the bugs are already fixed, and a historical fix is not
+// evidence of a present defect.
+//
+// HOW A SECURITY FIX IS RECOGNISED, AND WHY THAT IS THE HARD PART. There is no
+// reliable marker. Commit messages are the only broad signal, and they are
+// written by humans in a hurry. So the classifier is deliberately conservative
+// and every match carries the evidence that produced it:
+//
+//   - A CVE/GHSA identifier is strong evidence and is treated as such.
+//   - A vocabulary of fix verbs paired with vulnerability nouns ("fix XSS",
+//     "patch the traversal") is medium evidence.
+//   - A bare vulnerability noun is weak: "add XSS tests", "refactor the auth
+//     module" and "document CSRF" all mention the noun without fixing
+//     anything. These are counted separately and never inflate the strong tier.
+//
+// FALSE POSITIVES ARE EXPECTED AND MUST STAY VISIBLE. A message-based
+// classifier cannot be precise, so the module reports its tiers separately
+// rather than collapsing them into one confident number, and every hotspot
+// carries the commit subjects behind it so a human can dismiss a bad match in
+// seconds. A single blended "risk score" would hide exactly the errors a
+// reader needs to see.
+//
+// Offline and cheap: one `git log` invocation, bounded by commit count and a
+// timeout, degrading to an empty result in a non-repository.
+
+import { execFileSync } from 'node:child_process';
+
+const CVE_RE = /\b(?:CVE-\d{4}-\d{4,7}|GHSA-[a-z0-9]{4}-[a-z0-9]{4}-[a-z0-9]{4})\b/i;
+
+const FIX_VERBS = /\b(?:fix(?:e[sd])?|patch(?:e[sd])?|resolv(?:e[sd])|remediat(?:e[sd])|harden(?:ed)?|mitigat(?:e[sd])|prevent(?:ed)?|sanitiz(?:e[sd])|escap(?:e[sd])|clos(?:e[sd]))\b/i;
+
+const VULN_NOUNS = new RegExp([
+  'xss', 'cross[- ]site scripting', 'csrf', 'cross[- ]site request forgery',
+  'sql[- ]?injection', 'sqli', 'command[- ]?injection', 'code[- ]?injection',
+  'path[- ]?traversal', 'directory[- ]?traversal', 'ssrf', 'xxe',
+  'deserializ', 'prototype[- ]pollution', 'open[- ]redirect', 'redos',
+  'privilege escalation', 'auth(?:entication|orization)? bypass', 'idor',
+  'insecure[- ]direct[- ]object', 'race condition', 'use[- ]after[- ]free',
+  'buffer overflow', 'integer overflow', 'timing attack', 'security', 'vulnerab',
+  'exploit', 'injection', 'sanitiz', 'unsafe[- ]eval', 'hardcoded (?:secret|password|key|credential)',
+].join('|'), 'i');
+
+// Messages that mention a vulnerability noun while plainly not fixing one.
+// Checked BEFORE the verb pair, because "add tests for the XSS fix" contains
+// both a fix verb and a noun yet fixes nothing.
+//
+// KEPT DELIBERATELY NARROW. Words like "comment", "format", "example", "spec"
+// and "demo" look like chore markers but are ordinary code vocabulary — "fix
+// XSS in the comment renderer" is a real fix, and an over-broad list demotes it
+// to the weak tier. Every word here has to be one that describes the COMMIT'S
+// PURPOSE and is unlikely to name a code component. When in doubt leave a word
+// out: a missed demotion costs one over-counted hotspot, while a wrong one
+// hides a real security fix from the ranking entirely.
+const NON_FIX_RE = /\b(?:test(?:s|ing|ed)?|doc(?:s|ument(?:s|ed|ing|ation)?)?|readme|changelog|typo|rename[ds]?|lint|bump(?:ed)?|revert(?:ed)?|wip|todo)\b/i;
+
+export const TIERS = Object.freeze(['identified', 'likely', 'mentioned']);
+
+/**
+ * Classify one commit subject.
+ * @returns {{tier:string, evidence:string}|null}
+ */
+export function classifyCommit(subject) {
+  if (typeof subject !== 'string' || !subject.trim()) return null;
+  const s = subject.trim();
+
+  const cve = s.match(CVE_RE);
+  if (cve) return { tier: 'identified', evidence: `references ${cve[0]}` };
+
+  const noun = s.match(VULN_NOUNS);
+  if (!noun) return null;
+
+  if (NON_FIX_RE.test(s)) {
+    return { tier: 'mentioned', evidence: `mentions "${noun[0]}" but reads as test/doc/chore work` };
+  }
+  const verb = s.match(FIX_VERBS);
+  if (verb) return { tier: 'likely', evidence: `"${verb[0]}" + "${noun[0]}"` };
+  return { tier: 'mentioned', evidence: `mentions "${noun[0]}" with no fix verb` };
+}
+
+function _gitLog(scanRoot, { maxCommits, timeoutMs }) {
+  // NUL-delimited records so subjects containing newlines cannot split a
+  // record — a commit message is arbitrary user text and must not be able to
+  // forge a record boundary.
+  const out = execFileSync('git', [
+    '-C', scanRoot, 'log', '-n', String(maxCommits), '--no-merges', '--no-color',
+    '--name-only', '--format=%x00%H%x1f%aI%x1f%s',
+  ], { encoding: 'utf8', timeout: timeoutMs, maxBuffer: 64 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] });
+  const commits = [];
+  for (const block of out.split('\0')) {
+    if (!block.trim()) continue;
+    const nl = block.indexOf('\n');
+    const header = nl === -1 ? block : block.slice(0, nl);
+    const [sha, date, ...rest] = header.split('\x1f');
+    if (!sha) continue;
+    const files = nl === -1 ? [] : block.slice(nl + 1).split('\n').map(l => l.trim()).filter(Boolean);
+    commits.push({ sha, date: date || null, subject: rest.join('\x1f') || '', files });
+  }
+  return commits;
+}
+
+/**
+ * Mine history for security-relevant commits and turn them into per-file priors.
+ *
+ * @returns {{available:boolean, reason:string|null, commitsScanned:number,
+ *            byTier:object, hotspots:Array, commits:Array}}
+ */
+export function mineVulnHistory(scanRoot, { maxCommits = 500, timeoutMs = 30000, maxHotspots = 25, minConcentration = 0.15 } = {}) {
+  const empty = {
+    available: false, reason: null, commitsScanned: 0,
+    byTier: { identified: 0, likely: 0, mentioned: 0 }, hotspots: [], commits: [],
+  };
+  if (!scanRoot) return { ...empty, reason: 'no scan root' };
+
+  let commits;
+  try {
+    commits = _gitLog(scanRoot, { maxCommits, timeoutMs });
+  } catch (e) {
+    // Not a repository, git absent, shallow clone, timeout — all "no history
+    // available", never an error that fails a scan.
+    return { ...empty, reason: `git history unavailable: ${String(e.message || e).split('\n')[0]}` };
+  }
+
+  const byTier = { identified: 0, likely: 0, mentioned: 0 };
+  const perFile = new Map();
+  const matched = [];
+
+  const _file = (f) => {
+    let e = perFile.get(f);
+    if (!e) { e = { file: f, identified: 0, likely: 0, mentioned: 0, totalCommits: 0, subjects: [] }; perFile.set(f, e); }
+    return e;
+  };
+
+  // Total touches first, across EVERY commit. Without this the ranking rewards
+  // churn: a release commit whose subject says "fix XSS ..." also touches the
+  // changelog, the manifest and the version file, so the most-edited files in
+  // the repository float to the top of a raw count and the actual vulnerable
+  // source is buried. Measured on this repository, the raw ranking returned
+  // CLAUDE.md and package.json as the top two hotspots.
+  for (const c of commits) for (const f of c.files) _file(f).totalCommits++;
+
+  for (const c of commits) {
+    const cls = classifyCommit(c.subject);
+    if (!cls) continue;
+    byTier[cls.tier]++;
+    matched.push({ sha: c.sha.slice(0, 12), date: c.date, subject: c.subject, tier: cls.tier, evidence: cls.evidence, files: c.files.length });
+    for (const file of c.files) {
+      const e = _file(file);
+      e[cls.tier]++;
+      // Keep a bounded sample of the evidence, so a hotspot can be judged
+      // without re-reading the log.
+      if (e.subjects.length < 5) e.subjects.push({ sha: c.sha.slice(0, 12), tier: cls.tier, subject: c.subject });
+    }
+  }
+
+  const hotspots = [...perFile.values()]
+    // `mentioned` deliberately does NOT contribute to the ranking weight. It is
+    // the tier most likely to be wrong, so letting it rank files would sort by
+    // classifier error. It is still reported per file so a reader can see it.
+    .map(e => {
+      const weight = e.identified * 3 + e.likely;
+      // What fraction of this file's history is security work. A file touched
+      // by 200 commits of which 3 were security fixes is not a hotspot; one
+      // touched 4 times, 3 of them security fixes, is.
+      const concentration = e.totalCommits ? (e.identified + e.likely) / e.totalCommits : 0;
+      return { ...e, weight, concentration: Number(concentration.toFixed(3)) };
+    })
+    .filter(e => e.weight > 0 && e.concentration >= minConcentration)
+    // Rank by concentration first: it is the churn-corrected signal. Weight
+    // breaks ties so that, among equally-concentrated files, more security
+    // history ranks higher.
+    .sort((a, b) => b.concentration - a.concentration || b.weight - a.weight || (a.file < b.file ? -1 : 1))
+    .slice(0, maxHotspots);
+
+  return {
+    available: true,
+    reason: null,
+    commitsScanned: commits.length,
+    // Stated so a reader knows whether they are looking at all of history.
+    truncated: commits.length >= maxCommits,
+    byTier,
+    hotspots,
+    commits: matched.slice(0, 100),
+  };
+}
+
+/**
+ * Attach the historical prior to findings whose file is a hotspot.
+ * Advisory only: never changes severity, never removes anything.
+ */
+export function annotateHistoricalRisk(findings, history) {
+  if (!Array.isArray(findings) || !history?.available) return 0;
+  const byFile = new Map(history.hotspots.map(h => [h.file, h]));
+  let n = 0;
+  for (const f of findings) {
+    const h = f && f.file ? byFile.get(f.file) : null;
+    if (!h) continue;
+    f.historicalRisk = {
+      priorSecurityFixes: h.identified + h.likely,
+      identified: h.identified,
+      likely: h.likely,
+      note: 'advisory prior from git history — not evidence about this finding',
+    };
+    n++;
+  }
+  return n;
+}
+
+/** One-line summary; null when there is no history to report. */
+export function renderArchaeology(h) {
+  if (!h) return null;
+  if (!h.available) return `vulnerability archaeology: skipped (${h.reason}).`;
+  const { identified, likely, mentioned } = h.byTier;
+  if (!identified && !likely && !mentioned) {
+    return `vulnerability archaeology: no security-relevant commits in the last ${h.commitsScanned}.`;
+  }
+  return `vulnerability archaeology: ${identified} CVE-identified, ${likely} likely and ${mentioned} `
+    + `merely-mentioning commit(s) across ${h.commitsScanned} scanned${h.truncated ? ' (history truncated)' : ''}; `
+    + `${h.hotspots.length} file hotspot(s). Ranking ignores the "mentioned" tier — it is the least reliable.`;
+}
+
+export const _internals = { CVE_RE, FIX_VERBS, VULN_NOUNS, NON_FIX_RE, _gitLog };

package/src/report/index.js

@@ -412,6 +412,13 @@ export function toJSON(scan, meta={}, opts={}){
     // It carries its own `proves` / `doesNotProve` statement — do not quote
     // the digest as cross-machine reproducibility, which it is not.
     attestation: scan.attestation || null,
+    // Coverage reduction, surfaced in the ARTIFACT. `disable:` in rules.yml
+    // removes findings from the report, and a removed finding is
+    // indistinguishable from clean code unless the removal is stated. Null when
+    // nothing was suppressed, so consumers can omit the section rather than
+    // render an empty one. An AUTHORISED suppression is reported too — the
+    // signature proves who asked for it, not that the results are absent.
+    suppressedRules: scan.suppressedRules || null,
     _scanMeta: scan._scanMeta || null,
   };
   if (opts.includeSuppressed) out.suppressed = scan.suppressions||[];

package/src/runScan.js

@@ -3,7 +3,7 @@
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
 import * as cp from 'node:child_process';
-import fg from 'fast-glob';
+import { listFiles } from './util/glob.js';
 import { runFullScan, shouldScan } from './engine.js';
 import { appendScanSnapshot } from './posture/security-trend.js';
 import { recover as recoverFixHistory } from './posture/fix-history.js';
@@ -26,11 +26,7 @@ const DEFAULT_IGNORE = [
 ];
 
 export async function readTree(root, { ignore = [] } = {}) {
-  const entries = await fg('**/*', {
-    cwd: root, dot: true, onlyFiles: true,
-    ignore: [...DEFAULT_IGNORE, ...ignore], followSymbolicLinks: false,
-    suppressErrors: true,
-  });
+  const entries = await listFiles(root, { ignore: [...DEFAULT_IGNORE, ...ignore] });
   const fileContents = {};
   const depFileContents = {};
   for (const rel of entries) {