fad-checker 2.3.1 → 2.4.0

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; }
@@ -1170,18 +1173,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 +1493,7 @@ function renderLicenseChapter(licenseResults) {
 	return intro + blocks;
 }
 
-function buildBody({ cveMatches, devCveMatches, embeddedMatches, retireMatches, vendoredJsInventory, eolResults, obsoleteResults, outdatedResults, licenseResults, 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 +1521,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,26 +1556,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,
-	});
+	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 });
@@ -1588,19 +1656,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" })}
+		${(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;
 }
@@ -1664,23 +1726,15 @@ function pickTopEol(eolResults, n) {
 	}).slice(0, n);
 }
 
-function renderToc({ hasWarnings, prodTotal, embeddedTotal, unmanagedTotal, vendoredJsTotal, retireTotal, devTotal, eolTotal, obsoleteTotal, outdatedTotal, licenseTotal, licenseFlagged, fpTotal, scannedTotal }) {
-	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})` });
-	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
@@ -1759,6 +1813,76 @@ function renderVendoredJsInventory(inventory, srcRoot) {
 	return intro + `<table><thead><tr><th>Library</th><th>Version</th><th>File</th><th>Detection</th><th>Status</th></tr></thead><tbody>${rows}</tbody></table>`;
 }
 
+function renderExcludedDirs(excludedDirs) {
+	if (!excludedDirs || !excludedDirs.length) return `<div class="empty">No directories were excluded from the scan.</div>`;
+	const byDefault = excludedDirs.filter(e => e.type === "default").length;
+	const byGlob    = excludedDirs.filter(e => e.type === "exclude-path").length;
+	const intro = `<div class="fp-intro">Directories the scan <strong>did not walk</strong> — pruned by the built-in default-exclude set (package stores, build output, VCS/IDE metadata) at any depth and by your <code>--exclude-path</code> rules, anchored to <code>--src</code>. Paths are relative to the scan root. <strong>${byDefault}</strong> pruned by default rules${byGlob ? `, <strong>${byGlob}</strong> by <code>--exclude-path</code>` : ""}. Nothing under these paths was read, so any dependency, vendored JS or binary inside them is <strong>not</strong> covered — re-run with <code>--no-default-excludes</code> or drop an <code>--exclude-path</code> rule to include one.</div>`;
+	const rows = excludedDirs.map(e => {
+		const tag = e.type === "exclude-path"
+			? pill("--exclude-path", "#b45309")
+			: pill("default", "#6b7280");
+		return `<tr><td class="dep"><code class="path">${esc(e.dir || "")}</code></td><td>${tag}</td><td><span style="color:#6b7280">${esc(e.reason || "")}</span></td></tr>`;
+	}).join("\n");
+	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>`;
@@ -2220,12 +2344,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, 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, 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

@@ -68,7 +68,7 @@ function buildFindings(payload = {}) {
 	const {
 		cveMatches = [], retireMatches = [], vendoredJsInventory = [], eolResults = [], obsoleteResults = [],
 		outdatedResults = [], licenseResults = null, resolvedDeps, projectInfo = {}, toolVersion = "0",
-		typosquats = [],
+		typosquats = [], excludedDirs = [], diff = null,
 	} = payload;
 
 	const { buildInventory } = require("./unmanaged");
@@ -91,6 +91,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 },
@@ -105,6 +108,7 @@ function buildFindings(payload = {}) {
 			suppressed: cveMatches.filter(m => m.suppressed).length,
 			malicious: cveMatches.filter(m => m.malicious && !m.suppressed).length,
 			typosquat: typosquats.length,
+			excludedDirs: excludedDirs.length,
 		},
 		cve: cveMatches.map(cveFinding),
 		vendored: retireMatches.map(cveFinding),
@@ -116,6 +120,10 @@ function buildFindings(payload = {}) {
 		embedded,
 		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/nvd.js

@@ -45,11 +45,18 @@ function cachePath(cveId) {
 	return path.join(NVD_CACHE_DIR, `${cveId}.json`);
 }
 
-function readCache(cveId) {
+function readCache(cveId, offline = false) {
 	const p = cachePath(cveId);
 	if (!fs.existsSync(p)) return null;
 	try {
 		const data = JSON.parse(fs.readFileSync(p, "utf8"));
+		// Offline (air-gapped): the warmed cache is the ONLY source — never reject it
+		// for age or an older schema. Dropping it would silently lose ALL NVD
+		// enrichment (CWEs, CVSS vector, references, CPE configs) for that CVE, which
+		// is exactly the "offline missed some CWE titles" regression. A stale/older
+		// body just means a field may be missing — strictly better than nothing.
+		// (Online still enforces schema + TTL so we re-fetch and upgrade.)
+		if (offline) return data.body ?? null;
 		// Schema mismatch → force re-fetch so newly-added fields (e.g. cwes) get populated.
 		if ((data._schema || 1) < NVD_CACHE_SCHEMA) return null;
 		if (Date.now() - data._fetchedAt < NVD_CACHE_TTL_MS) return data.body;
@@ -165,7 +172,7 @@ function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }
 
 async function fetchOne(cveId, opts = {}) {
 	const { fetcher = globalThis.fetch, verbose, offline } = opts;
-	const cached = readCache(cveId);
+	const cached = readCache(cveId, offline);
 	if (cached !== null && cached !== undefined) return cached;
 	if (offline) return null;
 	const headers = { "User-Agent": "fad-checker-nvd-enrich" };
@@ -210,7 +217,7 @@ async function enrichMatches(matches, opts = {}) {
 	const byId = new Map();
 	const liveIds = [];
 	for (const cveId of uniqueCves) {
-		const cached = readCache(cveId);
+		const cached = readCache(cveId, offline);
 		if (cached !== null && cached !== undefined) {
 			byId.set(cveId, cached);
 			continue;
@@ -296,6 +303,10 @@ module.exports = {
 	enrichMatches,
 	fetchOne,
 	extractFromNvdRecord,
+	readCache,
+	writeCache,
 	NVD_CACHE_DIR,
+	NVD_CACHE_SCHEMA,
+	NVD_CACHE_TTL_MS,
 	getNvdApiKey,
 };

package/lib/path-filter.js

@@ -14,6 +14,7 @@
  * @author: N.BRAUN
  * @email: pp9ping@gmail.com
  */
+const fs = require("fs");
 const path = require("path");
 const { minimatch } = require("minimatch");
 
@@ -21,7 +22,9 @@ const { minimatch } = require("minimatch");
  * Compile glob strings into (relPath) → bool matchers. Each glob prunes both the
  * matched directory itself and its whole subtree, so `packages/legacy/**` (or the
  * bare `packages/legacy`) stops the walk at `packages/legacy` — a manifest sitting
- * directly in it is never collected.
+ * directly in it is never collected. Each matcher carries `.glob` (the original
+ * trimmed pattern) so a caller can report WHICH glob matched (see makeDirFilter's
+ * onSkip / collectExcludedDirs).
  */
 function compileGlobs(globs) {
 	return (globs || []).filter(Boolean).map(String).map(g => g.trim()).filter(Boolean).map(g => {
@@ -31,28 +34,104 @@ function compileGlobs(globs) {
 		const patterns = base.endsWith("/**")
 			? [base, base.slice(0, -3).replace(/\/+$/, "")] // dir + its subtree
 			: [base, base + "/**"];
-		return rel => patterns.some(p => p && minimatch(rel, p, { dot: true }));
+		const fn = rel => patterns.some(p => p && minimatch(rel, p, { dot: true }));
+		fn.glob = g;
+		return fn;
 	});
 }
 
+/**
+ * Superset of every walker's default-skip basename set (Maven core.js, detectCodecs,
+ * npm parse.js, the composer/go/nuget/pypi/ruby/gradle/binary codecs, retire.js).
+ * Used as the canonical "what the prune policy excludes" set for the report's
+ * ignored-directories appendix (collectExcludedDirs). Individual walkers still use
+ * their OWN narrower sets — this union is purely for reporting which dirs the scan
+ * skipped. Keep in sync when a codec adds a SKIP entry.
+ */
+const DEFAULT_EXCLUDE_DIRS = new Set([
+	// package stores / vendored trees
+	"node_modules", "bower_components", "jspm_packages", "vendor", "packages", "site-packages",
+	// build output
+	"target", "dist", "build", "build-output", "out", "bin", "obj", "coverage", ".next", ".nuxt",
+	// language caches / virtualenvs
+	"__pycache__", ".venv", "venv", ".tox", ".mypy_cache", ".cache", ".m2", "tmp", "testdata",
+	// VCS / IDE / tool metadata
+	".git", ".svn", ".hg", ".idea", ".vscode", ".gradle", ".mvn",
+]);
+
 /**
  * Build a skipDir(absChildDir) predicate.
  *   srcRoot       scan root the globs are relative to
  *   defaultSkip   Set of basenames the walker prunes by default (its own SKIP)
  *   excludePath   user glob strings
  *   useDefaults   when false, ignore defaultSkip entirely (--no-default-excludes)
+ *   onSkip        optional (absChild, reason) callback fired when a dir is pruned;
+ *                 reason is { type:"default", name } or { type:"exclude-path", glob }.
  */
-function makeDirFilter({ srcRoot, defaultSkip = null, excludePath = [], useDefaults = true } = {}) {
+function makeDirFilter({ srcRoot, defaultSkip = null, excludePath = [], useDefaults = true, onSkip = null } = {}) {
 	const matchers = compileGlobs(excludePath);
 	return function skipDir(absChild) {
 		const name = path.basename(absChild);
-		if (useDefaults && defaultSkip && defaultSkip.has(name)) return true;
+		if (useDefaults && defaultSkip && defaultSkip.has(name)) {
+			if (onSkip) onSkip(absChild, { type: "default", name });
+			return true;
+		}
 		if (matchers.length && srcRoot) {
 			const rel = path.relative(srcRoot, absChild).split(path.sep).join("/");
-			if (rel && !rel.startsWith("..") && matchers.some(m => m(rel))) return true;
+			if (rel && !rel.startsWith("..")) {
+				const hit = matchers.find(m => m(rel));
+				if (hit) {
+					if (onSkip) onSkip(absChild, { type: "exclude-path", glob: hit.glob });
+					return true;
+				}
+			}
 		}
 		return false;
 	};
 }
 
-module.exports = { makeDirFilter, compileGlobs };
+/**
+ * Walk `srcRoot` once and return the ACTUAL directories the scan's prune policy
+ * excludes — the report's ignored-directories appendix. Applies the same policy the
+ * codec walkers do (DEFAULT_EXCLUDE_DIRS by basename + the user's --exclude-path
+ * globs, both honoring --no-default-excludes), records each pruned dir relative to
+ * the scan root with WHY it was pruned, and never descends into a pruned dir (so a
+ * top-level `node_modules` is reported once, not its thousands of children).
+ *
+ * Returns [{ dir, type, reason }] sorted by path. `dir` is POSIX-relative to srcRoot.
+ */
+function collectExcludedDirs({ srcRoot, excludePath = [], defaultExcludes = true } = {}) {
+	if (!srcRoot) return [];
+	let root;
+	try { root = fs.realpathSync(path.resolve(srcRoot)); } catch { root = path.resolve(srcRoot); }
+	const found = [];
+	const onSkip = (absChild, reason) => {
+		const rel = path.relative(root, absChild).split(path.sep).join("/") || ".";
+		found.push(reason.type === "default"
+			? { dir: rel, type: "default", reason: `default-exclude (${reason.name})` }
+			: { dir: rel, type: "exclude-path", reason: `--exclude-path (${reason.glob})` });
+	};
+	const skipDir = makeDirFilter({ srcRoot: root, defaultSkip: DEFAULT_EXCLUDE_DIRS, excludePath, useDefaults: defaultExcludes !== false, onSkip });
+	// Iterative DFS. We only ever descend into NON-pruned dirs, so the heavy trees
+	// (node_modules, …) are cut at the top — the walk stays bounded by the real
+	// source tree. A high guard backstops a pathological symlink-free deep tree.
+	const stack = [root];
+	let guard = 0;
+	const GUARD_MAX = 2_000_000;
+	while (stack.length && guard < GUARD_MAX) {
+		const dir = stack.pop();
+		let entries;
+		try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+		for (const e of entries) {
+			if (!e.isDirectory()) continue;   // isDirectory() is false for symlinks → no loops
+			guard++;
+			const absChild = path.join(dir, e.name);
+			if (skipDir(absChild)) continue;  // onSkip recorded it; do NOT descend
+			stack.push(absChild);
+		}
+	}
+	found.sort((a, b) => a.dir.localeCompare(b.dir));
+	return found;
+}
+
+module.exports = { makeDirFilter, compileGlobs, collectExcludedDirs, DEFAULT_EXCLUDE_DIRS };