@cdxgen/cdxgen 0.0.1 → 13.0.1

package/lib/inventory/osinfo.js

@@ -0,0 +1,383 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * Ubuntu / Debian codename map and RHEL display-name aliases.
+ * Keep this list updated every year.
+ */
+export const OS_DISTRO_ALIAS = {
+  "ubuntu-4.10": "warty",
+  "ubuntu-5.04": "hoary",
+  "ubuntu-5.10": "breezy",
+  "ubuntu-6.06": "dapper",
+  "ubuntu-6.10": "edgy",
+  "ubuntu-7.04": "feisty",
+  "ubuntu-7.10": "gutsy",
+  "ubuntu-8.04": "hardy",
+  "ubuntu-8.10": "intrepid",
+  "ubuntu-9.04": "jaunty",
+  "ubuntu-9.10": "karmic",
+  "ubuntu-10.04": "lucid",
+  "ubuntu-10.10": "maverick",
+  "ubuntu-11.04": "natty",
+  "ubuntu-11.10": "oneiric",
+  "ubuntu-12.04": "precise",
+  "ubuntu-12.10": "quantal",
+  "ubuntu-13.04": "raring",
+  "ubuntu-13.10": "saucy",
+  "ubuntu-14.04": "trusty",
+  "ubuntu-14.10": "utopic",
+  "ubuntu-15.04": "vivid",
+  "ubuntu-15.10": "wily",
+  "ubuntu-16.04": "xenial",
+  "ubuntu-16.10": "yakkety",
+  "ubuntu-17.04": "zesty",
+  "ubuntu-17.10": "artful",
+  "ubuntu-18.04": "bionic",
+  "ubuntu-18.10": "cosmic",
+  "ubuntu-19.04": "disco",
+  "ubuntu-19.10": "eoan",
+  "ubuntu-20.04": "focal",
+  "ubuntu-20.10": "groovy",
+  "ubuntu-21.04": "hirsute",
+  "ubuntu-21.10": "impish",
+  "ubuntu-22.04": "jammy",
+  "ubuntu-22.10": "kinetic",
+  "ubuntu-23.04": "lunar",
+  "ubuntu-23.10": "mantic",
+  "ubuntu-24.04": "noble",
+  "ubuntu-24.10": "oracular",
+  "ubuntu-25.04": "plucky",
+  "ubuntu-25.10": "questing",
+  "debian-15": "duke",
+  "debian-14": "forky",
+  "debian-14.5": "forky",
+  "debian-13": "trixie",
+  "debian-13.5": "trixie",
+  "debian-12": "bookworm",
+  "debian-12.5": "bookworm",
+  "debian-12.6": "bookworm",
+  "debian-11": "bullseye",
+  "debian-11.5": "bullseye",
+  "debian-10": "buster",
+  "debian-10.5": "buster",
+  "debian-9": "stretch",
+  "debian-9.5": "stretch",
+  "debian-8": "jessie",
+  "debian-8.5": "jessie",
+  "debian-7": "wheezy",
+  "debian-7.5": "wheezy",
+  "debian-6": "squeeze",
+  "debian-5": "lenny",
+  "debian-4": "etch",
+  "debian-3.1": "sarge",
+  "debian-3": "woody",
+  "debian-2.2": "potato",
+  "debian-2.1": "slink",
+  "debian-2": "hamm",
+  "debian-1.3": "bo",
+  "debian-1.2": "rex",
+  "debian-1.1": "buzz",
+  "red hat enterprise linux": "rhel",
+  "red hat enterprise linux 6": "rhel-6",
+  "red hat enterprise linux 7": "rhel-7",
+  "red hat enterprise linux 8": "rhel-8",
+  "red hat enterprise linux 9": "rhel-9",
+  "red hat enterprise linux 10": "rhel-10",
+};
+
+/**
+ * Canonical purl namespace for distro vendors that are published under more
+ * than one spelling. Both the os-release path (`getDistroInfo`) and the trivy
+ * passthrough in `lib/managers/binary.js` route through this single map so the
+ * two paths cannot drift apart again.
+ *
+ * Azure Linux 2.0 is CBL-Mariner 2.0 — Microsoft renamed the product — and the
+ * OSV feed publishes `pkg:rpm/azure-linux/<name>` for every generation
+ * (ecosystems "Azure Linux:2" and "Azure Linux:3"), so the historical
+ * spellings azurelinux, cbl-mariner and mariner all canonicalise to
+ * "azure-linux". rhel/ol/amzn/opensuse-* are the cases previously inlined in
+ * getDistroInfo(); alma/rocky-linux were previously inlined in binary.js.
+ *
+ * Amazon Linux canonicalises to "amazon", the spelling the vulnerability feeds
+ * publish (AppThreat vuln-list `amazon`): the os-release ID is `amzn` and
+ * trivy emits `amazon`, and the previous `amazonlinux` mapping here matched
+ * neither, so live-host Amazon Linux purls matched nothing at all.
+ */
+export const OS_NAMESPACE_ALIAS = {
+  alma: "almalinux",
+  amazonlinux: "amazon",
+  amzn: "amazon",
+  azurelinux: "azure-linux",
+  "cbl-mariner": "azure-linux",
+  mariner: "azure-linux",
+  ol: "oracle",
+  "opensuse-leap": "opensuse",
+  "opensuse-tumbleweed": "opensuse",
+  rhel: "redhat",
+  "rocky-linux": "rocky",
+};
+
+/**
+ * Vendor prefixes that `distro` qualifier values are canonicalised for, so one
+ * release has exactly one qualifier value no matter which side produced it.
+ *
+ * trivy stamps the qualifier from its own distro table while cdxgen stamps it
+ * from os-release, and the two disagree: an Oracle Linux 9.8 image came out
+ * with `oracle-9.8` on 99 components and `ol-9.8` on 43, and a RHEL 9.8 image
+ * with namespace `redhat` but qualifier `rhel-9.8`. Canonicalising both sides
+ * through this map collapses each release onto the vendor its purl namespace
+ * already uses.
+ *
+ * SUSE is deliberately absent. `sles-15.6`, `opensuse-leap-15.6` and
+ * `opensuse-tumbleweed-<snapshot>` are the values consumers derive the release
+ * channel from (vulnerability-db maps them to per-release channels), and both
+ * sides already agree on them; folding Leap and Tumbleweed onto a bare
+ * `opensuse-` vendor would destroy exactly the distinction that matters.
+ *
+ * Keys are matched longest-first so `cbl-mariner-2.0` resolves against the
+ * full vendor segment rather than a shorter prefix.
+ */
+export const OS_DISTRO_QUALIFIER_ALIAS = {
+  alma: "almalinux",
+  amazonlinux: "amazon",
+  amzn: "amazon",
+  azurelinux: "azure-linux",
+  "cbl-mariner": "azure-linux",
+  mariner: "azure-linux",
+  ol: "oracle",
+  rhel: "redhat",
+  "rocky-linux": "rocky",
+};
+
+// A distro qualifier reaches a purl verbatim, so anything outside the purl
+// qualifier charset makes the whole purl — and with it the whole BOM —
+// invalid. trivy emits Amazon Linux as
+// `amazon-2023.12.20260727+(Amazon Linux)`, which failed cdxgen's own schema
+// validation and cost the entire SBOM.
+const SAFE_DISTRO_QUALIFIER = /^[A-Za-z0-9._-]+$/;
+
+/**
+ * Whether a `distro` qualifier value is safe to place in a purl unencoded.
+ *
+ * @param {string} qualifier - distro qualifier value
+ * @returns {boolean} true when the value contains only purl-safe characters
+ */
+export function isCleanDistroQualifier(qualifier) {
+  return !!qualifier && SAFE_DISTRO_QUALIFIER.test(qualifier);
+}
+
+const OS_DISTRO_QUALIFIER_ALIAS_KEYS = Object.keys(
+  OS_DISTRO_QUALIFIER_ALIAS,
+).sort((a, b) => b.length - a.length);
+
+/**
+ * Canonicalise the vendor prefix of a `distro` qualifier value
+ * (e.g. "cbl-mariner-2.0" or "mariner-2.0" -> "azure-linux-2.0") so a release
+ * has exactly one qualifier spelling regardless of which tool emitted it.
+ * Values without a known vendor prefix are returned unchanged.
+ *
+ * @param {string} qualifier - distro qualifier value such as "azurelinux-3.0"
+ * @returns {string} canonical qualifier value
+ */
+export function canonicalDistroQualifier(qualifier) {
+  if (!qualifier) {
+    return qualifier;
+  }
+  for (const key of OS_DISTRO_QUALIFIER_ALIAS_KEYS) {
+    if (qualifier.startsWith(`${key}-`)) {
+      return `${OS_DISTRO_QUALIFIER_ALIAS[key]}${qualifier.slice(key.length)}`;
+    }
+  }
+  return qualifier;
+}
+
+// ---------------------------------------------------------------------------
+// Raw os-release cache — keyed by the osRelease file path so the live-host
+// cache (/etc/os-release) and any container rootfs path are kept separate.
+// ---------------------------------------------------------------------------
+const _osReleaseCache = new Map();
+
+/**
+ * Parse an os-release file from an arbitrary root path and return a plain
+ * key→value object.  Results are cached per root path so the file is read
+ * at most once per process per distinct root.
+ *
+ * @param {string} [root="/"] - Root of the filesystem to search (e.g. a
+ *   container rootfs extracted to a temp directory, or "/" for the live host).
+ * @returns {Object} Raw key/value pairs from the os-release file.
+ */
+export function readOsRelease(root = "/") {
+  if (_osReleaseCache.has(root)) {
+    return _osReleaseCache.get(root);
+  }
+
+  // Candidate locations, in preference order
+  const candidates = [
+    join(root, "etc", "os-release"),
+    join(root, "usr", "lib", "os-release"),
+  ];
+
+  const data = {};
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) {
+      try {
+        const content = readFileSync(candidate, "utf-8");
+        for (const line of content.split("\n")) {
+          if (line.startsWith("#") || !line.includes("=")) {
+            continue;
+          }
+          const eqIdx = line.indexOf("=");
+          const key = line.substring(0, eqIdx).trim();
+          const raw = line.substring(eqIdx + 1).trim();
+          // Strip surrounding single or double quotes
+          data[key] = raw.replace(/^["']|["']$/g, "");
+        }
+        break; // Stop at the first readable file
+      } catch (_e) {
+        // Try the next candidate
+      }
+    }
+  }
+
+  _osReleaseCache.set(root, data);
+  return data;
+}
+
+// Exported only for unit tests — resets the per-root cache.
+/**
+ * Reset the per-root os-release cache. Exported for unit tests only.
+ */
+export function _resetOsReleaseCache() {
+  _osReleaseCache.clear();
+}
+
+/**
+ * Derive structured distro information from an os-release file.
+ *
+ * Returns an object with:
+ *   - purlType    {string}  "deb" | "apk" | "rpm"
+ *   - namespace   {string}  canonical purl namespace (e.g. "ubuntu", "alpine",
+ *                           "azure-linux" for both Azure Linux and CBL-Mariner)
+ *   - distroId    {string}  ID + "-" + VERSION_ID with a canonical vendor
+ *                           prefix (e.g. "ubuntu-22.04", "azure-linux-3.0")
+ *   - distroName  {string}  codename/alias          (e.g. "jammy")
+ *
+ * Mirrors the logic in lib/managers/binary.js getOSPackages() so that both
+ * callers share a single implementation.
+ *
+ * @param {string} [root="/"] - Filesystem root to look for os-release.
+ * @returns {{ purlType: string, namespace: string, distroId: string, distroName: string }}
+ */
+export function getDistroInfo(root = "/") {
+  const info = readOsRelease(root);
+
+  const rawId = (info.ID || "").toLowerCase();
+  const idLike = (info.ID_LIKE || "").toLowerCase();
+  const versionId = info.VERSION_ID || "";
+
+  // Determine the purl type
+  let purlType = "rpm"; // safe default for unknown Linux
+  switch (rawId) {
+    case "debian":
+    case "ubuntu":
+    case "pop":
+    case "kali":
+    case "raspbian":
+    case "linuxmint":
+      purlType = "deb";
+      break;
+    case "alpine":
+    case "openwrt":
+      purlType = "apk";
+      break;
+    case "sles":
+    case "suse":
+    case "opensuse":
+    case "opensuse-leap":
+    case "opensuse-tumbleweed":
+    case "fedora":
+    case "rhel":
+    case "centos":
+    case "rocky":
+    case "almalinux":
+    case "azurelinux":
+    case "cbl-mariner":
+    case "mariner":
+    case "oracle":
+    case "ol":
+    case "amzn":
+    case "mageia":
+    case "photon":
+      purlType = "rpm";
+      break;
+    default:
+      if (idLike.includes("debian") || idLike.includes("ubuntu")) {
+        purlType = "deb";
+      } else if (idLike.includes("alpine")) {
+        purlType = "apk";
+      } else if (
+        idLike.includes("rhel") ||
+        idLike.includes("centos") ||
+        idLike.includes("fedora") ||
+        idLike.includes("suse")
+      ) {
+        purlType = "rpm";
+      }
+      break;
+  }
+
+  // Determine the purl namespace (vendor), canonicalising vendors that are
+  // published under several spellings (e.g. mariner -> azure-linux)
+  let namespace = OS_NAMESPACE_ALIAS[rawId] || rawId;
+  if (!rawId) {
+    // Fallback via ID_LIKE
+    if (idLike.includes("rhel") || idLike.includes("centos")) {
+      namespace = "redhat";
+    } else if (idLike.includes("fedora")) {
+      namespace = "fedora";
+    } else if (idLike.includes("suse")) {
+      namespace = "opensuse";
+    } else if (idLike.includes("debian")) {
+      namespace = "debian";
+    } else if (idLike.includes("ubuntu")) {
+      namespace = "ubuntu";
+    } else {
+      namespace = "linux";
+    }
+  }
+
+  // Build distroId = ID-VERSION_ID (e.g. "fedora-25", "alpine-3.17"),
+  // canonicalising the vendor prefix so one release has a single qualifier
+  // value (e.g. "mariner-2.0" and "azurelinux-3.0" -> "azure-linux-2.0"/
+  // "azure-linux-3.0")
+  let distroId = versionId ? `${rawId}-${versionId}` : rawId;
+  distroId = canonicalDistroQualifier(distroId);
+
+  // Special-case Alpine: truncate to major.minor
+  if (purlType === "apk" && versionId) {
+    const parts = versionId.split(".");
+    if (parts.length >= 2) {
+      distroId = `${rawId}-${parts[0]}.${parts[1]}`;
+    }
+  }
+
+  // Determine codename / alias
+  let distroName =
+    info.VERSION_CODENAME ||
+    info.CENTOS_MANTISBT_PROJECT ||
+    info.REDHAT_BUGZILLA_PRODUCT ||
+    info.REDHAT_SUPPORT_PRODUCT ||
+    "";
+  distroName = distroName.toLowerCase();
+
+  // Resolve well-known display name aliases
+  if (distroName.includes(" ") && OS_DISTRO_ALIAS[distroName]) {
+    distroName = OS_DISTRO_ALIAS[distroName];
+  }
+  if (!distroName && OS_DISTRO_ALIAS[distroId]) {
+    distroName = OS_DISTRO_ALIAS[distroId];
+  }
+
+  return { purlType, namespace, distroId, distroName };
+}

package/lib/inventory/osqueryTransform.js

@@ -0,0 +1,274 @@
+import { getDistroInfo } from "./osinfo.js";
+import { tryBuildPurl } from "./purl.js";
+
+/**
+ * Derive a version value from an osquery result row.
+ *
+ * Falls back through alternate row fields (e.g. `hotfix_id`, `port`, `pid`)
+ * that carry version-like values for the given query category.
+ *
+ * @param {Object} res osquery result row
+ * @returns {string|undefined} First present version-like field value
+ */
+export function deriveOsQueryVersion(res) {
+  return (
+    res.version ||
+    res.hotfix_id ||
+    res.hardware_version ||
+    res.port ||
+    res.pid ||
+    res.subject_key_id ||
+    res.interface ||
+    res.instance_id
+  );
+}
+
+/**
+ * Derive a name value from an osquery result row.
+ *
+ * @param {Object} res osquery result row
+ * @param {boolean} singleResult Whether the query returned exactly one row
+ * @param {string} queryName Query name used as a fallback name for single-result queries
+ * @returns {string|undefined} First present name-like field value
+ */
+export function deriveOsQueryName(res, singleResult, queryName) {
+  let name =
+    res.name ||
+    res.device_id ||
+    res.hotfix_id ||
+    res.uuid ||
+    res.serial ||
+    res.pid ||
+    res.address ||
+    res.ami_id ||
+    res.interface ||
+    res.client_app_id;
+  if (!name && singleResult && queryName) {
+    name = queryName;
+  }
+  return name;
+}
+
+/**
+ * Derive a publisher value from an osquery result row.
+ *
+ * @param {Object} res osquery result row
+ * @returns {string} Publisher-like value, or an empty string when absent or literal `"null"`
+ */
+export function deriveOsQueryPublisher(res) {
+  const publisher =
+    res.publisher ||
+    res.maintainer ||
+    res.creator ||
+    res.manufacturer ||
+    res.provider ||
+    "";
+  return publisher === "null" ? "" : publisher;
+}
+
+/**
+ * Derive a description value from an osquery result row.
+ *
+ * @param {Object} res osquery result row
+ * @returns {string} First present description-like field value, or an empty string
+ */
+export function deriveOsQueryDescription(res) {
+  return (
+    res.description ||
+    res.summary ||
+    res.arguments ||
+    res.device ||
+    res.codename ||
+    res.section ||
+    res.status ||
+    res.identifier ||
+    res.components ||
+    ""
+  );
+}
+
+/**
+ * Sanitize an identity string for use in component names and references.
+ *
+ * @param {string} value Raw identity value
+ * @returns {string} Value with spaces mapped to `+`, `:`/`%` mapped to `-`, and `@`/brace delimiters trimmed
+ */
+export function sanitizeOsQueryIdentity(value) {
+  return String(value || "")
+    .replace(/ /g, "+")
+    .replace(/[:%]/g, "-")
+    .replace(/^[@{]/g, "")
+    .replace(/[}]$/g, "");
+}
+
+/**
+ * Sanitize a value for safe use inside a `bom-ref`.
+ *
+ * @param {string} value Raw value
+ * @param {string} [fallback="unknown"] Value returned when the input is empty or `"null"`
+ * @returns {string} Whitespace-collapsed value with bom-ref delimiters replaced by `-`
+ */
+export function sanitizeOsQueryBomRefValue(value, fallback = "unknown") {
+  const normalizedValue = String(value || "")
+    .replace(/[\r\n\t]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!normalizedValue || normalizedValue === "null") {
+    return fallback;
+  }
+  return normalizedValue.replace(/[:@#\[\]=]/g, "-");
+}
+
+/**
+ * Build a deterministic fallback `bom-ref` for an osquery-derived component.
+ *
+ * @param {string} queryCategory Osquery category (e.g. `deb_packages`)
+ * @param {string} componentType CycloneDX component type
+ * @param {string|undefined} name Component name
+ * @param {string|undefined} version Component version
+ * @param {string|undefined} identityField Row field used to distinguish the component's identity
+ * @param {string|undefined} identityValue Value of the identity field
+ * @returns {string} BOM ref of the form `osquery:<category>:<type>:<name>@<version>[<field>=<value>]`
+ */
+export function createOsQueryFallbackBomRef(
+  queryCategory,
+  componentType,
+  name,
+  version,
+  identityField,
+  identityValue,
+) {
+  const categoryRef = sanitizeOsQueryBomRefValue(queryCategory, "component");
+  const componentTypeRef = sanitizeOsQueryBomRefValue(
+    componentType,
+    "component",
+  );
+  const nameRef = sanitizeOsQueryBomRefValue(
+    name || queryCategory,
+    "component",
+  );
+  const versionRef = sanitizeOsQueryBomRefValue(version, "unknown");
+  const baseBomRef = `osquery:${categoryRef}:${componentTypeRef}:${nameRef}@${versionRef}`;
+  if (!identityField || !identityValue) {
+    return baseBomRef;
+  }
+  const identityFieldRef = sanitizeOsQueryBomRefValue(
+    identityField,
+    "identity",
+  );
+  const identityValueRef = sanitizeOsQueryBomRefValue(identityValue, "unknown");
+  return `${baseBomRef}[${identityFieldRef}=${identityValueRef}]`;
+}
+
+/**
+ * Determine whether an osquery-derived component type may carry a purl.
+ *
+ * @param {string} componentType CycloneDX component type
+ * @returns {boolean} `false` for `cryptographic-asset`, `data`, `device`, and `information`
+ */
+export function shouldCreateOsQueryPurl(componentType) {
+  return !["cryptographic-asset", "data", "device", "information"].includes(
+    componentType || "",
+  );
+}
+
+// Purl types whose type rules require a namespace. For OS package types the
+// namespace is the distro vendor (`pkg:deb/debian/...`, `pkg:rpm/redhat/...`),
+// which osquery does not report but /etc/os-release does.
+const NAMESPACE_REQUIRED_TYPES = new Set([
+  "deb",
+  "rpm",
+  "apk",
+  "alpm",
+  "ebuild",
+]);
+
+/**
+ * Construct a purl string for an osquery-derived component.
+ *
+ * Builds through `tryBuildPurl`, so an invalid combination yields `null`
+ * instead of throwing. Derives a swid `tag_id` qualifier when missing and a
+ * distro namespace from `/etc/os-release` for OS package types that require one.
+ *
+ * @param {string} purlType Purl type (e.g. `deb`, `rpm`, `generic`)
+ * @param {string|null} group Purl namespace or group
+ * @param {string} name Component name
+ * @param {string} version Component version
+ * @param {Object|null} qualifiers Purl qualifiers
+ * @param {string|null} subpath Purl subpath (leading slashes are stripped)
+ * @returns {string|null} Canonical purl string, or `null` when the parts do not form a valid purl
+ */
+export function createOsQueryPurl(
+  purlType,
+  group,
+  name,
+  version,
+  qualifiers,
+  subpath,
+) {
+  // cdx-purl rejects absolute subpaths; strip a leading slash so filesystem
+  // paths like /usr/lib/libcrypto.dylib become relative subpath segments.
+  const safeSubpath = subpath ? subpath.replace(/^\/+/, "") : null;
+  const type = purlType || "generic";
+  const finalQualifiers = { ...qualifiers };
+  // swid purls require a tag_id qualifier (ISO/IEC 19770-2). Auto-derive one
+  // from the component name when the caller did not provide one.
+  if (type === "swid" && !finalQualifiers.tag_id) {
+    finalQualifiers.tag_id = name;
+  }
+  // The Linux OS package queries (deb_packages, rpm_packages, portage) yield no
+  // group, but their purl types require a namespace. Derive the vendor from
+  // /etc/os-release the same way osPackageResolver does, so these keep a valid
+  // purl instead of losing one.
+  let namespace = group || null;
+  if (!namespace && NAMESPACE_REQUIRED_TYPES.has(type)) {
+    namespace = getDistroInfo().namespace || null;
+  }
+  // tryBuildPurl rather than build: a component that cannot be expressed as a
+  // valid purl must not abort the whole SBOM. Before this, an unknown distro on
+  // Linux threw E_REQUIRED_COMPONENT out of the middle of createCppBom.
+  return tryBuildPurl({
+    type,
+    namespace,
+    name: name,
+    version: version || null,
+    qualifiers: Object.keys(finalQualifiers).length ? finalQualifiers : null,
+    subpath: safeSubpath,
+  });
+}
+
+function _deriveCertificateFormat(certificateFileExtension) {
+  switch ((certificateFileExtension || "").toLowerCase()) {
+    case "pem":
+      return "PEM";
+    case "der":
+      return "DER";
+    case "cer":
+    case "crt":
+      return "X.509";
+    default:
+      return undefined;
+  }
+}
+
+function _normalizeCertificateDate(value) {
+  if (value === undefined || value === null || value === "") {
+    return undefined;
+  }
+  const stringValue = `${value}`.trim();
+  if (!stringValue) {
+    return undefined;
+  }
+  const numericValue = Number(stringValue);
+  if (Number.isFinite(numericValue)) {
+    const millis = stringValue.length > 10 ? numericValue : numericValue * 1000;
+    const parsedDate = new Date(millis);
+    return Number.isNaN(parsedDate.getTime())
+      ? undefined
+      : parsedDate.toISOString();
+  }
+  const parsedDate = new Date(stringValue);
+  return Number.isNaN(parsedDate.getTime())
+    ? undefined
+    : parsedDate.toISOString();
+}