@cyclonedx/cdxgen 12.3.2 → 12.4.0

package/lib/server/server.js

@@ -27,7 +27,7 @@ import {
 } from "../helpers/source.js";
 import {
   CDXGEN_VERSION,
-  hasDangerousUnicode,
+  isAllowedHttpHost,
   isSecureMode,
   isWin,
 } from "../helpers/utils.js";
@@ -76,29 +76,7 @@ const ALLOWED_PARAMS = [
 
 const app = connect();
 
-function isAllowedHttpHost(hostname) {
-  if (!process.env.CDXGEN_ALLOWED_HOSTS) {
-    return true;
-  }
-  if (!hostname || hasDangerousUnicode(hostname)) {
-    return false;
-  }
-  const allowHosts = process.env.CDXGEN_ALLOWED_HOSTS.split(",")
-    .map((host) => host.trim())
-    .filter(Boolean);
-  for (const allowedHost of allowHosts) {
-    if (hostname === allowedHost) {
-      return true;
-    }
-    if (
-      allowedHost.startsWith("*.") &&
-      hostname.endsWith(allowedHost.slice(1))
-    ) {
-      return true;
-    }
-  }
-  return false;
-}
+export { isAllowedHttpHost };
 
 app.use(
   bodyParser.json({

package/lib/server/server.poku.js

@@ -12,7 +12,12 @@ import {
   validateAndRejectGitSource,
 } from "../helpers/source.js";
 import { isWin } from "../helpers/utils.js";
-import { getQueryParams, parseQueryString, parseValue } from "./server.js";
+import {
+  getQueryParams,
+  isAllowedHttpHost,
+  parseQueryString,
+  parseValue,
+} from "./server.js";
 
 function nullProtoObj(obj) {
   if (obj === null || typeof obj !== "object") {
@@ -171,6 +176,36 @@ describe("isAllowedHost()", () => {
   });
 });
 
+describe("isAllowedHttpHost()", () => {
+  let originalAllowedHosts;
+
+  beforeEach(() => {
+    originalAllowedHosts = process.env.CDXGEN_ALLOWED_HOSTS;
+  });
+
+  afterEach(() => {
+    if (originalAllowedHosts === undefined) {
+      delete process.env.CDXGEN_ALLOWED_HOSTS;
+    } else {
+      process.env.CDXGEN_ALLOWED_HOSTS = originalAllowedHosts;
+    }
+  });
+
+  it("allows exact host matches", () => {
+    process.env.CDXGEN_ALLOWED_HOSTS = "dependencytrack.example.com";
+    assert.strictEqual(isAllowedHttpHost("dependencytrack.example.com"), true);
+    assert.strictEqual(isAllowedHttpHost("other.example.com"), false);
+  });
+
+  it("allows only real subdomains for wildcard entries", () => {
+    process.env.CDXGEN_ALLOWED_HOSTS = "*.example.com";
+    assert.strictEqual(isAllowedHttpHost("api.example.com"), true);
+    assert.strictEqual(isAllowedHttpHost("deep.api.example.com"), true);
+    assert.strictEqual(isAllowedHttpHost("example.com"), false);
+    assert.strictEqual(isAllowedHttpHost("evil-example.com"), false);
+  });
+});
+
 describe("isAllowedPath()", () => {
   let originalPaths;
 

package/lib/stages/postgen/annotator.js

@@ -1,6 +1,12 @@
 import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
+import {
+  formatHbomHardwareClassSummary,
+  getHbomSummary,
+  isHbomLikeBom,
+} from "../../helpers/hbomAnalysis.js";
+import { getContainerFileInventoryStats } from "../../helpers/inventoryStats.js";
 import { thoughtLog } from "../../helpers/logger.js";
 import { getTrustedPublishingComponentCounts } from "../../helpers/provenanceUtils.js";
 import { dirNameStr } from "../../helpers/utils.js";
@@ -247,6 +253,11 @@ export function findBomType(bomJson) {
     bomType = "SBOM";
     description = "Software Bill-of-Materials (SBOM) including GitHub Actions";
   }
+  // Is this an HBOM?
+  else if (isHbomLikeBom(bomJson)) {
+    bomType = "HBOM";
+    description = "Hardware Bill-of-Materials (HBOM)";
+  }
   // Is this an OBOM?
   else if (lifecycles.filter((l) => l.phase === "operations").length > 0) {
     bomType = "OBOM";
@@ -296,7 +307,10 @@ export function textualMetadata(bomJson) {
   const swidCount = bomJson?.components?.filter((c) =>
     c?.purl?.startsWith("pkg:swid"),
   ).length;
+  const { unpackagedExecutableCount, unpackagedSharedLibraryCount } =
+    getContainerFileInventoryStats(bomJson?.components);
   const githubStats = getGitHubWorkflowStats(bomJson?.components);
+  const hbomSummary = bomType === "HBOM" ? getHbomSummary(bomJson) : undefined;
   const trustedPublishingCounts = getTrustedPublishingComponentCounts(
     bomJson?.components,
   );
@@ -511,6 +525,9 @@ export function textualMetadata(bomJson) {
   if (bundledSdks.length) {
     text = `${text} Furthermore, the container image bundles the following SDKs: ${bundledSdks.join(", ")}.`;
   }
+  if (unpackagedExecutableCount || unpackagedSharedLibraryCount) {
+    text = `${text} The container or rootfs inventory includes ${unpackagedExecutableCount} executable file component(s) and ${unpackagedSharedLibraryCount} shared library component(s) that were not traced to OS package ownership.`;
+  }
   if (bomPkgTypes.length && bomPkgNamespaces.length) {
     if (bomPkgTypes.length === 1) {
       if (bomPkgNamespaces.length === 1) {
@@ -537,6 +554,27 @@ export function textualMetadata(bomJson) {
       text = `${text} In addition, there are ${swidCount} applications installed on the system.`;
     }
   }
+  if (bomType === "HBOM" && hbomSummary) {
+    if (hbomSummary.hardwareClassCount > 0) {
+      text = `${text} The hardware inventory spans ${hbomSummary.hardwareClassCount} hardware classes.`;
+      const hardwareClassSummary = formatHbomHardwareClassSummary(
+        hbomSummary.hardwareClassCounts,
+      );
+      if (hardwareClassSummary) {
+        text = `${text} The most represented hardware classes are ${hardwareClassSummary}.`;
+      }
+    }
+    if (hbomSummary.collectorProfile) {
+      text = `${text} Collector profile '${hbomSummary.collectorProfile}' recorded ${hbomSummary.evidenceCommandCount} command evidence entr${hbomSummary.evidenceCommandCount === 1 ? "y" : "ies"}`;
+      if (hbomSummary.evidenceFileCount > 0) {
+        text = `${text} and ${hbomSummary.evidenceFileCount} observed file entr${hbomSummary.evidenceFileCount === 1 ? "y" : "ies"}`;
+      }
+      text = `${text}.`;
+    }
+    if (hbomSummary.identifierPolicy) {
+      text = `${text} Identifier policy is '${hbomSummary.identifierPolicy}'.`;
+    }
+  }
   if (bomType === "SaaSBOM") {
     text = `${text} ${bomJson.services.length} are described in this ${bomType} under services.`;
   }

package/lib/stages/postgen/annotator.poku.js

@@ -1,6 +1,6 @@
 import { assert, it } from "poku";
 
-import { extractTags, textualMetadata } from "./annotator.js";
+import { extractTags, findBomType, textualMetadata } from "./annotator.js";
 
 it("textualMetadata tests", () => {
   assert.deepStrictEqual(textualMetadata({}), undefined);
@@ -303,6 +303,36 @@ it("textualMetadata tests", () => {
       "Trusted publishing metadata is present for 1 npm component(s) and 1 PyPI component(s).",
     ),
   );
+
+  assert.ok(
+    textualMetadata({
+      metadata: {
+        component: {
+          name: "demo-image",
+          type: "container",
+          version: "1.0.0",
+        },
+        timestamp: "2026-01-01T00:00:00Z",
+        tools: {
+          components: [{ name: "cdxgen" }],
+        },
+      },
+      components: [
+        {
+          type: "file",
+          name: "demo",
+          properties: [{ name: "internal:is_executable", value: "true" }],
+        },
+        {
+          type: "file",
+          name: "libdemo.so",
+          properties: [{ name: "internal:is_shared_library", value: "true" }],
+        },
+      ],
+    }).includes(
+      "The container or rootfs inventory includes 1 executable file component(s) and 1 shared library component(s) that were not traced to OS package ownership.",
+    ),
+  );
 });
 
 it("extractTags tests", () => {
@@ -326,3 +356,79 @@ it("textualMetadata includes the CycloneDX 1.7 TLP classification from distribut
     /TLP\) classification for this document is 'AMBER_AND_STRICT'/,
   );
 });
+
+it("recognizes HBOMs and summarizes hardware-specific metadata", () => {
+  const hbom = {
+    bomFormat: "CycloneDX",
+    specVersion: "1.7",
+    metadata: {
+      timestamp: "2026-01-01T00:00:00Z",
+      tools: {
+        components: [{ name: "cdxgen" }],
+      },
+      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",
+        type: "device",
+        properties: [
+          { name: "cdx:hbom:hardwareClass", value: "network-interface" },
+        ],
+      },
+      {
+        name: "wlan0",
+        type: "device",
+        properties: [
+          { name: "cdx:hbom:hardwareClass", value: "network-interface" },
+        ],
+      },
+      {
+        name: "nvme0",
+        type: "device",
+        properties: [{ name: "cdx:hbom:hardwareClass", value: "storage" }],
+      },
+    ],
+    properties: [
+      { name: "cdx:hbom:collectorProfile", value: "linux-amd64-v1" },
+      { 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",
+      },
+    ],
+  };
+
+  assert.deepStrictEqual(findBomType(hbom), {
+    bomType: "HBOM",
+    bomTypeDescription: "Hardware Bill-of-Materials (HBOM)",
+  });
+  const summary = textualMetadata(hbom);
+  assert.match(summary, /Hardware Bill-of-Materials \(HBOM\)/u);
+  assert.match(summary, /The hardware inventory spans 2 hardware classes\./u);
+  assert.match(
+    summary,
+    /The most represented hardware classes are network-interface \(2\), storage \(1\)\./u,
+  );
+  assert.match(
+    summary,
+    /Collector profile 'linux-amd64-v1' recorded 2 command evidence entries\./u,
+  );
+  assert.match(summary, /Identifier policy is 'redacted-by-default'\./u);
+});

package/lib/stages/postgen/auditBom.js

@@ -10,6 +10,7 @@ import {
   expandBomAuditCategories,
   validateBomAuditCategories,
 } from "../../helpers/auditCategories.js";
+import { isHbomLikeBom as isHbomLikeBomDocument } from "../../helpers/hbomAnalysis.js";
 import { table } from "../../helpers/table.js";
 import {
   DEBUG_MODE,
@@ -21,17 +22,7 @@ import { evaluateRules, loadRules } from "./ruleEngine.js";
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
 const BUILTIN_RULES_DIR = join(__dirname, "..", "..", "..", "data", "rules");
 
-/**
- * Audit BOM formulation section using JSONata-powered rule engine
- * @param {Object} bomJson - Generated CycloneDX BOM
- * @param {Object} options - CLI options
- * @returns {Promise<Array>} Array of audit findings
- */
-export async function auditBom(bomJson, options) {
-  if (!bomJson) {
-    return [];
-  }
-  const findings = [];
+async function loadConfiguredBomAuditRules(options = {}) {
   const rules = await loadRules(BUILTIN_RULES_DIR);
   if (options.bomAuditRulesDir && safeExistsSync(options.bomAuditRulesDir)) {
     const userRulesDir = resolve(options.bomAuditRulesDir);
@@ -41,11 +32,11 @@ export async function auditBom(bomJson, options) {
     }
     rules.push(...userRules);
   }
-  if (rules.length === 0) {
-    if (DEBUG_MODE) {
-      console.log("No audit rules loaded; formulation audit skipped");
-    }
-    return findings;
+  if (!rules.length) {
+    return {
+      activeRules: [],
+      rules,
+    };
   }
   let activeRules = rules;
   if (options.bomAuditCategories) {
@@ -64,6 +55,107 @@ export async function auditBom(bomJson, options) {
       }
     }
   }
+  return {
+    activeRules,
+    rules,
+  };
+}
+
+/**
+ * Detect whether a BOM looks like an HBOM inventory.
+ *
+ * @param {object} bomJson CycloneDX BOM
+ * @returns {boolean} True when the BOM appears to represent hardware inventory
+ */
+export function isHbomLikeBom(bomJson) {
+  return isHbomLikeBomDocument(bomJson);
+}
+
+/**
+ * Detect whether a BOM looks like an OBOM/runtime inventory.
+ *
+ * @param {object} bomJson CycloneDX BOM
+ * @returns {boolean} True when the BOM appears to represent operations/runtime data
+ */
+export function isObomLikeBom(bomJson) {
+  if (!bomJson) {
+    return false;
+  }
+  if (isHbomLikeBom(bomJson)) {
+    return false;
+  }
+  if (
+    bomJson?.metadata?.component?.type === "operating-system" ||
+    bomJson?.metadata?.component?.type === "device"
+  ) {
+    return true;
+  }
+  if (
+    Array.isArray(bomJson?.metadata?.lifecycles) &&
+    bomJson.metadata.lifecycles.some(
+      (lifecycle) => lifecycle?.phase === "operations",
+    )
+  ) {
+    return true;
+  }
+  return (bomJson?.components || []).some((component) =>
+    (component?.properties || []).some(
+      (property) => property?.name === "cdx:osquery:category",
+    ),
+  );
+}
+
+function summarizeDryRunSupport(activeRules = []) {
+  const summary = {
+    fullCount: 0,
+    noCount: 0,
+    partialCount: 0,
+    totalRules: activeRules.length,
+  };
+  for (const rule of activeRules) {
+    if (rule?.dryRunSupport === "no") {
+      summary.noCount += 1;
+      continue;
+    }
+    if (rule?.dryRunSupport === "full") {
+      summary.fullCount += 1;
+      continue;
+    }
+    summary.partialCount += 1;
+  }
+  return summary;
+}
+
+export async function getBomAuditDryRunSupportSummary(options = {}) {
+  const { activeRules } = await loadConfiguredBomAuditRules(options);
+  return summarizeDryRunSupport(activeRules);
+}
+
+export function formatDryRunSupportSummary(summary) {
+  if (!summary) {
+    return "";
+  }
+  return `BOM audit dry-run summary: ${summary.noCount} rule(s) do not support dry-run, ${summary.partialCount} rule(s) have partial dry-run support, ${summary.totalRules} active rule(s) total.`;
+}
+
+/**
+ * Audit BOM formulation section using JSONata-powered rule engine
+ * @param {Object} bomJson - Generated CycloneDX BOM
+ * @param {Object} options - CLI options
+ * @returns {Promise<Array>} Array of audit findings
+ */
+export async function auditBom(bomJson, options) {
+  if (!bomJson) {
+    return [];
+  }
+  const findings = [];
+  const { activeRules, rules } = await loadConfiguredBomAuditRules(options);
+  if (rules.length === 0) {
+    if (DEBUG_MODE) {
+      console.log("No audit rules loaded; formulation audit skipped");
+    }
+    return findings;
+  }
   const allFindings = await evaluateRules(activeRules, bomJson);
   if (options.bomAuditMinSeverity) {
     const minSeverity = options.bomAuditMinSeverity.toLowerCase();
@@ -87,7 +179,7 @@ export async function auditBom(bomJson, options) {
 /**
  * Format findings for console output with color-coded severity
  */
-export function formatConsoleOutput(findings) {
+export function renderBomAuditConsoleReport(findings) {
   if (!findings?.length) {
     return "";
   }
@@ -119,7 +211,18 @@ export function formatConsoleOutput(findings) {
     line.push(f.location?.file || "");
     data.push(line);
   }
-  console.log(table(data, config));
+  return table(data, config);
+}
+
+/**
+ * Format findings for console output with color-coded severity
+ */
+export function formatConsoleOutput(findings) {
+  const output = renderBomAuditConsoleReport(findings);
+  if (output) {
+    console.log(output);
+  }
+  return output;
 }
 
 /**