fad-checker 1.0.0

package/lib/npm/parse.js

@@ -0,0 +1,291 @@
+/**
+ * lib/npm/parse.js — parse package.json, package-lock.json (v1/v2/v3),
+ * and yarn.lock v1. Pure functions: no I/O scheduling, no console output.
+ *
+ * The shape returned by each parser is normalised to:
+ *   {
+ *     manifestPath,           // absolute path to the parsed file
+ *     manifestType,           // "package.json" | "package-lock" | "yarn.lock"
+ *     packageName,            // top-level project name (if known)
+ *     packageVersion,         // top-level project version (if known)
+ *     deps: [                 // every package present (direct + transitive)
+ *       {
+ *         name,               // "lodash" | "@scope/pkg"
+ *         version,            // resolved (lockfile) or range (package.json)
+ *         scope,              // "prod" | "dev" | "peer" | "optional"
+ *         depth,              // 0 for top-level; >0 for transitive in lockfile tree
+ *         from,               // for transitives in npm v1 lockfile: parent chain
+ *       },
+ *     ],
+ *   }
+ *
+ * The collector (lib/npm/collect.js) is responsible for merging across
+ * files and applying exclusion rules.
+ */
+const fs = require("fs");
+const path = require("path");
+
+function isWorkspaceVersion(v) {
+	// npm v9+ uses "*" / "" for workspace-local refs; yarn uses "workspace:*"
+	if (!v) return true;
+	return v === "*" || v === "" || String(v).startsWith("workspace:") || String(v).startsWith("file:") || String(v).startsWith("link:");
+}
+
+function pickName(pkgKey) {
+	// npm v2/v3 lockfile keys look like "node_modules/foo" or "node_modules/foo/node_modules/bar"
+	const parts = pkgKey.split("node_modules/");
+	const last = parts[parts.length - 1];
+	return last || null;
+}
+
+function depthFromKey(pkgKey) {
+	// "node_modules/a/node_modules/b" → depth 2
+	const n = (pkgKey.match(/node_modules\//g) || []).length;
+	return Math.max(0, n - 1);
+}
+
+/* -------- package.json ---------- */
+function parsePackageJson(filePath) {
+	const raw = fs.readFileSync(filePath, "utf8");
+	let json;
+	try { json = JSON.parse(raw); }
+	catch (e) { throw new Error(`package.json parse failed (${filePath}): ${e.message}`); }
+	const deps = [];
+	const push = (obj, scope) => {
+		for (const [name, version] of Object.entries(obj || {})) {
+			if (isWorkspaceVersion(version)) continue;
+			const isDev = scope === "dev" || scope === "optional";
+			deps.push({ name, version: String(version), scope, isDev, depth: 0 });
+		}
+	};
+	push(json.dependencies, "prod");
+	push(json.devDependencies, "dev");
+	push(json.peerDependencies, "peer");
+	push(json.optionalDependencies, "optional");
+	return {
+		manifestPath: filePath,
+		manifestType: "package.json",
+		packageName: json.name || null,
+		packageVersion: json.version || null,
+		workspaces: Array.isArray(json.workspaces) ? json.workspaces : (json.workspaces?.packages || []),
+		deps,
+	};
+}
+
+/* -------- package-lock.json (v1, v2, v3) ---------- */
+function parsePackageLock(filePath) {
+	const raw = fs.readFileSync(filePath, "utf8");
+	let json;
+	try { json = JSON.parse(raw); }
+	catch (e) { throw new Error(`package-lock parse failed (${filePath}): ${e.message}`); }
+
+	const lockfileVersion = json.lockfileVersion || 1;
+	const out = {
+		manifestPath: filePath,
+		manifestType: "package-lock",
+		packageName: json.name || null,
+		packageVersion: json.version || null,
+		lockfileVersion,
+		deps: [],
+	};
+
+	if (lockfileVersion >= 2 && json.packages) {
+		// v2/v3: flat `packages` map keyed by relative path.
+		// The empty-string key is the root project; node_modules/foo → installed dep.
+		const root = json.packages[""] || {};
+		const directProd = root.dependencies || {};
+		const directDev = root.devDependencies || {};
+		const directOpt = root.optionalDependencies || {};
+		const directPeer = root.peerDependencies || {};
+		const isDirect = (name, scope) => {
+			if (scope === "prod" && Object.prototype.hasOwnProperty.call(directProd, name)) return true;
+			if (scope === "dev" && Object.prototype.hasOwnProperty.call(directDev, name)) return true;
+			if (scope === "optional" && Object.prototype.hasOwnProperty.call(directOpt, name)) return true;
+			if (scope === "peer" && Object.prototype.hasOwnProperty.call(directPeer, name)) return true;
+			return false;
+		};
+		const isAnyDirect = name =>
+			Object.prototype.hasOwnProperty.call(directProd, name) ||
+			Object.prototype.hasOwnProperty.call(directDev, name) ||
+			Object.prototype.hasOwnProperty.call(directOpt, name) ||
+			Object.prototype.hasOwnProperty.call(directPeer, name);
+
+		for (const [pkgKey, entry] of Object.entries(json.packages)) {
+			if (pkgKey === "") continue;                  // root
+			if (!pkgKey.includes("node_modules/")) continue; // workspace member, not a dep
+			if (entry.link) continue;                     // symlink to workspace
+			const name = pickName(pkgKey);
+			if (!name) continue;
+			const depth = depthFromKey(pkgKey);
+			// scope inference. npm v3+ flattens transitives into the top-level
+			// node_modules/, so depth===0 alone doesn't mean "direct". An entry
+			// is direct iff it appears in the root project's dependency lists.
+			let scope = "prod";
+			if (entry.dev || entry.devOptional) scope = "dev";
+			else if (entry.optional) scope = "optional";
+			else if (entry.peer) scope = "peer";
+			const isDirectDep = depth === 0 && isAnyDirect(name);
+			if (isDirectDep) {
+				if (isDirect(name, "dev")) scope = "dev";
+				else if (isDirect(name, "optional")) scope = "optional";
+				else if (isDirect(name, "peer")) scope = "peer";
+				else scope = "prod";
+			} else if (depth > 0 || !isAnyDirect(name)) {
+				// Flattened-but-not-direct = transitive. Keep dev/optional flags
+				// for filtering, but record it as a transitive.
+				scope = "transitive";
+			}
+			// isDev flag survives the scope reclassification: a flattened
+			// transitive of a dev-only dep is still dev-only.
+			const isDev = !!(entry.dev || entry.devOptional || (isDirectDep && isDirect(name, "dev")));
+			out.deps.push({
+				name,
+				version: entry.version || null,
+				scope,
+				isDev,
+				depth,
+				resolved: entry.resolved || null,
+				integrity: entry.integrity || null,
+			});
+		}
+	} else if (json.dependencies) {
+		// v1: nested `dependencies` tree
+		const walk = (node, depth, parentChain, parentIsDev) => {
+			for (const [name, entry] of Object.entries(node)) {
+				let scope = "prod";
+				if (entry.dev) scope = "dev";
+				else if (entry.optional) scope = "optional";
+				const isDev = !!entry.dev || parentIsDev;
+				out.deps.push({
+					name,
+					version: entry.version || null,
+					scope,
+					isDev,
+					depth,
+					from: parentChain.length ? parentChain.join(" > ") : null,
+					resolved: entry.resolved || null,
+					integrity: entry.integrity || null,
+				});
+				if (entry.dependencies) walk(entry.dependencies, depth + 1, [...parentChain, name], isDev);
+			}
+		};
+		walk(json.dependencies, 0, [], false);
+	}
+
+	return out;
+}
+
+/* -------- yarn.lock v1 ----------
+   Format example:
+     "lodash@^4.17.0":
+       version "4.17.21"
+       resolved "https://registry.yarnpkg.com/..."
+       integrity sha512-...
+       dependencies:
+         "another-pkg" "^1.0.0"
+   Each block starts at column 0 with one or more comma-separated specifiers,
+   ending with ":". Indented lines hold key-value pairs and dependency blocks.
+*/
+function parseYarnLockV1(filePath) {
+	const raw = fs.readFileSync(filePath, "utf8");
+	if (raw.includes("__metadata:")) {
+		// Berry / yarn 2+ uses YAML. Punt for now — return empty deps + a flag.
+		return {
+			manifestPath: filePath,
+			manifestType: "yarn.lock",
+			lockfileVersion: "berry",
+			deps: [],
+			unsupported: "yarn-berry",
+		};
+	}
+	const out = {
+		manifestPath: filePath,
+		manifestType: "yarn.lock",
+		lockfileVersion: 1,
+		deps: [],
+	};
+	const lines = raw.split(/\r?\n/);
+	let i = 0;
+	// Track unique (name, version) so we don't emit duplicate entries for
+	// every range spec that resolves to the same version.
+	const seen = new Set();
+	while (i < lines.length) {
+		const line = lines[i];
+		if (!line || /^#/.test(line)) { i++; continue; }
+		if (line[0] === " " || line[0] === "\t") { i++; continue; }
+		// Header line: one or more comma-separated specifiers ending with ":"
+		const header = line.replace(/:\s*$/, "");
+		const specifiers = header.split(",").map(s => s.trim().replace(/^"|"$/g, ""));
+		// Each specifier is "name@range". Names may contain "@" for scoped pkgs.
+		const names = new Set();
+		for (const spec of specifiers) {
+			const at = spec.lastIndexOf("@");
+			if (at <= 0) continue; // malformed
+			names.add(spec.slice(0, at));
+		}
+		i++;
+		// Read the indented body until the next non-indented line
+		let version = null;
+		let resolved = null;
+		while (i < lines.length && (lines[i].startsWith("  ") || lines[i].startsWith("\t") || lines[i] === "")) {
+			const body = lines[i].trim();
+			if (body.startsWith("version ")) {
+				version = body.slice("version ".length).replace(/^"|"$/g, "");
+			} else if (body.startsWith("resolved ")) {
+				resolved = body.slice("resolved ".length).replace(/^"|"$/g, "");
+			}
+			i++;
+		}
+		for (const name of names) {
+			if (!version) continue;
+			const k = `${name}@${version}`;
+			if (seen.has(k)) continue;
+			seen.add(k);
+			out.deps.push({ name, version, scope: "prod", depth: 0, resolved });
+		}
+	}
+	return out;
+}
+
+/* -------- discovery ---------- */
+// Dirs that hold packaged / generated content — never our own source.
+// Conservative list: only well-known build-output / package-cache dirs.
+const DEFAULT_JS_SKIP_DIRS = new Set([
+	"node_modules", "bower_components", "jspm_packages",
+	".git", ".idea", ".vscode", ".gradle", ".mvn",
+	"dist", "build", "out", "target", "coverage", ".next", ".nuxt",
+]);
+
+function findJsManifests(rootDir, opts = {}) {
+	const { skipDirs = DEFAULT_JS_SKIP_DIRS } = opts;
+	const found = [];
+	const stack = [rootDir];
+	while (stack.length) {
+		const cur = stack.pop();
+		let entries;
+		try { entries = fs.readdirSync(cur, { withFileTypes: true }); }
+		catch { continue; }
+		// Group lockfile per directory so we can prefer lock > package.json
+		const here = { dir: cur, packageJson: null, packageLock: null, yarnLock: null };
+		for (const e of entries) {
+			const p = path.join(cur, e.name);
+			if (e.isDirectory()) {
+				if (skipDirs.has(e.name)) continue;
+				stack.push(p);
+			} else if (e.isFile()) {
+				if (e.name === "package.json") here.packageJson = p;
+				else if (e.name === "package-lock.json") here.packageLock = p;
+				else if (e.name === "yarn.lock") here.yarnLock = p;
+			}
+		}
+		if (here.packageJson || here.packageLock || here.yarnLock) found.push(here);
+	}
+	return found;
+}
+
+module.exports = {
+	parsePackageJson,
+	parsePackageLock,
+	parseYarnLockV1,
+	findJsManifests,
+};

package/lib/nvd.js

@@ -0,0 +1,239 @@
+/**
+ * lib/nvd.js — enrich already-found CVEs with the NIST NVD record.
+ *
+ * NVD's API doesn't expose a Maven-coord index, so we don't use it for
+ * recall. Instead we look up each known CVE ID to get the canonical
+ * description, full CVSS metrics (v2 / v3.1 / v4.0), CPE configurations,
+ * and reference URLs.
+ *
+ * API: https://services.nvd.nist.gov/rest/json/cves/2.0?cveId=CVE-YYYY-NNNN
+ * Rate limit: 5 req / 30s unauthenticated, 50 req / 30s with NVD_API_KEY env var.
+ *
+ * Cache: ~/.fad-check/nvd-cache/<cve-id>.json, 7-day TTL.
+ */
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const { getNvdApiKey } = require("./config");
+
+const NVD_CACHE_DIR = path.join(os.homedir(), ".fad-check", "nvd-cache");
+const NVD_CACHE_TTL_MS = 7 * 24 * 3600 * 1000;
+const NVD_BASE = "https://services.nvd.nist.gov/rest/json/cves/2.0";
+
+function getRateDelay() {
+	// 50 req / 30s with API key, 5 req / 30s without
+	return getNvdApiKey() ? 600 : 6000;
+}
+
+function cachePath(cveId) {
+	return path.join(NVD_CACHE_DIR, `${cveId}.json`);
+}
+
+function readCache(cveId) {
+	const p = cachePath(cveId);
+	if (!fs.existsSync(p)) return null;
+	try {
+		const data = JSON.parse(fs.readFileSync(p, "utf8"));
+		if (Date.now() - data._fetchedAt < NVD_CACHE_TTL_MS) return data.body;
+	} catch { /* ignore */ }
+	return null;
+}
+
+function writeCache(cveId, body) {
+	fs.mkdirSync(NVD_CACHE_DIR, { recursive: true });
+	fs.writeFileSync(cachePath(cveId), JSON.stringify({ _fetchedAt: Date.now(), body }));
+}
+
+function bestMetric(metrics) {
+	// NVD 2.0 returns metrics organised by version: cvssMetricV40, V31, V30, V2
+	const order = ["cvssMetricV40", "cvssMetricV31", "cvssMetricV30", "cvssMetricV2"];
+	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:"),
+				score: cv.baseScore,
+				severity: (cv.baseSeverity || severityFromScore(cv.baseScore) || "UNKNOWN").toUpperCase(),
+				vector: cv.vectorString,
+			};
+		}
+	}
+	return 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 extractFromNvdRecord(record) {
+	if (!record) return null;
+	const desc = (record.descriptions || []).find(d => d.lang === "en")?.value || "";
+	const metric = bestMetric(record.metrics);
+	// Keep each reference together with its NVD tags (Patch, Exploit, Vendor Advisory, Third Party Advisory, Mailing List, ...)
+	const refs = (record.references || []).map(r => ({
+		url: r.url,
+		source: r.source || null,
+		tags: r.tags || [],
+	}));
+	const cpes = [];
+	for (const c of record.configurations || []) {
+		for (const n of c.nodes || []) {
+			for (const m of n.cpeMatch || []) cpes.push(m.criteria);
+		}
+	}
+	// Preserve the full configurations tree so cve-match / cpe.js can evaluate
+	// AND/OR nodes and version ranges (versionStartIncluding, etc.). We strip
+	// `matchCriteriaId` and other UUID-only fields to keep the cache compact.
+	const configurations = (record.configurations || []).map(c => ({
+		operator: c.operator || "OR",
+		negate: c.negate || false,
+		nodes: (c.nodes || []).map(slimNode),
+	}));
+	// CWE identifiers (Common Weakness Enumeration). NVD shape:
+	//   weaknesses: [{ source, type, description: [{ lang, value: "CWE-79" }] }]
+	const cwes = [];
+	const seenCwe = new Set();
+	for (const w of record.weaknesses || []) {
+		for (const d of w.description || []) {
+			const v = (d.value || "").trim();
+			if (/^CWE-\d+$/i.test(v) && !seenCwe.has(v.toUpperCase())) {
+				seenCwe.add(v.toUpperCase());
+				cwes.push(v.toUpperCase());
+			}
+		}
+	}
+	return {
+		id: record.id,
+		description: desc,
+		severity: metric?.severity || "UNKNOWN",
+		score: metric?.score ?? null,
+		cvssVector: metric?.vector || null,
+		cvssVersion: metric?.version || null,
+		published: record.published || null,
+		modified: record.lastModified || null,
+		references: refs,
+		cpes,
+		cwes,
+		configurations,
+	};
+}
+
+function slimNode(n) {
+	return {
+		operator: n.operator || "OR",
+		negate: n.negate || false,
+		cpeMatch: (n.cpeMatch || []).map(m => ({
+			vulnerable: m.vulnerable !== false,
+			criteria: m.criteria,
+			versionStartIncluding: m.versionStartIncluding,
+			versionStartExcluding: m.versionStartExcluding,
+			versionEndIncluding: m.versionEndIncluding,
+			versionEndExcluding: m.versionEndExcluding,
+		})),
+		children: Array.isArray(n.children) ? n.children.map(slimNode) : undefined,
+	};
+}
+
+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);
+	if (cached !== null && cached !== undefined) return cached;
+	if (offline) return null;
+	const headers = { "User-Agent": "fad-check-nvd-enrich" };
+	const key = getNvdApiKey();
+	if (key) headers["apiKey"] = key;
+	const url = `${NVD_BASE}?cveId=${encodeURIComponent(cveId)}`;
+	try {
+		const r = await fetcher(url, { headers });
+		if (r.status === 404) { writeCache(cveId, null); return null; }
+		if (!r.ok) {
+			if (verbose) console.warn(`   NVD HTTP ${r.status} for ${cveId}`);
+			return null;
+		}
+		const data = await r.json();
+		const record = data.vulnerabilities?.[0]?.cve;
+		const extracted = extractFromNvdRecord(record);
+		writeCache(cveId, extracted);
+		return extracted;
+	} catch (err) {
+		if (verbose) console.warn(`   NVD fetch failed for ${cveId}: ${err.message}`);
+		return null;
+	}
+}
+
+/**
+ * Enrich an array of fad-check matches in place by fetching their NVD records.
+ * Adds: cve.description (replaced by NVD's), cve.cvssVector, cve.cvssVersion,
+ * cve.references, cve.cpes. Severity/score are only overwritten if currently UNKNOWN/null.
+ *
+ * Rate limited per the NIST policy (use NVD_API_KEY for faster access).
+ */
+async function enrichMatches(matches, opts = {}) {
+	const { verbose, offline } = opts;
+	const uniqueCves = new Set();
+	for (const m of matches) if (m.cve?.id?.startsWith("CVE-")) uniqueCves.add(m.cve.id);
+	const hasKey = !!getNvdApiKey();
+	const delay = getRateDelay();
+	if (verbose) console.log(`🔍 NVD: enriching ${uniqueCves.size} unique CVEs${offline ? " (offline — cache only)" : hasKey ? " (with API key, 50/30s)" : " (no API key — throttled to 5/30s; pass --set-nvd-key for 10× faster)"}…`);
+
+	const byId = new Map();
+	let i = 0;
+	for (const cveId of uniqueCves) {
+		// Only sleep between live (non-cached) requests.
+		const cached = readCache(cveId);
+		if (cached !== null && cached !== undefined) {
+			byId.set(cveId, cached);
+			continue;
+		}
+		if (offline) { byId.set(cveId, null); continue; }
+		const data = await fetchOne(cveId, opts);
+		byId.set(cveId, data);
+		i++;
+		if (verbose && i % 5 === 0) process.stdout.write(`\r   NVD: ${i} fetched`);
+		// Rate limit between requests
+		await sleep(delay);
+	}
+	if (verbose && i) process.stdout.write(`\r   NVD: ${i} fetched                  \n`);
+
+	for (const m of matches) {
+		const data = byId.get(m.cve?.id);
+		if (!data) continue;
+		// Merge: prefer NVD's official text + CVSS but keep what fad-check/OSV already has
+		// NVD's description is the official long form — prefer it when available.
+		if (data.description) {
+			m.cve.description = data.description.length > 2000
+				? data.description.slice(0, 2000) + "…"
+				: data.description;
+		}
+		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;
+		m.cve.nvdRefs = data.references || [];   // [{url, tags, source}]
+		m.cve.cpes = data.cpes || [];
+		m.cve.cwes = data.cwes || [];
+		m.cve.configurations = data.configurations || [];
+		if (!m.cve.published && data.published) m.cve.published = data.published;
+		if (!m.cve.modified  && data.modified)  m.cve.modified  = data.modified;
+		// Tag NVD as a contributing source so the report shows fad+nvd / osv+nvd.
+		const sources = new Set((m.source || "").split("+").filter(Boolean));
+		sources.add("nvd");
+		m.source = [...sources].sort().join("+");
+	}
+	return matches;
+}
+
+module.exports = {
+	enrichMatches,
+	fetchOne,
+	extractFromNvdRecord,
+	NVD_CACHE_DIR,
+	getNvdApiKey,
+};