@cyclonedx/cdxgen 12.3.3 → 12.4.0

package/lib/helpers/hbomAnalysis.js

@@ -0,0 +1,268 @@
+import { getPropertyValue } from "./inventoryStats.js";
+
+function getPropertyValues(propertiesOrObject, propertyName) {
+  const properties = Array.isArray(propertiesOrObject)
+    ? propertiesOrObject
+    : Array.isArray(propertiesOrObject?.properties)
+      ? propertiesOrObject.properties
+      : [];
+  return properties
+    .filter((property) => property?.name === propertyName)
+    .map((property) => property.value)
+    .filter(
+      (value) => value !== undefined && value !== null && `${value}` !== "",
+    );
+}
+
+function safeParseDiagnosticValue(value) {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  try {
+    const parsedValue = JSON.parse(value);
+    if (!parsedValue || typeof parsedValue !== "object") {
+      return undefined;
+    }
+    return parsedValue;
+  } catch {
+    return undefined;
+  }
+}
+
+function uniqueSortedStrings(values = []) {
+  return [
+    ...new Set(values.map((value) => `${value}`.trim()).filter(Boolean)),
+  ].sort((firstValue, secondValue) => firstValue.localeCompare(secondValue));
+}
+
+function getDiagnosticIdentifiers(commandDiagnostics = []) {
+  return uniqueSortedStrings(
+    commandDiagnostics
+      .map((entry) => entry.id ?? entry.command)
+      .filter((value) => value !== undefined && value !== null),
+  );
+}
+
+const HBOM_KNOWN_COMMAND_DIAGNOSTIC_ISSUES = new Set([
+  "missing-command",
+  "permission-denied",
+  "partial-support",
+  "timeout",
+]);
+
+export function getHbomCommandDiagnostics(bomJson) {
+  return getPropertyValues(bomJson, "cdx:hbom:evidence:commandDiagnostic")
+    .map((value) => safeParseDiagnosticValue(value))
+    .filter(Boolean);
+}
+
+export function getHbomCommandDiagnosticSummary(bomJson) {
+  const commandDiagnostics = getHbomCommandDiagnostics(bomJson);
+  const missingCommandDiagnostics = commandDiagnostics.filter(
+    (entry) => entry.issue === "missing-command",
+  );
+  const permissionDeniedDiagnostics = commandDiagnostics.filter(
+    (entry) => entry.issue === "permission-denied",
+  );
+  const partialSupportDiagnostics = commandDiagnostics.filter(
+    (entry) => entry.issue === "partial-support",
+  );
+  const timeoutDiagnostics = commandDiagnostics.filter(
+    (entry) => entry.issue === "timeout",
+  );
+  const commandErrorDiagnostics = commandDiagnostics.filter((entry) => {
+    const issue = `${entry.issue ?? ""}`.trim();
+    return !!issue && !HBOM_KNOWN_COMMAND_DIAGNOSTIC_ISSUES.has(issue);
+  });
+  const installHints = uniqueSortedStrings(
+    missingCommandDiagnostics
+      .map((entry) => entry.installHint)
+      .filter((value) => value !== undefined && value !== null),
+  );
+  const privilegeHints = uniqueSortedStrings(
+    permissionDeniedDiagnostics
+      .map((entry) => entry.privilegeHint)
+      .filter((value) => value !== undefined && value !== null),
+  );
+  const missingCommands = uniqueSortedStrings(
+    missingCommandDiagnostics
+      .map((entry) => entry.command ?? entry.id)
+      .filter((value) => value !== undefined && value !== null),
+  );
+  const permissionDeniedCommands = uniqueSortedStrings(
+    permissionDeniedDiagnostics
+      .map((entry) => entry.command ?? entry.id)
+      .filter((value) => value !== undefined && value !== null),
+  );
+  const diagnosticIssues = uniqueSortedStrings(
+    commandDiagnostics
+      .map((entry) => entry.issue)
+      .filter((value) => value !== undefined && value !== null),
+  );
+
+  return {
+    actionableDiagnosticCount:
+      missingCommandDiagnostics.length + permissionDeniedDiagnostics.length,
+    commandDiagnosticCount: commandDiagnostics.length,
+    commandDiagnostics,
+    commandErrorCount: commandErrorDiagnostics.length,
+    commandErrorIds: getDiagnosticIdentifiers(commandErrorDiagnostics),
+    diagnosticIssues,
+    installHintCount: installHints.length,
+    installHints,
+    missingCommandCount: missingCommandDiagnostics.length,
+    missingCommandIds: getDiagnosticIdentifiers(missingCommandDiagnostics),
+    missingCommands,
+    partialSupportCount: partialSupportDiagnostics.length,
+    partialSupportIds: getDiagnosticIdentifiers(partialSupportDiagnostics),
+    permissionDeniedCommands,
+    permissionDeniedCount: permissionDeniedDiagnostics.length,
+    permissionDeniedIds: getDiagnosticIdentifiers(permissionDeniedDiagnostics),
+    privilegeHintCount: privilegeHints.length,
+    privilegeHints,
+    requiresPrivilegedEnrichment:
+      permissionDeniedDiagnostics.length > 0 && privilegeHints.length > 0,
+    timeoutIds: getDiagnosticIdentifiers(timeoutDiagnostics),
+    timeoutCount: timeoutDiagnostics.length,
+  };
+}
+
+export function isHbomLikeBom(bomJson) {
+  if (!bomJson) {
+    return false;
+  }
+  if (
+    getPropertyValues(bomJson, "cdx:hbom:collectorProfile").length ||
+    getPropertyValues(bomJson, "cdx:hbom:targetPlatform").length ||
+    (bomJson?.properties || []).some((property) =>
+      `${property?.name || ""}`.startsWith("cdx:hbom:"),
+    )
+  ) {
+    return true;
+  }
+  if (
+    (bomJson?.metadata?.component?.properties || []).some((property) =>
+      `${property?.name || ""}`.startsWith("cdx:hbom:"),
+    )
+  ) {
+    return true;
+  }
+  return (bomJson?.components || []).some((component) =>
+    (component?.properties || []).some(
+      (property) =>
+        property?.name === "cdx:hbom:hardwareClass" ||
+        `${property?.name || ""}`.startsWith("cdx:hbom:"),
+    ),
+  );
+}
+
+export function getHbomHardwareClass(component) {
+  return getPropertyValue(component, "cdx:hbom:hardwareClass");
+}
+
+export function getHbomHardwareClassCounts(components = []) {
+  const counts = new Map();
+  for (const component of components || []) {
+    const hardwareClass = getHbomHardwareClass(component);
+    if (!hardwareClass) {
+      continue;
+    }
+    counts.set(hardwareClass, (counts.get(hardwareClass) || 0) + 1);
+  }
+  return Array.from(counts.entries())
+    .map(([hardwareClass, count]) => ({ hardwareClass, count }))
+    .sort(
+      (firstEntry, secondEntry) =>
+        secondEntry.count - firstEntry.count ||
+        firstEntry.hardwareClass.localeCompare(secondEntry.hardwareClass),
+    );
+}
+
+export function formatHbomHardwareClassSummary(hardwareClassCounts = []) {
+  return hardwareClassCounts
+    .slice(0, 5)
+    .map(({ hardwareClass, count }) => `${hardwareClass} (${count})`)
+    .join(", ");
+}
+
+export function getHbomSummary(bomJson) {
+  const metadataComponent = bomJson?.metadata?.component;
+  const hardwareClassCounts = getHbomHardwareClassCounts(
+    bomJson?.components || [],
+  );
+  const commandDiagnosticSummary = getHbomCommandDiagnosticSummary(bomJson);
+  const evidenceCommands = getPropertyValues(
+    bomJson,
+    "cdx:hbom:evidence:command",
+  );
+  const evidenceFiles = getPropertyValues(bomJson, "cdx:hbom:evidence:file");
+  const commandCountValue = getPropertyValue(
+    bomJson,
+    "cdx:hbom:evidence:commandCount",
+  );
+  const fileCountValue = getPropertyValue(
+    bomJson,
+    "cdx:hbom:evidence:fileCount",
+  );
+  const evidenceCommandCount = Number.parseInt(
+    `${commandCountValue ?? evidenceCommands.length}`,
+    10,
+  );
+  const evidenceFileCount = Number.parseInt(
+    `${fileCountValue ?? evidenceFiles.length}`,
+    10,
+  );
+
+  return {
+    actionableDiagnosticCount:
+      commandDiagnosticSummary.actionableDiagnosticCount,
+    architecture:
+      getPropertyValue(metadataComponent, "cdx:hbom:architecture") ||
+      getPropertyValue(bomJson, "cdx:hbom:targetArchitecture") ||
+      getPropertyValue(bomJson, "cdx:hbom:architecture"),
+    collectorProfile: getPropertyValue(bomJson, "cdx:hbom:collectorProfile"),
+    commandDiagnosticCount: commandDiagnosticSummary.commandDiagnosticCount,
+    commandDiagnostics: commandDiagnosticSummary.commandDiagnostics,
+    commandErrorCount: commandDiagnosticSummary.commandErrorCount,
+    commandErrorIds: commandDiagnosticSummary.commandErrorIds,
+    componentCount: (bomJson?.components || []).length,
+    diagnosticIssues: commandDiagnosticSummary.diagnosticIssues,
+    evidenceCommandCount: Number.isNaN(evidenceCommandCount)
+      ? evidenceCommands.length
+      : evidenceCommandCount,
+    evidenceCommands,
+    evidenceFileCount: Number.isNaN(evidenceFileCount)
+      ? evidenceFiles.length
+      : evidenceFileCount,
+    evidenceFiles,
+    hardwareClassCount: hardwareClassCounts.length,
+    hardwareClassCounts,
+    identifierPolicy:
+      getPropertyValue(metadataComponent, "cdx:hbom:identifierPolicy") ||
+      getPropertyValue(bomJson, "cdx:hbom:identifierPolicy"),
+    installHintCount: commandDiagnosticSummary.installHintCount,
+    installHints: commandDiagnosticSummary.installHints,
+    manufacturer: metadataComponent?.manufacturer?.name,
+    metadataName: metadataComponent?.name,
+    metadataType: metadataComponent?.type,
+    missingCommandCount: commandDiagnosticSummary.missingCommandCount,
+    missingCommandIds: commandDiagnosticSummary.missingCommandIds,
+    missingCommands: commandDiagnosticSummary.missingCommands,
+    partialSupportCount: commandDiagnosticSummary.partialSupportCount,
+    partialSupportIds: commandDiagnosticSummary.partialSupportIds,
+    platform:
+      getPropertyValue(metadataComponent, "cdx:hbom:platform") ||
+      getPropertyValue(bomJson, "cdx:hbom:targetPlatform") ||
+      getPropertyValue(bomJson, "cdx:hbom:platform"),
+    permissionDeniedCommands: commandDiagnosticSummary.permissionDeniedCommands,
+    permissionDeniedCount: commandDiagnosticSummary.permissionDeniedCount,
+    permissionDeniedIds: commandDiagnosticSummary.permissionDeniedIds,
+    privilegeHintCount: commandDiagnosticSummary.privilegeHintCount,
+    privilegeHints: commandDiagnosticSummary.privilegeHints,
+    requiresPrivilegedEnrichment:
+      commandDiagnosticSummary.requiresPrivilegedEnrichment,
+    timeoutIds: commandDiagnosticSummary.timeoutIds,
+    timeoutCount: commandDiagnosticSummary.timeoutCount,
+    topHardwareClasses: hardwareClassCounts.slice(0, 5),
+  };
+}

package/lib/helpers/hbomAnalysis.poku.js

@@ -0,0 +1,249 @@
+import { assert, describe, it } from "poku";
+
+import {
+  formatHbomHardwareClassSummary,
+  getHbomCommandDiagnosticSummary,
+  getHbomHardwareClassCounts,
+  getHbomSummary,
+  isHbomLikeBom,
+} from "./hbomAnalysis.js";
+
+describe("hbomAnalysis helpers", () => {
+  const hbomFixture = {
+    metadata: {
+      component: {
+        name: "demo-host",
+        type: "device",
+        manufacturer: { name: "Example Corp" },
+        properties: [
+          { name: "cdx:hbom:platform", value: "linux" },
+          { name: "cdx:hbom:architecture", value: "amd64" },
+          { name: "cdx:hbom:identifierPolicy", value: "redacted-by-default" },
+        ],
+      },
+    },
+    components: [
+      {
+        name: "eth0",
+        properties: [
+          { name: "cdx:hbom:hardwareClass", value: "network-interface" },
+        ],
+      },
+      {
+        name: "wlan0",
+        properties: [
+          { name: "cdx:hbom:hardwareClass", value: "network-interface" },
+        ],
+      },
+      {
+        name: "nvme0",
+        properties: [{ name: "cdx:hbom:hardwareClass", value: "storage" }],
+      },
+      {
+        name: "BAT0",
+        properties: [{ name: "cdx:hbom:hardwareClass", value: "power" }],
+      },
+    ],
+    properties: [
+      { name: "cdx:hbom:collectorProfile", value: "linux-amd64-v1" },
+      { name: "cdx:hbom:targetPlatform", value: "linux" },
+      { name: "cdx:hbom:targetArchitecture", value: "amd64" },
+      { name: "cdx:hbom:evidence:commandCount", value: "2" },
+      {
+        name: "cdx:hbom:evidence:command",
+        value: "lscpu-json|cpu-memory|/usr/bin/lscpu -J",
+      },
+      {
+        name: "cdx:hbom:evidence:command",
+        value: "ip-link-json|network|/usr/sbin/ip -j link",
+      },
+      { name: "cdx:hbom:evidence:commandDiagnosticCount", value: "2" },
+      {
+        name: "cdx:hbom:evidence:commandDiagnostic",
+        value: JSON.stringify({
+          command: "lsusb",
+          id: "lsusb",
+          installHint:
+            "Command not found: install the Linux package providing lsusb (commonly `usbutils`).",
+          issue: "missing-command",
+          message: "lsusb failed with missing-command",
+        }),
+      },
+      {
+        name: "cdx:hbom:evidence:commandDiagnostic",
+        value: JSON.stringify({
+          command: "drm_info",
+          id: "drm-info-json",
+          issue: "permission-denied",
+          message: "drm_info failed with permission-denied",
+          privilegeHint:
+            "Retry with --privileged to allow a non-interactive sudo attempt for permission-sensitive Linux commands.",
+        }),
+      },
+      { name: "cdx:hbom:evidence:fileCount", value: "1" },
+      { name: "cdx:hbom:evidence:file", value: "/etc/os-release" },
+    ],
+  };
+
+  it("detects HBOMs from document and component properties", () => {
+    assert.strictEqual(isHbomLikeBom(hbomFixture), true);
+    assert.strictEqual(
+      isHbomLikeBom({ metadata: { component: { type: "application" } } }),
+      false,
+    );
+  });
+
+  it("summarizes hardware classes and evidence", () => {
+    assert.deepStrictEqual(getHbomHardwareClassCounts(hbomFixture.components), [
+      { hardwareClass: "network-interface", count: 2 },
+      { hardwareClass: "power", count: 1 },
+      { hardwareClass: "storage", count: 1 },
+    ]);
+    assert.strictEqual(
+      formatHbomHardwareClassSummary(
+        getHbomHardwareClassCounts(hbomFixture.components),
+      ),
+      "network-interface (2), power (1), storage (1)",
+    );
+
+    assert.deepStrictEqual(getHbomCommandDiagnosticSummary(hbomFixture), {
+      actionableDiagnosticCount: 2,
+      commandDiagnosticCount: 2,
+      commandDiagnostics: [
+        {
+          command: "lsusb",
+          id: "lsusb",
+          installHint:
+            "Command not found: install the Linux package providing lsusb (commonly `usbutils`).",
+          issue: "missing-command",
+          message: "lsusb failed with missing-command",
+        },
+        {
+          command: "drm_info",
+          id: "drm-info-json",
+          issue: "permission-denied",
+          message: "drm_info failed with permission-denied",
+          privilegeHint:
+            "Retry with --privileged to allow a non-interactive sudo attempt for permission-sensitive Linux commands.",
+        },
+      ],
+      commandErrorCount: 0,
+      commandErrorIds: [],
+      diagnosticIssues: ["missing-command", "permission-denied"],
+      installHintCount: 1,
+      installHints: [
+        "Command not found: install the Linux package providing lsusb (commonly `usbutils`).",
+      ],
+      missingCommandCount: 1,
+      missingCommandIds: ["lsusb"],
+      missingCommands: ["lsusb"],
+      partialSupportCount: 0,
+      partialSupportIds: [],
+      permissionDeniedCommands: ["drm_info"],
+      permissionDeniedCount: 1,
+      permissionDeniedIds: ["drm-info-json"],
+      privilegeHintCount: 1,
+      privilegeHints: [
+        "Retry with --privileged to allow a non-interactive sudo attempt for permission-sensitive Linux commands.",
+      ],
+      requiresPrivilegedEnrichment: true,
+      timeoutIds: [],
+      timeoutCount: 0,
+    });
+
+    assert.deepStrictEqual(getHbomSummary(hbomFixture), {
+      actionableDiagnosticCount: 2,
+      architecture: "amd64",
+      collectorProfile: "linux-amd64-v1",
+      commandDiagnosticCount: 2,
+      commandDiagnostics: [
+        {
+          command: "lsusb",
+          id: "lsusb",
+          installHint:
+            "Command not found: install the Linux package providing lsusb (commonly `usbutils`).",
+          issue: "missing-command",
+          message: "lsusb failed with missing-command",
+        },
+        {
+          command: "drm_info",
+          id: "drm-info-json",
+          issue: "permission-denied",
+          message: "drm_info failed with permission-denied",
+          privilegeHint:
+            "Retry with --privileged to allow a non-interactive sudo attempt for permission-sensitive Linux commands.",
+        },
+      ],
+      commandErrorCount: 0,
+      commandErrorIds: [],
+      componentCount: 4,
+      diagnosticIssues: ["missing-command", "permission-denied"],
+      evidenceCommandCount: 2,
+      evidenceCommands: [
+        "lscpu-json|cpu-memory|/usr/bin/lscpu -J",
+        "ip-link-json|network|/usr/sbin/ip -j link",
+      ],
+      evidenceFileCount: 1,
+      evidenceFiles: ["/etc/os-release"],
+      hardwareClassCount: 3,
+      hardwareClassCounts: [
+        { hardwareClass: "network-interface", count: 2 },
+        { hardwareClass: "power", count: 1 },
+        { hardwareClass: "storage", count: 1 },
+      ],
+      identifierPolicy: "redacted-by-default",
+      installHintCount: 1,
+      installHints: [
+        "Command not found: install the Linux package providing lsusb (commonly `usbutils`).",
+      ],
+      manufacturer: "Example Corp",
+      metadataName: "demo-host",
+      metadataType: "device",
+      missingCommandCount: 1,
+      missingCommandIds: ["lsusb"],
+      missingCommands: ["lsusb"],
+      partialSupportCount: 0,
+      partialSupportIds: [],
+      platform: "linux",
+      permissionDeniedCommands: ["drm_info"],
+      permissionDeniedCount: 1,
+      permissionDeniedIds: ["drm-info-json"],
+      privilegeHintCount: 1,
+      privilegeHints: [
+        "Retry with --privileged to allow a non-interactive sudo attempt for permission-sensitive Linux commands.",
+      ],
+      requiresPrivilegedEnrichment: true,
+      timeoutIds: [],
+      timeoutCount: 0,
+      topHardwareClasses: [
+        { hardwareClass: "network-interface", count: 2 },
+        { hardwareClass: "power", count: 1 },
+        { hardwareClass: "storage", count: 1 },
+      ],
+    });
+  });
+
+  it("counts invalid command argument diagnostics as other command errors", () => {
+    const summary = getHbomCommandDiagnosticSummary({
+      properties: [
+        {
+          name: "cdx:hbom:evidence:commandDiagnostic",
+          value: JSON.stringify({
+            argumentName: "edid-path",
+            command: "edid-decode",
+            id: "edid-decode:display-1",
+            issue: "invalid-command-argument",
+            message:
+              "edid-decode:display-1 blocked invalid edid-path: expected an absolute /sys/class/drm/<connector>/edid path after normalization",
+          }),
+        },
+      ],
+    });
+
+    assert.deepStrictEqual(summary.commandErrorIds, ["edid-decode:display-1"]);
+    assert.strictEqual(summary.commandErrorCount, 1);
+    assert.deepStrictEqual(summary.diagnosticIssues, [
+      "invalid-command-argument",
+    ]);
+  });
+});

package/lib/helpers/hbomLoader.js

@@ -0,0 +1,35 @@
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+import { safeExistsSync } from "./utils.js";
+
+const LOCAL_HBOM_MODULE_URL = new URL(
+  "../../cdx-hbom/index.js",
+  import.meta.url,
+);
+const LOCAL_HBOM_MODULE_PATH = fileURLToPath(LOCAL_HBOM_MODULE_URL);
+
+/**
+ * Resolve the optional cdx-hbom module.
+ *
+ * @returns {Promise<object>} Loaded cdx-hbom module namespace.
+ */
+export async function importHbomModule() {
+  if (safeExistsSync(LOCAL_HBOM_MODULE_PATH)) {
+    return await import(pathToFileURL(LOCAL_HBOM_MODULE_PATH).href);
+  }
+  let hbomModule;
+  try {
+    hbomModule = await import("@cdxgen/cdx-hbom");
+  } catch (error) {
+    if (
+      error?.code === "ERR_MODULE_NOT_FOUND" ||
+      `${error?.message || ""}`.includes("@cdxgen/cdx-hbom")
+    ) {
+      throw new Error(
+        "HBOM support requires the optional '@cdxgen/cdx-hbom' dependency. Install it or use a build that bundles HBOM support.",
+      );
+    }
+    throw error;
+  }
+  return hbomModule;
+}