@mitre/hdf-utilities 3.2.0 → 3.3.0

package/dist/index.js

@@ -41,7 +41,890 @@ function impactToSeverity(impact) {
 	if (impact > 0) return "low";
 	return "informational";
 }
+/**
+* Map a raw CVSS base score (0.0–10.0) to a FIRST qualitative severity band.
+*
+* Bands per FIRST CVSS v3.x / v4.0 spec:
+*   none     = 0.0
+*   low      = 0.1 – 3.9
+*   medium   = 4.0 – 6.9
+*   high     = 7.0 – 8.9
+*   critical = 9.0 – 10.0
+*
+* Out-of-range inputs are clamped: scores < 0.1 → "none" (band floor),
+* scores > 10.0 → "critical". This matches scanner behavior of treating
+* malformed scores as informational/critical extremes rather than throwing.
+*
+* @param score - CVSS base score
+* @returns FIRST severity band label
+*/
+function cvssScoreToSeverity(score) {
+	if (!Number.isFinite(score) || score < .1) return "none";
+	if (score < 4) return "low";
+	if (score < 7) return "medium";
+	if (score < 9) return "high";
+	return "critical";
+}
+//#endregion
+//#region src/cvss/index.ts
+/**
+* Allowed values for each metric, keyed by CVSS major version.
+*
+* Sourced from FIRST specifications (linked above). Only metrics present
+* in a given version's grammar appear in that version's map; unknown metrics
+* encountered during validation are ignored (forward-compat).
+*/
+const METRIC_VALUES = {
+	"2.0": {
+		AV: [
+			"L",
+			"A",
+			"N"
+		],
+		AC: [
+			"H",
+			"M",
+			"L"
+		],
+		Au: [
+			"M",
+			"S",
+			"N"
+		],
+		C: [
+			"N",
+			"P",
+			"C"
+		],
+		I: [
+			"N",
+			"P",
+			"C"
+		],
+		A: [
+			"N",
+			"P",
+			"C"
+		],
+		E: [
+			"U",
+			"POC",
+			"F",
+			"H",
+			"ND"
+		],
+		RL: [
+			"OF",
+			"TF",
+			"W",
+			"U",
+			"ND"
+		],
+		RC: [
+			"UC",
+			"UR",
+			"C",
+			"ND"
+		],
+		CDP: [
+			"N",
+			"L",
+			"LM",
+			"MH",
+			"H",
+			"ND"
+		],
+		TD: [
+			"N",
+			"L",
+			"M",
+			"H",
+			"ND"
+		],
+		CR: [
+			"L",
+			"M",
+			"H",
+			"ND"
+		],
+		IR: [
+			"L",
+			"M",
+			"H",
+			"ND"
+		],
+		AR: [
+			"L",
+			"M",
+			"H",
+			"ND"
+		]
+	},
+	"3.0": {
+		AV: [
+			"N",
+			"A",
+			"L",
+			"P"
+		],
+		AC: ["L", "H"],
+		PR: [
+			"N",
+			"L",
+			"H"
+		],
+		UI: ["N", "R"],
+		S: ["U", "C"],
+		C: [
+			"N",
+			"L",
+			"H"
+		],
+		I: [
+			"N",
+			"L",
+			"H"
+		],
+		A: [
+			"N",
+			"L",
+			"H"
+		],
+		E: [
+			"X",
+			"U",
+			"P",
+			"F",
+			"H"
+		],
+		RL: [
+			"X",
+			"O",
+			"T",
+			"W",
+			"U"
+		],
+		RC: [
+			"X",
+			"U",
+			"R",
+			"C"
+		],
+		CR: [
+			"X",
+			"L",
+			"M",
+			"H"
+		],
+		IR: [
+			"X",
+			"L",
+			"M",
+			"H"
+		],
+		AR: [
+			"X",
+			"L",
+			"M",
+			"H"
+		],
+		MAV: [
+			"X",
+			"N",
+			"A",
+			"L",
+			"P"
+		],
+		MAC: [
+			"X",
+			"L",
+			"H"
+		],
+		MPR: [
+			"X",
+			"N",
+			"L",
+			"H"
+		],
+		MUI: [
+			"X",
+			"N",
+			"R"
+		],
+		MS: [
+			"X",
+			"U",
+			"C"
+		],
+		MC: [
+			"X",
+			"N",
+			"L",
+			"H"
+		],
+		MI: [
+			"X",
+			"N",
+			"L",
+			"H"
+		],
+		MA: [
+			"X",
+			"N",
+			"L",
+			"H"
+		]
+	},
+	"3.1": {
+		AV: [
+			"N",
+			"A",
+			"L",
+			"P"
+		],
+		AC: ["L", "H"],
+		PR: [
+			"N",
+			"L",
+			"H"
+		],
+		UI: ["N", "R"],
+		S: ["U", "C"],
+		C: [
+			"N",
+			"L",
+			"H"
+		],
+		I: [
+			"N",
+			"L",
+			"H"
+		],
+		A: [
+			"N",
+			"L",
+			"H"
+		],
+		E: [
+			"X",
+			"U",
+			"P",
+			"F",
+			"H"
+		],
+		RL: [
+			"X",
+			"O",
+			"T",
+			"W",
+			"U"
+		],
+		RC: [
+			"X",
+			"U",
+			"R",
+			"C"
+		],
+		CR: [
+			"X",
+			"L",
+			"M",
+			"H"
+		],
+		IR: [
+			"X",
+			"L",
+			"M",
+			"H"
+		],
+		AR: [
+			"X",
+			"L",
+			"M",
+			"H"
+		],
+		MAV: [
+			"X",
+			"N",
+			"A",
+			"L",
+			"P"
+		],
+		MAC: [
+			"X",
+			"L",
+			"H"
+		],
+		MPR: [
+			"X",
+			"N",
+			"L",
+			"H"
+		],
+		MUI: [
+			"X",
+			"N",
+			"R"
+		],
+		MS: [
+			"X",
+			"U",
+			"C"
+		],
+		MC: [
+			"X",
+			"N",
+			"L",
+			"H"
+		],
+		MI: [
+			"X",
+			"N",
+			"L",
+			"H"
+		],
+		MA: [
+			"X",
+			"N",
+			"L",
+			"H"
+		]
+	},
+	"4.0": {
+		AV: [
+			"N",
+			"A",
+			"L",
+			"P"
+		],
+		AC: ["L", "H"],
+		AT: ["N", "P"],
+		PR: [
+			"N",
+			"L",
+			"H"
+		],
+		UI: [
+			"N",
+			"P",
+			"A"
+		],
+		VC: [
+			"H",
+			"L",
+			"N"
+		],
+		VI: [
+			"H",
+			"L",
+			"N"
+		],
+		VA: [
+			"H",
+			"L",
+			"N"
+		],
+		SC: [
+			"H",
+			"L",
+			"N"
+		],
+		SI: [
+			"H",
+			"L",
+			"N"
+		],
+		SA: [
+			"H",
+			"L",
+			"N"
+		],
+		E: [
+			"X",
+			"A",
+			"P",
+			"U"
+		],
+		MAV: [
+			"X",
+			"N",
+			"A",
+			"L",
+			"P"
+		],
+		MAC: [
+			"X",
+			"L",
+			"H"
+		],
+		MAT: [
+			"X",
+			"N",
+			"P"
+		],
+		MPR: [
+			"X",
+			"N",
+			"L",
+			"H"
+		],
+		MUI: [
+			"X",
+			"N",
+			"P",
+			"A"
+		],
+		MVC: [
+			"X",
+			"H",
+			"L",
+			"N"
+		],
+		MVI: [
+			"X",
+			"H",
+			"L",
+			"N"
+		],
+		MVA: [
+			"X",
+			"H",
+			"L",
+			"N"
+		],
+		MSC: [
+			"X",
+			"H",
+			"L",
+			"N"
+		],
+		MSI: [
+			"X",
+			"S",
+			"H",
+			"L",
+			"N"
+		],
+		MSA: [
+			"X",
+			"S",
+			"H",
+			"L",
+			"N"
+		],
+		CR: [
+			"X",
+			"H",
+			"M",
+			"L"
+		],
+		IR: [
+			"X",
+			"H",
+			"M",
+			"L"
+		],
+		AR: [
+			"X",
+			"H",
+			"M",
+			"L"
+		],
+		S: [
+			"X",
+			"N",
+			"P"
+		],
+		AU: [
+			"X",
+			"N",
+			"Y"
+		],
+		R: [
+			"X",
+			"A",
+			"U",
+			"I"
+		],
+		V: [
+			"X",
+			"D",
+			"C"
+		],
+		RE: [
+			"X",
+			"L",
+			"M",
+			"H"
+		],
+		U: [
+			"X",
+			"Clear",
+			"Green",
+			"Amber",
+			"Red"
+		]
+	}
+};
+const REQUIRED_METRICS = {
+	"2.0": [
+		"AV",
+		"AC",
+		"Au",
+		"C",
+		"I",
+		"A"
+	],
+	"3.0": [
+		"AV",
+		"AC",
+		"PR",
+		"UI",
+		"S",
+		"C",
+		"I",
+		"A"
+	],
+	"3.1": [
+		"AV",
+		"AC",
+		"PR",
+		"UI",
+		"S",
+		"C",
+		"I",
+		"A"
+	],
+	"4.0": [
+		"AV",
+		"AC",
+		"AT",
+		"PR",
+		"UI",
+		"VC",
+		"VI",
+		"VA",
+		"SC",
+		"SI",
+		"SA"
+	]
+};
+/**
+* Parse a CVSS vector string into version + metric map.
+*
+* Version detection rule: a leading `CVSS:X.Y` segment yields version "X.Y".
+* Otherwise (legacy v2 vectors), version is "2.0". Malformed input yields
+* "unknown" with an empty metric map; no exceptions are thrown.
+*
+* @param vector - CVSS vector string (e.g. "CVSS:3.1/AV:N/AC:L/...")
+* @returns Parsed version + metric map
+*/
+function parseCvssVector(vector) {
+	const metrics = /* @__PURE__ */ new Map();
+	if (typeof vector !== "string" || vector.length === 0) return {
+		version: "unknown",
+		metrics
+	};
+	const segments = vector.split("/").filter((s) => s.length > 0);
+	if (segments.length === 0) return {
+		version: "unknown",
+		metrics
+	};
+	let version = "2.0";
+	let start = 0;
+	const first = segments[0];
+	if (first === void 0) return {
+		version: "unknown",
+		metrics
+	};
+	if (first.startsWith("CVSS:")) {
+		version = first.slice(5);
+		start = 1;
+	} else if (!first.includes(":")) return {
+		version: "unknown",
+		metrics
+	};
+	for (let i = start; i < segments.length; i++) {
+		const seg = segments[i];
+		if (seg === void 0) continue;
+		const colon = seg.indexOf(":");
+		if (colon <= 0 || colon === seg.length - 1) continue;
+		const key = seg.slice(0, colon);
+		const value = seg.slice(colon + 1);
+		metrics.set(key, value);
+	}
+	return {
+		version,
+		metrics
+	};
+}
+/**
+* Validate a CVSS vector string against the FIRST grammar for its version.
+*
+* Checks:
+*  - Version is one of the supported set (2.0, 3.0, 3.1, 4.0).
+*  - All required base metrics for the version are present.
+*  - All known metric values are within the allowed enum.
+*
+* Unknown metric keys are tolerated (forward-compat with future minor versions
+* or scanner-specific extensions). To check a v2 vector without the CVSS:
+* prefix, callers may pass version="2.0" explicitly; otherwise the parser
+* defaults to "2.0" on prefix absence.
+*
+* @param vector  - CVSS vector string
+* @param version - Optional explicit version override (else inferred)
+* @returns `{ valid, errors[] }` — never throws
+*/
+function validateCvssVector(vector, version) {
+	const errors = [];
+	if (typeof vector !== "string" || vector.length === 0) return {
+		valid: false,
+		errors: ["vector is empty"]
+	};
+	const parsed = parseCvssVector(vector);
+	const v = version ?? parsed.version;
+	const grammar = METRIC_VALUES[v];
+	const required = REQUIRED_METRICS[v];
+	if (!grammar || !required) {
+		errors.push(`unsupported CVSS version: ${v}`);
+		return {
+			valid: false,
+			errors
+		};
+	}
+	for (const req of required) if (!parsed.metrics.has(req)) errors.push(`missing required metric: ${req}`);
+	for (const [key, value] of parsed.metrics.entries()) {
+		const allowed = grammar[key];
+		if (!allowed) continue;
+		if (!allowed.includes(value)) errors.push(`invalid value for metric ${key}: ${value} (allowed: ${allowed.join(",")})`);
+	}
+	return {
+		valid: errors.length === 0,
+		errors
+	};
+}
+//#endregion
+//#region src/cpe/index.ts
+const CPE_PREFIX = "cpe:2.3:";
+const EXPECTED_TOTAL_FIELDS = 13;
+const PRODUCT_FIELD_COUNT = 11;
+const VALID_PARTS = new Set([
+	"a",
+	"o",
+	"h",
+	"*"
+]);
+/**
+* Split a CPE 2.3 body on unescaped `:` separators.
+*
+* Per CPE 2.3 spec section 6.1.2.4, `:` and `\` inside a field must be
+* escaped as `\:` and `\\`. We respect those escapes during the split and
+* unescape the result.
+*/
+function splitOnUnescapedColons(body) {
+	const result = [];
+	let current = "";
+	for (let i = 0; i < body.length; i++) {
+		const ch = body[i];
+		if (ch === "\\" && i + 1 < body.length) {
+			const next = body[i + 1];
+			if (next === ":" || next === "\\") {
+				current += next;
+				i++;
+				continue;
+			}
+			current += ch;
+			continue;
+		}
+		if (ch === ":") {
+			result.push(current);
+			current = "";
+			continue;
+		}
+		current += ch;
+	}
+	result.push(current);
+	return result;
+}
+/**
+* Parse a CPE 2.3 URI.
+*
+* Accept-and-warn semantics:
+* - Input missing the `cpe:2.3:` prefix → returns `null`.
+* - Input with the prefix but fewer than 11 product fields → fields are
+*   padded with `"*"` and a `truncated:` warning is added.
+* - Input with more than 11 product fields → extras are dropped and an
+*   `"extra fields ignored"` warning is added.
+* - Unknown `part` value → kept as-is in the result, `"unknown part: X"`
+*   warning is added.
+* - `\:` and `\\` escapes inside fields are honored during splitting and
+*   unescaped in the returned field values.
+*
+* @param cpeUri - CPE 2.3 URI string
+* @returns Parsed CPE with warnings, or `null` if input lacks the prefix
+*
+* @example
+* ```typescript
+* parseCpe('cpe:2.3:a:openssl:openssl:1.1.1k:*:*:*:*:*:*:*');
+* // { part: 'a', vendor: 'openssl', product: 'openssl', version: '1.1.1k', ... warnings: [] }
+*
+* parseCpe('cpe:2.3:a:openssl:openssl:1.1.1k');
+* // truncated input → padded with '*', warnings: ['truncated: expected 13 colon-separated fields, got 6']
+*
+* parseCpe('openssl:1.1.1k'); // null — no prefix
+* ```
+*/
+function parseCpe(cpeUri) {
+	if (!cpeUri.startsWith(CPE_PREFIX)) return null;
+	const warnings = [];
+	const body = cpeUri.slice(8);
+	const isBarePrefix = body.length === 0;
+	const bodyParts = isBarePrefix ? [] : splitOnUnescapedColons(body);
+	const totalFields = isBarePrefix ? 2 : 2 + bodyParts.length;
+	if (bodyParts.length > PRODUCT_FIELD_COUNT) warnings.push("extra fields ignored");
+	else if (bodyParts.length < PRODUCT_FIELD_COUNT) warnings.push(`truncated: expected ${EXPECTED_TOTAL_FIELDS} colon-separated fields, got ${totalFields}`);
+	const padValue = isBarePrefix ? "" : "*";
+	const fields = bodyParts.slice(0, PRODUCT_FIELD_COUNT);
+	while (fields.length < PRODUCT_FIELD_COUNT) fields.push(padValue);
+	const [part = "", vendor = "", product = "", version = "", update = "", edition = "", language = "", swEdition = "", targetSw = "", targetHw = "", other = ""] = fields;
+	if (!VALID_PARTS.has(part)) warnings.push(`unknown part: ${part}`);
+	return {
+		raw: cpeUri,
+		part,
+		vendor,
+		product,
+		version,
+		update,
+		edition,
+		language,
+		swEdition,
+		targetSw,
+		targetHw,
+		other,
+		warnings
+	};
+}
+//#endregion
+//#region src/purl/index.ts
+const PURL_PREFIX = "pkg:";
+/**
+* Parse a Package URL string.
+*
+* Returns `null` only when the input is missing the mandatory `pkg:` prefix
+* or the type segment. Other deviations are surfaced via `warnings` on the
+* returned object.
+*
+* @param purlStr - PURL string, e.g. `pkg:npm/lodash@4.17.21`
+* @returns Parsed PURL or `null` if the input is unrecoverably malformed
+*
+* @example
+* ```typescript
+* const r = parsePurl('pkg:rpm/redhat/openssl@1.1.1k-7.el8_4?arch=x86_64');
+* r?.type;                    // "rpm"
+* r?.namespace;               // "redhat"
+* r?.name;                    // "openssl"
+* r?.qualifiers.get('arch');  // "x86_64"
+* ```
+*/
+function parsePurl(purlStr) {
+	if (!purlStr || !purlStr.startsWith(PURL_PREFIX)) return null;
+	const raw = purlStr;
+	const warnings = [];
+	let remainder = purlStr.slice(4);
+	while (remainder.startsWith("/")) remainder = remainder.slice(1);
+	if (remainder.length === 0) return null;
+	let subpath = null;
+	const hashIdx = remainder.indexOf("#");
+	if (hashIdx !== -1) {
+		subpath = remainder.slice(hashIdx + 1);
+		remainder = remainder.slice(0, hashIdx);
+		if (subpath.length === 0) subpath = null;
+	}
+	const qualifiers = /* @__PURE__ */ new Map();
+	const qIdx = remainder.indexOf("?");
+	if (qIdx !== -1) {
+		const qStr = remainder.slice(qIdx + 1);
+		remainder = remainder.slice(0, qIdx);
+		parseQualifiers(qStr, qualifiers, warnings);
+	}
+	while (remainder.endsWith("/")) remainder = remainder.slice(0, -1);
+	const firstSlash = remainder.indexOf("/");
+	let type;
+	let pathPart;
+	if (firstSlash === -1) {
+		type = remainder;
+		pathPart = "";
+	} else {
+		type = remainder.slice(0, firstSlash);
+		pathPart = remainder.slice(firstSlash + 1);
+	}
+	if (type.length === 0) return null;
+	type = type.toLowerCase();
+	let version = null;
+	const lastAt = pathPart.lastIndexOf("@");
+	let nameAndNs = pathPart;
+	if (lastAt !== -1) {
+		version = pathPart.slice(lastAt + 1);
+		nameAndNs = pathPart.slice(0, lastAt);
+		version = safeDecode(version);
+	}
+	let namespace = null;
+	let name;
+	const lastSlash = nameAndNs.lastIndexOf("/");
+	if (lastSlash === -1) name = nameAndNs;
+	else {
+		namespace = nameAndNs.slice(0, lastSlash);
+		name = nameAndNs.slice(lastSlash + 1);
+	}
+	if (namespace !== null) namespace = namespace.split("/").map(safeDecode).join("/");
+	name = safeDecode(name);
+	if (name.length === 0) warnings.push("PURL is missing the name segment");
+	if (namespace !== null && namespace.length === 0) namespace = null;
+	if (version !== null && version.length === 0) version = null;
+	return {
+		raw,
+		type,
+		namespace,
+		name,
+		version,
+		qualifiers,
+		subpath,
+		warnings
+	};
+}
+/**
+* Parse the `?key=value&key=value` qualifier string. Empty segments are
+* skipped silently; segments with no `=` are recorded with empty value and
+* a warning. Values are URL-decoded.
+*/
+function parseQualifiers(qStr, out, warnings) {
+	const parts = qStr.split("&");
+	for (const part of parts) {
+		if (part.length === 0) continue;
+		const eq = part.indexOf("=");
+		if (eq === -1) {
+			out.set(part, "");
+			warnings.push(`qualifier "${part}" has no value`);
+			continue;
+		}
+		const key = part.slice(0, eq);
+		const value = part.slice(eq + 1);
+		out.set(key, safeDecode(value));
+	}
+}
+/**
+* decodeURIComponent that returns the original string on failure rather than
+* throwing. PURLs in the wild occasionally contain stray `%` characters that
+* aren't legitimate percent-encoding.
+*/
+function safeDecode(s) {
+	try {
+		return decodeURIComponent(s);
+	} catch {
+		return s;
+	}
+}
 //#endregion
-export { buildCsv, buildCsvArray, buildXml, extractColumn, extractColumn as extractCsvColumn, extractTextFromXml, findRows as findCsvRows, findRows, findValuesByKey as findJsonValues, findValuesByKey, findValuesByKey as findXmlValues, generateHash, hashObject, impactToSeverity, isValidCsv, isValidJSON, isValidXml, parseCsv, parseCsvArray, parseJSON, parseTimestamp, parseXml, parseXmlWithArrays, sanitizeCsvArray, sanitizeCsvObject, sanitizeCsvValue, severityToImpact, sha256, sha512, stringifyJSON, stripHtml, verifyHash };
+export { buildCsv, buildCsvArray, buildXml, cvssScoreToSeverity, extractColumn, extractColumn as extractCsvColumn, extractTextFromXml, findRows as findCsvRows, findRows, findValuesByKey as findJsonValues, findValuesByKey, findValuesByKey as findXmlValues, generateHash, hashObject, impactToSeverity, isValidCsv, isValidJSON, isValidXml, parseCpe, parseCsv, parseCsvArray, parseCvssVector, parseJSON, parsePurl, parseTimestamp, parseXml, parseXmlWithArrays, sanitizeCsvArray, sanitizeCsvObject, sanitizeCsvValue, severityToImpact, sha256, sha512, stringifyJSON, stripHtml, validateCvssVector, verifyHash };
 
 //# sourceMappingURL=index.js.map