fad-checker 1.0.0

package/lib/cpe.js

@@ -0,0 +1,287 @@
+/**
+ * lib/cpe.js — CPE 2.3 parsing + matching of NVD configuration trees.
+ *
+ * CPE 2.3 URI binding:
+ *   cpe:2.3:part:vendor:product:version:update:edition:language:
+ *           sw_edition:target_sw:target_hw:other
+ * Each field can be a literal, "*" (ANY) or "-" (NA). Some characters
+ * are percent-encoded, we only need to undo "\:" and "\\" for the
+ * fields we read.
+ *
+ * Used in two directions:
+ *   1. Given a NVD-enriched match (cve.cpes[] + cve.configurations[]),
+ *      decide whether a dep is _truly_ affected (version range check)
+ *      and whether we can upgrade the match confidence.
+ *   2. Given a dep coord, find CVEs in the index whose CPE configurations
+ *      it satisfies. (Future use — kept compatible with the data shape.)
+ */
+const { compareMavenVersions } = require("./maven-version");
+
+let CPE_COORD_MAP_CACHE = null;
+function loadCpeCoordMap() {
+	if (CPE_COORD_MAP_CACHE) return CPE_COORD_MAP_CACHE;
+	try {
+		CPE_COORD_MAP_CACHE = require("../data/cpe-coord-map.json");
+	} catch {
+		CPE_COORD_MAP_CACHE = { byVendorProduct: {}, byProduct: {} };
+	}
+	return CPE_COORD_MAP_CACHE;
+}
+
+/**
+ * Parse a CPE 2.3 URI. Returns null on malformed input.
+ * Field order: cpe:2.3:part:vendor:product:version:update:edition:language:
+ *              sw_edition:target_sw:target_hw:other
+ */
+function parseCpe23(uri) {
+	if (typeof uri !== "string") return null;
+	if (!uri.startsWith("cpe:2.3:")) return null;
+	// Split on `:` but respect backslash escaping.
+	const fields = [];
+	let buf = "";
+	for (let i = 0; i < uri.length; i++) {
+		const c = uri[i];
+		if (c === "\\" && i + 1 < uri.length) {
+			buf += uri[i + 1]; i++;
+		} else if (c === ":") {
+			fields.push(buf); buf = "";
+		} else {
+			buf += c;
+		}
+	}
+	fields.push(buf);
+	// fields = ["cpe","2.3","a","vendor","product","version","update","edition","language","sw_edition","target_sw","target_hw","other"]
+	if (fields.length < 7) return null;
+	return {
+		part:        fields[2] || "*",
+		vendor:      fields[3] || "*",
+		product:     fields[4] || "*",
+		version:     fields[5] || "*",
+		update:      fields[6] || "*",
+		edition:     fields[7] || "*",
+		language:    fields[8] || "*",
+		sw_edition:  fields[9] || "*",
+		target_sw:   fields[10] || "*",
+		target_hw:   fields[11] || "*",
+		other:       fields[12] || "*",
+	};
+}
+
+/**
+ * Match a dep version against a single NVD cpeMatch entry.
+ * The entry has the shape:
+ *   { criteria: "cpe:2.3:a:vendor:product:version:...",
+ *     vulnerable: true,
+ *     versionStartIncluding, versionStartExcluding,
+ *     versionEndIncluding,   versionEndExcluding }
+ *
+ * Returns true if `depVersion` is in range. If the CPE itself pins a
+ * concrete version (criteria's version field != "*"/"-"), that pin wins.
+ */
+function matchVersionRange(depVersion, cpeMatch) {
+	if (!cpeMatch) return false;
+	if (!depVersion) return true; // unknown version → assume affected
+	const parsed = parseCpe23(cpeMatch.criteria || "");
+	if (!parsed) return false;
+
+	// Hard pin in the criteria URI itself
+	if (parsed.version && parsed.version !== "*" && parsed.version !== "-") {
+		try { return compareMavenVersions(depVersion, parsed.version) === 0; }
+		catch { return false; }
+	}
+
+	try {
+		if (cpeMatch.versionStartIncluding && compareMavenVersions(depVersion, cpeMatch.versionStartIncluding) < 0) return false;
+		if (cpeMatch.versionStartExcluding && compareMavenVersions(depVersion, cpeMatch.versionStartExcluding) <= 0) return false;
+		if (cpeMatch.versionEndIncluding && compareMavenVersions(depVersion, cpeMatch.versionEndIncluding) > 0) return false;
+		if (cpeMatch.versionEndExcluding && compareMavenVersions(depVersion, cpeMatch.versionEndExcluding) >= 0) return false;
+	} catch { return false; }
+	return true;
+}
+
+/**
+ * Evaluate a node (OR/AND of cpeMatch entries). For our use we only care
+ * about the `vulnerable` matches — "AND runs on Windows" runtime context
+ * is ignored on purpose: we assume the library is being _used_, so any
+ * vulnerable-marked CPE that matches the dep version is a real hit.
+ *
+ * Returns true if any vulnerable cpeMatch in the node matches the dep.
+ */
+function nodeAffectsDep(node, dep, cpeCoordMap) {
+	if (!node) return false;
+	const matches = node.cpeMatch || node.cpe_match || [];
+	for (const m of matches) {
+		if (m.vulnerable === false) continue;
+		const parsed = parseCpe23(m.criteria || "");
+		if (!parsed) continue;
+		if (!cpeMatchesDep(parsed, dep, cpeCoordMap)) continue;
+		if (!matchVersionRange(dep.version, m)) continue;
+		return true;
+	}
+	// Recurse into children (NVD nests AND/OR nodes)
+	if (Array.isArray(node.children)) {
+		for (const child of node.children) {
+			if (nodeAffectsDep(child, dep, cpeCoordMap)) return true;
+		}
+	}
+	return false;
+}
+
+/**
+ * Decide whether a CPE (parsed) refers to the same artifact as a dep.
+ * Lookup order:
+ *   1. Curated map `byVendorProduct["vendor:product"]` — array of dep keys
+ *      (maven "g:a" or "npm:name"). Exact, high confidence.
+ *   2. Curated map `byProduct[product]` — same shape, used when vendor is
+ *      ambiguous (Apache wraps several groupIds).
+ *   3. Heuristic: vendor token appears in groupId, or groupId/artifactId
+ *      equals/contains product. Same logic as cve-match.vendorMatchesGroup
+ *      but kept local here so cpe.js is standalone.
+ */
+function cpeMatchesDep(cpe, dep, cpeCoordMap) {
+	if (!cpe || !dep) return false;
+	if (cpe.part !== "a" && cpe.part !== "*") return false; // we only care about apps
+	const map = cpeCoordMap || loadCpeCoordMap();
+	const vp = `${cpe.vendor}:${cpe.product}`.toLowerCase();
+	const depKey = depToKey(dep).toLowerCase();
+	const altKey = altDepKey(dep).toLowerCase();
+
+	const inList = arr => Array.isArray(arr) && arr.some(k => {
+		const lk = String(k).toLowerCase();
+		return lk === depKey || lk === altKey;
+	});
+
+	if (inList(map.byVendorProduct?.[vp])) return true;
+	if (inList(map.byProduct?.[cpe.product?.toLowerCase()])) return true;
+
+	// Heuristic fallback
+	if (dep.ecosystem === "npm") {
+		const name = (dep.artifactId || "").toLowerCase();
+		if (cpe.product?.toLowerCase() === name) return true;
+		// scoped packages: @scope/name → CPE vendor="scope", product="name"
+		const m = name.match(/^@([^/]+)\/(.+)$/);
+		if (m && cpe.vendor?.toLowerCase() === m[1] && cpe.product?.toLowerCase() === m[2]) return true;
+	} else {
+		const g = (dep.groupId || "").toLowerCase();
+		const a = (dep.artifactId || "").toLowerCase();
+		const v = (cpe.vendor || "").toLowerCase();
+		const p = (cpe.product || "").toLowerCase();
+		if (p !== a) return false;
+		if (g === v) return true;
+		if (g.split(".").includes(v)) return true;
+		if (g.includes(v) || v.includes(g)) return true;
+	}
+	return false;
+}
+
+function depToKey(dep) {
+	if (dep.ecosystem === "npm") return `npm:${dep.artifactId}`;
+	return `${dep.groupId}:${dep.artifactId}`;
+}
+function altDepKey(dep) {
+	// For artifactId-only matching against curated lists keyed by artifact-only.
+	return dep.ecosystem === "npm" ? `npm:${dep.artifactId}` : dep.artifactId || "";
+}
+
+/**
+ * Run the CPE configurations of `cveRecord` against `dep`.
+ * `cveRecord.configurations` follows NVD's shape. Returns:
+ *   { affected: boolean, confidence: "exact" | "probable" | null }
+ *
+ * - "exact" when a curated mapping confirms vendor:product → dep
+ * - "probable" when only heuristic matched
+ */
+function evaluateCveForDep(cveRecord, dep, cpeCoordMap) {
+	const map = cpeCoordMap || loadCpeCoordMap();
+	const configs = cveRecord?.configurations || [];
+	let bestConfidence = null;
+	const note = c => {
+		if (c === "exact" || bestConfidence === "exact") bestConfidence = "exact";
+		else if (c === "probable") bestConfidence = bestConfidence || "probable";
+	};
+
+	for (const cfg of configs) {
+		const nodes = cfg.nodes || [];
+		const op = (cfg.operator || "OR").toUpperCase();
+		const evals = nodes.map(n => {
+			const hit = nodeAffectsDep(n, dep, map);
+			return hit;
+		});
+		const passes = op === "AND" ? evals.every(Boolean) : evals.some(Boolean);
+		if (passes) {
+			// Determine confidence: scan vulnerable cpeMatches that hit
+			for (const n of nodes) {
+				for (const m of n.cpeMatch || n.cpe_match || []) {
+					if (m.vulnerable === false) continue;
+					const parsed = parseCpe23(m.criteria || "");
+					if (!parsed) continue;
+					if (!cpeMatchesDep(parsed, dep, map)) continue;
+					if (!matchVersionRange(dep.version, m)) continue;
+					const vp = `${parsed.vendor}:${parsed.product}`.toLowerCase();
+					const depKey = depToKey(dep).toLowerCase();
+					const curated = (map.byVendorProduct?.[vp] || []).some(k => String(k).toLowerCase() === depKey);
+					note(curated ? "exact" : "probable");
+				}
+			}
+		}
+	}
+
+	// Fallback: no configurations[] (some NVD records only have cpes[]).
+	// We accept a hit if any CPE string matches the dep coord — but with no
+	// version range info, we can only say "possible" (caller's existing
+	// confidence stays unless we can prove version match).
+	if (!configs.length && Array.isArray(cveRecord?.cpes)) {
+		for (const uri of cveRecord.cpes) {
+			const parsed = parseCpe23(uri);
+			if (!parsed) continue;
+			if (cpeMatchesDep(parsed, dep, map)) {
+				note("probable");
+				break;
+			}
+		}
+	}
+
+	return { affected: bestConfidence !== null, confidence: bestConfidence };
+}
+
+/**
+ * Walk an enriched matches list and refine each entry using NVD CPE data.
+ * Mutates each match in place:
+ *   - sets m.cpeConfidence = "exact" | "probable" | null
+ *   - if NVD configurations include version ranges that the dep version does NOT
+ *     satisfy AND no other configuration places it in scope, sets
+ *     m.cpeFiltered = true so the report can mark it as "likely false positive".
+ *   - upgrades m.confidence from "possible" → "probable", "probable" → "exact"
+ *     when the CPE side confirms with curated mapping.
+ *
+ * Note: m.cve.configurations is only present on NVD-enriched records. If
+ * absent, we still try m.cve.cpes[] (URI list) for vendor:product matching.
+ */
+function refineMatchesWithCpe(matches, opts = {}) {
+	const map = opts.cpeCoordMap || loadCpeCoordMap();
+	for (const m of matches) {
+		const cve = m.cve || {};
+		// Build a tiny record shape that evaluateCveForDep accepts
+		const rec = { configurations: cve.configurations || [], cpes: cve.cpes || [] };
+		if (!rec.configurations.length && !rec.cpes.length) continue;
+		const { affected, confidence } = evaluateCveForDep(rec, m.dep, map);
+		m.cpeConfidence = confidence;
+		if (!affected && rec.configurations.length) {
+			// Configurations exist but version doesn't satisfy any → likely FP
+			m.cpeFiltered = true;
+		}
+		if (affected && confidence === "exact" && m.confidence !== "exact") m.confidence = "exact";
+		else if (affected && confidence === "probable" && m.confidence === "possible") m.confidence = "probable";
+	}
+	return matches;
+}
+
+module.exports = {
+	parseCpe23,
+	matchVersionRange,
+	cpeMatchesDep,
+	nodeAffectsDep,
+	evaluateCveForDep,
+	refineMatchesWithCpe,
+	loadCpeCoordMap,
+};

package/lib/cve-download.js

@@ -0,0 +1,369 @@
+/**
+ * lib/cve-download.js — fetch the CVEProject/cvelistV5 daily bundle and
+ * build a compact Maven-relevant index (~5-20 MB).
+ *
+ * The bundle is ~500 MB+. We shell out to curl + unzip rather than
+ * bundling a zip library. The extracted JSON is deleted after the index
+ * is built.
+ */
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { execFile } = require("child_process");
+const { promisify } = require("util");
+const execFileP = promisify(execFile);
+
+const CVE_DATA_DIR = path.join(os.homedir(), ".fad-check", "cve-data");
+const CVE_INDEX_PATH = path.join(CVE_DATA_DIR, "maven-cve-index.json");
+const CVE_META_PATH = path.join(CVE_DATA_DIR, "meta.json");
+const CVE_EXTRACT_DIR = path.join(CVE_DATA_DIR, "extracted");
+const CVE_ZIP_PATH = path.join(CVE_DATA_DIR, "cves.zip");
+
+const KNOWN_JAVA_VENDORS = new Set([
+	"apache", "org.apache", "com.apache",
+	"spring", "springframework", "org.springframework", "pivotal", "pivotal_software",
+	"fasterxml", "com.fasterxml",
+	"jboss", "redhat", "wildfly",
+	"oracle", "sun", "openjdk",
+	"google", "com.google", "guava",
+	"eclipse", "org.eclipse",
+	"hibernate", "org.hibernate",
+	"netty", "io.netty",
+	"jetty", "eclipse_jetty",
+	"tomcat", "apache_tomcat",
+	"log4j", "logback",
+	"struts", "apache_struts",
+	"shiro", "apache_shiro",
+	"xstream", "thoughtworks",
+	"jackson", "snakeyaml",
+	"squareup", "okhttp",
+]);
+
+function isMavenRelevant(affected) {
+	if (!affected || !Array.isArray(affected)) return false;
+	for (const a of affected) {
+		if (a.packageName && String(a.packageName).includes(":")) return true;
+		if (a.collectionURL && /maven|sonatype|jboss\.org|jcenter/i.test(a.collectionURL)) return true;
+		if (a.versions?.some(v => v.versionType === "maven")) return true;
+		const v = String(a.vendor || "").toLowerCase();
+		const p = String(a.product || "").toLowerCase();
+		if (KNOWN_JAVA_VENDORS.has(v)) return true;
+		// Heuristic: product names that look like Maven artifactIds
+		if (/^(spring-|jackson-|commons-|hibernate-|netty-|guava|log4j|slf4j|okhttp|httpclient|jetty-|tomcat-|struts-)/.test(p)) return true;
+	}
+	return false;
+}
+
+function extractDescription(cveJson) {
+	const descs = cveJson?.containers?.cna?.descriptions || cveJson?.containers?.adp?.[0]?.descriptions || [];
+	const en = descs.find(d => (d.lang || "").startsWith("en"));
+	const txt = (en?.value || descs[0]?.value || "").trim();
+	return txt.length > 400 ? txt.slice(0, 400) + "…" : txt;
+}
+
+function extractSeverity(cveJson) {
+	const containers = [cveJson?.containers?.cna, ...(cveJson?.containers?.adp || [])];
+	for (const c of containers) {
+		const metrics = c?.metrics;
+		if (!Array.isArray(metrics)) continue;
+		for (const m of metrics) {
+			const cvss = m.cvssV3_1 || m.cvssV3_0 || m.cvssV4_0 || m.cvssV2_0;
+			if (cvss) {
+				return {
+					severity: (cvss.baseSeverity || severityFromScore(cvss.baseScore) || "UNKNOWN").toUpperCase(),
+					score: cvss.baseScore != null ? Number(cvss.baseScore) : null,
+				};
+			}
+		}
+	}
+	return { severity: "UNKNOWN", score: null };
+}
+
+function severityFromScore(s) {
+	if (s == null) return null;
+	if (s >= 9) return "CRITICAL";
+	if (s >= 7) return "HIGH";
+	if (s >= 4) return "MEDIUM";
+	if (s > 0) return "LOW";
+	return "NONE";
+}
+
+function extractAffectedRanges(affected) {
+	const out = [];
+	for (const a of affected || []) {
+		const packageName = a.packageName && String(a.packageName).includes(":") ? a.packageName : null;
+		const vendor = a.vendor ? String(a.vendor).toLowerCase() : null;
+		const product = a.product ? String(a.product).toLowerCase() : null;
+		const versions = Array.isArray(a.versions) ? a.versions : [];
+		const ranges = versions.map(v => ({
+			version: v.version,
+			status: v.status,
+			versionType: v.versionType,
+			lessThan: v.lessThan,
+			lessThanOrEqual: v.lessThanOrEqual,
+		}));
+		out.push({ packageName, vendor, product, ranges });
+	}
+	return out;
+}
+
+function fixVersionFromRanges(ranges) {
+	for (const r of ranges) {
+		if (r.lessThan) return r.lessThan;
+		if (r.lessThanOrEqual) return r.lessThanOrEqual;
+	}
+	return null;
+}
+
+function extractMavenRelevantCve(json) {
+	const cveId = json?.cveMetadata?.cveId || json?.cve?.id;
+	if (!cveId) return null;
+	const affected = json?.containers?.cna?.affected || [];
+	if (!isMavenRelevant(affected)) return null;
+
+	const { severity, score } = extractSeverity(json);
+	const description = extractDescription(json);
+	const ranges = extractAffectedRanges(affected);
+
+	return {
+		id: cveId,
+		severity,
+		score,
+		description,
+		published: json?.cveMetadata?.datePublished || null,
+		modified: json?.cveMetadata?.dateUpdated || null,
+		affected: ranges,
+		fixVersion: fixVersionFromRanges(ranges.flatMap(a => a.ranges)),
+	};
+}
+
+function newIndex() {
+	return {
+		meta: { builtAt: null, releaseTag: null, cveCount: 0 },
+		byPackageName: {},
+		byProduct: {},
+	};
+}
+
+function addToIndex(index, cve) {
+	for (const a of cve.affected) {
+		const entry = {
+			id: cve.id,
+			severity: cve.severity,
+			score: cve.score,
+			description: cve.description,
+			fixVersion: cve.fixVersion,
+			ranges: a.ranges,
+			vendor: a.vendor,
+			product: a.product,
+		};
+		if (a.packageName) {
+			(index.byPackageName[a.packageName.toLowerCase()] ||= []).push(entry);
+		}
+		if (a.product) {
+			(index.byProduct[a.product] ||= []).push(entry);
+		}
+	}
+}
+
+async function commandExists(name) {
+	try {
+		await execFileP(process.platform === "win32" ? "where" : "which", [name]);
+		return true;
+	} catch { return false; }
+}
+
+async function fetchLatestRelease() {
+	const headers = { "User-Agent": "fad-check-cve-downloader" };
+	if (process.env.GITHUB_TOKEN) headers.Authorization = `Bearer ${process.env.GITHUB_TOKEN}`;
+	const res = await fetch("https://api.github.com/repos/CVEProject/cvelistV5/releases/latest", { headers });
+	if (!res.ok) throw new Error(`GitHub API HTTP ${res.status}`);
+	const data = await res.json();
+	const asset = data.assets?.find(a => /\.zip$/i.test(a.name) && /(cves|main|all)/i.test(a.name)) || data.assets?.[0];
+	if (!asset) throw new Error("no zip asset on latest cvelistV5 release");
+	return { url: asset.browser_download_url, tag: data.tag_name, name: asset.name };
+}
+
+async function download(url, dest, opts = {}) {
+	const { verbose } = opts;
+	if (await commandExists("curl")) {
+		const args = ["-L", "--fail", "--retry", "3", "-o", dest, url];
+		if (verbose) args.unshift("-#");
+		else args.unshift("-s");
+		await execFileP("curl", args, { maxBuffer: 1024 * 1024 * 16 });
+		return;
+	}
+	// Fallback to node fetch (slower for 500MB but works)
+	const res = await fetch(url);
+	if (!res.ok || !res.body) throw new Error(`download HTTP ${res.status}`);
+	const w = fs.createWriteStream(dest);
+	const reader = res.body.getReader();
+	while (true) {
+		const { done, value } = await reader.read();
+		if (done) break;
+		w.write(value);
+	}
+	w.end();
+	await new Promise(r => w.on("close", r));
+}
+
+async function extractZipOnce(zip, dest) {
+	await fs.promises.mkdir(dest, { recursive: true });
+	if (await commandExists("unzip")) {
+		await execFileP("unzip", ["-o", "-q", zip, "-d", dest], { maxBuffer: 1024 * 1024 * 16 });
+		return;
+	}
+	if (process.platform === "win32" && await commandExists("powershell")) {
+		await execFileP("powershell", ["-NoProfile", "-Command",
+			`Expand-Archive -Path '${zip}' -DestinationPath '${dest}' -Force`]);
+		return;
+	}
+	throw new Error("no unzip/powershell available; please install unzip");
+}
+
+// CVEProject ships ".zip.zip" bundles — a zip whose sole content is another zip.
+// Extract once and, if the result is a single nested zip, extract that one too.
+async function extractZip(zip, dest, opts = {}) {
+	const { verbose, depth = 0 } = opts;
+	if (depth > 3) throw new Error("zip nesting too deep");
+	await extractZipOnce(zip, dest);
+	const entries = await fs.promises.readdir(dest, { withFileTypes: true });
+	const zips = entries.filter(e => e.isFile() && /\.zip$/i.test(e.name));
+	if (zips.length === 1 && entries.length === 1) {
+		const nested = path.join(dest, zips[0].name);
+		if (verbose) console.log(`   nested zip found: ${zips[0].name} (${Math.round(fs.statSync(nested).size / 1024 / 1024)} MB) — extracting…`);
+		const nestedDest = path.join(dest, "_inner");
+		await extractZip(nested, nestedDest, { verbose, depth: depth + 1 });
+		await fs.promises.rm(nested, { force: true });
+		// Move the inner contents up
+		const innerEntries = await fs.promises.readdir(nestedDest, { withFileTypes: true });
+		for (const e of innerEntries) {
+			const from = path.join(nestedDest, e.name);
+			const to = path.join(dest, e.name);
+			await fs.promises.rename(from, to);
+		}
+		await fs.promises.rm(nestedDest, { recursive: true, force: true });
+	}
+}
+
+function walkJsonFiles(dir, onFile) {
+	const stack = [dir];
+	let count = 0;
+	while (stack.length) {
+		const cur = stack.pop();
+		let entries;
+		try { entries = fs.readdirSync(cur, { withFileTypes: true }); }
+		catch { continue; }
+		for (const e of entries) {
+			const p = path.join(cur, e.name);
+			if (e.isDirectory()) stack.push(p);
+			else if (e.name.endsWith(".json")) {
+				try { onFile(p); count++; } catch { /* skip malformed */ }
+			}
+		}
+	}
+	return count;
+}
+
+async function buildCveIndex(extractDir, opts = {}) {
+	const { verbose, releaseTag } = opts;
+	const index = newIndex();
+	let processed = 0;
+	let added = 0;
+	const tick = 5000;
+	walkJsonFiles(extractDir, file => {
+		processed++;
+		let json;
+		try { json = JSON.parse(fs.readFileSync(file, "utf8")); }
+		catch { return; }
+		const cve = extractMavenRelevantCve(json);
+		if (cve) {
+			addToIndex(index, cve);
+			added++;
+		}
+		if (verbose && processed % tick === 0) {
+			process.stdout.write(`\r  scanned ${processed} CVE files, ${added} Maven-relevant`);
+		}
+	});
+	if (verbose) process.stdout.write(`\r  scanned ${processed} CVE files, ${added} Maven-relevant\n`);
+	index.meta.builtAt = new Date().toISOString();
+	index.meta.releaseTag = releaseTag || null;
+	index.meta.cveCount = added;
+	await fs.promises.mkdir(CVE_DATA_DIR, { recursive: true });
+	await fs.promises.writeFile(CVE_INDEX_PATH, JSON.stringify(index));
+	await fs.promises.writeFile(CVE_META_PATH, JSON.stringify(index.meta, null, 2));
+	return index;
+}
+
+function loadCveIndex() {
+	if (!fs.existsSync(CVE_INDEX_PATH)) return null;
+	try { return JSON.parse(fs.readFileSync(CVE_INDEX_PATH, "utf8")); }
+	catch { return null; }
+}
+
+function isCveIndexFresh(maxAgeHours = 24) {
+	if (!fs.existsSync(CVE_META_PATH)) return false;
+	try {
+		const meta = JSON.parse(fs.readFileSync(CVE_META_PATH, "utf8"));
+		if (!meta.builtAt) return false;
+		const age = Date.now() - new Date(meta.builtAt).getTime();
+		return age < maxAgeHours * 3600 * 1000;
+	} catch { return false; }
+}
+
+async function downloadCveData(opts = {}) {
+	const { verbose, force } = opts;
+	await fs.promises.mkdir(CVE_DATA_DIR, { recursive: true });
+	if (!force && isCveIndexFresh()) {
+		if (verbose) console.log("CVE index is fresh (<24h); skipping download");
+		return loadCveIndex();
+	}
+
+	if (verbose) console.log("📥 fetching latest CVE release metadata…");
+	const { url, tag, name } = await fetchLatestRelease();
+	if (verbose) console.log(`   ${tag} → ${name}`);
+
+	if (verbose) console.log("📥 downloading CVE zip (this may take a while)…");
+	await download(url, CVE_ZIP_PATH, { verbose });
+
+	if (verbose) console.log("📦 extracting…");
+	try { await fs.promises.rm(CVE_EXTRACT_DIR, { recursive: true, force: true }); } catch {}
+	await extractZip(CVE_ZIP_PATH, CVE_EXTRACT_DIR, { verbose });
+
+	if (verbose) console.log("🔎 building Maven CVE index…");
+	const index = await buildCveIndex(CVE_EXTRACT_DIR, { verbose, releaseTag: tag });
+
+	// cleanup heavy files
+	try { await fs.promises.rm(CVE_EXTRACT_DIR, { recursive: true, force: true }); } catch {}
+	try { await fs.promises.rm(CVE_ZIP_PATH, { force: true }); } catch {}
+
+	return index;
+}
+
+/**
+ * Single entry point used by fad-check.js: returns a usable CVE index,
+ * downloading/refreshing as needed.
+ */
+async function ensureCveIndex(opts = {}) {
+	const { force, offline, verbose } = opts;
+	const cached = loadCveIndex();
+	if (offline) {
+		if (!cached) throw new Error("--cve-offline set but no cached CVE index found");
+		return cached;
+	}
+	if (!force && cached && isCveIndexFresh()) return cached;
+	return downloadCveData({ verbose, force });
+}
+
+module.exports = {
+	CVE_DATA_DIR,
+	CVE_INDEX_PATH,
+	CVE_META_PATH,
+	downloadCveData,
+	buildCveIndex,
+	loadCveIndex,
+	isCveIndexFresh,
+	ensureCveIndex,
+	extractMavenRelevantCve,
+	isMavenRelevant,
+};