@cyclonedx/cdxgen 12.3.3 → 12.4.1

package/lib/managers/docker.poku.js

@@ -124,6 +124,8 @@ it("parseImageName tests", () => {
 async function loadDockerModule({
   clientResponse,
   fsOverrides,
+  streamOverrides,
+  tarOverrides,
   utilsOverrides,
 } = {}) {
   const dockerClient = sinon.stub().resolves(
@@ -151,7 +153,13 @@ async function loadDockerModule({
     getAllFiles: sinon.stub().returns([]),
     getTmpDir: sinon.stub().returns("/tmp"),
     isDryRun: false,
+    readEnvironmentVariable: sinon
+      .stub()
+      .callsFake((varName) => process.env[varName]),
     recordActivity: sinon.stub(),
+    recordDecisionActivity: sinon.stub(),
+    recordSensitiveFileRead: sinon.stub(),
+    safeExtractArchive: sinon.stub().resolves(true),
     safeExistsSync: sinon.stub().returns(false),
     safeMkdirSync: sinon.stub(),
     safeMkdtempSync: sinon.stub().returns("/tmp/docker-images-test"),
@@ -162,7 +170,15 @@ async function loadDockerModule({
   };
   const dockerModule = await esmock("./docker.js", {
     "node:fs": fsStub,
+    "node:stream/promises": {
+      pipeline: sinon.stub().resolves(),
+      ...streamOverrides,
+    },
     got: { default: gotStub },
+    tar: {
+      x: sinon.stub().returns("extractor"),
+      ...tarOverrides,
+    },
     "../helpers/utils.js": utilsStub,
   });
   return { dockerClient, dockerModule, fsStub, gotStub, utilsStub };
@@ -386,12 +402,265 @@ await it("docker getConnection reports blocked network activity in dry-run mode"
   });
 });
 
-await it("docker extractTar reports a blocked untar activity in dry-run mode", async () => {
+await it("docker getConnection skips dry-run tracing on containerd runtimes", async () => {
+  const recordActivity = sinon.stub();
+  const recordSensitiveFileRead = sinon.stub();
+  await withEnv(
+    {
+      CONTAINERD_ADDRESS: "/run/containerd/containerd.sock",
+    },
+    async () => {
+      const { dockerModule } = await loadDockerModule({
+        fsOverrides: {
+          readFileSync: sinon.stub().returns(authConfigData("docker.io")),
+        },
+        utilsOverrides: {
+          isDryRun: true,
+          recordActivity,
+          recordSensitiveFileRead,
+          safeExistsSync: dockerConfigExistsStub(),
+        },
+      });
+      const conn = await dockerModule.getConnection({}, "docker.io");
+      assert.strictEqual(conn, undefined);
+    },
+  );
+  sinon.assert.notCalled(recordActivity);
+  sinon.assert.notCalled(recordSensitiveFileRead);
+});
+
+await it("docker getConnection traces docker credential file reads in dry-run mode", async () => {
   const recordActivity = sinon.stub();
+  const recordSensitiveFileRead = sinon.stub();
+  await withDockerConfig(async () => {
+    const { dockerModule } = await loadDockerModule({
+      fsOverrides: {
+        readFileSync: sinon.stub().returns(authConfigData("docker.io")),
+      },
+      utilsOverrides: {
+        isDryRun: true,
+        recordActivity,
+        recordSensitiveFileRead,
+        safeExistsSync: dockerConfigExistsStub(),
+      },
+    });
+    await dockerModule.getConnection({}, "docker.io");
+  });
+  sinon.assert.calledWithMatch(recordSensitiveFileRead, sinon.match.string, {
+    label: "Docker credential file",
+  });
+  sinon.assert.calledWithMatch(recordActivity, {
+    kind: "network",
+    status: "blocked",
+    target: "docker.io",
+  });
+});
+
+await it("docker makeRequest does not trace docker credential file reads when the read fails", async () => {
+  const recordSensitiveFileRead = sinon.stub();
+  await withEnv(
+    {
+      DOCKER_AUTH_CONFIG: undefined,
+      DOCKER_EMAIL: undefined,
+      DOCKER_PASSWORD: undefined,
+      DOCKER_USER: undefined,
+    },
+    async () => {
+      await withDockerConfig(async () => {
+        const { dockerModule } = await loadDockerModule({
+          fsOverrides: {
+            readFileSync: sinon.stub().throws(new Error("read failed")),
+          },
+          utilsOverrides: {
+            recordSensitiveFileRead,
+            safeExistsSync: dockerConfigExistsStub(),
+          },
+        });
+        await assert.rejects(() =>
+          dockerModule.makeRequest(
+            "images/create?fromImage=docker.io/library/alpine:latest",
+            "POST",
+            "docker.io/library/alpine:latest",
+          ),
+        );
+      });
+    },
+  );
+  sinon.assert.notCalled(recordSensitiveFileRead);
+});
+
+await it("docker getConnection does not trace TLS client files when reading them fails", async () => {
+  const recordSensitiveFileRead = sinon.stub();
+  await withEnv(
+    {
+      DOCKER_AUTH_CONFIG: undefined,
+      DOCKER_CERT_PATH: "/tmp/docker-certs",
+      DOCKER_EMAIL: undefined,
+      DOCKER_HOST: "tcp://docker.example.test:2376",
+      DOCKER_PASSWORD: undefined,
+      DOCKER_USER: undefined,
+    },
+    async () => {
+      const { dockerModule } = await loadDockerModule({
+        fsOverrides: {
+          readFileSync: sinon
+            .stub()
+            .onFirstCall()
+            .throws(new Error("cert read failed")),
+        },
+        utilsOverrides: {
+          recordSensitiveFileRead,
+        },
+      });
+      await assert.rejects(() => dockerModule.getConnection({}, "docker.io"));
+    },
+  );
+  sinon.assert.notCalled(recordSensitiveFileRead);
+});
+
+await it("docker makeRequest does not trace TLS client files when reading them fails", async () => {
+  const recordSensitiveFileRead = sinon.stub();
+  await withEnv(
+    {
+      DOCKER_AUTH_CONFIG: undefined,
+      DOCKER_CERT_PATH: "/tmp/docker-certs",
+      DOCKER_EMAIL: undefined,
+      DOCKER_HOST: "tcp://docker.example.test:2376",
+      DOCKER_PASSWORD: undefined,
+      DOCKER_USER: undefined,
+    },
+    async () => {
+      const { dockerModule } = await loadDockerModule({
+        fsOverrides: {
+          readFileSync: sinon
+            .stub()
+            .onFirstCall()
+            .throws(new Error("cert read failed")),
+        },
+        utilsOverrides: {
+          recordSensitiveFileRead,
+        },
+      });
+      await assert.rejects(() =>
+        dockerModule.makeRequest(
+          "images/create?fromImage=docker.io/library/alpine:latest",
+          "POST",
+          "docker.io/library/alpine:latest",
+        ),
+      );
+    },
+  );
+  sinon.assert.notCalled(recordSensitiveFileRead);
+});
+
+await it("docker getConnection records which credential source was selected", async () => {
+  const recordDecisionActivity = sinon.stub();
+  await withDockerConfig(async () => {
+    const { dockerModule } = await loadDockerModule({
+      fsOverrides: {
+        readFileSync: sinon.stub().returns(authConfigData("docker.io")),
+      },
+      utilsOverrides: {
+        isDryRun: true,
+        recordDecisionActivity,
+        safeExistsSync: dockerConfigExistsStub(),
+      },
+    });
+    await dockerModule.getConnection({}, "docker.io");
+  });
+  sinon.assert.calledWithMatch(
+    recordDecisionActivity,
+    "docker-auth:docker.io",
+    {
+      metadata: sinon.match({
+        decisionType: "credential-source-selection",
+        selectedSource: "docker-config-auth",
+      }),
+    },
+  );
+});
+
+await it("docker getConnection traces credential helper resolution in dry-run mode", async () => {
+  const safeSpawnSync = sinon.stub().returns({
+    status: 1,
+    stdout: "",
+    stderr: "",
+  });
+  await withDockerConfig(async () => {
+    const { dockerModule } = await loadDockerModule({
+      fsOverrides: {
+        readFileSync: sinon.stub().returns(credHelperConfigData("docker.io")),
+      },
+      utilsOverrides: {
+        isDryRun: true,
+        safeExistsSync: dockerConfigExistsStub(),
+        safeSpawnSync,
+      },
+    });
+    await dockerModule.getConnection({}, "docker.io");
+  });
+  sinon.assert.calledWithExactly(
+    safeSpawnSync,
+    credHelperExe("osxkeychain"),
+    ["get"],
+    {
+      input: "docker.io",
+    },
+  );
+});
+
+await it("docker extractTar reports a blocked untar activity in dry-run mode", async () => {
+  const safeExtractArchive = sinon.stub().resolves(false);
   const { dockerModule } = await loadDockerModule({
     utilsOverrides: {
-      isDryRun: true,
-      recordActivity,
+      safeExtractArchive,
+    },
+  });
+  const result = await dockerModule.extractTar(
+    "/tmp/image.tar",
+    "/tmp/out",
+    {},
+  );
+  assert.strictEqual(result, false);
+  sinon.assert.calledWithMatch(
+    safeExtractArchive,
+    "/tmp/image.tar",
+    "/tmp/out",
+    sinon.match.func,
+    "untar",
+    {
+      blockedReason:
+        "Dry run mode blocks untar and layer extraction operations because they create files on disk.",
+      metadata: {
+        archiveFormat: "tar",
+      },
+    },
+  );
+});
+
+await it("docker extractTar delegates successful untar tracing to safeExtractArchive", async () => {
+  const safeExtractArchive = sinon.stub().resolves(true);
+  const { dockerModule } = await loadDockerModule({
+    utilsOverrides: {
+      safeExtractArchive,
+    },
+  });
+  const result = await dockerModule.extractTar(
+    "/tmp/image.tar",
+    "/tmp/out",
+    {},
+  );
+  assert.strictEqual(result, true);
+  sinon.assert.calledOnce(safeExtractArchive);
+});
+
+await it("docker extractTar preserves failure handling after safeExtractArchive rejects", async () => {
+  const extractionError = new Error("permission denied");
+  extractionError.code = "EACCES";
+  const safeExtractArchive = sinon.stub().rejects(extractionError);
+  const { dockerModule } = await loadDockerModule({
+    utilsOverrides: {
+      safeExtractArchive,
     },
   });
   const result = await dockerModule.extractTar(
@@ -400,28 +669,84 @@ await it("docker extractTar reports a blocked untar activity in dry-run mode", a
     {},
   );
   assert.strictEqual(result, false);
+  sinon.assert.calledOnce(safeExtractArchive);
+});
+
+await it("docker exportImage reports a blocked container activity in dry-run mode", async () => {
+  const recordActivity = sinon.stub();
+  const recordSensitiveFileRead = sinon.stub();
+  await withDockerConfig(async () => {
+    const { dockerModule } = await loadDockerModule({
+      fsOverrides: {
+        readFileSync: sinon.stub().returns(authConfigData("docker.io")),
+      },
+      utilsOverrides: {
+        isDryRun: true,
+        recordActivity,
+        recordSensitiveFileRead,
+        safeExistsSync: dockerConfigExistsStub(),
+      },
+    });
+    const result = await dockerModule.exportImage("alpine:3.20", {});
+    assert.strictEqual(result, undefined);
+  });
+  sinon.assert.calledWithMatch(recordSensitiveFileRead, sinon.match.string, {
+    label: "Docker credential file",
+  });
   sinon.assert.calledWithMatch(recordActivity, {
-    kind: "untar",
+    kind: "container",
     status: "blocked",
-    target: "/tmp/image.tar -> /tmp/out",
+    target: "alpine:3.20",
   });
 });
 
-await it("docker exportImage reports a blocked container activity in dry-run mode", async () => {
+await it("docker exportImage preserves scoped registry refs for dry-run auth tracing", async () => {
+  const recordDecisionActivity = sinon.stub();
+  await withDockerConfig(async () => {
+    const { dockerModule } = await loadDockerModule({
+      fsOverrides: {
+        readFileSync: sinon
+          .stub()
+          .returns(authConfigData("registry.example.com/team")),
+      },
+      utilsOverrides: {
+        isDryRun: true,
+        recordDecisionActivity,
+        safeExistsSync: dockerConfigExistsStub(),
+      },
+    });
+    const result = await dockerModule.exportImage(
+      "registry.example.com/team/app:latest",
+      {},
+    );
+    assert.strictEqual(result, undefined);
+  });
+  sinon.assert.calledWithMatch(
+    recordDecisionActivity,
+    "docker-auth:registry.example.com/team/app",
+    {
+      metadata: sinon.match({
+        selectedSource: "docker-config-auth",
+      }),
+    },
+  );
+});
+
+await it("docker exportImage skips dry-run tracing for local paths", async () => {
   const recordActivity = sinon.stub();
+  const recordSensitiveFileRead = sinon.stub();
   const { dockerModule } = await loadDockerModule({
     utilsOverrides: {
       isDryRun: true,
       recordActivity,
+      recordSensitiveFileRead,
+      safeExistsSync: sinon.stub().returns(true),
     },
   });
-  const result = await dockerModule.exportImage("alpine:3.20", {});
+  const result = await dockerModule.exportImage("/tmp/image.tar", {});
   assert.strictEqual(result, undefined);
-  sinon.assert.calledWithMatch(recordActivity, {
-    kind: "container",
-    status: "blocked",
-    target: "alpine:3.20",
-  });
+  sinon.assert.notCalled(recordActivity);
+  sinon.assert.notCalled(recordSensitiveFileRead);
 });
 
 await it("docker exportImage ignores local directories", async () => {

package/lib/server/server.js

@@ -8,6 +8,7 @@ import compression from "compression";
 import connect from "connect";
 
 import { createBom, submitBom } from "../cli/index.js";
+import { isCycloneDxBom } from "../helpers/bomUtils.js";
 import { normalizeOutputFormats } from "../helpers/exportUtils.js";
 import {
   cleanupSourceDir,
@@ -27,7 +28,7 @@ import {
 } from "../helpers/source.js";
 import {
   CDXGEN_VERSION,
-  hasDangerousUnicode,
+  isAllowedHttpHost,
   isSecureMode,
   isWin,
 } from "../helpers/utils.js";
@@ -76,32 +77,7 @@ const ALLOWED_PARAMS = [
 
 const app = connect();
 
-export function isAllowedHttpHost(hostname) {
-  if (!process.env.CDXGEN_ALLOWED_HOSTS) {
-    return true;
-  }
-  if (!hostname || hasDangerousUnicode(hostname)) {
-    return false;
-  }
-  const normalizedHostname = hostname.toLowerCase();
-  const allowHosts = process.env.CDXGEN_ALLOWED_HOSTS.split(",")
-    .map((host) => host.trim())
-    .filter(Boolean);
-  for (const allowedHost of allowHosts) {
-    const normalizedAllowedHost = allowedHost.toLowerCase();
-    if (normalizedHostname === normalizedAllowedHost) {
-      return true;
-    }
-    if (
-      normalizedAllowedHost.startsWith("*.") &&
-      normalizedHostname.length > normalizedAllowedHost.length - 1 &&
-      normalizedHostname.endsWith(`.${normalizedAllowedHost.slice(2)}`)
-    ) {
-      return true;
-    }
-  }
-  return false;
-}
+export { isAllowedHttpHost };
 
 app.use(
   bodyParser.json({
@@ -492,7 +468,7 @@ const start = (options) => {
       let responseBomJson = bomNSData.bomJson;
       if (
         requestedFormats.includes("spdx") &&
-        bomNSData?.bomJson?.bomFormat === "CycloneDX"
+        isCycloneDxBom(bomNSData?.bomJson)
       ) {
         responseBomJson = convertCycloneDxToSpdx(bomNSData.bomJson, reqOptions);
       }

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);
+});