fad-checker 2.0.0 → 2.1.0

package/lib/nvd.js

@@ -10,6 +10,9 @@
  * Rate limit: 5 req / 30s unauthenticated, 50 req / 30s with NVD_API_KEY env var.
  *
  * Cache: ~/.fad-checker/nvd-cache/<cve-id>.json, 7-day TTL.
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
  */
 const fs = require("fs");
 const path = require("path");
@@ -62,11 +65,15 @@ function writeCache(cveId, body) {
 function bestMetric(metrics) {
 	// NVD 2.0 returns metrics organised by version: cvssMetricV40, V31, V30, V2
 	const order = ["cvssMetricV40", "cvssMetricV31", "cvssMetricV30", "cvssMetricV2"];
+	// Proper CVSS version label — NOT "cvssMetricV31".replace(...) which yielded the
+	// malformed "CVSS:V31" that downstream consumers (csaf cvssV3Version, sbom
+	// cvssMethod, the report) test with .includes("3.1") and so always missed.
+	const VER = { cvssMetricV40: "CVSS:4.0", cvssMetricV31: "CVSS:3.1", cvssMetricV30: "CVSS:3.0", cvssMetricV2: "CVSS:2.0" };
 	for (const k of order) {
 		if (Array.isArray(metrics?.[k]) && metrics[k].length) {
 			const cv = metrics[k][0].cvssData;
 			return {
-				version: k.replace("cvssMetric", "CVSS:"),
+				version: VER[k],
 				score: cv.baseScore,
 				severity: (cv.baseSeverity || severityFromScore(cv.baseScore) || "UNKNOWN").toUpperCase(),
 				vector: cv.vectorString,
@@ -191,7 +198,7 @@ async function fetchOne(cveId, opts = {}) {
  * Rate limited per the NIST policy (use NVD_API_KEY for faster access).
  */
 async function enrichMatches(matches, opts = {}) {
-	const { offline } = opts;
+	const { offline, onProgress } = opts;
 	const uniqueCves = new Set();
 	for (const m of matches) if (m.cve?.id?.startsWith("CVE-")) uniqueCves.add(m.cve.id);
 	const hasKey = !!getNvdApiKey();
@@ -212,13 +219,13 @@ async function enrichMatches(matches, opts = {}) {
 		liveIds.push(cveId);
 	}
 
-	if (liveIds.length) {
+	if (liveIds.length && !onProgress) {
 		const etaSec = Math.ceil((liveIds.length / burst) * (NVD_WINDOW_MS / 1000));
 		const keyHint = hasKey ? "with API key (50/30s)" : "no API key — throttled to 5/30s, run `fad-checker --set-nvd-key <KEY>` (free, instant) to be 10× faster";
 		const cachedCount = byId.size;
 		const cachedHint = cachedCount ? `, ${cachedCount} cached` : "";
 		console.log(`🔍 NVD: enriching ${liveIds.length} CVEs${cachedHint} — ${keyHint}. ETA ~${etaSec}s.`);
-	} else if (uniqueCves.size) {
+	} else if (uniqueCves.size && !onProgress) {
 		console.log(`🔍 NVD: ${uniqueCves.size} CVEs (all cached).`);
 	}
 
@@ -229,6 +236,7 @@ async function enrichMatches(matches, opts = {}) {
 	const startedAt = [];
 	const startProgress = Date.now();
 	const printProgress = (final = false) => {
+		if (onProgress) { onProgress(done, liveIds.length); return; }
 		const elapsed = Math.round((Date.now() - startProgress) / 1000);
 		const pct = liveIds.length ? Math.round((done / liveIds.length) * 100) : 100;
 		const line = `   NVD: ${done}/${liveIds.length} (${pct}%) — ${elapsed}s elapsed`;
@@ -265,8 +273,11 @@ async function enrichMatches(matches, opts = {}) {
 		}
 		if (m.cve.severity === "UNKNOWN" || !m.cve.severity) m.cve.severity = data.severity;
 		if (m.cve.score == null) m.cve.score = data.score;
-		m.cve.cvssVector = data.cvssVector || null;
-		m.cve.cvssVersion = data.cvssVersion || null;
+		// Only overwrite the vector/version when NVD actually has one — an NVD record
+		// without CVSS metrics must not clobber an OSV-derived vector/version (which is
+		// what feeds CSAF cvssV3Version + SBOM cvssMethod).
+		if (data.cvssVector) m.cve.cvssVector = data.cvssVector;
+		if (data.cvssVersion) m.cve.cvssVersion = data.cvssVersion;
 		m.cve.nvdRefs = data.references || [];   // [{url, tags, source}]
 		m.cve.cpes = data.cpes || [];
 		m.cve.cwes = data.cwes || [];

package/lib/osv.js

@@ -12,6 +12,9 @@
  *   GET  /v1/vulns/{id}  to fetch full details
  *
  * Cached responses live in ~/.fad-checker/osv-cache/ for 12h.
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
  */
 const fs = require("fs");
 const path = require("path");
@@ -50,31 +53,74 @@ function normalizeSeverity(s) {
 	return SEVERITY_ALIASES[up] || up;
 }
 
-/** Map an OSV severity score string ("9.8", "CVSS:3.1/AV:N/.../I:H/A:H") to a level. */
-function severityFromOsv(vuln) {
-	// Severity may live in `severity[]` (CVSS vector strings) or
-	// `database_specific.severity` (GHSA-style: "CRITICAL", "HIGH", "MODERATE"...).
-	const direct = vuln.database_specific?.severity;
-	if (direct) return { severity: normalizeSeverity(direct), score: scoreFromVuln(vuln) };
-	const sev = vuln.severity?.[0]?.score || "";
-	const numeric = parseFloat(sev.match(/(\d+(\.\d+)?)/)?.[1]);
-	if (Number.isFinite(numeric)) {
-		if (numeric >= 9) return { severity: "CRITICAL", score: numeric };
-		if (numeric >= 7) return { severity: "HIGH", score: numeric };
-		if (numeric >= 4) return { severity: "MEDIUM", score: numeric };
-		if (numeric > 0) return { severity: "LOW", score: numeric };
+function severityFromScore(n) {
+	if (!Number.isFinite(n)) return "UNKNOWN";
+	if (n >= 9) return "CRITICAL";
+	if (n >= 7) return "HIGH";
+	if (n >= 4) return "MEDIUM";
+	if (n > 0) return "LOW";
+	return "NONE";
+}
+
+// Compute a CVSS v3.0/3.1 base score from its vector string. Returns null for
+// non-v3 vectors (v2/v4) or anything unparseable. OSV stores the *vector* in
+// `severity[].score` for CVSS_V3 — there is NO bare base number to read, so the
+// old "first number in the string" approach extracted the VERSION ("3.1") as the
+// score, mislabelling HIGH findings as ~low everywhere downstream (SARIF
+// security-severity, priority banding, SBOM/CSAF ratings).
+function cvss3BaseScore(vector) {
+	const v = String(vector || "");
+	if (!/^CVSS:3\.[01]\//.test(v)) return null;
+	const p = {};
+	for (const kv of v.split("/").slice(1)) {
+		const [k, val] = kv.split(":");
+		if (k && val) p[k] = val;
 	}
-	return { severity: "UNKNOWN", score: null };
+	const AV = { N: 0.85, A: 0.62, L: 0.55, P: 0.2 }[p.AV];
+	const AC = { L: 0.77, H: 0.44 }[p.AC];
+	const UI = { N: 0.85, R: 0.62 }[p.UI];
+	const scopeChanged = p.S === "C";
+	const PR = scopeChanged
+		? { N: 0.85, L: 0.68, H: 0.5 }[p.PR]
+		: { N: 0.85, L: 0.62, H: 0.27 }[p.PR];
+	const imp = { H: 0.56, L: 0.22, N: 0 };
+	const C = imp[p.C], I = imp[p.I], A = imp[p.A];
+	if ([AV, AC, UI, PR, C, I, A].some(x => x == null)) return null;
+	const iss = 1 - (1 - C) * (1 - I) * (1 - A);
+	const impact = scopeChanged ? 7.52 * (iss - 0.029) - 3.25 * Math.pow(iss - 0.02, 15) : 6.42 * iss;
+	if (impact <= 0) return 0;
+	const exploit = 8.22 * AV * AC * PR * UI;
+	const base = Math.min(scopeChanged ? 1.08 * (impact + exploit) : impact + exploit, 10);
+	return Math.ceil(base * 10) / 10; // CVSS roundup to one decimal
 }
 
-function scoreFromVuln(vuln) {
+/** Best CVSS info from an OSV vuln: { score, vector, version } (version like "3.1"). */
+function cvssInfoFromVuln(vuln) {
 	for (const s of vuln.severity || []) {
-		const m = String(s.score || "").match(/(\d+(\.\d+)?)/);
-		if (m) return parseFloat(m[1]);
+		const str = String(s.score || "");
+		const mver = str.match(/^CVSS:(\d\.\d)\//);
+		if (mver) {
+			const version = mver[1];
+			const score = (version === "3.0" || version === "3.1") ? cvss3BaseScore(str) : null;
+			return { score, vector: str, version };
+		}
+		const mnum = str.match(/^\s*(\d+(\.\d+)?)\s*$/); // a bare numeric score ("9.8")
+		if (mnum) return { score: parseFloat(mnum[1]), vector: null, version: null };
 	}
-	return null;
+	return { score: null, vector: null, version: null };
 }
 
+/** Map an OSV vuln to { severity, score }. */
+function severityFromOsv(vuln) {
+	const direct = vuln.database_specific?.severity;
+	const { score } = cvssInfoFromVuln(vuln);
+	if (direct) return { severity: normalizeSeverity(direct), score };
+	if (score != null) return { severity: severityFromScore(score), score };
+	return { severity: "UNKNOWN", score: null };
+}
+
+function scoreFromVuln(vuln) { return cvssInfoFromVuln(vuln).score; }
+
 /** Extract the first fix version from OSV affected ranges (semver/ecosystem events). */
 function fixVersionFromOsv(vuln, depKey) {
 	for (const a of vuln.affected || []) {
@@ -97,7 +143,7 @@ function pickPrimaryId(vuln) {
 }
 
 // OSV ecosystem name per codec id. OSV.dev natively supports all of these.
-const OSV_ECO = { maven: "Maven", npm: "npm", yarn: "npm", nuget: "NuGet", composer: "Packagist", pypi: "PyPI" };
+const OSV_ECO = { maven: "Maven", npm: "npm", yarn: "npm", nuget: "NuGet", composer: "Packagist", pypi: "PyPI", go: "Go", ruby: "RubyGems" };
 
 /** OSV ecosystem string for a dep, derived from its codec id. */
 function osvEcosystemFor(dep) { return OSV_ECO[dep.ecosystem] || "Maven"; }
@@ -115,6 +161,7 @@ function osvPkgName(dep) {
 function vulnToMatch(dep, vuln) {
 	const id = pickPrimaryId(vuln);
 	const { severity, score } = severityFromOsv(vuln);
+	const cvss = cvssInfoFromVuln(vuln);
 	// `details` (long markdown) is the substantive description; `summary` is just the title.
 	// We keep them both: summary as headline, details as body.
 	const summary = (vuln.summary || "").trim();
@@ -137,6 +184,8 @@ function vulnToMatch(dep, vuln) {
 			id,
 			severity,
 			score,
+			...(cvss.vector ? { cvssVector: cvss.vector } : {}),
+			...(cvss.version ? { cvssVersion: `CVSS:${cvss.version}` } : {}),
 			description,
 			summary,
 			fixVersion: fixVersionFromOsv(vuln, osvPkgName(dep)),
@@ -152,7 +201,7 @@ function vulnToMatch(dep, vuln) {
 }
 
 async function queryBatch(deps, opts = {}) {
-	const { verbose, offline, fetcher = globalThis.fetch } = opts;
+	const { verbose, offline, fetcher = globalThis.fetch, onProgress } = opts;
 	// Build query list + parallel cached/uncached split
 	const queries = [];
 	const indexMap = []; // index in `deps` → either { cached: vulns } or { queryIdx: N }
@@ -187,7 +236,8 @@ async function queryBatch(deps, opts = {}) {
 		let batchIdx = 0;
 		for (const batch of batches) {
 			batchIdx++;
-			if (process.stdout.isTTY) process.stdout.write(`\r   OSV batch ${batchIdx}/${batches.length} (${batch.length} deps)…                  `);
+			if (onProgress) onProgress(batchIdx, batches.length);
+			else if (process.stdout.isTTY) process.stdout.write(`\r   OSV batch ${batchIdx}/${batches.length} (${batch.length} deps)…                  `);
 			else if (batches.length > 1) console.log(`   OSV batch ${batchIdx}/${batches.length} (${batch.length} deps)…`);
 			const res = await fetcher(`${OSV_BASE}/v1/querybatch`, {
 				method: "POST",
@@ -205,7 +255,8 @@ async function queryBatch(deps, opts = {}) {
 				allResults[(batchIdx - 1) * BATCH_SIZE + j] = results[j] || { vulns: [] };
 			}
 		}
-		if (process.stdout.isTTY) process.stdout.write(`\r   OSV batches complete (${batches.length})                          \n`);
+		if (onProgress) { /* finalized by caller */ }
+		else if (process.stdout.isTTY) process.stdout.write(`\r   OSV batches complete (${batches.length})                          \n`);
 
 		// Persist per-dep cache (stub list — details cached separately)
 		for (let i = 0; i < deps.length; i++) {
@@ -239,12 +290,13 @@ async function queryBatch(deps, opts = {}) {
 	}
 
 	if (liveIds.length) {
-		console.log(`   OSV details: ${liveIds.length} to fetch${allIds.size - liveIds.length ? `, ${allIds.size - liveIds.length} cached` : ""}…`);
+		if (!onProgress) console.log(`   OSV details: ${liveIds.length} to fetch${allIds.size - liveIds.length ? `, ${allIds.size - liveIds.length} cached` : ""}…`);
 		const concurrency = 10;
 		let cursor = 0;
 		let fetched = 0;
 		const startedAt = Date.now();
 		const printOsvProgress = (final = false) => {
+			if (onProgress) { onProgress(fetched, liveIds.length); return; }
 			const elapsed = Math.round((Date.now() - startedAt) / 1000);
 			const pct = Math.round((fetched / liveIds.length) * 100);
 			const line = `   OSV details: ${fetched}/${liveIds.length} (${pct}%) — ${elapsed}s`;

package/lib/outdated.js

@@ -4,6 +4,9 @@
  * EOL data comes from endoflife.date (with on-disk cache).
  * Obsolete data is curated locally (data/known-obsolete.json).
  * Outdated comes from Maven Central's maven-metadata.xml.
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
  */
 const fs = require("fs");
 const path = require("path");
@@ -251,7 +254,7 @@ function parseMavenMetadataLatest(xml) {
 }
 
 async function checkOutdatedDeps(resolvedDeps, opts = {}) {
-	const { verbose, offline, concurrency = 8, repos } = opts;
+	const { verbose, offline, concurrency = 8, repos, onProgress } = opts;
 	const cache = loadJsonCache(VERSION_CACHE_PATH);
 	const fresh = cache.meta?.fetchedAt && (Date.now() - cache.meta.fetchedAt) < VERSION_CACHE_MAX_AGE_MS;
 	if (!fresh && !offline) cache.entries = {};
@@ -263,7 +266,7 @@ async function checkOutdatedDeps(resolvedDeps, opts = {}) {
 	// seconds with 8-way concurrency, but on first run (cold cache) the user
 	// would see total silence for 20-60s.
 	const liveCount = offline ? 0 : list.filter(d => !cache.entries[`${d.groupId}:${d.artifactId}`]).length;
-	if (liveCount && !offline) {
+	if (liveCount && !offline && !onProgress) {
 		console.log(`📅 Outdated: checking ${list.length} deps against Maven Central (${liveCount} live, ${list.length - liveCount} cached)…`);
 	}
 
@@ -271,6 +274,7 @@ async function checkOutdatedDeps(resolvedDeps, opts = {}) {
 	let processed = 0;
 	const startedAt = Date.now();
 	const printOutdatedProgress = (final = false) => {
+		if (onProgress) { onProgress(processed, list.length); return; }
 		if (!liveCount) return;
 		const elapsed = Math.round((Date.now() - startedAt) / 1000);
 		const pct = Math.round((processed / list.length) * 100);
@@ -308,6 +312,10 @@ module.exports = {
 	checkObsolete,
 	checkOutdatedDeps,
 	findEolProduct,
+	findCycleForVersion,
+	isEol,
 	isEolCacheFresh,
+	EOL_MAPPING,
+	EOL_CACHE_PATH,
 	KNOWN_OBSOLETE,
 };

package/lib/priority.js

@@ -0,0 +1,90 @@
+/**
+ * lib/priority.js — composite prioritisation of a CVE match.
+ *
+ * Blends three independent signals the report already carries:
+ *   - CVSS base score (severity of the flaw if exploited)
+ *   - EPSS percentile (likelihood it WILL be exploited — lib/epss.js)
+ *   - CISA KEV membership (it IS being exploited in the wild — lib/kev.js)
+ *
+ * KEV always wins (band "exploited", score floored at 90). Otherwise the score
+ * is an 80/20 blend of CVSS and EPSS percentile. Pure — no I/O.
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
+ */
+
+const SEV_SCORE = { CRITICAL: 9.5, HIGH: 7.5, MEDIUM: 5, LOW: 2, NONE: 0, UNKNOWN: 0 };
+
+function severityToScore(sev) {
+	return SEV_SCORE[(sev || "UNKNOWN").toUpperCase()] ?? 0;
+}
+
+function clamp(n, lo, hi) {
+	return Math.max(lo, Math.min(hi, n));
+}
+
+/**
+ * Compute a priority object for a cve sub-record.
+ * Returns { score (0-100), band, cvss, epssPercentile, kev, sortKey }.
+ */
+function computePriority(cve = {}) {
+	// A literal 0 is treated as "no CVSS" and we fall back to the severity label:
+	// enrichers emit null for scoreless CVEs, so a 0 here is a placeholder, and a
+	// CRITICAL-labelled finding must not band as "low" just because score===0.
+	const cvss = (typeof cve.score === "number" && cve.score > 0) ? cve.score : severityToScore(cve.severity);
+	const epssKnown = typeof cve.epssPercentile === "number";
+	const epssPercentile = epssKnown ? clamp(cve.epssPercentile, 0, 1) : 0;
+	const kev = !!cve.kev;
+
+	// When EPSS is known, blend 80% CVSS + 20% exploit-likelihood (so a known-low
+	// EPSS slightly deprioritises a high-CVSS flaw). When EPSS is absent we don't
+	// dilute — a CVSS 9.8 with no EPSS data must still read as critical.
+	let score = epssKnown
+		? clamp(cvss * 10 * 0.8 + epssPercentile * 100 * 0.2, 0, 100)
+		: clamp(cvss * 10, 0, 100);
+	let band;
+	if (kev) {
+		score = Math.max(score, 90);
+		band = "exploited";
+	} else if (score >= 90) band = "critical";
+	else if (score >= 70) band = "high";
+	else if (score >= 40) band = "medium";
+	else band = "low";
+
+	const rounded = Math.round(score * 10) / 10;
+	return {
+		score: rounded,
+		band,
+		cvss,
+		epssPercentile,
+		kev,
+		// Descending-sort tuple, aligned with the displayed score: exploited
+		// first, then the blended score (which already folds in CVSS + EPSS).
+		sortKey: [kev ? 1 : 0, rounded],
+	};
+}
+
+/** Attach m.cve.priority to every match in place. */
+function attachPriority(matches) {
+	for (const m of matches || []) {
+		if (m && m.cve) m.cve.priority = computePriority(m.cve);
+	}
+	return matches;
+}
+
+/** Compare two matches descending by priority sortKey, then CVE id ascending. */
+function comparePriority(a, b) {
+	const pa = a.cve?.priority || computePriority(a.cve);
+	const pb = b.cve?.priority || computePriority(b.cve);
+	for (let i = 0; i < pa.sortKey.length; i++) {
+		if (pb.sortKey[i] !== pa.sortKey[i]) return pb.sortKey[i] - pa.sortKey[i];
+	}
+	return (a.cve?.id || "").localeCompare(b.cve?.id || "");
+}
+
+/** Return a new array sorted descending by priority. */
+function sortByPriority(matches) {
+	return [...(matches || [])].sort(comparePriority);
+}
+
+module.exports = { computePriority, attachPriority, comparePriority, sortByPriority, severityToScore };

package/lib/purl.js

@@ -0,0 +1,77 @@
+/**
+ * lib/purl.js — build Package URL (purl) strings from a depRecord.
+ *
+ * purl spec: pkg:<type>/<namespace>/<name>@<version>?qualifiers#subpath
+ * We only emit type/namespace/name@version — enough for CycloneDX `bom-ref`
+ * and CSAF `product_identification_helper.purl`.
+ *
+ * Pure (no I/O). Shared by lib/sbom-export.js and lib/csaf-export.js.
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
+ */
+
+// purl type per ecosystem. Maven keeps the dotted groupId as a single namespace
+// segment (not slash-separated); npm/composer carry a namespace; pypi/nuget don't.
+const TYPE = {
+	maven: "maven",
+	npm: "npm",
+	composer: "composer",
+	pypi: "pypi",
+	nuget: "nuget",
+	go: "golang",
+	ruby: "gem",
+};
+
+// Per the purl spec, each namespace segment and the name are percent-encoded,
+// but the dots inside a Maven groupId and the separators are preserved by
+// encodeURIComponent (it leaves "." "-" "_" "~" alone), so it is the right tool.
+function enc(s) {
+	return encodeURIComponent(String(s));
+}
+
+// PEP 503 normalisation for PyPI names (purl mandates the canonical form).
+function normalizePypi(name) {
+	return String(name).toLowerCase().replace(/[-_.]+/g, "-");
+}
+
+/**
+ * Build a purl for a depRecord. Returns null when the dep lacks a usable
+ * ecosystem/name. Version is omitted when absent.
+ */
+function purlFor(dep) {
+	if (!dep || typeof dep !== "object") return null;
+	const eco = dep.ecosystem || dep.ecosystemType;
+	const type = TYPE[eco];
+	if (!type) return null;
+
+	const rawName = dep.name || dep.artifactId;
+	if (!rawName) return null;
+	let namespace = dep.namespace || dep.groupId || "";
+	let name = rawName;
+
+	if (eco === "npm" && !namespace && name.startsWith("@") && name.includes("/")) {
+		// Scoped package: "@scope/pkg" → namespace "@scope", name "pkg".
+		const slash = name.indexOf("/");
+		namespace = name.slice(0, slash);
+		name = name.slice(slash + 1);
+	} else if (eco === "pypi") {
+		name = normalizePypi(name);
+		namespace = "";
+	} else if (eco === "nuget") {
+		namespace = "";
+	} else if (eco === "go" && !namespace && name.includes("/")) {
+		// Go module path: namespace = everything up to the last "/", name = last segment.
+		const slash = name.lastIndexOf("/");
+		namespace = name.slice(0, slash);
+		name = name.slice(slash + 1);
+	}
+
+	// Namespace may itself be slash-separated (Go module paths); encode each
+	// segment but keep the separators.
+	const nsPart = namespace ? `${String(namespace).split("/").map(enc).join("/")}/` : "";
+	const verPart = dep.version ? `@${enc(dep.version)}` : "";
+	return `pkg:${type}/${nsPart}${enc(name)}${verPart}`;
+}
+
+module.exports = { purlFor };

package/lib/retire.js

@@ -12,6 +12,9 @@
  * The CLI is expected at node_modules/.bin/retire (declared in
  * package.json deps). When bundled with bun, we also try `retire`
  * on PATH as a fallback.
+ *
+ * @author: N.BRAUN
+ * @email: pp9ping@gmail.com
  */
 const fs = require("fs");
 const path = require("path");
@@ -24,6 +27,15 @@ const execFileP = promisify(execFile);
 const RETIRE_CACHE_DIR = path.join(os.homedir(), ".fad-checker", "retire-cache");
 const RETIRE_CACHE_TTL_MS = 24 * 3600 * 1000;
 
+// retire's own signature DB. By default retire caches it in /tmp/.retire-cache
+// (outside ~/.fad-checker/, with a 1h TTL → a network refetch on expiry). For the
+// PASSI offline workflow we instead keep a stable local copy INSIDE ~/.fad-checker/
+// so `--export-cache` carries it, and feed it to retire via `--jsrepo <file>`
+// (loaded from file, never the network — no TTL).
+const RETIRE_SIG_DIR = path.join(os.homedir(), ".fad-checker", "retire-signatures");
+const RETIRE_SIG_FILE = path.join(RETIRE_SIG_DIR, "jsrepository-v5.json");
+const RETIRE_REPO_URL = "https://raw.githubusercontent.com/RetireJS/retire.js/master/repository/jsrepository-v5.json";
+
 function cacheKey(srcDir) {
 	return crypto.createHash("md5").update(path.resolve(srcDir)).digest("hex") + ".json";
 }
@@ -50,6 +62,54 @@ function findRetireBin() {
 	return "retire"; // fall back to PATH
 }
 
+/**
+ * Fetch retire's signature DB to a stable file inside ~/.fad-checker/ so it can
+ * be bundled by --export-cache and reused offline via --jsrepo. Network call —
+ * online only. Returns { ok, path } | { ok:false, error }. Never throws.
+ */
+async function warmRetireSignatures(opts = {}) {
+	const { verbose, force } = opts;
+	if (!force && fs.existsSync(RETIRE_SIG_FILE)) {
+		if (verbose) console.log(`retire: signatures already present (${RETIRE_SIG_FILE})`);
+		return { ok: true, path: RETIRE_SIG_FILE, cached: true };
+	}
+	try {
+		const res = await fetch(RETIRE_REPO_URL);
+		if (!res.ok) throw new Error(`HTTP ${res.status}`);
+		const text = await res.text();
+		JSON.parse(text);   // validate it's the repo JSON before persisting
+		fs.mkdirSync(RETIRE_SIG_DIR, { recursive: true });
+		fs.writeFileSync(RETIRE_SIG_FILE, text);
+		if (verbose) console.log(`retire: signatures warmed → ${RETIRE_SIG_FILE}`);
+		return { ok: true, path: RETIRE_SIG_FILE };
+	} catch (e) {
+		if (verbose) console.warn(`retire: signature warm failed — ${e.message}`);
+		return { ok: false, error: e.message };
+	}
+}
+
+// Ensure a local signature file exists. Online: fetch it if missing. Offline:
+// only report whether it's already there (no network).
+async function ensureSignatures({ verbose, offline } = {}) {
+	if (fs.existsSync(RETIRE_SIG_FILE)) return true;
+	if (offline) return false;
+	const r = await warmRetireSignatures({ verbose });
+	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 }) {
+	const args = [
+		"--outputformat", "json",
+		"--outputpath", outPath,
+		"--jspath", srcDir,
+		"--ignore", ignoredDirs,
+	];
+	if (jsRepo) { args.push("--jsrepo", jsRepo); }
+	return args;
+}
+
 /**
  * Run retire.js against `srcDir`. Returns the parsed JSON output (an array
  * of file-level findings) or null if retire is unavailable.
@@ -59,12 +119,9 @@ function findRetireBin() {
  */
 async function runRetire(srcDir, opts = {}) {
 	const { verbose, force, offline } = opts;
-	if (offline) {
-		const cached = readCache(srcDir);
-		if (cached) return cached;
-		if (verbose) console.warn("retire: --offline and no cache — skipped");
-		return null;
-	}
+	// No source tree (e.g. --import-anonymized) → nothing to scan for vendored JS.
+	if (!srcDir) { if (verbose) console.warn("retire: no source dir — skipped"); return null; }
+	// Findings-cache fast path (path-keyed). Works online and offline.
 	if (!force) {
 		const cached = readCache(srcDir);
 		if (cached) {
@@ -73,6 +130,15 @@ async function runRetire(srcDir, opts = {}) {
 		}
 	}
 
+	// No findings cache → we must scan. We need a signature DB. Offline, we can
+	// only proceed if a local signature file was previously warmed (and bundled
+	// via --export-cache / --import-cache); otherwise honor --offline and skip.
+	const haveSig = await ensureSignatures({ verbose, offline });
+	if (offline && !haveSig) {
+		if (verbose) console.warn("retire: --offline, no findings cache and no local signatures — skipped");
+		return null;
+	}
+
 	const bin = findRetireBin();
 	const ignoredDirs = [
 		"node_modules", "bower_components", "jspm_packages",
@@ -83,13 +149,8 @@ async function runRetire(srcDir, opts = {}) {
 	// 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 = [
-		"--outputformat", "json",
-		"--outputpath", tmpOut,
-		"--jspath", srcDir,
-		"--ignore", ignoredDirs,
-	];
-	if (verbose) console.log(`retire: scanning ${srcDir}…`);
+	const args = buildRetireArgs({ srcDir, outPath: tmpOut, ignoredDirs, jsRepo: haveSig ? RETIRE_SIG_FILE : null });
+	if (verbose) console.log(`retire: scanning ${srcDir}…${haveSig ? " (local signatures)" : ""}`);
 
 	try {
 		// retire.js exits with code 13 when it finds vulnerabilities — that's
@@ -207,5 +268,11 @@ module.exports = {
 	runRetire,
 	normaliseRetireResults,
 	findRetireBin,
+	warmRetireSignatures,
+	ensureSignatures,
+	buildRetireArgs,
 	RETIRE_CACHE_DIR,
+	RETIRE_SIG_DIR,
+	RETIRE_SIG_FILE,
+	RETIRE_REPO_URL,
 };