@cyclonedx/cdxgen 12.3.3 → 12.4.0

package/lib/helpers/display.js

@@ -2,6 +2,14 @@ import { readFileSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
 
+import { formatOccurrenceEvidence } from "./evidenceUtils.js";
+import {
+  formatHbomHardwareClassSummary,
+  getHbomSummary,
+  isHbomLikeBom,
+} from "./hbomAnalysis.js";
+import { getHostViewSummary, isMergedHostViewBom } from "./hostTopology.js";
+import { getPropertyValue } from "./inventoryStats.js";
 import {
   hasComponentRegistryProvenance,
   REGISTRY_PROVENANCE_ICON,
@@ -83,6 +91,66 @@ export const buildTableSummaryLines = (
   const summaryLines = [];
   if (summaryText) {
     summaryLines.push(summaryText);
+  } else if (!filterTypes && isHbomLikeBom(bomJson)) {
+    const hbomSummary = getHbomSummary(bomJson);
+    summaryLines.push(
+      `HBOM includes ${hbomSummary.componentCount} hardware component(s) across ${hbomSummary.hardwareClassCount} hardware class(es)`,
+    );
+    if (hbomSummary.hardwareClassCounts.length) {
+      summaryLines.push(
+        `Top hardware classes: ${formatHbomHardwareClassSummary(hbomSummary.hardwareClassCounts)}`,
+      );
+    }
+    if (hbomSummary.collectorProfile) {
+      summaryLines.push(
+        `Collector profile: ${hbomSummary.collectorProfile}; command evidence: ${hbomSummary.evidenceCommandCount}; observed files: ${hbomSummary.evidenceFileCount}`,
+      );
+    }
+    if (hbomSummary.commandDiagnosticCount) {
+      const diagnosticDetails = [];
+      if (hbomSummary.missingCommandCount) {
+        diagnosticDetails.push(
+          `missing commands: ${hbomSummary.missingCommandCount}`,
+        );
+      }
+      if (hbomSummary.permissionDeniedCount) {
+        diagnosticDetails.push(
+          `permission denied: ${hbomSummary.permissionDeniedCount}`,
+        );
+      }
+      if (hbomSummary.partialSupportCount) {
+        diagnosticDetails.push(
+          `partial support: ${hbomSummary.partialSupportCount}`,
+        );
+      }
+      if (hbomSummary.timeoutCount) {
+        diagnosticDetails.push(`timeouts: ${hbomSummary.timeoutCount}`);
+      }
+      if (hbomSummary.commandErrorCount) {
+        diagnosticDetails.push(
+          `other command errors: ${hbomSummary.commandErrorCount}`,
+        );
+      }
+      summaryLines.push(
+        `Collector diagnostics: ${hbomSummary.commandDiagnosticCount} issue(s)${diagnosticDetails.length ? `; ${diagnosticDetails.join(", ")}` : ""}`,
+      );
+      if (hbomSummary.requiresPrivilegedEnrichment) {
+        summaryLines.push(
+          "Permission-sensitive enrichments were skipped or blocked. Re-run with --privileged where policy allows.",
+        );
+      }
+    }
+    if (isMergedHostViewBom(bomJson)) {
+      const hostViewSummary = getHostViewSummary(bomJson);
+      summaryLines.push(
+        `Host topology view: ${hostViewSummary.runtimeComponentCount} runtime component(s), ${hostViewSummary.topologyLinkCount} strict host/runtime topology link(s), ${hostViewSummary.linkedHardwareComponentCount} linked hardware component(s)`,
+      );
+      if (hostViewSummary.linkedRuntimeCategories.length) {
+        summaryLines.push(
+          `Linked runtime categories: ${hostViewSummary.linkedRuntimeCategories.join(", ")}`,
+        );
+      }
+    }
   } else if (!filterTypes) {
     summaryLines.push(
       `BOM includes ${bomJson?.components?.length || 0} components and ${
@@ -105,6 +173,214 @@ export const buildTableSummaryLines = (
   return summaryLines;
 };
 
+const HBOM_COLUMN_PRIORITY = Object.freeze([
+  ["cdx:hbom:status", "status"],
+  ["cdx:hbom:connected", "connected"],
+  ["cdx:hbom:connectionState", "connectionState"],
+  ["cdx:hbom:securityMode", "securityMode"],
+  ["cdx:hbom:health", "health"],
+  ["cdx:hbom:smartStatus", "smartStatus"],
+  ["cdx:hbom:powerSource", "powerSource"],
+  ["cdx:hbom:maximumCapacity", "maximumCapacity"],
+  ["cdx:hbom:chargePercent", "chargePercent"],
+  ["cdx:hbom:capacity", "capacity"],
+  ["cdx:hbom:size", "size"],
+  ["cdx:hbom:sizeBytes", "sizeBytes"],
+  ["cdx:hbom:linkRateMbps", "linkRateMbps"],
+  ["cdx:hbom:speedMbps", "speedMbps"],
+  ["cdx:hbom:resolution", "resolution"],
+  ["cdx:hbom:transport", "transport"],
+  ["cdx:hbom:connectionType", "connectionType"],
+  ["cdx:hbom:firmwareVersion", "firmwareVersion"],
+  ["cdx:hbom:driver", "driver"],
+  ["cdx:hbom:channel", "channel"],
+  ["cdx:hbom:phyMode", "phyMode"],
+  ["cdx:hbom:temperatureCelsius", "temperatureCelsius"],
+  ["cdx:hostview:runtimeAddressCount", "runtimeAddrs"],
+  ["cdx:hostview:kernel_modules:count", "kernelMods"],
+  ["cdx:hostview:mount_hardening:count", "runtimeMounts"],
+  ["cdx:hostview:runtime-storage:count", "runtimeStorage"],
+  ["cdx:hostview:linkedRuntimeCategoryCount", "runtimeLinks"],
+]);
+
+const HBOM_CLASS_PROPERTY_PRIORITY = Object.freeze({
+  "audio-device": Object.freeze([
+    ["cdx:hbom:transport", "transport"],
+    ["cdx:hbom:defaultOutput", "defaultOutput"],
+    ["cdx:hbom:defaultInput", "defaultInput"],
+    ["cdx:hbom:sampleRate", "sampleRate"],
+  ]),
+  bus: Object.freeze([
+    ["cdx:hbom:speed", "speed"],
+    ["cdx:hbom:linkStatus", "linkStatus"],
+    ["cdx:hbom:receptacleStatus", "receptacleStatus"],
+  ]),
+  camera: Object.freeze([
+    ["cdx:hbom:isVirtual", "virtual"],
+    ["cdx:hbom:cameraModelId", "modelId"],
+  ]),
+  "bluetooth-controller": Object.freeze([
+    ["cdx:hbom:state", "state"],
+    ["cdx:hbom:transport", "transport"],
+    ["cdx:hbom:firmwareVersion", "firmware"],
+  ]),
+  "bluetooth-device": Object.freeze([
+    ["cdx:hbom:connectionState", "connection"],
+    ["cdx:hbom:rssi", "rssi"],
+    ["cdx:hbom:firmwareVersion", "firmware"],
+    ["cdx:hbom:minorType", "minorType"],
+  ]),
+  display: Object.freeze([
+    ["cdx:hbom:resolution", "resolution"],
+    ["cdx:hbom:connectionType", "connection"],
+    ["cdx:hbom:vendorId", "vendorId"],
+    ["cdx:hbom:productId", "productId"],
+  ]),
+  memory: Object.freeze([
+    ["cdx:hbom:size", "size"],
+    ["cdx:hbom:sizeBytes", "sizeBytes"],
+    ["cdx:hbom:memoryOnlineSize", "onlineSize"],
+    ["cdx:hbom:addressSizes", "addressSizes"],
+  ]),
+  "network-interface": Object.freeze([
+    ["cdx:hbom:status", "status"],
+    ["cdx:hbom:speedMbps", "speedMbps"],
+    ["cdx:hbom:duplex", "duplex"],
+    ["cdx:hbom:driver", "driver"],
+    ["cdx:hostview:runtimeAddressCount", "runtimeAddrs"],
+    ["cdx:hostview:kernel_modules:count", "kernelMods"],
+  ]),
+  power: Object.freeze([
+    ["cdx:hbom:health", "health"],
+    ["cdx:hbom:chargePercent", "charge%"],
+    ["cdx:hbom:maximumCapacity", "maxCapacity"],
+    ["cdx:hbom:cycleCount", "cycles"],
+    ["cdx:hbom:powerSource", "source"],
+  ]),
+  "power-adapter": Object.freeze([
+    ["cdx:hbom:connected", "connected"],
+    ["cdx:hbom:watts", "watts"],
+    ["cdx:hbom:isCharging", "charging"],
+  ]),
+  processor: Object.freeze([
+    ["cdx:hbom:coreCount", "cores"],
+    ["cdx:hbom:logicalCpuCount", "logical"],
+    ["cdx:hbom:physicalCpuCount", "physical"],
+  ]),
+  storage: Object.freeze([
+    ["cdx:hbom:capacity", "capacity"],
+    ["cdx:hbom:smartStatus", "smart"],
+    ["cdx:hbom:wearPercentageUsed", "wearUsed"],
+    ["cdx:hbom:transport", "transport"],
+    ["cdx:hbom:firmwareVersion", "firmware"],
+    ["cdx:hostview:mount_hardening:count", "runtimeMounts"],
+    ["cdx:hostview:runtime-storage:count", "runtimeStorage"],
+  ]),
+  "storage-volume": Object.freeze([
+    ["cdx:hbom:size", "size"],
+    ["cdx:hbom:capacity", "capacity"],
+    ["cdx:hbom:fileVault", "fileVault"],
+    ["cdx:hbom:isEncrypted", "encrypted"],
+    ["cdx:hbom:isRemovable", "removable"],
+    ["cdx:hostview:mount_hardening:count", "runtimeMounts"],
+    ["cdx:hostview:runtime-storage:count", "runtimeStorage"],
+  ]),
+  sensor: Object.freeze([
+    ["cdx:hbom:temperatureCelsius", "tempC"],
+    ["cdx:hbom:fanCount", "fanCount"],
+  ]),
+  "thermal-zone": Object.freeze([
+    ["cdx:hbom:temperatureCelsius", "tempC"],
+    ["cdx:hbom:fanCount", "fanCount"],
+  ]),
+  "wireless-adapter": Object.freeze([
+    ["cdx:hbom:connected", "connected"],
+    ["cdx:hbom:securityMode", "security"],
+    ["cdx:hbom:linkRateMbps", "linkMbps"],
+    ["cdx:hbom:channel", "channel"],
+    ["cdx:hbom:phyMode", "phy"],
+    ["cdx:hostview:runtimeAddressCount", "runtimeAddrs"],
+  ]),
+});
+
+function formatHbomKeyProperties(component) {
+  const hardwareClass = getPropertyValue(component, "cdx:hbom:hardwareClass");
+  const classSpecificPriority =
+    HBOM_CLASS_PROPERTY_PRIORITY[hardwareClass] || [];
+  const details = [];
+  const seenPropertyNames = new Set();
+  for (const [propertyName, label] of [
+    ...classSpecificPriority,
+    ...HBOM_COLUMN_PRIORITY,
+  ]) {
+    if (seenPropertyNames.has(propertyName)) {
+      continue;
+    }
+    seenPropertyNames.add(propertyName);
+    const value = getPropertyValue(component, propertyName);
+    if (value === undefined || value === null || value === "") {
+      continue;
+    }
+    details.push(`${label}=${value}`);
+    if (details.length >= 3) {
+      break;
+    }
+  }
+  return details.join(", ");
+}
+
+function printHBOMTable(bomJson, filterTypes, highlight, summaryText) {
+  const config = {
+    columnDefault: {
+      width: 28,
+    },
+    columnCount: 5,
+    columns: [
+      { width: 22 },
+      { width: 32 },
+      { width: 24 },
+      { width: 52 },
+      { width: 24 },
+    ],
+  };
+  const stream = createStream(config);
+  stream.write([
+    "Hardware Class",
+    "Name",
+    "Manufacturer / Version",
+    "Key Properties",
+    "Tags",
+  ]);
+  for (const comp of bomJson.components) {
+    if (filterTypes && !filterTypes.includes(comp.type)) {
+      continue;
+    }
+    const manufacturerOrVersion = [comp.manufacturer?.name, comp.version]
+      .filter(Boolean)
+      .join(" / ");
+    stream.write([
+      highlightStr(
+        getPropertyValue(comp, "cdx:hbom:hardwareClass") || comp.type || "",
+        highlight,
+      ),
+      formatComponentName(comp, highlight),
+      highlightStr(manufacturerOrVersion, highlight),
+      highlightStr(formatHbomKeyProperties(comp), highlight),
+      (comp.tags || []).join(", "),
+    ]);
+  }
+  stream.end();
+  console.log();
+  for (const line of buildTableSummaryLines(
+    bomJson,
+    filterTypes,
+    summaryText,
+    0,
+  )) {
+    console.log(line);
+  }
+}
+
 /**
  * Builds legend lines for dependency tree marker icons.
  *
@@ -230,6 +506,9 @@ export function printTable(
   ) {
     return printOSTable(bomJson);
   }
+  if (isHbomLikeBom(bomJson) && !filterTypes?.includes("cryptographic-asset")) {
+    return printHBOMTable(bomJson, filterTypes, highlight, summaryText);
+  }
   const config = {
     columnDefault: {
       width: 30,
@@ -394,6 +673,17 @@ const locationComparator = (a, b) => {
       }
     }
   }
+  if (a && b) {
+    const tmpA = a.match(/^(.*):(\d+)(?::(\d+))?$/);
+    const tmpB = b.match(/^(.*):(\d+)(?::(\d+))?$/);
+    if (tmpA && tmpB && tmpA[1] === tmpB[1]) {
+      const lineComparison = Number(tmpA[2]) - Number(tmpB[2]);
+      if (lineComparison !== 0) {
+        return lineComparison;
+      }
+      return Number(tmpA[3] || 0) - Number(tmpB[3] || 0);
+    }
+  }
   return a.localeCompare(b);
 };
 
@@ -433,7 +723,7 @@ export function printOccurrences(bomJson) {
         comp.name,
         comp.version || "",
         comp.evidence.occurrences
-          .map((l) => l.location)
+          .map((occurrence) => formatOccurrenceEvidence(occurrence))
           .sort(locationComparator)
           .join("\n"),
       ];

package/lib/helpers/display.poku.js

@@ -80,6 +80,155 @@ it("prints a provenance icon for registry-backed components", async () => {
   );
 });
 
+it("renders HBOM tables with hardware-centric columns and summary lines", async () => {
+  const rows = [];
+  const consoleLogStub = sinon.stub(console, "log");
+  try {
+    const bomJson = {
+      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: [
+        {
+          type: "device",
+          name: "eth0",
+          manufacturer: { name: "Intel" },
+          version: "en0",
+          properties: [
+            { name: "cdx:hbom:hardwareClass", value: "network-interface" },
+            { name: "cdx:hbom:status", value: "active" },
+            { name: "cdx:hbom:speedMbps", value: "2500" },
+            { name: "cdx:hbom:driver", value: "igc" },
+          ],
+        },
+        {
+          type: "device",
+          name: "wifi0",
+          properties: [
+            { name: "cdx:hbom:hardwareClass", value: "wireless-adapter" },
+            { name: "cdx:hbom:connected", value: "true" },
+            { name: "cdx:hbom:securityMode", value: "wpa3-personal" },
+            { name: "cdx:hbom:linkRateMbps", value: "1200" },
+            { name: "cdx:hbom:channel", value: "36" },
+          ],
+        },
+        {
+          type: "device",
+          name: "nvme0",
+          manufacturer: { name: "Samsung" },
+          properties: [
+            { name: "cdx:hbom:hardwareClass", value: "storage" },
+            { name: "cdx:hbom:capacity", value: "1 TB" },
+            { name: "cdx:hbom:smartStatus", value: "Verified" },
+            { name: "cdx:hbom:wearPercentageUsed", value: "2" },
+            { name: "cdx:hbom:transport", value: "nvme" },
+          ],
+        },
+        {
+          type: "device",
+          name: "Internal Battery",
+          properties: [
+            { name: "cdx:hbom:hardwareClass", value: "power" },
+            { name: "cdx:hbom:health", value: "Good" },
+            { name: "cdx:hbom:chargePercent", value: "80" },
+            { name: "cdx:hbom:maximumCapacity", value: "91%" },
+            { name: "cdx:hbom:cycleCount", value: "120" },
+          ],
+        },
+      ],
+      properties: [
+        { name: "cdx:hbom:collectorProfile", value: "linux-amd64-v1" },
+        { name: "cdx:hbom:evidence:commandCount", value: "2" },
+        { name: "cdx:hbom:evidence:commandDiagnosticCount", value: "2" },
+        {
+          name: "cdx:hbom:evidence:commandDiagnostic",
+          value: JSON.stringify({
+            command: "lsusb",
+            installHint:
+              "Command not found: install the Linux package providing lsusb (commonly `usbutils`).",
+            issue: "missing-command",
+          }),
+        },
+        {
+          name: "cdx:hbom:evidence:commandDiagnostic",
+          value: JSON.stringify({
+            command: "drm_info",
+            issue: "permission-denied",
+            privilegeHint:
+              "Retry with --privileged to allow a non-interactive sudo attempt for permission-sensitive Linux commands.",
+          }),
+        },
+      ],
+    };
+    const { printTable } = await esmock("./display.js", {
+      "./table.js": {
+        createStream: () => ({
+          end() {
+            // intentional no-op for stream stub
+          },
+          write(row) {
+            rows.push(row);
+          },
+        }),
+        table: sinon.stub().returns(""),
+      },
+      "./utils.js": {
+        getRecordedActivities: sinon.stub().returns([]),
+        isDryRun: false,
+        isSecureMode: false,
+        safeExistsSync: sinon.stub(),
+        toCamel: sinon.stub(),
+      },
+    });
+
+    printTable(bomJson);
+
+    assert.deepStrictEqual(rows[0], [
+      "Hardware Class",
+      "Name",
+      "Manufacturer / Version",
+      "Key Properties",
+      "Tags",
+    ]);
+    assert.strictEqual(rows[1][0], "network-interface");
+    assert.strictEqual(rows[1][1], "eth0");
+    assert.strictEqual(rows[1][2], "Intel / en0");
+    assert.match(rows[1][3], /status=active/u);
+    assert.match(rows[1][3], /speedMbps=2500/u);
+    assert.match(rows[1][3], /driver=igc/u);
+    assert.strictEqual(rows[2][0], "wireless-adapter");
+    assert.match(
+      rows[2][3],
+      /^connected=true, security=wpa3-personal, linkMbps=1200$/u,
+    );
+    assert.strictEqual(rows[3][0], "storage");
+    assert.match(rows[3][3], /^capacity=1 TB, smart=Verified, wearUsed=2$/u);
+    assert.strictEqual(rows[4][0], "power");
+    assert.match(rows[4][3], /^health=Good, charge%=80, maxCapacity=91%$/u);
+    assert.deepStrictEqual(buildTableSummaryLines(bomJson), [
+      "HBOM includes 4 hardware component(s) across 4 hardware class(es)",
+      "Top hardware classes: network-interface (1), power (1), storage (1), wireless-adapter (1)",
+      "Collector profile: linux-amd64-v1; command evidence: 2; observed files: 0",
+      "Collector diagnostics: 2 issue(s); missing commands: 1, permission denied: 1",
+      "Permission-sensitive enrichments were skipped or blocked. Re-run with --privileged where policy allows.",
+    ]);
+  } finally {
+    consoleLogStub.restore();
+  }
+});
+
 it("displaySelfThreatModel does not assume a default TLP classification", async () => {
   const tableStub = sinon.stub().returns("table-output");
   try {

package/lib/helpers/evidenceUtils.js

@@ -0,0 +1,58 @@
+export function createOccurrenceEvidence(location, details = {}) {
+  const normalizedLocation = String(location || "").trim();
+  if (!normalizedLocation) {
+    return undefined;
+  }
+  const occurrence = {
+    location: normalizedLocation,
+  };
+  for (const [key, value] of Object.entries(details || {})) {
+    if (value !== undefined && value !== null && value !== "") {
+      occurrence[key] = value;
+    }
+  }
+  return occurrence;
+}
+
+export function parseOccurrenceEvidenceLocation(location, details = {}) {
+  const normalizedLocation = String(location || "").trim();
+  if (!normalizedLocation) {
+    return undefined;
+  }
+  const hashMatch = normalizedLocation.match(/^(.*)#(\d+)$/);
+  if (hashMatch) {
+    return createOccurrenceEvidence(hashMatch[1], {
+      ...details,
+      line: Number(hashMatch[2]),
+    });
+  }
+  const lineOffsetMatch = normalizedLocation.match(/^(.*):(\d+):(\d+)$/);
+  if (lineOffsetMatch) {
+    return createOccurrenceEvidence(lineOffsetMatch[1], {
+      ...details,
+      line: Number(lineOffsetMatch[2]),
+      offset: Number(lineOffsetMatch[3]),
+    });
+  }
+  const lineMatch = normalizedLocation.match(/^(.*):(\d+)$/);
+  if (lineMatch) {
+    return createOccurrenceEvidence(lineMatch[1], {
+      ...details,
+      line: Number(lineMatch[2]),
+    });
+  }
+  return createOccurrenceEvidence(normalizedLocation, details);
+}
+
+export function formatOccurrenceEvidence(occurrence) {
+  if (!occurrence?.location) {
+    return "";
+  }
+  if (typeof occurrence.line === "number") {
+    if (typeof occurrence.offset === "number") {
+      return `${occurrence.location}:${occurrence.line}:${occurrence.offset}`;
+    }
+    return `${occurrence.location}#${occurrence.line}`;
+  }
+  return occurrence.location;
+}

package/lib/helpers/evidenceUtils.poku.js

@@ -0,0 +1,54 @@
+import { assert, describe, it } from "poku";
+
+import {
+  createOccurrenceEvidence,
+  formatOccurrenceEvidence,
+  parseOccurrenceEvidenceLocation,
+} from "./evidenceUtils.js";
+
+describe("evidence utils", () => {
+  it("creates occurrence evidence with structured line details", () => {
+    assert.deepStrictEqual(
+      createOccurrenceEvidence("src/index.js", {
+        line: 14,
+        offset: 3,
+        symbol: "node:crypto.createHash",
+      }),
+      {
+        location: "src/index.js",
+        line: 14,
+        offset: 3,
+        symbol: "node:crypto.createHash",
+      },
+    );
+  });
+
+  it("parses hash-style line locations", () => {
+    assert.deepStrictEqual(parseOccurrenceEvidenceLocation("src/index.js#27"), {
+      location: "src/index.js",
+      line: 27,
+    });
+  });
+
+  it("parses colon-style line and offset locations", () => {
+    assert.deepStrictEqual(
+      parseOccurrenceEvidenceLocation("src/index.js:29:7"),
+      {
+        location: "src/index.js",
+        line: 29,
+        offset: 7,
+      },
+    );
+  });
+
+  it("formats structured occurrence evidence for display", () => {
+    assert.strictEqual(
+      formatOccurrenceEvidence({
+        location: "src/index.js",
+        line: 12,
+        offset: 1,
+      }),
+      "src/index.js:12:1",
+    );
+  });
+});

package/lib/helpers/exportUtils.js

@@ -49,9 +49,18 @@ export function deriveSpdxOutputPath(outputPath) {
   if (outputPath.endsWith(".spdx.json")) {
     return outputPath;
   }
+  if (outputPath.endsWith(".cdx.bin")) {
+    return outputPath.replace(/\.cdx\.bin$/u, ".spdx.json");
+  }
   if (outputPath.endsWith(".cdx.json")) {
     return outputPath.replace(/\.cdx\.json$/u, ".spdx.json");
   }
+  if (outputPath.endsWith(".cdx")) {
+    return outputPath.replace(/\.cdx$/u, ".spdx.json");
+  }
+  if (outputPath.endsWith(".proto")) {
+    return outputPath.replace(/\.proto$/u, ".spdx.json");
+  }
   if (outputPath.endsWith(".json")) {
     return outputPath.replace(/\.json$/u, ".spdx.json");
   }