@cyclonedx/cdxgen 12.2.1 → 12.3.0

package/lib/managers/docker.poku.js

@@ -1,28 +1,22 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import process from "node:process";
 
-import { assert, beforeEach, describe, it, skip } from "poku";
+import esmock from "esmock";
+import { assert, beforeEach, describe, it } from "poku";
+import sinon from "sinon";
+import { create as createTar } from "tar";
 
 import {
   addSkippedSrcFiles,
+  exportArchive,
   exportImage,
-  getConnection,
-  getImage,
+  extractFromManifest,
   isWin,
   parseImageName,
-  removeImage,
 } from "./docker.js";
 
-if (process.env.CI === "true" && (isWin || process.platform === "darwin")) {
-  skip("Skipping Docker tests on Windows and Mac");
-}
-
-await it("docker connection", async () => {
-  const dockerConn = await getConnection();
-  if (dockerConn) {
-    assert.ok(dockerConn);
-  }
-});
-
 it("parseImageName tests", () => {
   if (isWin && process.env.CI === "true") {
     return;
@@ -127,25 +121,330 @@ it("parseImageName tests", () => {
   );
 });
 
-await it("docker getImage", async () => {
-  if (isWin && process.env.CI === "true") {
-    return;
+async function loadDockerModule({ clientResponse, utilsOverrides } = {}) {
+  const dockerClient = sinon.stub().resolves(
+    clientResponse || {
+      Id: "sha256:hello-world",
+      RepoTags: ["hello-world:latest"],
+    },
+  );
+  dockerClient.stream = sinon.stub();
+  const gotStub = {
+    extend: sinon.stub().returns(dockerClient),
+    get: sinon.stub().resolves({ body: "OK" }),
+  };
+  const utilsStub = {
+    DEBUG_MODE: false,
+    extractPathEnv: sinon.stub().returns([]),
+    getAllFiles: sinon.stub().returns([]),
+    getTmpDir: sinon.stub().returns("/tmp"),
+    safeExistsSync: sinon.stub().returns(false),
+    safeMkdirSync: sinon.stub(),
+    safeSpawnSync: sinon.stub().returns({ status: 1, stdout: "", stderr: "" }),
+    ...utilsOverrides,
+  };
+  const dockerModule = await esmock("./docker.js", {
+    got: { default: gotStub },
+    "../helpers/utils.js": utilsStub,
+  });
+  return { dockerClient, dockerModule, gotStub, utilsStub };
+}
+
+await it("docker connection uses the detected daemon client", async () => {
+  const { dockerModule, gotStub, dockerClient } = await loadDockerModule();
+  const dockerConn = await dockerModule.getConnection();
+  assert.strictEqual(dockerConn, dockerClient);
+  sinon.assert.calledOnce(gotStub.get);
+  sinon.assert.calledOnce(gotStub.extend);
+});
+
+await it("docker getImage returns inspect data from the daemon client", async () => {
+  const inspectData = {
+    Id: "sha256:hello-world",
+    RepoTags: ["hello-world:latest"],
+  };
+  const { dockerModule, dockerClient } = await loadDockerModule({
+    clientResponse: inspectData,
+  });
+  const imageData = await dockerModule.getImage("hello-world:latest");
+  assert.deepStrictEqual(imageData, inspectData);
+  sinon.assert.calledWith(
+    dockerClient,
+    "images/hello-world:latest/json",
+    sinon.match.has("method", "GET"),
+  );
+});
+
+await it("docker getImage falls back to the daemon client when cli inspect fails", async () => {
+  const originalDockerUseCli = process.env.DOCKER_USE_CLI;
+  process.env.DOCKER_USE_CLI = "1";
+  try {
+    const inspectData = {
+      Id: "sha256:hello-world",
+      RepoTags: ["hello-world:latest"],
+    };
+    const { dockerModule, dockerClient } = await loadDockerModule({
+      clientResponse: inspectData,
+    });
+    const imageData = await dockerModule.getImage("hello-world:latest");
+    assert.deepStrictEqual(imageData, inspectData);
+    sinon.assert.calledWith(
+      dockerClient,
+      "images/hello-world:latest/json",
+      sinon.match.has("method", "GET"),
+    );
+  } finally {
+    if (originalDockerUseCli === undefined) {
+      delete process.env.DOCKER_USE_CLI;
+    } else {
+      process.env.DOCKER_USE_CLI = originalDockerUseCli;
+    }
   }
-  const imageData = await getImage("hello-world:latest");
-  if (imageData) {
-    const removeData = await removeImage("hello-world:latest");
-    if (removeData) {
-      assert.ok(removeData);
+});
+
+await it("docker getImage uses nerdctl when DOCKER_CMD is configured", async () => {
+  const originalDockerCmd = process.env.DOCKER_CMD;
+  const originalDockerUseCli = process.env.DOCKER_USE_CLI;
+  process.env.DOCKER_CMD = "nerdctl";
+  delete process.env.DOCKER_USE_CLI;
+  try {
+    const inspectData = {
+      Id: "sha256:hello-world",
+      RepoTags: ["hello-world:latest"],
+    };
+    const safeSpawnSync = sinon.stub();
+    safeSpawnSync
+      .onCall(0)
+      .returns({
+        status: 0,
+        stdout: '{"Repository":"hello-world","Tag":"latest"}\n',
+        stderr: "",
+      })
+      .onCall(1)
+      .returns({
+        status: 0,
+        stdout: JSON.stringify([inspectData]),
+        stderr: "",
+      });
+    const { dockerModule, utilsStub } = await loadDockerModule({
+      clientResponse: inspectData,
+      utilsOverrides: {
+        safeSpawnSync,
+      },
+    });
+    const imageData = await dockerModule.getImage("hello-world:latest");
+    assert.deepStrictEqual(imageData, inspectData);
+    sinon.assert.calledWithExactly(safeSpawnSync, "nerdctl", [
+      "images",
+      "--format=json",
+    ]);
+    sinon.assert.calledWithExactly(safeSpawnSync, "nerdctl", [
+      "inspect",
+      "hello-world:latest",
+    ]);
+    sinon.assert.notCalled(utilsStub.safeMkdirSync);
+  } finally {
+    if (originalDockerCmd === undefined) {
+      delete process.env.DOCKER_CMD;
+    } else {
+      process.env.DOCKER_CMD = originalDockerCmd;
+    }
+    if (originalDockerUseCli === undefined) {
+      delete process.env.DOCKER_USE_CLI;
+    } else {
+      process.env.DOCKER_USE_CLI = originalDockerUseCli;
     }
   }
 });
 
-await it("docker getImage", async () => {
-  if (isWin && process.env.CI === "true") {
-    return;
+await it("docker exportImage ignores local directories", async () => {
+  const imageData = await exportImage(".");
+  assert.strictEqual(imageData, undefined);
+});
+
+await it("extractFromManifest derives PATH metadata from archive config", async () => {
+  const tempDir = mkdtempSync(join(tmpdir(), "cdxgen-docker-"));
+  try {
+    const allLayersExplodedDir = join(tempDir, "all-layers");
+    const manifestFile = join(tempDir, "manifest.json");
+    mkdirSync(allLayersExplodedDir, { recursive: true });
+    writeFileSync(
+      manifestFile,
+      JSON.stringify([
+        {
+          Config: "blobs/sha256/config.json",
+          Layers: ["blobs/sha256/layer.tar"],
+        },
+      ]),
+    );
+    mkdirSync(join(tempDir, "blobs", "sha256"), { recursive: true });
+    writeFileSync(
+      join(tempDir, "blobs", "sha256", "config.json"),
+      JSON.stringify({
+        config: {
+          Env: [
+            "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+          ],
+          WorkingDir: "/work",
+        },
+      }),
+    );
+    writeFileSync(join(tempDir, "blobs", "sha256", "layer.tar"), "");
+
+    const exportData = await extractFromManifest(
+      manifestFile,
+      {},
+      tempDir,
+      allLayersExplodedDir,
+      {},
+    );
+
+    assert.deepStrictEqual(exportData.binPaths, [
+      "/usr/local/sbin",
+      "/usr/local/bin",
+      "/usr/sbin",
+      "/usr/bin",
+      "/sbin",
+      "/bin",
+    ]);
+    assert.deepStrictEqual(exportData.inspectData?.Config?.Env, [
+      "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
+    ]);
+    assert.strictEqual(
+      exportData.lastWorkingDir,
+      join(allLayersExplodedDir, "/work"),
+    );
+  } finally {
+    rmSync(tempDir, { force: true, recursive: true });
+  }
+});
+
+await it("extractFromManifest resolves OCI index manifests", async () => {
+  const tempDir = mkdtempSync(join(tmpdir(), "cdxgen-docker-"));
+  try {
+    const allLayersExplodedDir = join(tempDir, "all-layers");
+    const manifestFile = join(tempDir, "index.json");
+    mkdirSync(allLayersExplodedDir, { recursive: true });
+    mkdirSync(join(tempDir, "blobs", "sha256"), { recursive: true });
+    writeFileSync(
+      manifestFile,
+      JSON.stringify({
+        schemaVersion: 2,
+        manifests: [
+          {
+            digest: "sha256:manifest-blob",
+            mediaType: "application/vnd.oci.image.manifest.v1+json",
+          },
+        ],
+      }),
+    );
+    writeFileSync(
+      join(tempDir, "blobs", "sha256", "manifest-blob"),
+      JSON.stringify({
+        schemaVersion: 2,
+        config: {
+          digest: "sha256:config-blob",
+        },
+        layers: [
+          {
+            digest: "sha256:layer-blob",
+          },
+        ],
+      }),
+    );
+    writeFileSync(
+      join(tempDir, "blobs", "sha256", "config-blob"),
+      JSON.stringify({
+        config: {
+          Env: ["PATH=/usr/local/bin:/usr/bin:/bin"],
+          WorkingDir: "/workspace",
+        },
+      }),
+    );
+    writeFileSync(join(tempDir, "blobs", "sha256", "layer-blob"), "");
+
+    const exportData = await extractFromManifest(
+      manifestFile,
+      {},
+      tempDir,
+      allLayersExplodedDir,
+      {},
+    );
+
+    assert.deepStrictEqual(exportData.binPaths, [
+      "/usr/local/bin",
+      "/usr/bin",
+      "/bin",
+    ]);
+    assert.deepStrictEqual(exportData.inspectData?.Config?.Env, [
+      "PATH=/usr/local/bin:/usr/bin:/bin",
+    ]);
+    assert.strictEqual(
+      exportData.lastWorkingDir,
+      join(allLayersExplodedDir, "/workspace"),
+    );
+  } finally {
+    rmSync(tempDir, { force: true, recursive: true });
+  }
+});
+
+await it("exportArchive derives PATH metadata from blobs-only podman archives", async () => {
+  const tempDir = mkdtempSync(join(tmpdir(), "cdxgen-docker-"));
+  try {
+    const archiveDir = join(tempDir, "archive");
+    const archiveFile = join(tempDir, "podman-archive.tar");
+    mkdirSync(join(archiveDir, "blobs", "sha256"), { recursive: true });
+    writeFileSync(
+      join(archiveDir, "blobs", "sha256", "manifest-blob"),
+      JSON.stringify({
+        schemaVersion: 2,
+        config: {
+          digest: "sha256:config-blob",
+        },
+        layers: [
+          {
+            digest: "sha256:layer-blob",
+          },
+        ],
+      }),
+    );
+    writeFileSync(
+      join(archiveDir, "blobs", "sha256", "config-blob"),
+      JSON.stringify({
+        config: {
+          Env: ["PATH=/usr/local/sbin:/usr/local/bin:/usr/bin:/bin"],
+          WorkingDir: "/app",
+        },
+      }),
+    );
+    writeFileSync(join(archiveDir, "blobs", "sha256", "layer-blob"), "");
+    await createTar(
+      {
+        cwd: archiveDir,
+        file: archiveFile,
+        portable: true,
+      },
+      ["blobs"],
+    );
+
+    const exportData = await exportArchive(archiveFile, {});
+
+    assert.deepStrictEqual(exportData.binPaths, [
+      "/usr/local/sbin",
+      "/usr/local/bin",
+      "/usr/bin",
+      "/bin",
+    ]);
+    assert.deepStrictEqual(exportData.inspectData?.Config?.Env, [
+      "PATH=/usr/local/sbin:/usr/local/bin:/usr/bin:/bin",
+    ]);
+    assert.strictEqual(
+      exportData.lastWorkingDir,
+      join(exportData.allLayersExplodedDir, "app"),
+    );
+  } finally {
+    rmSync(tempDir, { force: true, recursive: true });
   }
-  const imageData = await exportImage("hello-world:latest");
-  assert.ok(imageData);
 });
 
 describe("addSkippedSrcFiles tests", () => {

package/lib/managers/oci.js

@@ -2,6 +2,7 @@ import { Buffer } from "node:buffer";
 import fs from "node:fs";
 import { arch } from "node:os";
 
+import { isCycloneDxBom } from "../helpers/bomUtils.js";
 import {
   getAllFiles,
   getTmpDir,
@@ -9,6 +10,100 @@ import {
   safeSpawnSync,
 } from "../helpers/utils.js";
 
+const ORAS_CREATED_ANNOTATION = "org.opencontainers.image.created";
+
+function getManifestDescriptors(manifestObj) {
+  if (Array.isArray(manifestObj?.manifests)) {
+    return manifestObj.manifests;
+  }
+  if (Array.isArray(manifestObj?.referrers)) {
+    return manifestObj.referrers;
+  }
+  return [];
+}
+
+function getRepositoryRef(image) {
+  let repositoryRef = image;
+  const digestIndex = repositoryRef.indexOf("@");
+  if (digestIndex !== -1) {
+    repositoryRef = repositoryRef.slice(0, digestIndex);
+  }
+  const lastSlashIndex = repositoryRef.lastIndexOf("/");
+  const tagIndex = repositoryRef.lastIndexOf(":");
+  if (tagIndex > lastSlashIndex) {
+    repositoryRef = repositoryRef.slice(0, tagIndex);
+  }
+  return repositoryRef;
+}
+
+function getManifestImageRef(image, manifest) {
+  if (manifest?.reference) {
+    return manifest.reference;
+  }
+  if (manifest?.digest) {
+    return `${getRepositoryRef(image)}@${manifest.digest}`;
+  }
+  return undefined;
+}
+
+function getManifestCreatedAt(manifest) {
+  const createdAt = manifest?.annotations?.[ORAS_CREATED_ANNOTATION];
+  if (!createdAt) {
+    return undefined;
+  }
+  const createdAtTimestamp = Date.parse(createdAt);
+  if (Number.isNaN(createdAtTimestamp)) {
+    return undefined;
+  }
+  return createdAtTimestamp;
+}
+
+function selectManifestImageRef(image, manifestObj) {
+  const manifestDescriptors = getManifestDescriptors(manifestObj);
+  const candidates = manifestDescriptors
+    .map((manifest, index) => {
+      const imageRef = getManifestImageRef(image, manifest);
+      if (!imageRef) {
+        return undefined;
+      }
+      return {
+        createdAt: getManifestCreatedAt(manifest),
+        imageRef,
+        index,
+      };
+    })
+    .filter(Boolean);
+  if (!candidates.length) {
+    return undefined;
+  }
+  candidates.sort((a, b) => {
+    if (a.createdAt !== undefined || b.createdAt !== undefined) {
+      if (a.createdAt === undefined) {
+        return 1;
+      }
+      if (b.createdAt === undefined) {
+        return -1;
+      }
+      if (b.createdAt !== a.createdAt) {
+        return b.createdAt - a.createdAt;
+      }
+    }
+    return b.index - a.index;
+  });
+  return candidates[0]?.imageRef;
+}
+
+function getBomFiles(tmpDir) {
+  let bomFiles = getAllFiles(tmpDir, "**/*.{bom,cdx}.json");
+  if (!bomFiles.length) {
+    bomFiles = getAllFiles(tmpDir, "**/bom.json");
+  }
+  if (!bomFiles.length) {
+    bomFiles = getAllFiles(tmpDir, "**/*.json");
+  }
+  return bomFiles;
+}
+
 /**
  * Retrieves a CycloneDX BOM attached to an OCI image using the `oras` CLI tool.
  * Discovers SBOM attachments via `oras discover`, pulls the first matching
@@ -50,26 +145,8 @@ export function getBomWithOras(image, platform = undefined) {
     const out = Buffer.from(result.stdout).toString();
     try {
       const manifestObj = JSON.parse(out);
-      let manifest;
-      if (manifestObj?.manifests) {
-        if (
-          manifestObj?.manifests?.length &&
-          Array.isArray(manifestObj.manifests) &&
-          manifestObj.manifests[0]?.reference
-        ) {
-          manifest = manifestObj.manifests[0];
-        }
-      } else if (manifestObj?.referrers) {
-        if (
-          manifestObj?.referrers?.length &&
-          Array.isArray(manifestObj.referrers) &&
-          manifestObj.referrers[0]?.reference
-        ) {
-          manifest = manifestObj.referrers[0];
-        }
-      }
-      if (manifest != null) {
-        const imageRef = manifest.reference;
+      const imageRef = selectManifestImageRef(image, manifestObj);
+      if (imageRef) {
         const tmpDir = getTmpDir();
         result = safeSpawnSync("oras", ["pull", imageRef, "-o", tmpDir], {
           shell: isWin,
@@ -80,9 +157,16 @@ export function getBomWithOras(image, platform = undefined) {
           );
           return undefined;
         }
-        const bomFiles = getAllFiles(tmpDir, "**/*.{bom,cdx}.json");
-        if (bomFiles.length) {
-          return JSON.parse(fs.readFileSync(bomFiles.pop(), "utf8"));
+        const bomFiles = getBomFiles(tmpDir);
+        for (const bomFile of bomFiles) {
+          try {
+            const bomJson = JSON.parse(fs.readFileSync(bomFile, "utf8"));
+            if (isCycloneDxBom(bomJson)) {
+              return bomJson;
+            }
+          } catch {
+            // Ignore unrelated or malformed JSON files pulled alongside the SBOM.
+          }
         }
       } else {
         console.log(`${image} does not contain any SBOM attachment!`);

package/lib/managers/oci.poku.js

@@ -0,0 +1,132 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import esmock from "esmock";
+import { assert, describe, it } from "poku";
+import sinon from "sinon";
+
+async function loadOciModule({ getAllFiles, getTmpDir, safeSpawnSync }) {
+  return esmock("./oci.js", {
+    "../helpers/utils.js": {
+      getAllFiles,
+      getTmpDir,
+      isWin: false,
+      safeSpawnSync,
+    },
+  });
+}
+
+describe("getBomWithOras()", () => {
+  it("pulls the newest digest-only SBOM referrer", async () => {
+    const tmpDir = mkdtempSync(path.join(os.tmpdir(), "cdxgen-oci-poku-"));
+    const bomFile = path.join(tmpDir, "sbom-oci-image.cdx.json");
+    const bomJson = {
+      bomFormat: "CycloneDX",
+      specVersion: "1.6",
+      signature: {
+        algorithm: "RS512",
+        value: "signed",
+      },
+    };
+    const safeSpawnSync = sinon.stub();
+    const getAllFiles = sinon.stub();
+    try {
+      writeFileSync(bomFile, JSON.stringify(bomJson), "utf8");
+      safeSpawnSync
+        .onCall(0)
+        .returns({
+          status: 0,
+          stdout: JSON.stringify({
+            referrers: [
+              {
+                digest: "sha256:older",
+                annotations: {
+                  "org.opencontainers.image.created": "2026-04-29T01:26:38Z",
+                },
+              },
+              {
+                digest: "sha256:newer",
+                annotations: {
+                  "org.opencontainers.image.created": "2026-04-29T02:00:20Z",
+                },
+              },
+            ],
+          }),
+        })
+        .onCall(1)
+        .returns({
+          status: 0,
+          stdout: "",
+        });
+      getAllFiles.withArgs(tmpDir, "**/*.{bom,cdx}.json").returns([bomFile]);
+      const { getBomWithOras } = await loadOciModule({
+        getAllFiles,
+        getTmpDir: sinon.stub().returns(tmpDir),
+        safeSpawnSync,
+      });
+      const result = getBomWithOras("ghcr.io/cdxgen/alpine-python313:master");
+      assert.deepStrictEqual(result, bomJson);
+      sinon.assert.calledWith(
+        safeSpawnSync,
+        "oras",
+        ["pull", "ghcr.io/cdxgen/alpine-python313@sha256:newer", "-o", tmpDir],
+        { shell: false },
+      );
+    } finally {
+      rmSync(tmpDir, { force: true, recursive: true });
+    }
+  });
+
+  it("falls back to bom.json when oras pulls a plain BOM filename", async () => {
+    const tmpDir = mkdtempSync(path.join(os.tmpdir(), "cdxgen-oci-poku-"));
+    const bomFile = path.join(tmpDir, "bom.json");
+    const bomJson = {
+      bomFormat: "CycloneDX",
+      specVersion: "1.6",
+      signature: {
+        algorithm: "RS512",
+        value: "signed",
+      },
+    };
+    const safeSpawnSync = sinon.stub();
+    const getAllFiles = sinon.stub();
+    try {
+      writeFileSync(bomFile, JSON.stringify(bomJson), "utf8");
+      safeSpawnSync
+        .onCall(0)
+        .returns({
+          status: 0,
+          stdout: JSON.stringify({
+            manifests: [
+              {
+                reference: "ghcr.io/cdxgen/demo@sha256:latest",
+              },
+            ],
+          }),
+        })
+        .onCall(1)
+        .returns({
+          status: 0,
+          stdout: "",
+        });
+      getAllFiles.withArgs(tmpDir, "**/*.{bom,cdx}.json").returns([]);
+      getAllFiles.withArgs(tmpDir, "**/bom.json").returns([bomFile]);
+      const { getBomWithOras } = await loadOciModule({
+        getAllFiles,
+        getTmpDir: sinon.stub().returns(tmpDir),
+        safeSpawnSync,
+      });
+      const result = getBomWithOras("ghcr.io/cdxgen/demo:master");
+      assert.deepStrictEqual(result, bomJson);
+      sinon.assert.calledWith(
+        safeSpawnSync,
+        "oras",
+        ["pull", "ghcr.io/cdxgen/demo@sha256:latest", "-o", tmpDir],
+        { shell: false },
+      );
+    } finally {
+      rmSync(tmpDir, { force: true, recursive: true });
+    }
+  });
+});

package/lib/server/openapi.yaml

@@ -134,6 +134,11 @@ paths:
           required: false
           schema:
             $ref: '#/components/schemas/CDXGEN/properties/specVersion'
+        - name: format
+          in: query
+          required: false
+          schema:
+            $ref: '#/components/schemas/CDXGEN/properties/format'
         - name: filter
           in: query
           required: false
@@ -298,6 +303,18 @@ components:
           type: string
           description: CycloneDX Specification version to use
           default: "1.7"
+        format:
+          type: array
+          items:
+            type: string
+            enum:
+              - cyclonedx
+              - cdx
+              - spdx
+              - spdx-json
+              - spdx3
+              - spdx3-json
+          description: Export format(s). Supports cyclonedx and spdx.
         filter:
           type: array
           items: