@cyclonedx/cdxgen 12.2.0 → 12.3.0

package/lib/helpers/registryProvenance.poku.js

@@ -0,0 +1,452 @@
+import { assert, describe, it } from "poku";
+
+import {
+  collectNpmRegistryProvenanceProperties,
+  collectPypiRegistryProvenanceProperties,
+} from "./registryProvenance.js";
+
+function getProperty(properties, propertyName) {
+  return properties.find((property) => property.name === propertyName)?.value;
+}
+
+describe("collectNpmRegistryProvenanceProperties()", () => {
+  it("extracts trusted publishing and publisher details from npm metadata", () => {
+    const properties = collectNpmRegistryProvenanceProperties(
+      {
+        time: {
+          "1.2.0": "2025-01-01T10:00:00.000Z",
+          "1.2.1": "2025-01-15T10:00:00.000Z",
+          "1.2.2": "2026-03-01T10:00:00.000Z",
+          "1.2.3": "2026-04-01T10:00:00.000Z",
+          created: "2024-01-01T10:00:00.000Z",
+          modified: "2026-04-01T10:00:00.000Z",
+        },
+        versions: {
+          "1.2.0": {
+            _npmUser: {
+              name: "previous-publisher",
+            },
+            maintainers: [{ name: "alice" }, { email: "alice@example.com" }],
+          },
+          "1.2.1": {
+            _npmUser: {
+              name: "previous-publisher",
+            },
+            maintainers: [{ name: "alice" }, { email: "alice@example.com" }],
+          },
+          "1.2.2": {
+            _npmUser: {
+              name: "previous-publisher",
+            },
+            maintainers: [{ name: "alice" }, { email: "alice@example.com" }],
+          },
+          "1.2.3": {
+            _npmUser: {
+              email: "publisher@example.com",
+              name: "publisher",
+            },
+            maintainers: [{ name: "bob" }, { email: "bob@example.com" }],
+            dist: {
+              integrity: "sha512-artifact-integrity",
+              provenance: {
+                predicateType: "https://slsa.dev/provenance/v1",
+                signatures: [
+                  {
+                    keyid: "sigstore-npm-key",
+                    sig: "MEUCIQDsig",
+                  },
+                ],
+                subject: {
+                  digest: {
+                    sha256: "npm-subject-digest",
+                  },
+                },
+                url: "https://registry.npmjs.org/-/npm/v1/attestations/example@1.2.3",
+              },
+              shasum: "deadbeefcafebabe",
+            },
+          },
+        },
+      },
+      "1.2.3",
+    );
+
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:trustedPublishing"),
+      "true",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:provenanceUrl"),
+      "https://registry.npmjs.org/-/npm/v1/attestations/example@1.2.3",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:publisher"),
+      "publisher",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:publisherEmail"),
+      "publisher@example.com",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:publishTime"),
+      "2026-04-01T10:00:00.000Z",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:artifactIntegrity"),
+      "sha512-artifact-integrity",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:artifactShasum"),
+      "deadbeefcafebabe",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:provenanceDigest"),
+      "npm-subject-digest",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:provenanceKeyId"),
+      "sigstore-npm-key",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:provenancePredicateType"),
+      "https://slsa.dev/provenance/v1",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:provenanceSignature"),
+      "MEUCIQDsig",
+    );
+    assert.strictEqual(getProperty(properties, "cdx:npm:versionCount"), "4");
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:priorVersion"),
+      "1.2.2",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:priorPublisher"),
+      "previous-publisher",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:publisherDrift"),
+      "true",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:packageCreatedTime"),
+      "2024-01-01T10:00:00.000Z",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:maintainerSet"),
+      "bob, bob@example.com, publisher, publisher@example.com",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:priorMaintainerSet"),
+      "alice, alice@example.com, previous-publisher",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:maintainerSetDrift"),
+      "true",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:releaseGapDays"),
+      "31.00",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:releaseGapBaselineDays"),
+      "212.00",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:releaseGapSampleSize"),
+      "2",
+    );
+  });
+
+  it("extracts compressed cadence and partial maintainer overlap drift from npm metadata", () => {
+    const properties = collectNpmRegistryProvenanceProperties(
+      {
+        time: {
+          "0.9.0": "2024-11-01T10:00:00.000Z",
+          "1.0.0": "2025-01-01T10:00:00.000Z",
+          "1.1.0": "2025-03-15T10:00:00.000Z",
+          "1.2.0": "2025-05-27T10:00:00.000Z",
+          "1.2.1": "2025-06-05T10:00:00.000Z",
+          created: "2024-01-01T10:00:00.000Z",
+          modified: "2025-06-05T10:00:00.000Z",
+        },
+        versions: {
+          "0.9.0": {
+            _npmUser: {
+              name: "alice",
+            },
+          },
+          "1.0.0": {
+            _npmUser: {
+              name: "alice",
+            },
+          },
+          "1.1.0": {
+            _npmUser: {
+              name: "alice",
+            },
+          },
+          "1.2.0": {
+            _npmUser: {
+              name: "bob",
+            },
+            maintainers: [{ name: "alice" }],
+          },
+          "1.2.1": {
+            _npmUser: {
+              name: "bob",
+            },
+            maintainers: [{ name: "charlie" }],
+          },
+        },
+      },
+      "1.2.1",
+    );
+
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:maintainerSetPartialDrift"),
+      "true",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:maintainerOverlapCount"),
+      "1",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:maintainerOverlapRatio"),
+      "0.33",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:compressedCadence"),
+      "true",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:releaseCadenceCompressionRatio"),
+      "0.12",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:npm:maintainerSetDrift"),
+      undefined,
+    );
+  });
+});
+
+describe("collectPypiRegistryProvenanceProperties()", () => {
+  it("extracts trusted publishing and uploader details from PyPI metadata", () => {
+    const properties = collectPypiRegistryProvenanceProperties(
+      {
+        releases: {
+          "1.7.0": [
+            {
+              upload_time_iso_8601: "2025-11-20T08:15:30.000Z",
+              uploader: "previous-uploader",
+            },
+          ],
+          "1.8.0": [
+            {
+              upload_time_iso_8601: "2025-12-05T08:15:30.000Z",
+              uploader: "previous-uploader",
+            },
+          ],
+          "1.9.0": [
+            {
+              upload_time_iso_8601: "2025-12-20T08:15:30.000Z",
+              uploader: "previous-uploader",
+            },
+          ],
+          "2.0.0": [
+            {
+              digests: {
+                blake2b_256: "pypi-blake",
+                sha256: "pypi-sha256",
+              },
+              md5_digest: "pypi-md5",
+              provenance: {
+                predicateType: "https://docs.pypi.org/attestations/publish/v1",
+                signatures: [
+                  {
+                    keyid: "sigstore-pypi-key",
+                    sig: "c2lnbmF0dXJl",
+                  },
+                ],
+                subject: {
+                  digest: {
+                    sha256: "pypi-provenance-digest",
+                  },
+                },
+              },
+              provenance_url:
+                "https://pypi.org/integrity/example/2.0.0/example-2.0.0.tar.gz/provenance",
+              upload_time_iso_8601: "2026-03-20T08:15:30.000Z",
+              uploader: "trusted-publisher",
+              uploader_verified: true,
+            },
+          ],
+        },
+      },
+      "2.0.0",
+    );
+
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:trustedPublishing"),
+      "true",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:provenanceUrl"),
+      "https://pypi.org/integrity/example/2.0.0/example-2.0.0.tar.gz/provenance",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:publishTime"),
+      "2026-03-20T08:15:30.000Z",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:publisher"),
+      "trusted-publisher",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:uploaderVerified"),
+      "true",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:artifactDigestSha256"),
+      "pypi-sha256",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:artifactDigestBlake2b256"),
+      "pypi-blake",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:artifactDigestMd5"),
+      "pypi-md5",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:provenanceDigest"),
+      "pypi-provenance-digest",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:provenanceKeyId"),
+      "sigstore-pypi-key",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:provenancePredicateType"),
+      "https://docs.pypi.org/attestations/publish/v1",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:provenanceSignature"),
+      "c2lnbmF0dXJl",
+    );
+    assert.strictEqual(getProperty(properties, "cdx:pypi:versionCount"), "4");
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:priorVersion"),
+      "1.9.0",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:priorPublisher"),
+      "previous-uploader",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:publisherDrift"),
+      "true",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:packageCreatedTime"),
+      "2025-11-20T08:15:30.000Z",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:uploaderSet"),
+      "trusted-publisher",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:priorUploaderSet"),
+      "previous-uploader",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:uploaderSetDrift"),
+      "true",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:releaseGapDays"),
+      "90.00",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:releaseGapBaselineDays"),
+      "15.00",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:releaseGapSampleSize"),
+      "2",
+    );
+  });
+
+  it("extracts compressed cadence and partial uploader overlap drift from PyPI metadata", () => {
+    const properties = collectPypiRegistryProvenanceProperties(
+      {
+        releases: {
+          "0.9.0": [
+            {
+              upload_time_iso_8601: "2024-11-01T08:15:30.000Z",
+              uploader: "alice",
+            },
+          ],
+          "1.0.0": [
+            {
+              upload_time_iso_8601: "2025-01-01T08:15:30.000Z",
+              uploader: "alice",
+            },
+          ],
+          "1.1.0": [
+            {
+              upload_time_iso_8601: "2025-03-15T08:15:30.000Z",
+              uploader: "alice",
+            },
+          ],
+          "1.2.0": [
+            {
+              upload_time_iso_8601: "2025-05-27T08:15:30.000Z",
+              uploader: "alice",
+            },
+            {
+              upload_time_iso_8601: "2025-05-27T08:16:30.000Z",
+              uploader: "bob",
+            },
+          ],
+          "1.2.1": [
+            {
+              upload_time_iso_8601: "2025-06-05T08:15:30.000Z",
+              uploader: "bob",
+            },
+            {
+              upload_time_iso_8601: "2025-06-05T08:16:30.000Z",
+              uploader: "charlie",
+            },
+          ],
+        },
+      },
+      "1.2.1",
+    );
+
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:uploaderSetPartialDrift"),
+      "true",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:uploaderOverlapCount"),
+      "1",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:uploaderOverlapRatio"),
+      "0.33",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:compressedCadence"),
+      "true",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:releaseCadenceCompressionRatio"),
+      "0.12",
+    );
+    assert.strictEqual(
+      getProperty(properties, "cdx:pypi:uploaderSetDrift"),
+      undefined,
+    );
+  });
+});

package/lib/helpers/remote/dependency-track.js

@@ -0,0 +1,84 @@
+import { Buffer } from "node:buffer";
+
+/**
+ * Returns the Dependency-Track BOM API URL.
+ *
+ * @param {string} serverUrl Dependency-Track server URL
+ * @returns {string} API URL to submit BOM payload
+ */
+export function getDependencyTrackBomUrl(serverUrl) {
+  return `${serverUrl.replace(/\/$/, "")}/api/v1/bom`;
+}
+
+/**
+ * Build the payload for Dependency-Track BOM submission.
+ *
+ * @param {Object} args CLI/server arguments
+ * @param {Object} bomContents BOM Json
+ * @returns {Object | undefined} payload object if project coordinates are valid
+ */
+export function buildDependencyTrackBomPayload(args, bomContents) {
+  let encodedBomContents = Buffer.from(JSON.stringify(bomContents)).toString(
+    "base64",
+  );
+  if (encodedBomContents.startsWith("77u/")) {
+    encodedBomContents = encodedBomContents.substring(4);
+  }
+  const autoCreate =
+    typeof args.autoCreate === "boolean"
+      ? args.autoCreate
+      : args.autoCreate !== "false";
+  const bomPayload = {
+    autoCreate: String(autoCreate),
+    bom: encodedBomContents,
+  };
+  if (
+    typeof args.projectId !== "undefined" ||
+    typeof args.projectName !== "undefined"
+  ) {
+    if (typeof args.projectId !== "undefined") {
+      bomPayload.project = args.projectId;
+    }
+    if (typeof args.projectName !== "undefined") {
+      bomPayload.projectName = args.projectName;
+    }
+    // Dependency-Track submissions use "main" as fallback when no version is provided.
+    bomPayload.projectVersion = args.projectVersion || "main";
+  } else {
+    return undefined;
+  }
+  const parentProjectId = args.parentProjectId || args.parentUUID;
+  const hasParentUuidMode = typeof parentProjectId !== "undefined";
+  const hasParentName = typeof args.parentProjectName !== "undefined";
+  const hasParentVersion = typeof args.parentProjectVersion !== "undefined";
+  const hasParentCoordsMode = hasParentName || hasParentVersion;
+  if (hasParentUuidMode && hasParentCoordsMode) {
+    return undefined;
+  }
+  if (!hasParentUuidMode && hasParentName !== hasParentVersion) {
+    return undefined;
+  }
+  if (hasParentUuidMode) {
+    bomPayload.parentUUID = parentProjectId;
+  }
+  if (hasParentName && hasParentVersion) {
+    bomPayload.parentName = args.parentProjectName;
+    bomPayload.parentVersion = args.parentProjectVersion;
+  }
+  if (
+    typeof args.isLatest === "boolean" ||
+    args.isLatest === "true" ||
+    args.isLatest === "false"
+  ) {
+    bomPayload.isLatest =
+      typeof args.isLatest === "boolean"
+        ? args.isLatest
+        : args.isLatest === "true";
+  }
+  if (typeof args.projectTag !== "undefined") {
+    bomPayload.projectTags = (
+      Array.isArray(args.projectTag) ? args.projectTag : [args.projectTag]
+    ).map((tag) => ({ name: tag }));
+  }
+  return bomPayload;
+}

package/lib/helpers/remote/dependency-track.poku.js

@@ -0,0 +1,119 @@
+import { assert, describe, it } from "poku";
+
+import {
+  buildDependencyTrackBomPayload,
+  getDependencyTrackBomUrl,
+} from "./dependency-track.js";
+
+describe("Dependency-Track helper tests", () => {
+  it("returns submission URL without trailing slash duplication", () => {
+    assert.strictEqual(
+      getDependencyTrackBomUrl("https://dtrack.example.com/"),
+      "https://dtrack.example.com/api/v1/bom",
+    );
+    assert.strictEqual(
+      getDependencyTrackBomUrl("https://dtrack.example.com"),
+      "https://dtrack.example.com/api/v1/bom",
+    );
+  });
+
+  it("builds payload with parentUUID and tags", () => {
+    const payload = buildDependencyTrackBomPayload(
+      {
+        projectName: "child",
+        projectVersion: "1.0.0",
+        parentProjectId: "d9628844-5f04-4ca7-88a2-64eb6bc64db0",
+        projectTag: ["tag1", "tag2"],
+      },
+      { bom: "test" },
+    );
+    assert.deepStrictEqual(payload, {
+      autoCreate: "true",
+      bom: "eyJib20iOiJ0ZXN0In0=",
+      parentUUID: "d9628844-5f04-4ca7-88a2-64eb6bc64db0",
+      projectName: "child",
+      projectTags: [{ name: "tag1" }, { name: "tag2" }],
+      projectVersion: "1.0.0",
+    });
+  });
+
+  it("builds payload with parentName and parentVersion", () => {
+    const payload = buildDependencyTrackBomPayload(
+      {
+        projectName: "child",
+        projectVersion: "1.0.0",
+        parentProjectName: "parent",
+        parentProjectVersion: "2.0.0",
+      },
+      { bom: "test2" },
+    );
+    assert.deepStrictEqual(payload, {
+      autoCreate: "true",
+      bom: "eyJib20iOiJ0ZXN0MiJ9",
+      parentName: "parent",
+      parentVersion: "2.0.0",
+      projectName: "child",
+      projectVersion: "1.0.0",
+    });
+  });
+
+  it("returns undefined when project identity is missing", () => {
+    const payload = buildDependencyTrackBomPayload({}, { bom: "test3" });
+    assert.strictEqual(payload, undefined);
+  });
+
+  it("supports configurable autoCreate and isLatest", () => {
+    const payload = buildDependencyTrackBomPayload(
+      {
+        autoCreate: false,
+        isLatest: true,
+        projectName: "child",
+      },
+      { bom: "test4" },
+    );
+    assert.deepStrictEqual(payload, {
+      autoCreate: "false",
+      bom: "eyJib20iOiJ0ZXN0NCJ9",
+      isLatest: true,
+      projectName: "child",
+      projectVersion: "main",
+    });
+  });
+
+  it("defaults projectVersion to main when only projectName is provided", () => {
+    const payload = buildDependencyTrackBomPayload(
+      { projectName: "child" },
+      { bom: "test5" },
+    );
+    assert.deepStrictEqual(payload, {
+      autoCreate: "true",
+      bom: "eyJib20iOiJ0ZXN0NSJ9",
+      projectName: "child",
+      projectVersion: "main",
+    });
+  });
+
+  it("returns undefined when parent UUID and parent name/version are both provided", () => {
+    const payload = buildDependencyTrackBomPayload(
+      {
+        parentProjectId: "d9628844-5f04-4ca7-88a2-64eb6bc64db0",
+        parentProjectName: "parent",
+        parentProjectVersion: "1.0.0",
+        projectName: "child",
+      },
+      { bom: "test6" },
+    );
+    assert.strictEqual(payload, undefined);
+  });
+
+  it("returns undefined when parent name/version mode is incomplete", () => {
+    const payload = buildDependencyTrackBomPayload(
+      {
+        parentProjectName: "parent",
+        projectName: "child",
+      },
+      { bom: "test7" },
+    );
+    assert.strictEqual(payload, undefined);
+  });
+});