fad-checker 2.3.0 → 2.3.2

package/CHANGELOG.md

@@ -32,6 +32,14 @@ This project adheres to [Semantic Versioning](https://semver.org/).
   across every ecosystem. Repeatable; also `excludePath: [...]` in `.fad-env.json`,
   unioned across config layers. **`--no-default-excludes`** walks the normally
   pruned dirs (`node_modules`, `vendor`, `target`, `.git`, …). New `lib/path-filter.js`.
+- **Ignored-directories appendix (report chapter 11 + JSON `excludedDirs`).** The
+  HTML/`.doc` report now ends with an appendix listing the ACTUAL directories the
+  scan did not walk — resolved by re-walking `--src` once under the same prune
+  policy the codecs use (the default-exclude set at any depth + your
+  `--exclude-path` rules), each path shown relative to the scan root and tagged
+  with the rule that pruned it (`default` vs `--exclude-path`). Surfaced in the
+  findings JSON as `excludedDirs[]` + `summary.excludedDirs`. New
+  `collectExcludedDirs()` in `lib/path-filter.js`.
 
 ### Changed
 - **BREAKING:** the persisted-registry store moved from the Maven-only
@@ -40,6 +48,26 @@ This project adheres to [Semantic Versioning](https://semver.org/).
   the `<ecosystem>=<url>` form (a bare URL is rejected). Re-add any private Maven
   repos with `--add-repo maven <name> <url>`.
 
+### Fixed
+- **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
+  `node_modules` (or `target`/`dist`/…) nested anywhere under `--src` was scanned
+  whenever fad-checker ran from a different directory than the source tree. retire
+  is now driven by a generated `--ignorefile` anchored to `--src` that prunes the
+  default SKIP dirs **at any depth** and honors `--exclude-path` /
+  `--no-default-excludes`, matching `lib/path-filter.js`.
+- **Offline NVD enrichment (incl. CWEs) no longer silently dropped.** The NVD cache
+  enforces a 7-day TTL and a schema version; offline, a TTL-expired or older-schema
+  entry was treated as a miss — and since an air-gapped box can't re-fetch, the CVE
+  lost **all** its NVD enrichment (CWE list, CVSS vector, references, CPE configs).
+  That was the "offline scan was missing some CWE titles that the online scan had".
+  Offline now reads the warmed cache regardless of age/schema (a missing field just
+  stays missing — strictly better than dropping everything); online still enforces
+  TTL + schema so it re-fetches and upgrades. CWE IDs were already persisted in the
+  cache body (`_schema:2`) and travel in `--export-cache`; CWE *titles* come from the
+  bundled `data/cwe-names.json` (identical online/offline).
+
 ## [2.1.0]
 
 ### Added

package/README.md

@@ -2,7 +2,7 @@
 
 [![npm version](https://img.shields.io/npm/v/fad-checker.svg)](https://www.npmjs.com/package/fad-checker)
 [![npm downloads](https://img.shields.io/npm/dm/fad-checker.svg)](https://www.npmjs.com/package/fad-checker)
-[![license](https://img.shields.io/npm/l/fad-checker.svg)](https://github.com/n8tz/fad-checker/blob/main/package.json)
+[![license](https://img.shields.io/npm/l/fad-checker.svg)](https://github.com/9pings/fad-checker/blob/main/package.json)
 [![node](https://img.shields.io/node/v/fad-checker.svg)](https://nodejs.org)
 
 > **F**abulous **A**utonomous **D**ependency **C**hecker<br>
@@ -10,7 +10,10 @@
 
 `fad-checker` audits **Maven · Gradle · npm · Yarn · pnpm · Composer · PyPI · NuGet · Go · Ruby**, vendored JavaScript and committed native binaries in any source tree — multi-module, monorepo, polyglot — and produces a self-contained **HTML + Word report** (CVE prioritised by EPSS + CISA KEV, EOL, obsolete, outdated, licenses) plus **CycloneDX SBOM / CSAF VEX / SARIF / JSON** exports. **No build tools, no Docker, no network needed** — it reads lockfiles and manifests straight off disk.
 
-🌐 **[Project site & docs →](https://n8tz.github.io/fad-checker/)**
+🌐 **[Project site & docs →](https://9pings.github.io/fad-checker/)**
+
+> [!WARNING]
+> **Young project — expect rough edges.** fad-checker is new and under active development, so it may still contain bugs (including false positives and false negatives). Treat its output as a strong first pass, **double-check anything critical**, and please [report issues](https://github.com/9pings/fad-checker/issues) — they get fixed fast.
 
 <p align="center"><img src="docs/assets/demo.gif" alt="fad-checker animated terminal demo — a [n/N] checklist warming each vulnerability database, then CVE findings coloured by severity with KEV badges" height="600"></p>
 

package/fad-checker.js

@@ -495,7 +495,7 @@ async function timedPhase(label, fn) {
 		// (still honor an explicit --report-<type> if a user really wants a path-free one).
 		const anyReportRequested = [options.reportHtml, options.reportDoc, options.reportSbom, options.reportCsaf, options.reportJson, options.reportSarif].some(v => v !== undefined);
 		if (!anyReportRequested) options.report = false;
-		await runReportFlow(resolved, { activeIds, runMaven, runNpm, privateLibIds: [], mavenRepos, regMap, collectWarnings: [] });
+		await runReportFlow(resolved, { activeIds, runMaven, runNpm, privateLibIds: [], mavenRepos, regMap, collectWarnings: [], walkOpts });
 		return;
 	}
 
@@ -716,7 +716,7 @@ async function timedPhase(label, fn) {
 	// The scan always runs — it feeds the terminal summary, the file outputs and the
 	// CI gate. Which files get written is decided by the --report-* family inside
 	// (HTML + .doc by default; --no-report writes nothing).
-	await runReportFlow(resolved, { activeIds, runMaven, runGradle, runNpm, privateLibIds, mavenRepos, regMap, collectWarnings, mavenPropsByPom: mavenCtx?.propsByPom, mavenStore: mavenCtx?.store, gradlePlatformBoms: gradleCtx?.platformBoms || [], parsedManifests });
+	await runReportFlow(resolved, { activeIds, runMaven, runGradle, runNpm, privateLibIds, mavenRepos, regMap, collectWarnings, mavenPropsByPom: mavenCtx?.propsByPom, mavenStore: mavenCtx?.store, gradlePlatformBoms: gradleCtx?.platformBoms || [], parsedManifests, walkOpts });
 	if (!readOnly) {
 		ui.section("Next step");
 		ui.info(`run Snyk on the cleaned tree:`);
@@ -725,7 +725,8 @@ async function timedPhase(label, fn) {
 })();
 
 async function runReportFlow(resolved, ecoFlags = {}) {
-	const { activeIds = [], runMaven = true, runGradle = false, runNpm = false, privateLibIds = [], mavenRepos = [], regMap = {}, collectWarnings = [], mavenPropsByPom = null, mavenStore = null, gradlePlatformBoms = [], parsedManifests = [] } = ecoFlags;
+	const { activeIds = [], runMaven = true, runGradle = false, runNpm = false, privateLibIds = [], mavenRepos = [], regMap = {}, collectWarnings = [], mavenPropsByPom = null, mavenStore = null, gradlePlatformBoms = [], parsedManifests = [], walkOpts = {} } = ecoFlags;
+	const { excludePath = [], defaultExcludes = true } = walkOpts;
 	const registriesFor = eco => regMap[eco] || [];
 	const { expandWithTransitives } = require("./lib/cve-match");
 	const { writeReports, computeStats } = require("./lib/cve-report");
@@ -1045,7 +1046,7 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 		else if (!options.src) { st.skip("no source tree (descriptor import)"); }
 		else {
 			try {
-				const r = await sc.scan(resolved, { src: options.src, verbose, retireRefresh: !!options.retireRefresh, offline });
+				const r = await sc.scan(resolved, { src: options.src, verbose, retireRefresh: !!options.retireRefresh, offline, excludePath, defaultExcludes });
 				retireMatches = r.matches || [];
 				if (options.vendoredJsInventory !== false) vendoredJsInventory = r.meta?.inventory || [];
 				const invN = vendoredJsInventory.length;
@@ -1273,6 +1274,18 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 		: { html: resolveOut("html"), doc: resolveOut("doc"), sbom: resolveOut("sbom"), csaf: resolveOut("csaf"), json: resolveOut("json"), sarif: resolveOut("sarif") };
 	const ensureDir = async p => { if (p) await fs.promises.mkdir(path.dirname(path.resolve(p)), { recursive: true }); };
 
+	// Ignored-directories appendix: re-walk --src ONCE under the same prune policy the
+	// codec walkers use (the default-exclude union at any depth + --exclude-path,
+	// anchored to --src) so the report can list exactly which directories the scan
+	// skipped, and why. Only computed when an output that renders it is requested.
+	let excludedDirs = [];
+	if (options.src && (out.html || out.doc || out.json)) {
+		try {
+			const { collectExcludedDirs } = require("./lib/path-filter");
+			excludedDirs = collectExcludedDirs({ srcRoot: options.src, excludePath, defaultExcludes });
+		} catch { /* best effort — never block the report on the appendix walk */ }
+	}
+
 	const reportWarnings = [
 		...(suppressedCount ? [{
 			type: "suppressed",
@@ -1299,7 +1312,7 @@ async function runReportFlow(resolved, ecoFlags = {}) {
 		await ensureDir(out.html); await ensureDir(out.doc);
 		const { htmlPath, docPath } = await writeReports({
 			cveMatches: prodMatches, devCveMatches: devMatches, embeddedMatches, retireMatches, vendoredJsInventory,
-			eolResults, obsoleteResults, outdatedResults, licenseResults,
+			eolResults, obsoleteResults, outdatedResults, licenseResults, excludedDirs,
 			resolvedDeps: resolved, projectInfo, warnings: reportWarnings, parsedManifests,
 			htmlPath: out.html, docPath: out.doc,
 		});
@@ -1329,7 +1342,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, 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 }, out.json);
 			wrote.push(["Findings JSON", out.json]);
 		} catch (err) { ui.warn(`JSON export failed: ${err.message}`); }
 	}

package/lib/codecs/gradle.codec.js

@@ -129,7 +129,7 @@ module.exports = {
 			const lockGoverned = lockedDirs.has(d) && !inBuildSrc(fp);
 			if (lockGoverned) continue; // lockfile already provided resolved deps for this dir
 			for (const dep of r.deps) addRec(dep, fp);
-			if (!inBuildSrc(fp)) warnings.push({ type: "gradle-no-lockfile", manifestPath: fp, message: `no gradle.lockfile next to ${path.relative(dir, fp) || path.basename(fp)} — versions resolved best-effort from the build script + version catalog (dynamic/programmatic deps may be missed). Enable Gradle dependency locking for exact coverage.` });
+			if (!inBuildSrc(fp)) warnings.push({ type: "no-lockfile", manifestPath: fp, message: `no gradle.lockfile next to ${path.relative(dir, fp) || path.basename(fp)} — versions resolved best-effort from the build script + version catalog (dynamic/programmatic deps may be missed). Enable Gradle dependency locking for exact coverage.` });
 			for (const u of r.unresolved) warnings.push({ type: "unresolved-versions", manifestPath: fp, message: `could not resolve the version variable for ${u.group}:${u.name} (${u.raw}) — excluded from CVE matching` });
 		}
 

package/lib/codecs/npm.codec.js

@@ -21,7 +21,7 @@ const retireScanner = {
 	kind: "vendored",   // résultats → chapitre vendored-JS (séparé des CVE)
 	async scan(_deps, opts = {}) {
 		const { scanWithRetireFull } = require("../retire");
-		const { matches, inventory, error } = await scanWithRetireFull(opts.src, { verbose: opts.verbose, force: !!opts.retireRefresh, offline: !!opts.offline });
+		const { matches, inventory, error } = await scanWithRetireFull(opts.src, { verbose: opts.verbose, force: !!opts.retireRefresh, offline: !!opts.offline, excludePath: opts.excludePath, defaultExcludes: opts.defaultExcludes });
 		return { matches, meta: { inventory, error } };
 	},
 };

package/lib/cve-report.js

@@ -1188,7 +1188,7 @@ function minorSection(title, contentHtml, opts = {}) {
 }
 
 const WARNING_HEADINGS = {
-	"no-lockfile":            { icon: "⚠️", title: "JS manifest without lockfile" },
+	"no-lockfile":            { icon: "⚠️", title: "Manifest without a lockfile — best-effort (ranges skipped)" },
 	"yarn-berry-unsupported": { icon: "⚠️", title: "Yarn 2+/Berry lockfile" },
 	"unresolved-versions":    { icon: "⚠️", title: "Maven deps without a concrete version — silently skipped, run a real Maven/Snyk scan to complete" },
 	"private-libs":           { icon: "🔒", title: "Private / internal libraries — not on Maven Central, not scanned" },
@@ -1485,7 +1485,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 = [], wrapTables = true }) {
 	setRenderCtx({ srcRoot: projectInfo?.src || null });
 	// Dedupe rows so a single (dep, cve) shows once with all via paths merged.
 	cveMatches      = mergeMatches(cveMatches || []);
@@ -1567,6 +1567,7 @@ function buildBody({ cveMatches, devCveMatches, embeddedMatches, retireMatches,
 		unmanagedTotal: unmanagedInventory.length,
 		vendoredJsTotal: vendoredJsInv.length,
 		fpTotal: prodMatchesFP.length + devMatchesFP.length + embMatchesFP.length,
+		excludedTotal: excludedDirs?.length || 0,
 	});
 
 	// Overview charts row, rendered right under the compact totals.
@@ -1601,6 +1602,7 @@ function buildBody({ cveMatches, devCveMatches, embeddedMatches, retireMatches,
 		${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" }) : ""}
 	`;
 	return wrapTables ? wrapTablesWithCopyButtons(body) : body;
 }
@@ -1664,7 +1666,7 @@ function pickTopEol(eolResults, n) {
 	}).slice(0, n);
 }
 
-function renderToc({ hasWarnings, prodTotal, embeddedTotal, unmanagedTotal, vendoredJsTotal, retireTotal, devTotal, eolTotal, obsoleteTotal, outdatedTotal, licenseTotal, licenseFlagged, fpTotal, scannedTotal }) {
+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})` });
@@ -1680,6 +1682,7 @@ function renderToc({ hasWarnings, prodTotal, embeddedTotal, unmanagedTotal, vend
 	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>`;
 }
 
@@ -1759,6 +1762,20 @@ 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>`;
+}
+
 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 +2237,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 }) {
 	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 };
 	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 = [],
 	} = payload;
 
 	const { buildInventory } = require("./unmanaged");
@@ -105,6 +105,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 +117,7 @@ function buildFindings(payload = {}) {
 		embedded,
 		vendoredJs: vendoredJsInventory,
 		typosquat: typosquats,
+		excludedDirs,
 	};
 }
 

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/osv.js

@@ -121,18 +121,32 @@ function severityFromOsv(vuln) {
 
 function scoreFromVuln(vuln) { return cvssInfoFromVuln(vuln).score; }
 
-/** Extract the first fix version from OSV affected ranges (semver/ecosystem events). */
-function fixVersionFromOsv(vuln, depKey) {
+/**
+ * Pick the fix version to recommend from OSV's affected ranges. A multi-branch advisory
+ * (e.g. Tomcat fixed in 9.0.118, 10.1.55 AND 11.0.22) lists one `fixed` per branch — the
+ * old code returned the FIRST, which for an 11.0.21 dep meant "upgrade to 9.0.118", i.e. a
+ * DOWNGRADE. Instead pick the smallest fix strictly ABOVE the current version: that's the
+ * next patched release on the dep's own branch. If none is greater (the branch has no
+ * published fix, or the dep is already patched), return null rather than suggest a downgrade.
+ */
+function fixVersionFromOsv(vuln, depKey, depVersion) {
+	const { compareMavenVersions } = require("./maven-version");
+	const fixes = [];
 	for (const a of vuln.affected || []) {
 		const name = a.package?.name?.toLowerCase();
 		if (name && name !== depKey.toLowerCase()) continue;
 		for (const r of a.ranges || []) {
 			for (const ev of r.events || []) {
-				if (ev.fixed) return ev.fixed;
+				if (ev.fixed) fixes.push(String(ev.fixed));
 			}
 		}
 	}
-	return null;
+	if (!fixes.length) return null;
+	const cmp = (x, y) => { try { return compareMavenVersions(x, y); } catch { return String(x).localeCompare(String(y)); } };
+	const sorted = [...fixes].sort(cmp);
+	if (!depVersion) return sorted[0]; // no current version to compare against → lowest published fix
+	const upgrades = sorted.filter(f => cmp(f, depVersion) > 0);
+	return upgrades.length ? upgrades[0] : null;
 }
 
 /** Pick the best CVE id from an OSV vuln (prefer CVE-* aliases over GHSA-*). */
@@ -188,7 +202,7 @@ function vulnToMatch(dep, vuln) {
 			...(cvss.version ? { cvssVersion: `CVSS:${cvss.version}` } : {}),
 			description,
 			summary,
-			fixVersion: fixVersionFromOsv(vuln, osvPkgName(dep)),
+			fixVersion: fixVersionFromOsv(vuln, osvPkgName(dep), dep.version),
 			ghsa: (vuln.aliases || []).find(a => a.startsWith("GHSA-")) || (vuln.id?.startsWith("GHSA-") ? vuln.id : null),
 			published: vuln.published || null,
 			modified: vuln.modified || null,

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 };

package/lib/retire.js

@@ -142,9 +142,58 @@ async function ensureSignatures({ verbose, offline } = {}) {
 	return !!r.ok;
 }
 
-// Pure: build the retire CLI argv. `jsRepo` (a local signature file) is added
-// when available so retire loads signatures from disk instead of the network.
-function buildRetireArgs({ srcDir, outPath, ignoredDirs, jsRepo }) {
+// Directories retire never needs to walk. Mirrors the per-walker default SKIP sets
+// the codecs use (lib/path-filter.js / npm parse.js): package stores, build output,
+// IDE/VCS metadata. Matched by BASENAME at any depth (see buildRetireIgnorePatterns).
+const DEFAULT_RETIRE_SKIP_DIRS = [
+	"node_modules", "bower_components", "jspm_packages",
+	".git", ".idea", ".vscode", ".gradle", ".mvn",
+	"target", "dist", "build", "build-output", "out", "coverage", ".next", ".nuxt",
+];
+
+/**
+ * Build the lines for a retire ignorefile, mirroring the rest of the scan's
+ * exclude policy (lib/path-filter.js#makeDirFilter) so retire skips the SAME dirs
+ * every codec walker prunes.
+ *
+ * Why an ignorefile and not `--ignore`: retire `path.resolve()`s every `--ignore`
+ * entry against ITS OWN cwd (cli.js), so a bare "node_modules" becomes
+ * `<cwd>/node_modules` and silently misses `<srcDir>/…/node_modules` whenever fad
+ * runs from a different directory than `-s` — and it can never express "this dir
+ * at ANY depth". An ignorefile line prefixed with `@` is kept VERBATIM (no resolve)
+ * and used as a substring regex, which is the only retire mechanism that can.
+ *
+ * Two layers, exactly like makeDirFilter:
+ *   - default skip dirs → `@/<name>/` : segment-bounded substring → matches the dir
+ *     at ANY depth (the bug: a deeply-nested node_modules), and the surrounding
+ *     slashes keep lookalike files (`node_modules_shim.js`) from being clipped.
+ *     Dropped entirely when defaultExcludes === false (--no-default-excludes).
+ *   - user --exclude-path globs → `@<absSrcDir>/<glob>/` : ANCHORED to the scan
+ *     root (not any-depth), retire expands `*`→[^/]* and `**`→.* itself.
+ *
+ * retire walks with POSIX-style paths (its own matchers use `/`), so we emit `/`.
+ */
+function buildRetireIgnorePatterns({ srcDir, excludePath = [], defaultExcludes = true } = {}) {
+	const lines = [];
+	if (defaultExcludes !== false) {
+		for (const d of DEFAULT_RETIRE_SKIP_DIRS) lines.push(`@/${d}/`);
+	}
+	const root = srcDir ? path.resolve(srcDir).split(path.sep).join("/").replace(/\/+$/, "") : "";
+	for (const g of excludePath || []) {
+		// Normalise like compileGlobs: strip a leading ./ or /, a trailing /, and a
+		// trailing /** (the dir's whole subtree is already covered by the segment).
+		const base = String(g || "").trim().replace(/^\.?\/+/, "").replace(/\/+$/, "").replace(/\/\*\*$/, "");
+		if (!base) continue;
+		lines.push(root ? `@${root}/${base}/` : `@/${base}/`);
+	}
+	return lines;
+}
+
+// Pure: build the retire CLI argv. `ignoreFile` (a path-anchored ignorefile, see
+// buildRetireIgnorePatterns) is passed when there's anything to exclude. `jsRepo`
+// (a local signature file) is added when available so retire loads signatures from
+// disk instead of the network.
+function buildRetireArgs({ srcDir, outPath, ignoreFile, jsRepo }) {
 	const args = [
 		// --verbose makes retire list EVERY identified library, not just the
 		// vulnerable ones (its own wording: "by default only vulnerable files are
@@ -154,8 +203,8 @@ function buildRetireArgs({ srcDir, outPath, ignoredDirs, jsRepo }) {
 		"--outputformat", "json",
 		"--outputpath", outPath,
 		"--jspath", srcDir,
-		"--ignore", ignoredDirs,
 	];
+	if (ignoreFile) { args.push("--ignorefile", ignoreFile); }
 	if (jsRepo) { args.push("--jsrepo", jsRepo); }
 	return args;
 }
@@ -222,11 +271,13 @@ function extractVendoredInventory(raw, srcDir) {
  * Run retire.js against `srcDir`. Returns the parsed JSON output (an array
  * of file-level findings) or null if retire is unavailable.
  *
- * `--outputformat json` is the structured form; `--ignore` takes a list of
- * dirs to skip; we add the standard suspects to keep runtime bounded.
+ * `--outputformat json` is the structured form; a generated `--ignorefile`
+ * prunes the same dirs the rest of the scan skips (default SKIP set at any depth
+ * + the user's --exclude-path globs, anchored to the scan root) so retire never
+ * walks node_modules/target/… or anything the auditor excluded.
  */
 async function runRetire(srcDir, opts = {}) {
-	const { verbose, force, offline } = opts;
+	const { verbose, force, offline, excludePath, defaultExcludes } = opts;
 	// Optional diagnostics collector: callers (scanWithRetireFull) read diag.error to
 	// surface a genuine SCAN FAILURE (retire crashed / produced no parseable output)
 	// as a report warning — instead of letting it masquerade as "no vendored JS found".
@@ -252,16 +303,25 @@ async function runRetire(srcDir, opts = {}) {
 	}
 
 	const launcher = findRetireLauncher();
-	const ignoredDirs = [
-		"node_modules", "bower_components", "jspm_packages",
-		".git", ".idea", ".vscode", ".gradle", ".mvn",
-		"target", "dist", "build", "build-output", "out", "coverage", ".next", ".nuxt",
-	].join(",");
 
 	// retire.js refuses to write to /dev/stdout, so we use a real temp file
 	// and read it back. Falls back to stdout if --outputpath is rejected.
 	const tmpOut = path.join(os.tmpdir(), `fad-checker-retire-${process.pid}-${Date.now()}.json`);
-	const args = buildRetireArgs({ srcDir, outPath: tmpOut, ignoredDirs, jsRepo: haveSig ? RETIRE_SIG_FILE : null });
+
+	// Pruning policy, written to a temp ignorefile so retire honors it for the tree
+	// it ACTUALLY walks (anchored to srcDir, not retire's cwd — the nested
+	// node_modules bug) and respects the same --exclude-path the codecs do.
+	const ignorePatterns = buildRetireIgnorePatterns({ srcDir, excludePath, defaultExcludes });
+	// retire treats a `.json` ignorefile as the structured descriptor form; keep a
+	// plain-text extension so the `@`-prefixed regex lines are read as such.
+	const tmpIgnore = ignorePatterns.length ? path.join(os.tmpdir(), `fad-checker-retire-ignore-${process.pid}-${Date.now()}.txt`) : null;
+	if (tmpIgnore) fs.writeFileSync(tmpIgnore, ignorePatterns.join("\n") + "\n");
+	const cleanup = () => {
+		try { fs.unlinkSync(tmpOut); } catch { /* best effort */ }
+		if (tmpIgnore) { try { fs.unlinkSync(tmpIgnore); } catch { /* best effort */ } }
+	};
+
+	const args = buildRetireArgs({ srcDir, outPath: tmpOut, ignoreFile: tmpIgnore, jsRepo: haveSig ? RETIRE_SIG_FILE : null });
 	if (verbose) console.log(`retire: scanning ${srcDir}…${haveSig ? " (local signatures)" : ""}`);
 
 	let execErr = null;
@@ -284,7 +344,7 @@ async function runRetire(srcDir, opts = {}) {
 			const reason = retireFailureReason(err.stderr, err.message);
 			diag.error = `retire.js scan failed: ${reason}`;
 			if (verbose) console.warn(`retire: failed to run — ${reason}`);
-			try { fs.unlinkSync(tmpOut); } catch { /* best effort */ }
+			cleanup();
 			return null;
 		}
 	}
@@ -299,7 +359,7 @@ async function runRetire(srcDir, opts = {}) {
 		if (verbose) console.warn(`retire: could not parse output — ${err.message}`);
 		return null;
 	} finally {
-		try { fs.unlinkSync(tmpOut); } catch { /* best effort */ }
+		cleanup();
 	}
 	writeCache(srcDir, parsed);
 	return parsed;
@@ -417,6 +477,8 @@ module.exports = {
 	warmRetireSignatures,
 	ensureSignatures,
 	buildRetireArgs,
+	buildRetireIgnorePatterns,
+	DEFAULT_RETIRE_SKIP_DIRS,
 	retireFailureReason,
 	readCache,
 	writeCache,

package/lib/sarif-export.js

@@ -116,7 +116,7 @@ function buildSarif(matches, opts = {}) {
 				driver: {
 					name: "fad-checker",
 					version: String(toolVersion),
-					informationUri: "https://github.com/n8tz/fad-checker",
+					informationUri: "https://github.com/9pings/fad-checker",
 					rules: [...rulesById.values()],
 				},
 			},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fad-checker",
-  "version": "2.3.0",
+  "version": "2.3.2",
   "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",
@@ -45,9 +45,9 @@
     "cli"
   ],
   "license": "MIT",
-  "repository": "https://github.com/n8tz/fad-checker",
-  "homepage": "https://github.com/n8tz/fad-checker#readme",
-  "bugs": "https://github.com/n8tz/fad-checker/issues",
+  "repository": "https://github.com/9pings/fad-checker",
+  "homepage": "https://github.com/9pings/fad-checker#readme",
+  "bugs": "https://github.com/9pings/fad-checker/issues",
   "author": "pp9Ping <pp9Ping@gmail.com>",
   "maintainers": [
     "pp9Ping <pp9Ping@gmail.com>"