@cdxgen/cdxgen 0.0.1 → 13.0.0

package/lib/inventory/auditCategories.js

@@ -0,0 +1,192 @@
+import { shouldRunPredictiveBomAudit } from "../core/env.js";
+
+/** Frozen list of hardware-bill-of-materials (HBOM) audit categories. */
+export const HBOM_AUDIT_CATEGORIES = Object.freeze([
+  "hbom-security",
+  "hbom-performance",
+  "hbom-compliance",
+]);
+
+/** Frozen list of cryptographic-bill-of-materials (CBOM) audit categories. */
+export const CBOM_AUDIT_CATEGORIES = Object.freeze([
+  "cbom-security",
+  "cbom-compliance",
+]);
+
+/** Frozen list of host-topology audit categories. */
+export const HOST_TOPOLOGY_AUDIT_CATEGORIES = Object.freeze(["host-topology"]);
+
+/** Frozen list of Golem (Go Evinse) audit categories. */
+export const GOLEM_AUDIT_CATEGORIES = Object.freeze([
+  "golem-security",
+  "golem-performance",
+  "golem-compliance",
+]);
+
+/** Frozen list of AI-bill-of-materials audit categories. */
+export const AI_BOM_AUDIT_CATEGORIES = Object.freeze([
+  "ai-governance",
+  "ai-security",
+  "ai-performance",
+]);
+
+/** Comma-separated default HBOM category string used when none is specified. */
+export const DEFAULT_HBOM_AUDIT_CATEGORIES = HBOM_AUDIT_CATEGORIES.join(",");
+
+/**
+ * Frozen map of category alias names to their expanded concrete category lists.
+ * Used by `expandBomAuditCategories` to resolve shorthand aliases.
+ */
+export const BOM_AUDIT_CATEGORY_ALIASES = Object.freeze({
+  "ai-inventory": ["ai-agent", "mcp-server"],
+  aibom: [...AI_BOM_AUDIT_CATEGORIES, "ai-agent", "mcp-server"],
+  "ai-bom": [...AI_BOM_AUDIT_CATEGORIES, "ai-agent", "mcp-server"],
+  "ai-provenance": ["ai-provenance", "ai-oversight"],
+  "ai-oversight": ["ai-oversight"],
+  cbom: [...CBOM_AUDIT_CATEGORIES],
+  "crypto-bom": [...CBOM_AUDIT_CATEGORIES],
+  golem: [...GOLEM_AUDIT_CATEGORIES],
+  hbom: [...HBOM_AUDIT_CATEGORIES],
+  host: [...HBOM_AUDIT_CATEGORIES, ...HOST_TOPOLOGY_AUDIT_CATEGORIES],
+});
+
+function uniqueNonEmptyCategories(categories) {
+  return [...new Set((categories || []).filter(Boolean))];
+}
+
+/**
+ * Normalize a category string or array into a deduplicated array of trimmed,
+ * non-empty category names.
+ *
+ * @param {string|string[]} categories Comma-separated string or array of categories.
+ * @returns {string[]} Deduplicated, trimmed category names.
+ */
+export function normalizeBomAuditCategories(categories) {
+  if (Array.isArray(categories)) {
+    return uniqueNonEmptyCategories(
+      categories.map((category) => String(category).trim()).filter(Boolean),
+    );
+  }
+  if (typeof categories !== "string") {
+    return [];
+  }
+  return uniqueNonEmptyCategories(
+    categories
+      .split(",")
+      .map((category) => category.trim())
+      .filter(Boolean),
+  );
+}
+
+/**
+ * Expand category aliases into their concrete category lists, returning a
+ * deduplicated array of resolved categories.
+ *
+ * @param {string|string[]} categories Comma-separated string or array of categories or aliases.
+ * @returns {string[]} Deduplicated, fully expanded category names.
+ */
+export function expandBomAuditCategories(categories) {
+  const normalizedCategories = normalizeBomAuditCategories(categories);
+  const expandedCategories = [];
+  for (const category of normalizedCategories) {
+    if (BOM_AUDIT_CATEGORY_ALIASES[category]?.length) {
+      expandedCategories.push(...BOM_AUDIT_CATEGORY_ALIASES[category]);
+      continue;
+    }
+    expandedCategories.push(category);
+  }
+  return uniqueNonEmptyCategories(expandedCategories);
+}
+
+/**
+ * Collect the sorted set of unique categories present in the loaded audit rules.
+ *
+ * @param {Array<{category?: string}>} rules Loaded audit rule objects.
+ * @returns {string[]} Sorted unique category names found in the rules.
+ */
+export function availableBomAuditCategories(rules) {
+  return uniqueNonEmptyCategories(
+    (rules || []).map((rule) => rule?.category).filter(Boolean),
+  ).sort();
+}
+
+function formatBomAuditCategoryOption(category) {
+  const aliasedCategories = BOM_AUDIT_CATEGORY_ALIASES[category];
+  if (!aliasedCategories?.length) {
+    return category;
+  }
+  return `${category} (alias for ${aliasedCategories.join(",")})`;
+}
+
+/**
+ * Validate that every requested category is a known category or alias,
+ * throwing an Error listing the valid options otherwise.
+ *
+ * @param {string|string[]} categories Comma-separated string or array of categories to validate.
+ * @param {Array<{category?: string}>} rules Loaded audit rule objects to derive valid categories from.
+ * @returns {{categories: string[], expandedCategories: string[], validCategories: string[]}} Normalized, expanded, and valid category lists.
+ */
+export function validateBomAuditCategories(categories, rules) {
+  const normalizedCategories = normalizeBomAuditCategories(categories);
+  const validCategories = availableBomAuditCategories(rules);
+  const allowedCategories = new Set([
+    ...validCategories,
+    ...Object.keys(BOM_AUDIT_CATEGORY_ALIASES),
+  ]);
+  const invalidCategories = normalizedCategories.filter(
+    (category) => !allowedCategories.has(category),
+  );
+  if (invalidCategories.length) {
+    const validCategoryOptions = [...allowedCategories]
+      .sort()
+      .map((category) => formatBomAuditCategoryOption(category));
+    throw new Error(
+      `Unknown BOM audit categor${invalidCategories.length === 1 ? "y" : "ies"}: ${invalidCategories.join(", ")}. Valid categories: ${validCategoryOptions.join(", ")}.`,
+    );
+  }
+  return {
+    categories: normalizedCategories,
+    expandedCategories: expandBomAuditCategories(normalizedCategories),
+    validCategories,
+  };
+}
+
+/**
+ * Determine the default BOM audit categories for the current CLI invocation.
+ *
+ * OBOM-focused runs should default to the runtime-specific rule pack unless the
+ * user explicitly requests other categories.
+ *
+ * @param {object} options CLI options
+ * @param {string} [commandPath] Invoked command path or name
+ * @returns {string | undefined} Default category string, if any
+ */
+export function getDefaultBomAuditCategories(options, commandPath) {
+  const normalizedCommandPath = `${commandPath || ""}`.toLowerCase();
+  const defaultHbomCategories = options?.includeRuntime
+    ? `${DEFAULT_HBOM_AUDIT_CATEGORIES},host-topology`
+    : DEFAULT_HBOM_AUDIT_CATEGORIES;
+  if (normalizedCommandPath.includes("hbom")) {
+    return defaultHbomCategories;
+  }
+  const projectTypes = Array.isArray(options?.projectType)
+    ? options.projectType
+    : typeof options?.projectType === "string"
+      ? options.projectType.split(",")
+      : [];
+  const normalizedProjectTypes = projectTypes
+    .map((projectType) => `${projectType || ""}`.trim().toLowerCase())
+    .filter(Boolean);
+  if (
+    normalizedProjectTypes.length &&
+    normalizedProjectTypes.every((projectType) =>
+      ["hbom", "hardware"].includes(projectType),
+    )
+  ) {
+    return defaultHbomCategories;
+  }
+  if (!shouldRunPredictiveBomAudit(options, commandPath)) {
+    return "obom-runtime";
+  }
+  return undefined;
+}

package/lib/inventory/bomUtils.js

@@ -0,0 +1,369 @@
+const SPDX_CONTEXT_PREFIX = "https://spdx.org/rdf/";
+const CYCLONEDX_FORMAT = "CycloneDX";
+
+/**
+ * The default CycloneDX specification version used across cdxgen when a caller
+ * does not specify one (matches the `--spec-version` CLI default).
+ */
+export const DEFAULT_CDX_SPEC_VERSION = 1.7;
+
+const LEGACY_CYCLONEDX_ROOT_KEY = "bomFormat";
+const MODERN_CYCLONEDX_ROOT_KEY = "specFormat";
+const BOM_FORMAT_CYCLONEDX = "cyclonedx";
+const BOM_FORMAT_SPDX = "spdx";
+const BOM_FORMAT_UNKNOWN = "unknown";
+const CYCLONEDX_SPEC_VERSION_PATTERN = /^(\d+)(?:\.(\d+))?$/u;
+const CYCLONEDX_FORMAT_KEYS = new Set([
+  LEGACY_CYCLONEDX_ROOT_KEY,
+  MODERN_CYCLONEDX_ROOT_KEY,
+  "specVersion",
+]);
+const COMPONENT_TYPES_1_4 = [
+  "application",
+  "framework",
+  "library",
+  "container",
+  "operating-system",
+  "device",
+  "firmware",
+  "file",
+];
+const COMPONENT_TYPES_1_5 = [
+  "application",
+  "framework",
+  "library",
+  "container",
+  "platform",
+  "operating-system",
+  "device",
+  "device-driver",
+  "firmware",
+  "file",
+  "machine-learning-model",
+  "data",
+];
+const COMPONENT_TYPES_1_6 = [...COMPONENT_TYPES_1_5, "cryptographic-asset"];
+
+/**
+ * Frozen map of CycloneDX spec versions (as "major.minor" strings) to the
+ * frozen list of component types supported by that version.
+ */
+export const CYCLONEDX_COMPONENT_TYPES_BY_SPEC_VERSION = Object.freeze({
+  1.4: Object.freeze(COMPONENT_TYPES_1_4),
+  1.5: Object.freeze(COMPONENT_TYPES_1_5),
+  1.6: Object.freeze(COMPONENT_TYPES_1_6),
+  1.7: Object.freeze(COMPONENT_TYPES_1_6),
+  "2.0": Object.freeze(COMPONENT_TYPES_1_6),
+});
+
+/**
+ * Determine whether the given BOM object is an SPDX JSON-LD document.
+ *
+ * @param {object} bomJson BOM JSON object to inspect.
+ * @returns {boolean} True when the object carries an SPDX `@context` and an `SpdxDocument` graph entry.
+ */
+export const isSpdxJsonLd = (bomJson) =>
+  Boolean(
+    bomJson?.["@context"]?.startsWith(SPDX_CONTEXT_PREFIX) &&
+      Array.isArray(bomJson?.["@graph"]) &&
+      bomJson["@graph"].some((element) => element?.type === "SpdxDocument"),
+  );
+
+const parseCycloneDxSpecVersion = (specVersion) => {
+  const match = `${specVersion ?? ""}`
+    .trim()
+    .match(CYCLONEDX_SPEC_VERSION_PATTERN);
+  if (!match) {
+    return undefined;
+  }
+  return {
+    major: Number.parseInt(match[1], 10),
+    minor: Number.parseInt(match[2] || "0", 10),
+    minorText: match[2] || "0",
+  };
+};
+
+/**
+ * Normalize a CycloneDX spec version to a numeric major.minor value.
+ *
+ * @param {string|number} specVersion Spec version string or number (e.g. "1.5", 1.6).
+ * @returns {number|undefined} Numeric major.minor version, or undefined when unparseable.
+ */
+export const normalizeCycloneDxSpecVersion = (specVersion) => {
+  const parsed = parseCycloneDxSpecVersion(specVersion);
+  if (!parsed) {
+    return undefined;
+  }
+  return Number(`${parsed.major}.${parsed.minor}`);
+};
+
+/**
+ * Format a CycloneDX spec version as a "major.minor" string.
+ *
+ * @param {string|number} specVersion Spec version string or number.
+ * @returns {string|undefined} "major.minor" string, or undefined when unparseable.
+ */
+export const toCycloneDxSpecVersionString = (specVersion) => {
+  const parsed = parseCycloneDxSpecVersion(specVersion);
+  if (!parsed) {
+    return undefined;
+  }
+  if (typeof specVersion === "string" && parsed.minorText !== "0") {
+    return `${parsed.major}.${parsed.minorText}`;
+  }
+  return `${parsed.major}.${parsed.minor}`;
+};
+
+/**
+ * Determine whether a spec version is greater than or equal to a minimum version,
+ * comparing major then minor components.
+ *
+ * @param {string|number} specVersion The spec version to test.
+ * @param {string|number} minimumVersion The minimum required spec version.
+ * @returns {boolean} True when specVersion is at least minimumVersion.
+ */
+export const isCycloneDxSpecVersionAtLeast = (specVersion, minimumVersion) => {
+  const parsedSpecVersion = parseCycloneDxSpecVersion(specVersion);
+  const parsedMinimumVersion = parseCycloneDxSpecVersion(minimumVersion);
+  if (!parsedSpecVersion || !parsedMinimumVersion) {
+    return false;
+  }
+  if (parsedSpecVersion.major !== parsedMinimumVersion.major) {
+    return parsedSpecVersion.major > parsedMinimumVersion.major;
+  }
+  return parsedSpecVersion.minor >= parsedMinimumVersion.minor;
+};
+
+/**
+ * Determine whether a spec version is CycloneDX 2.0 or later.
+ *
+ * @param {string|number} specVersion The spec version to test.
+ * @returns {boolean} True when the spec version is at least 2.0.
+ */
+export const isCycloneDx20SpecVersion = (specVersion) =>
+  isCycloneDxSpecVersionAtLeast(specVersion, 2);
+
+/**
+ * Return the list of component types supported by a given CycloneDX spec
+ * version, falling back to the 1.7 list when the version is unrecognized.
+ *
+ * @param {string|number} [specVersion=1.7] CycloneDX spec version.
+ * @returns {string[]} Supported component type names for that version.
+ */
+export const getSupportedCycloneDxComponentTypes = (specVersion = 1.7) => {
+  const normalizedSpecVersion = toCycloneDxSpecVersionString(specVersion);
+  return [
+    ...(CYCLONEDX_COMPONENT_TYPES_BY_SPEC_VERSION[normalizedSpecVersion] ||
+      CYCLONEDX_COMPONENT_TYPES_BY_SPEC_VERSION["1.7"]),
+  ];
+};
+
+/**
+ * Normalize a component type filter (single value, array, or falsy) into a
+ * deduplicated array of trimmed, non-empty type strings.
+ *
+ * @param {string|string[]} componentType Component type or array of types.
+ * @returns {string[]} Deduplicated, trimmed component type strings.
+ */
+export const normalizeCycloneDxComponentTypeFilter = (componentType) => {
+  if (!componentType) {
+    return [];
+  }
+  const componentTypes = Array.isArray(componentType)
+    ? componentType
+    : [componentType];
+  return Array.from(
+    new Set(componentTypes.map((type) => `${type}`.trim()).filter(Boolean)),
+  );
+};
+
+/**
+ * Determine whether a component type is enabled given the configured type
+ * filter and spec version.
+ *
+ * @param {string} componentType The component type to test.
+ * @param {object} [options] Options carrying the filter and spec version.
+ * @param {string|string[]} [options.componentType] Explicit type filter from CLI options.
+ * @param {string|number} [options.specVersion] CycloneDX spec version for default support lookup.
+ * @returns {boolean} True when the component type passes the filter.
+ */
+export const isCycloneDxComponentTypeEnabled = (
+  componentType,
+  options = {},
+) => {
+  if (!componentType) {
+    return false;
+  }
+  const requestedComponentTypes = normalizeCycloneDxComponentTypeFilter(
+    options.componentType,
+  );
+  if (requestedComponentTypes.length) {
+    return requestedComponentTypes.includes(componentType);
+  }
+  return getSupportedCycloneDxComponentTypes(options.specVersion).includes(
+    componentType,
+  );
+};
+
+/**
+ * Return the appropriate CycloneDX root format key ("bomFormat" or
+ * "specFormat") for the given spec version or BOM object.
+ *
+ * @param {string|number|object} specVersionOrBom Spec version, or a BOM object whose `specVersion` is read.
+ * @returns {string} The root format key name to use.
+ */
+export const getCycloneDxRootFormatKey = (specVersionOrBom) => {
+  const specVersion =
+    specVersionOrBom && typeof specVersionOrBom === "object"
+      ? specVersionOrBom.specVersion
+      : specVersionOrBom;
+  return isCycloneDx20SpecVersion(specVersion)
+    ? MODERN_CYCLONEDX_ROOT_KEY
+    : LEGACY_CYCLONEDX_ROOT_KEY;
+};
+
+/**
+ * Return the BOM format identifier string from a BOM object.
+ *
+ * @param {object} bomJson BOM JSON object.
+ * @returns {string|undefined} The `specFormat` or `bomFormat` value.
+ */
+export const getCycloneDxFormat = (bomJson) =>
+  bomJson?.specFormat || bomJson?.bomFormat;
+
+/**
+ * Determine whether a BOM object carries the CycloneDX format identifier.
+ *
+ * @param {object} bomJson BOM JSON object.
+ * @returns {boolean} True when the format identifier equals "CycloneDX".
+ */
+export const hasCycloneDxFormat = (bomJson) =>
+  getCycloneDxFormat(bomJson) === CYCLONEDX_FORMAT;
+
+/**
+ * Determine whether an object is a valid CycloneDX BOM by checking both the
+ * format identifier and a parseable spec version.
+ *
+ * @param {object} bomJson BOM JSON object.
+ * @returns {boolean} True when the object is a valid CycloneDX BOM.
+ */
+export const isCycloneDxBom = (bomJson) =>
+  hasCycloneDxFormat(bomJson) &&
+  normalizeCycloneDxSpecVersion(bomJson?.specVersion) !== undefined;
+
+const rewriteCycloneDxRootFields = (
+  bomJson,
+  rootKey,
+  specVersion,
+  preserveLegacyBomFormat,
+) => {
+  const remainingEntries = Object.entries(bomJson).filter(
+    ([key]) => !CYCLONEDX_FORMAT_KEYS.has(key),
+  );
+  for (const key of Object.keys(bomJson)) {
+    delete bomJson[key];
+  }
+  if (rootKey === LEGACY_CYCLONEDX_ROOT_KEY) {
+    bomJson.bomFormat = CYCLONEDX_FORMAT;
+    if (specVersion !== undefined) {
+      bomJson.specVersion = specVersion;
+    }
+  } else if (preserveLegacyBomFormat) {
+    bomJson.bomFormat = CYCLONEDX_FORMAT;
+    if (specVersion !== undefined) {
+      bomJson.specVersion = specVersion;
+    }
+    bomJson.specFormat = CYCLONEDX_FORMAT;
+  } else {
+    bomJson.specFormat = CYCLONEDX_FORMAT;
+    if (specVersion !== undefined) {
+      bomJson.specVersion = specVersion;
+    }
+  }
+  for (const [key, value] of remainingEntries) {
+    bomJson[key] = value;
+  }
+};
+
+/**
+ * Mutates a CycloneDX BOM object so the appropriate root format key is present
+ * for the requested spec version, while preserving conventional serialized
+ * root-key ordering (`bomFormat`/`specFormat` and `specVersion` first). Only the currently
+ * supported CycloneDX major.minor version shape is accepted; multi-component
+ * future versions such as `2.0.1` intentionally return `undefined` from the
+ * normalizer rather than being silently truncated.
+ *
+ * @param {object} bomJson BOM JSON object to mutate.
+ * @param {string|number} specVersion Desired CycloneDX spec version.
+ * @param {object} options Root-key compatibility options.
+ * @returns {object} The same `bomJson` object, after in-place mutation.
+ */
+export const setCycloneDxFormat = (
+  bomJson,
+  specVersion,
+  { preserveLegacyBomFormat = false } = {},
+) => {
+  if (!bomJson || typeof bomJson !== "object" || Array.isArray(bomJson)) {
+    return bomJson;
+  }
+  const resolvedSpecVersion =
+    toCycloneDxSpecVersionString(specVersion ?? bomJson.specVersion) ||
+    bomJson.specVersion;
+  if (resolvedSpecVersion !== undefined) {
+    bomJson.specVersion = resolvedSpecVersion;
+  }
+  if (
+    getCycloneDxRootFormatKey(resolvedSpecVersion) === MODERN_CYCLONEDX_ROOT_KEY
+  ) {
+    rewriteCycloneDxRootFields(
+      bomJson,
+      MODERN_CYCLONEDX_ROOT_KEY,
+      resolvedSpecVersion,
+      preserveLegacyBomFormat,
+    );
+    return bomJson;
+  }
+  rewriteCycloneDxRootFields(
+    bomJson,
+    LEGACY_CYCLONEDX_ROOT_KEY,
+    resolvedSpecVersion,
+    false,
+  );
+  return bomJson;
+};
+
+/**
+ * Detect the format of a BOM object, distinguishing CycloneDX, SPDX JSON-LD,
+ * and unknown formats.
+ *
+ * @param {object} bomJson BOM JSON object.
+ * @returns {string} "cyclonedx", "spdx", or "unknown".
+ */
+export const detectBomFormat = (bomJson) => {
+  if (isCycloneDxBom(bomJson)) {
+    return BOM_FORMAT_CYCLONEDX;
+  }
+  if (isSpdxJsonLd(bomJson)) {
+    return BOM_FORMAT_SPDX;
+  }
+  return BOM_FORMAT_UNKNOWN;
+};
+
+/**
+ * Build a user-facing error message explaining that the supplied BOM is not a
+ * CycloneDX document, tailored to the detected format.
+ *
+ * @param {object} bomJson BOM JSON object that was rejected.
+ * @param {string} [commandName="This command"] Name of the command requiring CycloneDX input.
+ * @returns {string} Human-readable error message.
+ */
+export const getNonCycloneDxErrorMessage = (
+  bomJson,
+  commandName = "This command",
+) => {
+  const detectedFormat = detectBomFormat(bomJson);
+  if (detectedFormat === BOM_FORMAT_SPDX) {
+    return `${commandName} expects a CycloneDX BOM. SPDX input is not supported for this command.`;
+  }
+  return `${commandName} expects a CycloneDX JSON BOM.`;
+};