fad-checker 2.3.2 → 2.4.1

package/CHANGELOG.md

@@ -5,7 +5,44 @@ This project adheres to [Semantic Versioning](https://semver.org/).
 
 ## [Unreleased]
 
+### Changed
+- **Report chapters reorganised into a two-level hierarchy.** Related chapters are now
+  grouped under six **root chapters**, each whose header carries a breakdown count:
+  **1. CVE** (`X direct, Y indirect, Z dev` — sub: Production, Vendored JS vulns, Dev,
+  Likely false positives) · **2. Unmanaged / unversioned components** (`X embedded,
+  Y native, Z vendored JS` — sub: embedded JAR/WAR/EAR, native binaries, vendored JS) ·
+  **3. Maintenance / lifecycle** (`X EOL, Y obsolete, Z outdated`) · **4. Licenses** ·
+  **5. Fix Recommendations** · **6. Scan context & limitations** (sub: scanned
+  descriptors, ignored dirs, methodology). **0. Warnings** and **Δ. Changes since
+  baseline** stay pinned at the top. The table of contents is now hierarchical
+  (roots + indented sub-chapters).
+
 ### Added
+- **Scan-provenance manifest + Methodology chapter (audit reproducibility).** Every
+  report now carries a provenance manifest — tool version, run mode (offline/online),
+  the findings-affecting configuration, and the **freshness of every data source**
+  (CVE index, OSV, NVD, KEV, EPSS, endoflife, registry caches) read from
+  `~/.fad-checker/`. Surfaced in the JSON export's `provenance` block and in the
+  report's new **chapter 12 — "Methodology, data sources & limitations"**, which also
+  states explicitly **what fad-checker does *not* assess** (reachability, runtime
+  config, secrets/IaC, first-party code, malware beyond the OSV/CIRCL signal, legal
+  license advice). New `lib/provenance.js`.
+- **Differential audits (`--baseline` / `fad diff`).** Diff a scan against a prior
+  findings JSON: the report gains a **"Δ Changes since baseline"** chapter, the JSON
+  export gains a `diff` block (summary + new/fixed CVEs), and CI can gate on **new**
+  findings with `--fail-on-new` (exit 1 on any new production CVE). Standalone
+  `fad-checker diff <baseline.json> <current.json> [--report-json <out>] [--fail-on-new]`
+  for ad-hoc comparison. Finding identity = CVE id + ecosystem + coord + version. New
+  `lib/diff.js`.
+- **Report integrity manifest.** A standard `SHA256SUMS` is written beside the report
+  artifacts (verifiable with `sha256sum -c`); `--no-checksums` disables it. New
+  `lib/report-integrity.js`.
+- **Private registries for NuGet and Composer** (previously the only registry-backed
+  ecosystems without private-feed support). NuGet custom feeds speak the v3
+  registration API (a service-index `…/index.json` is auto-resolved to its
+  `RegistrationsBaseUrl`); Composer custom feeds are queried via the v2
+  `<base>/p2/<vendor>/<pkg>.json` metadata API. Same `--add-repo nuget|composer …`
+  CRUD + auth as the other ecosystems.
 - **Custom registries for npm, PyPI, Ruby and Go** (previously Maven-only). Point
   fad-checker at private Verdaccio/Artifactory/GitHub Packages (npm), devpi (PyPI),
   Gemfury/Geminabox (Ruby) or a private GOPROXY/Athens (Go). They are tried in
@@ -49,6 +86,17 @@ This project adheres to [Semantic Versioning](https://semver.org/).
   repos with `--add-repo maven <name> <url>`.
 
 ### Fixed
+- **A failing `--snyk` run is no longer silently reported as "0 findings".** Snyk
+  exits 2 on a command error (e.g. not authenticated) and 3 when it detects no
+  supported project — but in `--json` mode it still writes a JSON document to
+  **stdout**, shaped `{ ok:false, error:"…" }`. `runSnykTest`'s catch block treated
+  *any* stdout on a non-zero exit as "vulns found (exit 1)", so that error JSON was
+  parsed to zero vulnerabilities and surfaced as a green `Snyk: 0 findings merged`,
+  hiding the failure. It now distinguishes real results (a `vulnerabilities` array or
+  `ok:true`) from error stubs and **throws the snyk error message** (deduped, joined),
+  which the orchestrator shows as a `Snyk run failed: …` warning. A snyk crash with no
+  stdout now surfaces `stderr` instead of `execFile`'s generic "Command failed", and a
+  timeout is reported as such. New pure helper `snykOutputError()` (unit-tested).
 - **retire.js now skips the same dirs as the rest of the scan.** The vendored-JS
   scan walks the tree itself and was handed a bare `--ignore node_modules,…` list,
   which retire `path.resolve()`s against its **own working directory** — so a

package/README.md

@@ -27,7 +27,8 @@
 - **Supply-chain risk** — known-**malicious** advisories (`MAL-`, always block the CI gate) + suspected **typosquats** (`--typosquat`).
 - **Lifecycle** — EOL (endoflife.date), obsolete/deprecated, outdated — across every ecosystem.
 - **Licenses** *(opt-in `--licenses`)* — SPDX-normalised, copyleft/proprietary flagged.
-- **Outputs & CI** — HTML + Word `.doc`, CycloneDX 1.6 SBOM, CSAF 2.0 VEX, SARIF 2.1.0, JSON; gate with `--fail-on`, triage with `--ignore`/`--vex`.
+- **Audit-grade & reproducible** — every report carries a **provenance manifest** (data-source freshness + run config) and a **Methodology, data sources & limitations** chapter; artifacts ship a **`SHA256SUMS`** integrity manifest (`sha256sum -c`); **differential audits** diff against a prior run (`--baseline`, or `fad diff a.json b.json`) and CI can gate on *new* findings (`--fail-on-new`).
+- **Outputs & CI** — HTML + Word `.doc`, CycloneDX 1.6 SBOM, CSAF 2.0 VEX, SARIF 2.1.0, JSON; gate with `--fail-on` / `--fail-on-new`, triage with `--ignore`/`--vex`. Private registries for Maven, npm, PyPI, Ruby, Go, **NuGet** and **Composer**.
 
 📖 **[Usage & all flags](docs/USAGE.md)** · **[Architecture](docs/ARCHITECTURE.md)** · **[Comparison vs other tools](docs/COMPARISON.md)** · **[Data sources](docs/DATA-SOURCES.md)**
 
@@ -46,27 +47,27 @@ fad-checker -s ./proj -t ../clean -e "^com\.acme\." --snyk     # cleaned POM tre
 fad-checker -s ./proj --offline                                # fully offline (zero network)
 fad-checker -s ./proj --osv-db --typosquat                     # offline-complete OSV + typosquat
 fad-checker -s ./proj --licenses --fail-on high                # license chapter + CI gate
+fad-checker -s ./proj --report-json --baseline last.json --fail-on-new   # differential audit: fail CI on NEW findings
+fad-checker diff last.json this.json                           # standalone diff of two findings JSONs
 ```
 
 A single self-contained binary (no Node), from-source install and shell completion are in → [docs/USAGE.md](docs/USAGE.md).
 
 ## What it finds
 
+The report is organised into **root chapters** (each grouping related sub-chapters):
+
 | Chapter | Source | What it catches |
 | --- | --- | --- |
-| **0. Warnings** | local heuristics | Missing lockfiles, unresolved Maven versions (BOM-managed), private libs not on Maven Central |
-| **1. CVE (production)** | CVEProject + OSV.dev + NVD + CPE | Public CVE / GHSA in production deps, per ecosystem, per manifest file — each row **prioritised** by CISA KEV + EPSS + CVSS |
-| **1B. Embedded binaries** | same, on coords read from archives | CVEs in libraries **shipped inside committed `.jar`/`.war`/`.ear`** (vendored libs, Spring-Boot fat-jars, shaded uber-jars) — not declared in any `pom.xml`. Grouped by containing archive |
-| **1C. Unmanaged / vendored binaries** | deps.dev + CIRCL (by checksum) | Committed **native binaries** (`.dll`/`.exe`/`.so`/`.dylib`) no package manager governs — identified by hash, flagged **should-be-managed** (exists in a registry), **name≠checksum** (filename disagrees with the hash), **unknown** (no source knows it) or **malicious** (free CIRCL signal) |
-| **1D. Unmanaged / vendored JavaScript** | [retire.js](https://retirejs.github.io/) (`--verbose`) | **Inventory of every standalone JS lib** committed into the tree (jQuery, Bootstrap, PDF.js, …) that no package manager governs — vulnerable *or not*. A cyber-hygiene constat: unknown provenance/integrity/patch story. `--no-vendored-js-inventory` to skip |
-| **2. Vendored JS (vulnerable)** | [retire.js](https://retirejs.github.io/) | The subset of the above with known CVEs/advisories — old jQuery/Bootstrap/Angular/PDF.js copies with no lockfile |
-| **3. CVE in dev deps** | same | Same as chapter 1, but for `test`/`provided` (Maven) and `dev`/`optional`/`peer` (npm) |
-| **Supply-chain risk** | OSV `MAL-…` + name heuristic | **Known-malicious** packages (always block the CI gate, any `--fail-on` level) and **suspected typosquats** (`--typosquat`: an npm/PyPI name one edit from a popular package — `lodahs`↔`lodash`) |
-| **4. EOL frameworks** | endoflife.date | Spring Boot 2.5, Hibernate 4.x, EOL JDKs, AngularJS, Laravel/Symfony, Django, .NET, etc. |
-| **5. Obsolete libraries** | curated list (Maven) + registry maintainer flags | log4j 1.x, jackson-mapper-asl, joda-time, …; npm `deprecated`, Composer `abandoned`, PyPI `yanked`/inactive, NuGet `deprecation` |
-| **6. Outdated libraries** | Maven Central + npm / Packagist / PyPI / NuGet registries | Available newer versions, with release dates |
-| **7. Licenses** *(opt-in: `--licenses`)* | registry metadata + Maven POMs → SPDX policy | Each dep's license normalised to SPDX and classified; copyleft (GPL/AGPL/LGPL/MPL), proprietary and unknown flagged for review |
-| **8. Fix Recommendations** | computed | Per-ecosystem pin recipes: Maven `<dependencyManagement>`, Gradle `constraints { }`, npm `overrides`, yarn `resolutions`, `composer require`, `pip install`, `dotnet add package` |
+| **0. Warnings** *(top)* | local heuristics | Missing lockfiles, unresolved Maven versions (BOM-managed), private libs not on Maven Central |
+| **Δ. Changes since baseline** *(top, with `--baseline`)* | diff vs prior JSON | New / fixed / unchanged findings per category + the list of **new production CVEs** — for repeat audits and `--fail-on-new` CI gating |
+| **1. CVE** *(X direct, Y indirect, Z dev)* | CVEProject + OSV.dev + NVD + CPE | **1.1 Production** — public CVE / GHSA in prod deps, per ecosystem, per manifest, **prioritised** by CISA KEV + EPSS + CVSS · **1.2 Vendored JS vulns** ([retire.js](https://retirejs.github.io/)) · **1.3 Dev** (`test`/`provided`, `dev`/`optional`/`peer`) · **1.4 Likely false positives** (CPE-filtered) |
+| **2. Unmanaged / unversioned components** | deps.dev + CIRCL (by checksum), retire.js | **2.1 Embedded binaries** — CVEs in libs shipped inside committed `.jar`/`.war`/`.ear` (fat-jars, shaded uber-jars) · **2.2 Native binaries** (`.dll`/`.exe`/`.so`/`.dylib`) identified by hash, flagged should-be-managed / name≠checksum / unknown / malicious · **2.3 Vendored JavaScript** inventory (jQuery, Bootstrap, …) vulnerable *or not* |
+| **3. Maintenance / lifecycle** *(X EOL, Y obsolete, Z outdated)* | endoflife.date · curated + registry flags · Maven Central / npm / Packagist / PyPI / NuGet | **3.1 End-of-Life** frameworks · **3.2 Obsolete / deprecated / abandoned / yanked** · **3.3 Outdated** (newer version available, with release dates) |
+| **4. Licenses** *(opt-in: `--licenses`)* | registry metadata + Maven POMs → SPDX policy | Each dep's license normalised to SPDX and classified; copyleft (GPL/AGPL/LGPL/MPL), proprietary and unknown flagged for review |
+| **5. Fix Recommendations** | computed | Per-ecosystem pin recipes: Maven `<dependencyManagement>`, Gradle `constraints { }`, npm `overrides`, yarn `resolutions`, `composer require`, `pip install`, `dotnet add package` |
+| **6. Scan context & limitations** | provenance manifest + walk | **6.1 Scanned descriptors** (every manifest parsed) · **6.2 Ignored directories** (pruned paths + rule) · **6.3 Methodology, data sources & limitations** (data-source freshness, run config, explicit statement of **what fad-checker does *not* assess**) |
+| **Supply-chain risk** *(cross-cutting)* | OSV `MAL-…` + name heuristic | **Known-malicious** packages (always block the CI gate, any `--fail-on` level) and **suspected typosquats** (`--typosquat`: an npm/PyPI name one edit from a popular package — `lodahs`↔`lodash`) |
 
 The HTML report opens in any browser, contains every detail (CVSS vectors, references, full descriptions, CPE configurations, via-paths for transitives) and ships a Word-compatible `.doc` twin. Every match carries a **composite priority** (KEV-exploited > EPSS likelihood > CVSS severity), and the run can additionally emit a **CycloneDX 1.6 SBOM** (`--report-sbom`, vulnerabilities inline) and a **CSAF 2.0 VEX** (`--report-csaf`) for downstream tooling.
 

package/completions/fad-checker.bash

@@ -6,7 +6,7 @@ _fad_check_complete() {
 	COMPREPLY=()
 	cur="${COMP_WORDS[COMP_CWORD]}"
 	prev="${COMP_WORDS[COMP_CWORD-1]}"
-	opts="--src --target --exclude --verbose --no-report --no-transitive --no-all-libs --no-osv --no-nvd --no-epss --no-kev --licenses --no-retire --retire-refresh --report-output --report-html --report-doc --report-sbom --report-csaf --report-json --report-sarif --fail-on --ignore --vex --ignore-test --cve-refresh --cve-offline --snyk --transitive-depth --offline --ecosystem --no-maven --no-npm --no-yarn --no-nuget --no-composer --no-pypi --no-go --no-ruby --no-jars --no-js --set-nvd-key --show-config --completion --help --version -s -t -e -v"
+	opts="--src --target --exclude --verbose --no-report --no-transitive --no-all-libs --no-osv --no-nvd --no-epss --no-kev --licenses --no-retire --retire-refresh --report-output --report-html --report-doc --report-sbom --report-csaf --report-json --report-sarif --fail-on --fail-on-new --baseline --no-checksums --ignore --vex --ignore-test --cve-refresh --cve-offline --snyk --transitive-depth --offline --ecosystem --no-maven --no-npm --no-yarn --no-nuget --no-composer --no-pypi --no-go --no-ruby --no-jars --no-js --set-nvd-key --show-config --completion --help --version -s -t -e -v"
 	case "$prev" in
 		--src|-s|--target|-t|--report-output)
 			COMPREPLY=( $(compgen -d -- "$cur") )

package/completions/fad-checker.zsh

@@ -27,6 +27,9 @@ _fad_check() {
 		'--no-go[skip the Go codec]'
 		'--no-ruby[skip the Ruby codec]'
 		'--fail-on[CI gate level]:level:(none low medium high critical kev)'
+		'--fail-on-new[fail CI on new production CVEs vs --baseline]'
+		'--baseline[diff this scan against a prior findings JSON]::file:_files'
+		'--no-checksums[do not write a SHA256SUMS integrity manifest]'
 		'--ignore[suppress findings file]:file:_files'
 		'--vex[ingest CSAF VEX]:file:_files'
 		'--ignore-test[skip test-scoped deps]'

package/fad-checker.js

@@ -180,6 +180,48 @@ if (process.argv.includes("--export-cache") || process.argv.includes("--import-c
 	return;
 }
 
+// -------- `fad diff <baseline.json> <current.json>` subcommand (pre-parse) --------
+// Standalone differential audit between two findings JSON exports. Mirrors the other
+// pre-parse intercepts so it never collides with the main option set (which requires -s).
+if (process.argv[2] === "diff") {
+	const { diffFindings, summarizeDiff, newProductionCveCount } = require("./lib/diff");
+	const rest = process.argv.slice(3);
+	const positionals = rest.filter(a => !a.startsWith("-"));
+	const [basePath, curPath] = positionals;
+	const failOnNew = rest.includes("--fail-on-new");
+	const jIdx = rest.indexOf("--report-json");
+	const jsonOut = jIdx > -1 && rest[jIdx + 1] && !rest[jIdx + 1].startsWith("-") ? rest[jIdx + 1] : null;
+	if (!basePath || !curPath) {
+		console.error(chalk.red("❌  usage: fad-checker diff <baseline.json> <current.json> [--report-json <out>] [--fail-on-new]"));
+		process.exit(2);
+	}
+	let baseDoc, curDoc;
+	try { baseDoc = JSON.parse(fs.readFileSync(basePath, "utf8")); }
+	catch (e) { console.error(chalk.red(`❌  cannot read baseline ${basePath}: ${e.message}`)); process.exit(2); }
+	try { curDoc = JSON.parse(fs.readFileSync(curPath, "utf8")); }
+	catch (e) { console.error(chalk.red(`❌  cannot read current ${curPath}: ${e.message}`)); process.exit(2); }
+	const d = diffFindings(baseDoc, curDoc);
+	const s = summarizeDiff(d);
+	const newProd = newProductionCveCount(d);
+	console.log(chalk.bold(`\nDifferential audit  ${chalk.dim(basePath)} → ${chalk.dim(curPath)}\n`));
+	const line = (label, c) => console.log(`  ${label.padEnd(10)} ${chalk.red(`+${c.added} new`)}  ${chalk.green(`-${c.removed} fixed`)}  ${chalk.dim(`${c.unchanged} unchanged`)}`);
+	line("CVE", s.cve); line("EOL", s.eol); line("Obsolete", s.obsolete); line("Outdated", s.outdated); line("Licenses", s.licenses);
+	console.log();
+	const sev = Object.entries(s.cve.addedBySeverity).filter(([, n]) => n).map(([k, n]) => `${n} ${k.toLowerCase()}`).join(", ") || "none";
+	console.log(`  ${chalk.bold("New production CVE findings:")} ${newProd ? chalk.red.bold(newProd) : chalk.green("0")}  ${chalk.dim(`(${sev})`)}`);
+	const newCves = (d.cve.added || []).filter(f => !f.suppressed && !f.cpeFiltered);
+	for (const f of newCves.slice(0, 25)) console.log(`    ${chalk.red("•")} ${f.id}  ${chalk.dim((f.severity || "") + " · " + ((f.dep && f.dep.coord) || "") + "@" + ((f.dep && f.dep.version) || ""))}`);
+	if (newCves.length > 25) console.log(chalk.dim(`    …and ${newCves.length - 25} more`));
+	if (jsonOut) {
+		const out = { tool: "fad-checker", kind: "fad-diff/1", baseline: basePath, current: curPath, summary: s, diff: d };
+		try { fs.mkdirSync(path.dirname(path.resolve(jsonOut)), { recursive: true }); } catch { /* ignore */ }
+		fs.writeFileSync(jsonOut, JSON.stringify(out, null, 2) + "\n");
+		console.log(chalk.green(`\n✅ diff written → ${jsonOut}`));
+	}
+	console.log();
+	process.exit(failOnNew && newProd > 0 ? 1 : 0);
+}
+
 const USAGE = `
 (1) fad-checker -s ./proj                                              # read-only: full report (CVE + EOL + obsolete + outdated + transitive)
 (2) fad-checker -s ./proj -e "^(org.private|client)"                   # same, with regex exclusion of private deps
@@ -220,6 +262,9 @@ program
 	.option("--report-json [file]", "write a flat machine-readable findings JSON (default: <report-output>/findings.json)")
 	.option("--report-sarif [file]", "write a SARIF 2.1.0 log for GitHub/GitLab code scanning (default: <report-output>/fad.sarif)")
 	.option("--fail-on <level>", "exit non-zero if a production finding meets <level>: low|medium|high|critical|kev|none", "none")
+	.option("--baseline <file>", "differential audit: diff this scan against a prior findings JSON (from --report-json) — shows new / fixed findings in the report + JSON export")
+	.option("--fail-on-new", "exit non-zero if the scan introduces any NEW production CVE finding vs --baseline (combine with or instead of --fail-on)")
+	.option("--no-checksums", "don't write a SHA256SUMS integrity manifest alongside the report files")
 	.option("--ignore <file>", "suppress findings listed in <file> (CVE ids / coords / globs, one per line)")
 	.option("--vex <file>", "ingest a CSAF VEX: suppress CVEs marked not_affected/fixed")
 	.option("--licenses", "run license detection + copyleft policy check (off by default)")
@@ -1254,6 +1299,13 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 		toolVersion: pkg.version,
 		cveDataDate,
 	};
+	// Scan-provenance manifest: data-source freshness + run configuration, for a
+	// reproducible/defensible audit. Surfaced in the report's Methodology chapter and
+	// the JSON export's `provenance` block.
+	try {
+		const { buildScanProvenance } = require("./lib/provenance");
+		projectInfo.provenance = buildScanProvenance({ toolVersion: pkg.version, generatedAt: projectInfo.generatedAt, options });
+	} catch (err) { if (verbose) ui.warn(`provenance manifest skipped: ${err.message}`); }
 
 	// --- Output target resolution -------------------------------------------------
 	// One --report-<type> flag per output, each taking an OPTIONAL path: a string is
@@ -1307,13 +1359,29 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 		}] : []),
 	];
 
+	// Differential audit vs --baseline: build the current findings doc once, diff it
+	// against the prior export → a `diff` block for the report + JSON export, and a
+	// `--fail-on-new` gate signal. Best-effort: a missing/unreadable baseline warns.
+	let diff = null, jsonDiff = null;
+	if (options.baseline) {
+		try {
+			const baseDoc = JSON.parse(fs.readFileSync(options.baseline, "utf8"));
+			const { buildFindings } = require("./lib/json-export");
+			const curDoc = buildFindings({ cveMatches, retireMatches, vendoredJsInventory, eolResults, obsoleteResults, outdatedResults, licenseResults, excludedDirs, resolvedDeps: resolved, projectInfo, toolVersion: pkg.version, typosquats });
+			const { diffFindings, summarizeDiff } = require("./lib/diff");
+			const dd = diffFindings(baseDoc, curDoc);
+			diff = { ...dd, summary: summarizeDiff(dd) };
+			jsonDiff = { summary: diff.summary, cve: { added: dd.cve.added, removed: dd.cve.removed } };
+		} catch (err) { ui.warn(`baseline diff skipped (${options.baseline}): ${err.message}`); }
+	}
+
 	const wrote = [];
 	if (out.html || out.doc) {
 		await ensureDir(out.html); await ensureDir(out.doc);
 		const { htmlPath, docPath } = await writeReports({
 			cveMatches: prodMatches, devCveMatches: devMatches, embeddedMatches, retireMatches, vendoredJsInventory,
 			eolResults, obsoleteResults, outdatedResults, licenseResults, excludedDirs,
-			resolvedDeps: resolved, projectInfo, warnings: reportWarnings, parsedManifests,
+			resolvedDeps: resolved, projectInfo, warnings: reportWarnings, parsedManifests, diff,
 			htmlPath: out.html, docPath: out.doc,
 		});
 		if (htmlPath) wrote.push(["HTML report", htmlPath]);
@@ -1342,7 +1410,7 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 		try {
 			const { writeFindings } = require("./lib/json-export");
 			await ensureDir(out.json);
-			writeFindings({ cveMatches, retireMatches, vendoredJsInventory, eolResults, obsoleteResults, outdatedResults, licenseResults, excludedDirs, resolvedDeps: resolved, projectInfo, toolVersion: pkg.version, typosquats }, out.json);
+			writeFindings({ cveMatches, retireMatches, vendoredJsInventory, eolResults, obsoleteResults, outdatedResults, licenseResults, excludedDirs, resolvedDeps: resolved, projectInfo, toolVersion: pkg.version, typosquats, diff: jsonDiff }, out.json);
 			wrote.push(["Findings JSON", out.json]);
 		} catch (err) { ui.warn(`JSON export failed: ${err.message}`); }
 	}
@@ -1355,6 +1423,20 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 		} catch (err) { ui.warn(`SARIF export failed: ${err.message}`); }
 	}
 
+	// Integrity manifest: a standard SHA256SUMS over every artifact written this run,
+	// for a tamper-evident deliverable (verify with `sha256sum -c SHA256SUMS`). On by
+	// default; --no-checksums disables. Written beside the first artifact.
+	if (wrote.length && options.checksums !== false) {
+		try {
+			const { writeChecksums } = require("./lib/report-integrity");
+			const files = wrote.map(([, p]) => p);
+			const manifestDir = path.dirname(path.resolve(files[0]));
+			const manifestPath = path.join(manifestDir, "SHA256SUMS");
+			writeChecksums(files, manifestPath, { baseDir: manifestDir });
+			wrote.push(["Integrity (SHA-256)", manifestPath]);
+		} catch (err) { ui.warn(`checksum manifest skipped: ${err.message}`); }
+	}
+
 	if (wrote.length) {
 		ui.section("Output");
 		for (const [label, p] of wrote) ui.ok(`${label} → ${chalk.white(p)}`);
@@ -1365,21 +1447,36 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 	}
 	console.log();
 
+	// Differential-audit summary (vs --baseline).
+	if (diff && diff.summary) {
+		const s = diff.summary;
+		ui.section("Baseline diff");
+		const sev = Object.entries(s.cve.addedBySeverity).filter(([, n]) => n).map(([k, n]) => `${n} ${k.toLowerCase()}`).join(", ") || "none";
+		console.log(`  CVE  ${chalk.red(`+${s.cve.added} new`)}  ${chalk.green(`-${s.cve.removed} fixed`)}  ${chalk.dim(`${s.cve.unchanged} unchanged`)}`);
+		console.log(`  ${chalk.bold("New production CVE:")} ${s.cve.addedProduction ? chalk.red.bold(s.cve.addedProduction) : chalk.green("0")} ${chalk.dim(`(${sev})`)}`);
+		console.log();
+	}
+
 	// CI gating — set a non-zero exit code (after all reports/exports are written)
-	// when a production finding meets the --fail-on threshold.
-	if (options.failOn && options.failOn !== "none") {
+	// when a production finding meets the --fail-on threshold, OR (--fail-on-new) when
+	// the scan introduces any new production CVE finding vs the --baseline.
+	const newProd = (options.failOnNew && diff && diff.summary) ? diff.summary.cve.addedProduction : 0;
+	if ((options.failOn && options.failOn !== "none") || options.failOnNew) {
 		const { evaluateGate } = require("./lib/gate");
 		// Embedded-binary findings are real production risk → gate on them too.
-		const gate = evaluateGate([...prodActive, ...embeddedActive], options.failOn);
+		const gate = (options.failOn && options.failOn !== "none")
+			? evaluateGate([...prodActive, ...embeddedActive], options.failOn)
+			: { failed: false, reason: "" };
 		// A known-malicious package always blocks, regardless of the --fail-on level.
 		const maliciousActive = [...prodActive, ...embeddedActive].filter(m => m.malicious);
-		if (gate.failed || maliciousActive.length) {
+		if (gate.failed || maliciousActive.length || newProd > 0) {
 			ui.section("Gate");
 			if (maliciousActive.length) console.log(chalk.red.bold(`✗ ${maliciousActive.length} known-malicious package(s) detected — always blocks`));
 			if (gate.failed) console.log(chalk.red(`✗ --fail-on ${options.failOn}: ${gate.reason}`));
+			if (newProd > 0) console.log(chalk.red(`✗ --fail-on-new: ${newProd} new production CVE finding(s) vs baseline`));
 			process.exitCode = 1;
 		} else if (verbose) {
-			ui.info(chalk.dim(`--fail-on ${options.failOn}: no blocking finding`));
+			ui.info(chalk.dim(`gate: no blocking finding`));
 		}
 	}
 }

package/lib/codecs/composer/registry.js

@@ -14,6 +14,7 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 let pLimit; try { pLimit = require("p-limit"); } catch { pLimit = () => (fn) => fn(); }
+const { authHeaderFor, normalise } = require("../../registries");
 
 const CACHE_DIR = path.join(os.homedir(), ".fad-checker");
 const CACHE_PATH = path.join(CACHE_DIR, "packagist-cache.json");
@@ -48,19 +49,50 @@ function packagistToFindings(pkg, { version }) {
 	return out;
 }
 
-async function fetchPackage(name, { offline }) {
+// Convert a Composer v2 metadata document (`/p2/<name>.json`) into the packagist-like
+// `package` shape packagistToFindings() consumes: { versions: { "<v>": {license} },
+// abandoned }. The v2 format is { packages: { "<name>": [ {version, license, …}, … ] } }.
+// Private feeds (Artifactory, Private Packagist) sometimes tag an abandoned package on
+// its version objects; surface that if present.
+function composerV2ToPackageObject(json, name) {
+	const arr = (json && json.packages && (json.packages[name] || json.packages[name.toLowerCase()])) || [];
+	const versions = {};
+	let abandoned = null;
+	for (const v of arr) {
+		if (!v || !v.version) continue;
+		versions[v.version] = { license: v.license || [] };
+		if (abandoned == null && v.abandoned != null && v.abandoned !== false) {
+			abandoned = (typeof v.abandoned === "string") ? v.abandoned : true;
+		}
+	}
+	return { versions, abandoned };
+}
+
+// Custom registries first (Composer v2 metadata: <base>/p2/<name>.json), then the
+// public Packagist rich API (packages/<name>.json). Per-registry Basic/Bearer auth.
+async function fetchPackage(name, { offline, registries = [], fetcher = globalThis.fetch } = {}) {
 	if (offline) return null;
+	let lastErr = null;
+	for (const base of registries || []) {
+		const headers = { "User-Agent": "fad-checker-packagist", Accept: "application/json" };
+		const ah = authHeaderFor(base); if (ah) headers.Authorization = ah;
+		try {
+			const res = await fetcher(`${normalise(base.url)}p2/${name}.json`, { headers });
+			if (res.ok) return composerV2ToPackageObject(await res.json(), name);
+			lastErr = `HTTP ${res.status}`;
+		} catch (e) { lastErr = e.message; }
+	}
 	try {
-		const res = await fetch(`${API}/${name}.json`, { headers: { "User-Agent": "fad-checker-packagist" } });
+		const res = await fetcher(`${API}/${name}.json`, { headers: { "User-Agent": "fad-checker-packagist", Accept: "application/json" } });
 		if (!res.ok) return { error: `HTTP ${res.status}` };
 		const json = await res.json();
 		return json.package || { error: "no package field" };
-	} catch (e) { return { error: e.message }; }
+	} catch (e) { return { error: lastErr || e.message }; }
 }
 
 // Mirror of checkNpmRegistryDeps: returns { deprecated:[], outdated:[] }.
 async function checkComposerRegistryDeps(deps, opts = {}) {
-	const { verbose, offline, allLibs = true, concurrency = 8 } = opts;
+	const { verbose, offline, allLibs = true, concurrency = 8, registries = [], fetcher } = opts;
 	const targets = [...deps.values()].filter(d => d.ecosystem === "composer" && d.version);
 	const result = { deprecated: [], outdated: [], licensed: [] };
 	if (!targets.length) return result;
@@ -73,7 +105,7 @@ async function checkComposerRegistryDeps(deps, opts = {}) {
 		const key = `${name}@${t.version}`;
 		let ex = cache.entries[key];
 		if (!ex) {
-			const pkg = await fetchPackage(name, { offline });
+			const pkg = await fetchPackage(name, { offline, registries, ...(fetcher ? { fetcher } : {}) });
 			if (pkg && !pkg.error) {
 				const f = packagistToFindings(pkg, { version: t.version });
 				ex = { abandoned: f.abandoned, latest: f.outdated?.latest || null, license: f.license || null };
@@ -97,4 +129,4 @@ async function checkComposerRegistryDeps(deps, opts = {}) {
 	return result;
 }
 
-module.exports = { packagistToFindings, checkComposerRegistryDeps };
+module.exports = { packagistToFindings, checkComposerRegistryDeps, fetchPackage, composerV2ToPackageObject };

package/lib/codecs/nuget/registry.js

@@ -14,11 +14,11 @@ const fs = require("fs");
 const path = require("path");
 const os = require("os");
 let pLimit; try { pLimit = require("p-limit"); } catch { pLimit = () => (fn) => fn(); }
+const { withPublic, authHeaderFor, normalise } = require("../../registries");
 
 const CACHE_DIR = path.join(os.homedir(), ".fad-checker");
 const CACHE_PATH = path.join(CACHE_DIR, "nuget-cache.json");
 const CACHE_MAX_AGE_MS = 24 * 3600 * 1000;
-const REG = "https://api.nuget.org/v3/registration5-gz-semver2";
 
 function loadCache() { try { return JSON.parse(fs.readFileSync(CACHE_PATH, "utf8")); } catch { return { entries: {}, meta: {} }; } }
 function saveCache(d) { try { fs.mkdirSync(CACHE_DIR, { recursive: true }); fs.writeFileSync(CACHE_PATH, JSON.stringify(d)); } catch { /* ignore */ } }
@@ -45,18 +45,57 @@ function nugetRegistrationToFindings(reg, { version }) {
 	return out;
 }
 
-async function fetchRegistration(name, { offline }) {
-	if (offline) return null;
+// A NuGet v3 service index (…/index.json) lists resources; the registration base is
+// the resource whose @type starts with "RegistrationsBaseUrl" (prefer a gz/semver2
+// variant). A configured base that is NOT a service index is treated as a
+// registration base directly. Resolved bases are memoised for the process lifetime.
+const _regBaseMemo = new Map();
+async function resolveRegistrationBase(base, fetcher, headers) {
+	const raw = String(base.url || "");
+	if (!/index\.json\/?$/i.test(raw)) return normalise(raw);
+	const url = raw.replace(/\/$/, "");
+	if (_regBaseMemo.has(url)) return _regBaseMemo.get(url);
+	let resolved = null;
 	try {
-		const res = await fetch(`${REG}/${name.toLowerCase()}/index.json`, { headers: { "User-Agent": "fad-checker-nuget" } });
-		if (!res.ok) return { error: `HTTP ${res.status}` };
-		return await res.json();
-	} catch (e) { return { error: e.message }; }
+		const res = await fetcher(url, { headers });
+		if (res.ok) {
+			const idx = await res.json();
+			const resources = idx.resources || [];
+			const pick = resources.find(r => /^RegistrationsBaseUrl\/.*(gz|semver2)/i.test(r["@type"]))
+				|| resources.find(r => String(r["@type"] || "").startsWith("RegistrationsBaseUrl"));
+			if (pick && pick["@id"]) resolved = normalise(pick["@id"]);
+		}
+	} catch { /* fall through → null */ }
+	_regBaseMemo.set(url, resolved);
+	return resolved;
+}
+
+// Custom registries first (NuGet v3 registration API: <regBase>/<lowerid>/index.json),
+// then api.nuget.org. A service-index base is resolved to its RegistrationsBaseUrl.
+async function fetchRegistration(name, { offline, registries = [], fetcher = globalThis.fetch } = {}) {
+	if (offline) return null;
+	const id = name.toLowerCase();
+	const bases = withPublic("nuget", registries);
+	let lastErr = null;
+	for (const base of bases) {
+		const headers = { "User-Agent": "fad-checker-nuget", Accept: "application/json" };
+		const ah = authHeaderFor(base); if (ah) headers.Authorization = ah;
+		let regBase;
+		try { regBase = await resolveRegistrationBase(base, fetcher, headers); }
+		catch (e) { lastErr = e.message; continue; }
+		if (!regBase) { lastErr = "no registration base"; continue; }
+		try {
+			const res = await fetcher(`${regBase}${id}/index.json`, { headers });
+			if (res.ok) return await res.json();
+			lastErr = `HTTP ${res.status}`;
+		} catch (e) { lastErr = e.message; }
+	}
+	return { error: lastErr || "no data" };
 }
 
 // Mirror of checkNpmRegistryDeps: returns { deprecated:[], outdated:[] }.
 async function checkNugetRegistryDeps(deps, opts = {}) {
-	const { verbose, offline, allLibs = true, concurrency = 8 } = opts;
+	const { verbose, offline, allLibs = true, concurrency = 8, registries = [], fetcher } = opts;
 	const targets = [...deps.values()].filter(d => d.ecosystem === "nuget" && d.version);
 	const result = { deprecated: [], outdated: [], licensed: [] };
 	if (!targets.length) return result;
@@ -68,7 +107,7 @@ async function checkNugetRegistryDeps(deps, opts = {}) {
 		const key = `${t.name.toLowerCase()}@${t.version}`;
 		let ex = cache.entries[key];
 		if (!ex) {
-			const reg = await fetchRegistration(t.name, { offline });
+			const reg = await fetchRegistration(t.name, { offline, registries, ...(fetcher ? { fetcher } : {}) });
 			if (reg && !reg.error) {
 				const f = nugetRegistrationToFindings(reg, { version: t.version });
 				ex = { deprecated: f.deprecated, latest: f.outdated?.latest || null, license: f.license || null };
@@ -92,4 +131,4 @@ async function checkNugetRegistryDeps(deps, opts = {}) {
 	return result;
 }
 
-module.exports = { nugetRegistrationToFindings, checkNugetRegistryDeps };
+module.exports = { nugetRegistrationToFindings, checkNugetRegistryDeps, fetchRegistration, resolveRegistrationBase };

package/lib/cve-report.js

@@ -130,6 +130,9 @@ h2 { margin: 32px 0 12px; font-size: 20px; border-bottom: 2px solid #e5e7eb; pad
 .toc { position: sticky; top: 0; z-index: 50; background: #fff; border: 1px solid #e5e7eb; border-radius: 6px; padding: 8px 12px; margin: 16px 0; display: flex; flex-wrap: wrap; gap: 6px 14px; font-size: 12px; box-shadow: 0 1px 4px rgba(0,0,0,.04); }
 .toc a { color: #4338ca; text-decoration: none; padding: 2px 6px; border-radius: 3px; }
 .toc a:hover { background: #eef2ff; }
+.toc a.toc-root { font-weight: 700; }
+.toc a.toc-sub { font-size: 11px; color: #6b7280; padding-left: 4px; }
+.toc a.toc-sub::before { content: "› "; color: #c7cdd6; }
 .exec-summary .exec-top { margin-top: 8px; padding-top: 10px; border-top: 1px dashed #e5e7eb; }
 .exec-summary .exec-top-title { font-size: 11px; font-weight: 700; text-transform: uppercase; letter-spacing: .8px; color: #6b7280; margin-bottom: 6px; }
 .exec-summary .exec-top-list { list-style: none; padding: 0; margin: 0; font-size: 12px; }
@@ -400,11 +403,20 @@ function renderDefinedIn(dep, srcRoot) {
 	const paths = (dep.manifestPaths && dep.manifestPaths.length) ? dep.manifestPaths
 		: (dep.pomPaths && dep.pomPaths.length) ? dep.pomPaths
 		: [];
-	if (!paths.length) return "";
-	const rel = paths.map(p => makeRelative(p, srcRoot));
-	const shown = rel.slice(0, 3).map(p => `<code>${esc(p)}</code>`).join(", ");
-	const more = rel.length > 3 ? ` <span class="defined-more">+${rel.length - 3} more</span>` : "";
-	return `<div class="defined-in"><span class="defined-label">defined in:</span> ${shown}${more}</div>`;
+	let definedLine = "";
+	if (paths.length) {
+		const rel = paths.map(p => makeRelative(p, srcRoot));
+		const shown = rel.slice(0, 3).map(p => `<code>${esc(p)}</code>`).join(", ");
+		const more = rel.length > 3 ? ` <span class="defined-more">+${rel.length - 3} more</span>` : "";
+		definedLine = `<div class="defined-in"><span class="defined-label">defined in:</span> ${shown}${more}</div>`;
+	}
+	// A versionless declared dep (typical Spring Boot / Gradle) gets its version from an import
+	// BOM, not the manifest it's declared in. Disclose that so 6.0.3 doesn't read as fabricated.
+	const vs = dep.versionSource;
+	const versionLine = (vs && vs.via === "bom" && vs.bom)
+		? `<div class="defined-in"><span class="defined-label">version managed by:</span> <code>${esc(vs.bom)}</code> (BOM)</div>`
+		: "";
+	return definedLine + versionLine;
 }
 
 function makeRelative(absPath, srcRoot) {
@@ -1170,18 +1182,23 @@ function attachRootUpdates(cveMatches, outdatedResults, resolvedDeps) {
 	}
 }
 
+// Every chapter / sub-chapter renders EXPANDED by default (the user wants the whole
+// report open on load). The `open` opt is accepted for call-site compatibility but
+// intentionally ignored — collapse is still available via the toolbar / clicking a
+// header. (Per-CVE detail rows are NOT <details>, so they stay collapsed-by-default.)
 function majorSection(title, contentHtml, opts = {}) {
-	const { open = true, id } = opts;
+	const { id } = opts;
 	const idAttr = id ? ` id="${esc(id)}"` : "";
-	return `<details class="report-section"${open ? " open" : ""}${idAttr}>
+	return `<details class="report-section" open${idAttr}>
 		<summary><h2>${title}</h2></summary>
 		<div>${contentHtml}</div>
 	</details>`;
 }
 
 function minorSection(title, contentHtml, opts = {}) {
-	const { open = true } = opts;
-	return `<details class="report-subsection"${open ? " open" : ""}>
+	const { id } = opts;
+	const idAttr = id ? ` id="${esc(id)}"` : "";
+	return `<details class="report-subsection" open${idAttr}>
 		<summary><h3>${title}</h3></summary>
 		<div>${contentHtml}</div>
 	</details>`;
@@ -1485,7 +1502,7 @@ function renderLicenseChapter(licenseResults) {
 	return intro + blocks;
 }
 
-function buildBody({ cveMatches, devCveMatches, embeddedMatches, retireMatches, vendoredJsInventory, eolResults, obsoleteResults, outdatedResults, licenseResults, excludedDirs = [], resolvedDeps, projectInfo, warnings, parsedManifests = [], wrapTables = true }) {
+function buildBody({ cveMatches, devCveMatches, embeddedMatches, retireMatches, vendoredJsInventory, eolResults, obsoleteResults, outdatedResults, licenseResults, excludedDirs = [], resolvedDeps, projectInfo, warnings, parsedManifests = [], diff = null, wrapTables = true }) {
 	setRenderCtx({ srcRoot: projectInfo?.src || null });
 	// Dedupe rows so a single (dep, cve) shows once with all via paths merged.
 	cveMatches      = mergeMatches(cveMatches || []);
@@ -1513,9 +1530,9 @@ function buildBody({ cveMatches, devCveMatches, embeddedMatches, retireMatches,
 	// Recos are built from prod matches only (dev/test issues aren't a release blocker).
 	const recos = buildFixRecommendations(prodMatchesActive, outdatedResults, resolvedDeps);
 
-	const cveContent       = renderCveBySectionByEco(prodMatchesActive, "1", projectInfo?.src);
+	const cveContent       = renderCveBySectionByEco(prodMatchesActive, "1.1", projectInfo?.src);
 	const vendoredContent  = renderRetireTable(retireMatches);
-	const devCveContent    = renderCveBySectionByEco(devMatchesActive, "3", projectInfo?.src);
+	const devCveContent    = renderCveBySectionByEco(devMatchesActive, "1.3", projectInfo?.src);
 	const licenseContent   = renderLicenseChapter(licenseResults);
 	const licenseTotal     = licenseResults?.assessed?.length || 0;
 	const licenseFlagged   = licenseResults?.flagged?.length || 0;
@@ -1548,27 +1565,86 @@ function buildBody({ cveMatches, devCveMatches, embeddedMatches, retireMatches,
 		interactive: wrapTables, // copy button + scripts only in the HTML output
 	});
 
-	// (C) Table of contents — rendered as a sticky nav. Only enumerates the
-	// chapters that actually have content (warnings, dev CVE, retire, FP appendix
-	// might be empty).
+	// ---- Chapters are grouped under "root" chapters (a two-level hierarchy) ----
 	const scanned = buildScannedManifests(resolvedDeps, projectInfo?.src, parsedManifests);
-	const toc = renderToc({
-		hasWarnings: !!(warnings?.length),
-		prodTotal: prodStats.total,
-		scannedTotal: scanned.length,
-		retireTotal: retireMatches.length,
-		devTotal: devStats.total,
-		eolTotal: eolResults?.length || 0,
-		obsoleteTotal: obsoleteResults?.length || 0,
-		outdatedTotal: outdatedResults?.length || 0,
-		licenseTotal,
-		licenseFlagged,
-		embeddedTotal: embeddedInventory.length,
-		unmanagedTotal: unmanagedInventory.length,
-		vendoredJsTotal: vendoredJsInv.length,
-		fpTotal: prodMatchesFP.length + devMatchesFP.length + embMatchesFP.length,
-		excludedTotal: excludedDirs?.length || 0,
-	});
+	const fpTotal = prodMatchesFP.length + devMatchesFP.length + embMatchesFP.length;
+	const eolTotal = eolResults?.length || 0;
+	const obsTotal = obsoleteResults?.length || 0;
+	const outTotal = outdatedResults?.length || 0;
+	const embTotal = embeddedInventory.length;
+	const unmTotal = unmanagedInventory.length;
+	const vjsTotal = vendoredJsInv.length;
+	const excTotal = excludedDirs?.length || 0;
+	// CVE root header breakdown: direct vs indirect (transitive) production vulns + the dev count.
+	const prodDirect   = prodMatchesActive.filter(m => m.dep?.scope !== "transitive").length;
+	const prodIndirect = prodMatchesActive.filter(m => m.dep?.scope === "transitive").length;
+
+	// Root 1 — CVE (production + vendored-JS vulns + dev + likely false positives).
+	const cveRoot = majorSection(
+		`1. CVE (${prodDirect} direct, ${prodIndirect} indirect, ${devStats.total} dev)`,
+		minorSection(`1.1 Production (${prodStats.total})`, cveContent, { id: "ch1", open: true }) +
+		minorSection(`1.2 Vendored JS vulns — retire.js (${retireMatches.length})`, vendoredContent, { id: "ch2", open: retireMatches.length > 0 && retireMatches.length <= 50 }) +
+		minorSection(`1.3 Dev dependencies (${devStats.total})`, devCveContent, { id: "ch3", open: devStats.total > 0 && devStats.total <= 50 }) +
+		(fpTotal ? minorSection(`1.4 Likely false positives — CPE-filtered (${fpTotal})`, fpContent, { id: "ch9", open: false }) : ""),
+		{ id: "chcve" });
+
+	// Root 2 — Unmanaged / unversioned components (binaries + vendored JS, no package manager).
+	const binRoot = majorSection(
+		`2. Unmanaged / unversioned components (${embTotal} embedded, ${unmTotal} native, ${vjsTotal} vendored JS)`,
+		(embTotal ? minorSection(`2.1 Embedded binaries — JAR/WAR/EAR (${embTotal})`, embeddedContent, { id: "ch1e", open: embTotal <= 50 }) : "") +
+		(unmTotal ? minorSection(`2.2 Unmanaged / vendored native binaries (${unmTotal})`, unmanagedContent, { id: "ch1c", open: unmTotal <= 50 }) : "") +
+		(vjsTotal ? minorSection(`2.3 Unmanaged / vendored JavaScript (${vjsTotal})`, vendoredJsContent, { id: "ch1d", open: vjsTotal <= 50 }) : "") ||
+		`<div class="empty">No unmanaged binaries or vendored JavaScript found.</div>`,
+		{ id: "chbin", open: (embTotal + unmTotal + vjsTotal) > 0 });
+
+	// Root 3 — Maintenance / lifecycle (EOL + obsolete + outdated).
+	const maintRoot = majorSection(
+		`3. Maintenance / lifecycle (${eolTotal} EOL, ${obsTotal} obsolete, ${outTotal} outdated)`,
+		minorSection(`3.1 End-of-Life frameworks (${eolTotal})`, renderEolTable(eolResults), { id: "ch4", open: eolTotal > 0 }) +
+		minorSection(`3.2 Obsolete / deprecated (${obsTotal})`, renderObsoleteTable(obsoleteResults), { id: "ch5", open: obsTotal > 0 }) +
+		minorSection(`3.3 Outdated (${outTotal})`, renderOutdatedTable(outdatedResults), { id: "ch6", open: outTotal > 0 && outTotal <= 50 }),
+		{ id: "chmaint" });
+
+	// Root 4 — Licenses (standalone). Root 5 — Fix Recommendations (standalone).
+	const licRoot = majorSection(`4. Licenses (${licenseTotal}${licenseFlagged ? `, ${licenseFlagged} to review` : ""})`, licenseContent, { open: licenseFlagged > 0, id: "ch7" });
+	const fixRoot = majorSection(`5. Fix Recommendations`, renderFixRecommendations(recos, prodMatchesActive, outdatedResults), { open: false, id: "ch8" });
+
+	// Root 6 — Scan context & limitations (scanned descriptors + ignored dirs + methodology).
+	const scanRoot = majorSection(
+		`6. Scan context & limitations`,
+		minorSection(`6.1 Scanned dependency descriptors (${scanned.length})`, renderScannedManifests(scanned), { id: "chsrc", open: false }) +
+		(excTotal ? minorSection(`6.2 Ignored directories (${excTotal})`, renderExcludedDirs(excludedDirs), { id: "chexcl", open: false }) : "") +
+		minorSection(`6.3 Methodology, data sources & limitations`, renderMethodologyChapter(projectInfo), { id: "chmethod", open: false }),
+		{ id: "chscan", open: false });
+
+	// (C) Table of contents — sticky nav, hierarchical (roots + indented sub-chapters).
+	const toc = renderToc([
+		...(warnings?.length ? [{ id: "ch0", label: "0. Warnings" }] : []),
+		...(diff && diff.summary ? [{ id: "chdiff", label: "Δ Baseline diff" }] : []),
+		{ id: "chcve", label: `1. CVE (${prodStats.total})`, sub: [
+			{ id: "ch1", label: `Prod (${prodStats.total})` },
+			{ id: "ch2", label: `Vendored JS (${retireMatches.length})` },
+			{ id: "ch3", label: `Dev (${devStats.total})` },
+			...(fpTotal ? [{ id: "ch9", label: `Likely FP (${fpTotal})` }] : []),
+		] },
+		{ id: "chbin", label: `2. Unmanaged components (${embTotal + unmTotal + vjsTotal})`, sub: [
+			...(embTotal ? [{ id: "ch1e", label: `Embedded (${embTotal})` }] : []),
+			...(unmTotal ? [{ id: "ch1c", label: `Native (${unmTotal})` }] : []),
+			...(vjsTotal ? [{ id: "ch1d", label: `Vendored JS (${vjsTotal})` }] : []),
+		] },
+		{ id: "chmaint", label: `3. Maintenance (${eolTotal + obsTotal + outTotal})`, sub: [
+			{ id: "ch4", label: `EOL (${eolTotal})` },
+			{ id: "ch5", label: `Obsolete (${obsTotal})` },
+			{ id: "ch6", label: `Outdated (${outTotal})` },
+		] },
+		{ id: "ch7", label: `4. Licenses (${licenseTotal}${licenseFlagged ? `, ${licenseFlagged}⚠` : ""})` },
+		{ id: "ch8", label: `5. Fix Recos` },
+		{ id: "chscan", label: `6. Scan context`, sub: [
+			{ id: "chsrc", label: `Descriptors (${scanned.length})` },
+			...(excTotal ? [{ id: "chexcl", label: `Ignored dirs (${excTotal})` }] : []),
+			{ id: "chmethod", label: `Methodology` },
+		] },
+	]);
 
 	// Overview charts row, rendered right under the compact totals.
 	const chartsRow = renderCharts({ prodMatches: prodMatchesActive }, { interactive: wrapTables });
@@ -1589,20 +1665,13 @@ function buildBody({ cveMatches, devCveMatches, embeddedMatches, retireMatches,
 		${toolbar}
 
 		${(warnings?.length || 0) ? majorSection(`0. Warnings & scan-completeness (${warnings.length})`, renderWarnings(warnings), { open: true, id: "ch0" }) : ""}
-		${majorSection(`1. CVE Vulnerabilities — production (${prodStats.total})`, cveContent, { id: "ch1" })}
-		${embeddedInventory.length ? majorSection(`1B. Embedded binaries — JAR/WAR/EAR (${embeddedInventory.length})`, embeddedContent, { open: embeddedInventory.length <= 50, id: "ch1e" }) : ""}
-		${unmanagedInventory.length ? majorSection(`1C. Unmanaged / vendored binaries (${unmanagedInventory.length})`, unmanagedContent, { open: unmanagedInventory.length <= 50, id: "ch1c" }) : ""}
-		${vendoredJsInv.length ? majorSection(`1D. Unmanaged / vendored JavaScript (${vendoredJsInv.length})`, vendoredJsContent, { open: vendoredJsInv.length <= 50, id: "ch1d" }) : ""}
-		${majorSection(`2. Vendored JS scan — retire.js (${retireMatches.length})`, vendoredContent, { open: retireMatches.length > 0 && retireMatches.length <= 50, id: "ch2" })}
-		${majorSection(`3. CVE in dev dependencies (${devStats.total})`, devCveContent, { open: devStats.total > 0 && devStats.total <= 50, id: "ch3" })}
-		${majorSection(`4. End-of-Life Frameworks (${eolResults?.length || 0})`, renderEolTable(eolResults), { id: "ch4" })}
-		${majorSection(`5. Obsolete / Deprecated Libraries (${obsoleteResults?.length || 0})`, renderObsoleteTable(obsoleteResults), { id: "ch5" })}
-		${majorSection(`6. Outdated Libraries (${outdatedResults?.length || 0})`, renderOutdatedTable(outdatedResults), { open: (outdatedResults?.length || 0) <= 50, id: "ch6" })}
-		${majorSection(`7. Licenses (${licenseTotal}${licenseFlagged ? `, ${licenseFlagged} to review` : ""})`, licenseContent, { open: licenseFlagged > 0, id: "ch7" })}
-		${majorSection(`8. Fix Recommendations`, renderFixRecommendations(recos, prodMatchesActive, outdatedResults), { open: false, id: "ch8" })}
-		${(prodMatchesFP.length + devMatchesFP.length + embMatchesFP.length) ? majorSection(`9. Appendix: Likely false positives (CPE-filtered) (${prodMatchesFP.length + devMatchesFP.length + embMatchesFP.length})`, fpContent, { open: false, id: "ch9" }) : ""}
-		${majorSection(`10. Appendix: Scanned dependency descriptors (${scanned.length})`, renderScannedManifests(scanned), { open: false, id: "chsrc" })}
-		${(excludedDirs?.length || 0) ? majorSection(`11. Appendix: Ignored directories (${excludedDirs.length})`, renderExcludedDirs(excludedDirs), { open: false, id: "chexcl" }) : ""}
+		${(diff && diff.summary) ? majorSection(`Δ Changes since baseline (+${diff.summary.cve.addedProduction} new prod CVE)`, renderDiffChapter(diff), { open: true, id: "chdiff" }) : ""}
+		${cveRoot}
+		${binRoot}
+		${maintRoot}
+		${licRoot}
+		${fixRoot}
+		${scanRoot}
 	`;
 	return wrapTables ? wrapTablesWithCopyButtons(body) : body;
 }
@@ -1666,24 +1735,15 @@ function pickTopEol(eolResults, n) {
 	}).slice(0, n);
 }
 
-function renderToc({ hasWarnings, prodTotal, embeddedTotal, unmanagedTotal, vendoredJsTotal, retireTotal, devTotal, eolTotal, obsoleteTotal, outdatedTotal, licenseTotal, licenseFlagged, fpTotal, scannedTotal, excludedTotal }) {
-	const entries = [];
-	if (hasWarnings)                  entries.push({ id: "ch0", label: "0. Warnings" });
-	entries.push({ id: "ch1", label: `1. Prod CVE (${prodTotal})` });
-	if (embeddedTotal)                entries.push({ id: "ch1e", label: `1B. Embedded (${embeddedTotal})` });
-	if (unmanagedTotal)               entries.push({ id: "ch1c", label: `1C. Unmanaged (${unmanagedTotal})` });
-	if (vendoredJsTotal)              entries.push({ id: "ch1d", label: `1D. Vendored JS (${vendoredJsTotal})` });
-	entries.push({ id: "ch2", label: `2. Vendored JS vulns (${retireTotal})` });
-	entries.push({ id: "ch3", label: `3. Dev CVE (${devTotal})` });
-	entries.push({ id: "ch4", label: `4. EOL (${eolTotal})` });
-	entries.push({ id: "ch5", label: `5. Obsolete (${obsoleteTotal})` });
-	entries.push({ id: "ch6", label: `6. Outdated (${outdatedTotal})` });
-	entries.push({ id: "ch7", label: `7. Licenses (${licenseTotal || 0}${licenseFlagged ? `, ${licenseFlagged}⚠` : ""})` });
-	entries.push({ id: "ch8", label: `8. Fix Recos` });
-	if (fpTotal)                      entries.push({ id: "ch9", label: `9. Likely FP (${fpTotal})` });
-	entries.push({ id: "chsrc", label: `10. Scanned descriptors (${scannedTotal || 0})` });
-	if (excludedTotal)                entries.push({ id: "chexcl", label: `11. Ignored dirs (${excludedTotal})` });
-	return `<nav class="toc">${entries.map(e => `<a href="#${e.id}">${esc(e.label)}</a>`).join("")}</nav>`;
+// Hierarchical TOC. `entries` is an array of { id, label, sub?: [{id,label}] };
+// roots render as bold chips, their sub-chapters as smaller muted chips after them.
+function renderToc(entries) {
+	const renderOne = e => {
+		const root = `<a class="toc-root" href="#${esc(e.id)}">${esc(e.label)}</a>`;
+		const subs = (e.sub || []).map(s => `<a class="toc-sub" href="#${esc(s.id)}">${esc(s.label)}</a>`).join("");
+		return root + subs;
+	};
+	return `<nav class="toc">${(entries || []).map(renderOne).join("")}</nav>`;
 }
 
 // Embedded-binary inventory chapter (1B): every embedded coordinate grouped by its
@@ -1776,6 +1836,62 @@ function renderExcludedDirs(excludedDirs) {
 	return intro + `<table><thead><tr><th>Directory (relative to --src)</th><th>Rule</th><th>Matched</th></tr></thead><tbody>${rows}</tbody></table>`;
 }
 
+// What fad-checker does NOT assess — stated explicitly so the audit's scope and
+// liability are unambiguous. Keep this list honest and in sync with the README.
+const LIMITATIONS = [
+	"<strong>Reachability / exploitability in your app.</strong> Findings flag a vulnerable version on the dependency graph; they do <em>not</em> prove the vulnerable code path is actually called at runtime. Triage with your application context.",
+	"<strong>Runtime configuration & mitigations.</strong> WAFs, feature flags, network isolation, disabled features, and other compensating controls are not modelled.",
+	"<strong>Secrets, IaC & container base images.</strong> No secret scanning, infrastructure-as-code, or OS/base-image layer analysis — fad-checker scans declared & vendored application dependencies only.",
+	"<strong>Business-logic & first-party code flaws.</strong> No SAST of your own source; only third-party components are assessed.",
+	"<strong>Malware beyond the available signal.</strong> Supply-chain risk uses OSV <code>MAL-</code> advisories and the free CIRCL <code>KnownMalicious</code> flag; there is no antivirus/behavioural lane.",
+	"<strong>License legal advice.</strong> License classification is informational SPDX categorisation, not a legal determination.",
+	"<strong>Private / internal coordinates.</strong> Components absent from public registries can't be CVE-matched here; audit them against your internal feed.",
+	"<strong>Data-source recency.</strong> Results reflect the cache state in the data-source table above; an <code>--offline</code> run uses exactly those snapshots.",
+];
+
+function renderMethodologyChapter(projectInfo) {
+	const prov = projectInfo && projectInfo.provenance;
+	const STATUS_PILL = { cached: ["cached", "#15803d"], disabled: ["disabled", "#6b7280"], missing: ["not warmed", "#b45309"] };
+	let sourcesTable = `<div class="empty">No provenance manifest available for this run.</div>`;
+	let cfgHtml = "";
+	if (prov) {
+		const rows = (prov.dataSources || []).map(s => {
+			const [txt, bg] = STATUS_PILL[s.status] || [s.status, "#6b7280"];
+			return `<tr><td>${esc(s.label)}</td><td>${pill(txt, bg)}</td><td>${esc(s.asOf || "—")}</td><td><span style="color:#6b7280">${esc(s.detail || "")}</span></td></tr>`;
+		}).join("\n");
+		sourcesTable = `<table><thead><tr><th>Data source</th><th>State</th><th>As of</th><th>Detail</th></tr></thead><tbody>${rows}</tbody></table>`;
+		const c = prov.configuration || {};
+		const rt = prov.runtime || {};
+		const kv = (k, v) => `<span class="meta-kv"><strong>${esc(k)}:</strong> ${esc(String(v))}</span>`;
+		cfgHtml = `<div class="fp-intro" style="margin-top:14px">
+			${kv("mode", prov.mode)} ${kv("ecosystems", c.ecosystems)} ${kv("transitive", c.transitive ? `on (depth ${c.transitiveDepth || "?"})` : "off")}
+			${kv("OSV", c.osv)} ${kv("NVD", c.nvd)} ${kv("EPSS", c.epss)} ${kv("KEV", c.kev)} ${kv("licenses", c.licenses)} ${kv("typosquat", c.typosquat)}
+			${kv("fail-on", c.failOn)}${c.ignoreFile ? " " + kv("ignore", c.ignoreFile) : ""}${c.vexFile ? " " + kv("vex", c.vexFile) : ""}
+			${kv("runtime", `${rt.node || "?"} · ${rt.platform || "?"}/${rt.arch || "?"}`)}
+		</div>`;
+	}
+	const intro = `<div class="fp-intro">How this report was produced and what it does <strong>not</strong> cover — stated for audit transparency and reproducibility. The data-source table shows the freshness of every feed used; the configuration line records the run's findings-affecting options. An <code>--offline</code> re-run against the same cache (ship it with <code>--export-cache</code>) reproduces these findings.</div>`;
+	const limitations = `<div class="defined-in" style="margin-top:14px"><span class="defined-label">Limitations — fad-checker does not assess:</span></div><ul class="methodology-limits">${LIMITATIONS.map(l => `<li>${l}</li>`).join("")}</ul>`;
+	return intro + sourcesTable + cfgHtml + limitations;
+}
+
+// Differential-audit chapter (vs --baseline): what changed since the prior findings JSON.
+function renderDiffChapter(diff) {
+	if (!diff || !diff.summary) return "";
+	const s = diff.summary;
+	const sevTxt = Object.entries(s.cve.addedBySeverity || {}).filter(([, n]) => n).map(([k, n]) => `${n} ${k.toLowerCase()}`).join(", ") || "none";
+	const intro = `<div class="fp-intro">Change since the baseline (<code>--baseline</code>). <strong>${s.cve.addedProduction}</strong> new production CVE finding(s) (${esc(sevTxt)}); ${s.cve.removed} resolved, ${s.cve.unchanged} unchanged.</div>`;
+	const cat = (label, c) => `<tr><td>${esc(label)}</td><td style="color:#b91c1c">+${c.added}</td><td style="color:#15803d">−${c.removed}</td><td><span style="color:#6b7280">${c.unchanged}</span></td></tr>`;
+	const table = `<table><thead><tr><th>Category</th><th>New</th><th>Resolved</th><th>Unchanged</th></tr></thead><tbody>
+		${cat("CVE", s.cve)}${cat("EOL", s.eol)}${cat("Obsolete", s.obsolete)}${cat("Outdated", s.outdated)}${cat("Licenses", s.licenses)}
+	</tbody></table>`;
+	const newCves = (diff.cve?.added || []).filter(f => !f.suppressed && !f.cpeFiltered);
+	const list = newCves.length
+		? `<div class="defined-in" style="margin-top:10px"><span class="defined-label">New CVE findings:</span></div><ul>${newCves.slice(0, 50).map(f => `<li><code>${esc(f.id)}</code> · ${esc(f.severity || "")} · <code>${esc((f.dep && f.dep.coord) || "")}@${esc((f.dep && f.dep.version) || "")}</code></li>`).join("")}${newCves.length > 50 ? `<li>…and ${newCves.length - 50} more</li>` : ""}</ul>`
+		: "";
+	return intro + table + list;
+}
+
 function renderFalsePositives(matches) {
 	if (!matches.length) return `<div class="empty">No CPE-filtered findings.</div>`;
 	const intro = `<div class="fp-intro">These entries were initially matched by name but NVD's CPE configurations show your dep version is outside every vulnerable range. They are almost certainly false positives — kept here for audit transparency.</div>`;
@@ -2237,12 +2353,12 @@ ${WORD_SECTION_PR}
 // Render the HTML and/or Word report. Callers pass explicit target paths;
 // a null/omitted path skips that format (so `--report-html` alone writes only HTML).
 // Back-compat: `outputDir` still writes both under the default file names.
-async function writeReports({ cveMatches, devCveMatches, embeddedMatches, retireMatches, vendoredJsInventory, eolResults, obsoleteResults, outdatedResults, licenseResults, excludedDirs, resolvedDeps, projectInfo, outputDir, htmlPath, docPath, warnings, parsedManifests }) {
+async function writeReports({ cveMatches, devCveMatches, embeddedMatches, retireMatches, vendoredJsInventory, eolResults, obsoleteResults, outdatedResults, licenseResults, excludedDirs, resolvedDeps, projectInfo, outputDir, htmlPath, docPath, warnings, parsedManifests, diff }) {
 	if (outputDir) {
 		if (htmlPath === undefined) htmlPath = path.join(outputDir, "cve-report.html");
 		if (docPath === undefined) docPath = path.join(outputDir, "cve-report.doc");
 	}
-	const payload = { cveMatches, devCveMatches, embeddedMatches, retireMatches, vendoredJsInventory, eolResults, obsoleteResults, outdatedResults, licenseResults, excludedDirs, resolvedDeps, projectInfo, warnings, parsedManifests };
+	const payload = { cveMatches, devCveMatches, embeddedMatches, retireMatches, vendoredJsInventory, eolResults, obsoleteResults, outdatedResults, licenseResults, excludedDirs, resolvedDeps, projectInfo, warnings, parsedManifests, diff };
 	const written = { htmlPath: null, docPath: null };
 	if (htmlPath) {
 		await fs.promises.mkdir(path.dirname(path.resolve(htmlPath)), { recursive: true });

package/lib/json-export.js

@@ -30,6 +30,9 @@ function depBrief(dep) {
 		provenance: dep.provenance || "manifest",
 		purl: purlFor(dep),
 		manifestPaths: dep.manifestPaths || dep.pomPaths || [],
+		// When the version was backfilled from an import/platform BOM, record which BOM
+		// supplied it — { via: "bom", bom: "g:a:v" } — so the finding is traceable.
+		versionSource: dep.versionSource || null,
 	};
 }
 
@@ -68,7 +71,7 @@ function buildFindings(payload = {}) {
 	const {
 		cveMatches = [], retireMatches = [], vendoredJsInventory = [], eolResults = [], obsoleteResults = [],
 		outdatedResults = [], licenseResults = null, resolvedDeps, projectInfo = {}, toolVersion = "0",
-		typosquats = [], excludedDirs = [],
+		typosquats = [], excludedDirs = [], diff = null,
 	} = payload;
 
 	const { buildInventory } = require("./unmanaged");
@@ -91,6 +94,9 @@ function buildFindings(payload = {}) {
 		tool: { name: "fad-checker", version: String(toolVersion) },
 		generatedAt: projectInfo.generatedAt || null,
 		project: { name: projectInfo.name || null, src: projectInfo.src || null },
+		// Scan-provenance manifest (data-source freshness + run configuration) for a
+		// reproducible/defensible audit. Null if the caller didn't supply one.
+		provenance: projectInfo.provenance || payload.provenance || null,
 		summary: {
 			dependencies: resolvedDeps?.size ?? null,
 			cve: { ...sevCounts, kev, total: cveMatches.filter(m => !m.cpeFiltered && !m.suppressed).length },
@@ -118,6 +124,9 @@ function buildFindings(payload = {}) {
 		vendoredJs: vendoredJsInventory,
 		typosquat: typosquats,
 		excludedDirs,
+		// Differential audit vs a --baseline document (summary + per-category deltas).
+		// Null when no baseline was provided.
+		diff: diff || null,
 	};
 }
 

package/lib/maven-bom.js

@@ -48,6 +48,12 @@ function collectImportBoms(propsByPom) {
 /**
  * Resolve each import BOM to its managed-version table and merge them into one map.
  * First BOM to manage a given g:a wins (mirrors Maven's declaration-order precedence).
+ *
+ * Each value is `{ version, bom }` where `bom` is the `groupId:artifactId:version` of the
+ * TOP-LEVEL platform/import BOM that supplied the version (e.g. spring-boot-dependencies),
+ * not the nested BOM it may import (spring-batch-bom) — that's the coordinate the user wrote
+ * in `platform(...)`/`<scope>import</scope>` and recognizes. Carried so backfillVersions can
+ * record per-dep provenance ("version managed by <bom>").
  */
 async function resolveBomManagedVersions(boms, opts = {}) {
 	const effectivePom = opts.effectivePom || transitive.effectivePom;
@@ -57,11 +63,12 @@ async function resolveBomManagedVersions(boms, opts = {}) {
 		try { eff = await effectivePom(bom.groupId, bom.artifactId, bom.version, opts); }
 		catch { eff = null; }
 		if (!eff || !eff.depMgmt) continue;
+		const bomCoord = `${bom.groupId}:${bom.artifactId}:${bom.version}`;
 		for (const d of eff.depMgmt) {
 			if (!d.groupId || !d.artifactId) continue;
 			const k = `${d.groupId}:${d.artifactId}`;
 			if (map.has(k)) continue;
-			if (d.version && !/\$\{/.test(String(d.version))) map.set(k, String(d.version));
+			if (d.version && !/\$\{/.test(String(d.version))) map.set(k, { version: String(d.version), bom: bomCoord });
 		}
 	}
 	return map;
@@ -69,7 +76,10 @@ async function resolveBomManagedVersions(boms, opts = {}) {
 
 /**
  * Fill the version of every Maven dep that has no concrete version (null or `${…}`)
- * from the BOM-managed map. Mutates the resolvedDeps Map entries in place.
+ * from the BOM-managed map. Mutates the resolvedDeps Map entries in place. Each filled
+ * dep is stamped with `versionSource = { via: "bom", bom: "<coord>" }` so the report can
+ * disclose that the version came from a BOM (e.g. "version managed by spring-boot-dependencies")
+ * rather than the manifest it's declared in — the usual versionless Spring Boot / Gradle case.
  * @returns number of deps filled
  */
 function backfillVersions(resolvedDeps, mgmtMap) {
@@ -78,11 +88,13 @@ function backfillVersions(resolvedDeps, mgmtMap) {
 		if (dep.ecosystem !== "maven") continue;
 		if (dep.provenance === "embedded" || dep.provenance === "binary") continue;
 		if (dep.version && !/\$\{/.test(String(dep.version))) continue; // already concrete
-		const v = mgmtMap.get(`${dep.groupId}:${dep.artifactId}`);
-		if (!v) continue;
+		const entry = mgmtMap.get(`${dep.groupId}:${dep.artifactId}`);
+		if (!entry) continue;
+		const v = entry.version;
 		dep.version = v;
 		if (!Array.isArray(dep.versions)) dep.versions = [];
 		if (!dep.versions.includes(v)) dep.versions.push(v);
+		dep.versionSource = { via: "bom", bom: entry.bom };
 		filled++;
 	}
 	return filled;

package/lib/provenance.js

@@ -0,0 +1,135 @@
+/**
+ * lib/provenance.js — scan-provenance / reproducibility manifest.
+ *
+ * A professional audit must be defensible and reproducible: a finding has to be
+ * explainable from the exact inputs that produced it, and a second auditor should be
+ * able to reproduce it. This module builds a manifest of WHAT fad-checker ran with —
+ * tool version, runtime, run mode (offline/online), the run configuration (only the
+ * flags that change WHAT is found), and the freshness of every data source (read from
+ * its own cache under ~/.fad-checker/).
+ *
+ * The manifest reports the CACHE STATE of each source, not "online vs offline this
+ * run" — the cache state is the reproducible truth and is what an --offline re-run
+ * reads from. Pure given a cacheDir (injected for tests).
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
+ */
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+
+const DEFAULT_CACHE_DIR = path.join(os.homedir(), ".fad-checker");
+
+function readJson(file) {
+	try { return JSON.parse(fs.readFileSync(file, "utf8")); } catch { return null; }
+}
+
+function iso(ms) {
+	if (!ms || !Number.isFinite(Number(ms))) return null;
+	try { return new Date(Number(ms)).toISOString(); } catch { return null; }
+}
+
+// Each data source declares how to read its freshness from its cache file/dir.
+// kind:
+//   "cve-meta"   cve-data/meta.json  → { builtAt, cveCount }
+//   "meta"       <file>.json         → { meta: { fetchedAt }, entries }
+//   "kev"        kev-cache.json       → { _fetchedAt, body: { catalogVersion, dateReleased } }
+//   "dir"        <dir>/               → file count + newest mtime
+const SOURCE_DEFS = [
+	{ id: "cve", label: "CVEProject (Maven index)", rel: "cve-data/meta.json", kind: "cve-meta" },
+	{ id: "osv", label: "OSV.dev", rel: "osv-cache", kind: "dir", flag: "osv" },
+	{ id: "osvDb", label: "OSV local DB (Maven)", rel: "osv-db/maven-index.json", kind: "mtime" },
+	{ id: "nvd", label: "NIST NVD", rel: "nvd-cache", kind: "dir", flag: "nvd" },
+	{ id: "epss", label: "EPSS (FIRST.org)", rel: "epss-cache.json", kind: "meta", flag: "epss" },
+	{ id: "kev", label: "CISA KEV", rel: "kev-cache.json", kind: "kev", flag: "kev" },
+	{ id: "eol", label: "endoflife.date", rel: "eol-cache.json", kind: "meta" },
+	{ id: "mavenCentral", label: "Maven Central (latest)", rel: "version-cache.json", kind: "meta" },
+	{ id: "npm", label: "npm registry", rel: "npm-registry-cache.json", kind: "meta" },
+	{ id: "nuget", label: "NuGet registry", rel: "nuget-cache.json", kind: "meta" },
+	{ id: "packagist", label: "Packagist", rel: "packagist-cache.json", kind: "meta" },
+	{ id: "go", label: "Go module proxy", rel: "go-proxy-cache.json", kind: "meta" },
+	{ id: "rubygems", label: "RubyGems", rel: "rubygems-cache.json", kind: "meta" },
+];
+
+// Read one source's freshness → { status, asOf, detail }.
+function readSource(def, cacheDir) {
+	const target = path.join(cacheDir, def.rel);
+	if (def.kind === "dir") {
+		let files; try { files = fs.readdirSync(target).filter(f => f.endsWith(".json")); } catch { return { status: "missing", asOf: null, detail: null }; }
+		if (!files.length) return { status: "missing", asOf: null, detail: null };
+		let newest = 0;
+		for (const f of files) { try { const m = fs.statSync(path.join(target, f)).mtimeMs; if (m > newest) newest = m; } catch { /* skip */ } }
+		return { status: "cached", asOf: iso(newest), detail: `${files.length} cached` };
+	}
+	if (def.kind === "mtime") {
+		let st; try { st = fs.statSync(target); } catch { return { status: "missing", asOf: null, detail: null }; }
+		return { status: "cached", asOf: iso(st.mtimeMs), detail: null };
+	}
+	const data = readJson(target);
+	if (!data) return { status: "missing", asOf: null, detail: null };
+	if (def.kind === "cve-meta") {
+		return { status: "cached", asOf: data.builtAt || null, detail: data.cveCount != null ? `${data.cveCount} CVEs` : null };
+	}
+	if (def.kind === "kev") {
+		const body = data.body || {};
+		const ver = body.catalogVersion || body.dateReleased || null;
+		return { status: "cached", asOf: iso(data._fetchedAt), detail: ver ? `catalog ${ver}` : null };
+	}
+	// "meta": { meta: { fetchedAt }, entries }
+	const n = data.entries && typeof data.entries === "object" ? Object.keys(data.entries).length : null;
+	return { status: "cached", asOf: iso(data.meta && data.meta.fetchedAt), detail: n != null ? `${n} entries` : null };
+}
+
+/**
+ * Inspect the cache directory → an array of data-source descriptors:
+ *   { id, label, status: "disabled"|"missing"|"cached", asOf, detail }
+ * A source whose feature flag is turned off this run is "disabled".
+ */
+function collectDataSources({ cacheDir = DEFAULT_CACHE_DIR, options = {} } = {}) {
+	return SOURCE_DEFS.map(def => {
+		if (def.flag && options[def.flag] === false) {
+			return { id: def.id, label: def.label, status: "disabled", asOf: null, detail: null };
+		}
+		const r = readSource(def, cacheDir);
+		return { id: def.id, label: def.label, ...r };
+	});
+}
+
+// Only the options that change WHAT is found belong in the reproducibility record.
+function runConfiguration(options = {}) {
+	return {
+		ecosystems: options.ecosystem || "auto",
+		transitive: options.transitive !== false,
+		transitiveDepth: options.transitiveDepth != null ? String(options.transitiveDepth) : null,
+		osv: options.osv !== false,
+		nvd: options.nvd !== false,
+		epss: options.epss !== false,
+		kev: options.kev !== false,
+		allLibs: options.allLibs !== false,
+		licenses: !!options.licenses,
+		typosquat: !!options.typosquat,
+		failOn: options.failOn || "none",
+		ignoreFile: options.ignore || null,
+		vexFile: options.vex || null,
+		excludePath: options.excludePath || [],
+		defaultExcludes: options.defaultExcludes !== false,
+	};
+}
+
+/**
+ * Assemble the full scan-provenance manifest. Pure given cacheDir + runtime.
+ */
+function buildScanProvenance({ toolVersion, generatedAt, options = {}, cacheDir = DEFAULT_CACHE_DIR, runtime } = {}) {
+	const rt = runtime || { node: process.version, platform: process.platform, arch: process.arch };
+	return {
+		tool: { name: "fad-checker", version: String(toolVersion || "0") },
+		generatedAt: generatedAt || null,
+		mode: options.offline ? "offline" : "online",
+		runtime: { node: rt.node, platform: rt.platform, arch: rt.arch },
+		configuration: runConfiguration(options),
+		dataSources: collectDataSources({ cacheDir, options }),
+	};
+}
+
+module.exports = { buildScanProvenance, collectDataSources, runConfiguration, DEFAULT_CACHE_DIR };

package/lib/registries.js

@@ -12,7 +12,7 @@
  * @author: N.BRAUN
  * @email: pp9ping@gmail.com
  */
-const SUPPORTED = ["maven", "npm", "pypi", "ruby", "go"];
+const SUPPORTED = ["maven", "npm", "pypi", "ruby", "go", "nuget", "composer"];
 
 const PUBLIC_BASES = {
 	maven: "https://repo1.maven.org/maven2/",
@@ -20,6 +20,11 @@ const PUBLIC_BASES = {
 	pypi: "https://pypi.org/pypi/",
 	ruby: "https://rubygems.org/api/v1/gems/",
 	go: "https://proxy.golang.org/",
+	// NuGet: the public v3 registration base (each fetch appends "<lowerid>/index.json").
+	nuget: "https://api.nuget.org/v3/registration5-gz-semver2/",
+	// Composer: the Packagist root (the public path is "packages/<name>.json"; custom
+	// feeds are queried via the v2 "p2/<name>.json" metadata API — see composer/registry.js).
+	composer: "https://packagist.org/",
 };
 
 function normalise(url) {

package/lib/report-integrity.js

@@ -0,0 +1,52 @@
+/**
+ * lib/report-integrity.js — tamper-evidence for the report deliverable.
+ *
+ * An audit handed to a client should be verifiable as unaltered. This writes a
+ * standard `sha256sum`-format manifest (`<hex>␠␠<relative-path>`) over every artifact
+ * produced by a run, verifiable offline with `sha256sum -c SHA256SUMS`. Checksums
+ * (not signatures) keep the CLI zero-config; signing the manifest with the auditor's
+ * own key is then a trivial external step.
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
+ */
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+/** SHA-256 of a file's bytes, as lowercase hex. */
+function sha256OfFile(filePath) {
+	const buf = fs.readFileSync(filePath);
+	return crypto.createHash("sha256").update(buf).digest("hex");
+}
+
+function relName(file, baseDir) {
+	if (!baseDir) return path.basename(file);
+	const rel = path.relative(baseDir, file);
+	return rel && !rel.startsWith("..") ? rel : path.basename(file);
+}
+
+/**
+ * Build a sha256sum-format manifest over `files` (existing ones only), sorted by
+ * relative name for a deterministic, diffable output.
+ */
+function buildChecksumManifest(files, { baseDir } = {}) {
+	const rows = [];
+	for (const f of files || []) {
+		if (!f) continue;
+		let hex;
+		try { hex = sha256OfFile(f); } catch { continue; } // missing/unreadable → skip
+		rows.push({ name: relName(f, baseDir), hex });
+	}
+	rows.sort((a, b) => a.name.localeCompare(b.name));
+	return rows.map(r => `${r.hex}  ${r.name}`).join("\n") + (rows.length ? "\n" : "");
+}
+
+/** Write the manifest to `manifestPath`; returns the manifest text. */
+function writeChecksums(files, manifestPath, { baseDir } = {}) {
+	const text = buildChecksumManifest(files, { baseDir: baseDir || path.dirname(manifestPath) });
+	fs.writeFileSync(manifestPath, text);
+	return text;
+}
+
+module.exports = { sha256OfFile, buildChecksumManifest, writeChecksums };

package/lib/snyk.js

@@ -28,13 +28,46 @@ async function runSnykTest(outputDir, opts = {}) {
 		});
 		return parseSnykStdout(stdout);
 	} catch (err) {
-		// snyk exits 1 when vulns are found — stdout still contains the JSON
-		if (err.stdout) return parseSnykStdout(err.stdout);
 		if (err.code === "ENOENT") throw new Error("snyk CLI not found on PATH — install snyk separately");
-		throw err;
+		if (err.killed) throw new Error(`snyk timed out after ${Math.round(timeoutMs / 1000)}s (raise opts.timeoutMs)`);
+		// snyk exits 1 when vulnerabilities are found — stdout holds the real findings
+		// JSON, so that's NOT a failure. BUT exit 2 (command error, e.g. auth) and
+		// exit 3 (no supported projects) ALSO write JSON to stdout, shaped
+		// { ok:false, error:"…" }. Returning that as-is makes parseSnykResults read it
+		// as "0 vulnerabilities" → a silent success that hides a real snyk failure.
+		if (err.stdout) {
+			const parsed = parseSnykStdout(err.stdout);
+			const snykErr = snykOutputError(parsed);
+			if (snykErr) throw new Error(`snyk failed (exit ${err.code}): ${snykErr}`);
+			return parsed;
+		}
+		// No JSON on stdout at all → surface stderr (the human-readable reason) rather
+		// than execFile's generic "Command failed: snyk test…".
+		const detail = (err.stderr && String(err.stderr).trim()) || err.message;
+		throw new Error(`snyk failed (exit ${err.code}): ${detail}`);
 	}
 }
 
+/**
+ * Inspect parsed `snyk --json` output and return a human-readable error string when
+ * snyk actually FAILED — i.e. every project is an error stub ({ ok:false, error }) and
+ * none carries usable results — or `null` when the output holds real findings.
+ *
+ * Snyk emits this error-shaped JSON on stdout for exit 2 (command error, e.g. auth) and
+ * exit 3 (no supported projects). Without this check those are read as "0 vulnerabilities",
+ * silently hiding the failure behind a green "Snyk: 0 findings merged".
+ */
+function snykOutputError(parsed) {
+	const projects = Array.isArray(parsed) ? parsed : (parsed != null ? [parsed] : []);
+	if (!projects.length) return null;
+	// A usable project either lists vulnerabilities (exit 1) or reports ok:true (clean).
+	const usable = projects.some(p => p && (Array.isArray(p.vulnerabilities) || p.ok === true));
+	if (usable) return null;
+	const errored = projects.filter(p => p && p.ok === false && p.error);
+	if (!errored.length) return null;
+	return [...new Set(errored.map(p => String(p.error).trim()).filter(Boolean))].join("; ");
+}
+
 function parseSnykStdout(stdout) {
 	if (!stdout) return [];
 	const str = String(stdout).trim();
@@ -126,5 +159,6 @@ module.exports = {
 	runSnykTest,
 	parseSnykResults,
 	parseSnykStdout,
+	snykOutputError,
 	mergeWithFadResults,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fad-checker",
-  "version": "2.3.2",
+  "version": "2.4.1",
   "description": "Scan ALL Maven, Gradle, npm, Yarn, Composer, Python, C#/.NET, Go & Ruby dependencies — plus embedded JARs (fat-jars/war/ear) — in a source tree ONE SHOT without mvn/python/etc — CVE (EPSS/KEV-prioritised), EOL, obsolete, outdated & licenses, with SBOM/CSAF/SARIF/JSON exports, CI gating and fix recos",
   "keywords": [
     "sca",