@cyclonedx/cdxgen 12.2.1 → 12.3.0

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

@@ -0,0 +1,341 @@
+import { assert, describe, it } from "poku";
+
+import { validateSpdx } from "../../validator/bomValidator.js";
+import {
+  convertCycloneDxToSpdx,
+  SPDX_JSONLD_CONTEXT,
+} from "./spdxConverter.js";
+
+function sampleBom() {
+  return {
+    bomFormat: "CycloneDX",
+    specVersion: 1.7,
+    serialNumber: "urn:uuid:1b671687-395b-41f5-a30f-a58921a69b79",
+    version: 1,
+    metadata: {
+      timestamp: "2024-02-02T00:00:00Z",
+      component: {
+        type: "application",
+        name: "demo-app",
+        version: "1.0.0",
+        "bom-ref": "pkg:generic/demo-app@1.0.0",
+        properties: [{ name: "cdx:app:tier", value: "backend" }],
+      },
+      properties: [{ name: "cdx:bom:componentTypes", value: "library" }],
+    },
+    components: [
+      {
+        type: "library",
+        name: "lodash",
+        version: "4.17.21",
+        purl: "pkg:npm/lodash@4.17.21",
+        "bom-ref": "pkg:npm/lodash@4.17.21",
+        hashes: [
+          { alg: "SHA-256", content: "abc123" },
+          { alg: "BLAKE2s", content: "def456" },
+        ],
+        properties: [{ name: "cdx:npm:hasInstallScript", value: "true" }],
+        externalReferences: [
+          { type: "website", url: "https://lodash.com" },
+          { type: "vcs", url: "https://github.com/lodash/lodash.git" },
+        ],
+        author: "Legacy Author",
+        authors: [{ name: "Lodash Author", email: "author@lodash.com" }],
+        publisher: "OpenJS Foundation",
+        maintainers: [{ name: "Lodash Maintainer" }],
+        tags: ["utility", "js"],
+        licenses: [{ license: { id: "MIT" } }],
+      },
+    ],
+    dependencies: [
+      {
+        ref: "pkg:generic/demo-app@1.0.0",
+        dependsOn: ["pkg:npm/lodash@4.17.21"],
+      },
+      { ref: "pkg:npm/lodash@4.17.21", dependsOn: [] },
+    ],
+    formulation: [
+      {
+        services: [
+          {
+            "bom-ref": "urn:example:service:api",
+            name: "api-service",
+            properties: [{ name: "cdx:service:httpMethod", value: "GET" }],
+          },
+        ],
+        workflows: [
+          {
+            "bom-ref": "urn:example:workflow:build",
+            name: "build-workflow",
+            tasks: [
+              {
+                "bom-ref": "urn:example:task:build",
+                name: "build-task",
+                properties: [
+                  {
+                    name: "cdx:github:workflow:hasWritePermissions",
+                    value: "true",
+                  },
+                ],
+              },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+}
+
+function minimalBom() {
+  return {
+    bomFormat: "CycloneDX",
+    specVersion: 1.7,
+    metadata: {
+      timestamp: "2024-02-02T00:00:00Z",
+      component: {
+        type: "application",
+        name: "demo-app",
+        version: "1.0.0",
+        purl: "pkg:generic/demo-app@1.0.0",
+        "bom-ref": "pkg:generic/demo-app@1.0.0",
+      },
+    },
+    components: [
+      {
+        type: "library",
+        name: "left-pad",
+        version: "1.3.0",
+        purl: "pkg:npm/left-pad@1.3.0",
+        "bom-ref": "pkg:npm/left-pad@1.3.0",
+      },
+    ],
+    dependencies: [
+      {
+        ref: "pkg:generic/demo-app@1.0.0",
+        dependsOn: ["pkg:npm/left-pad@1.3.0"],
+      },
+      { ref: "pkg:npm/left-pad@1.3.0", dependsOn: [] },
+    ],
+  };
+}
+
+function getExtensionPropertyMap(spdxElement) {
+  const propertyMap = new Map();
+  for (const extension of spdxElement?.extension || []) {
+    for (const entry of extension?.extension_cdxProperty || []) {
+      propertyMap.set(
+        entry.extension_cdxPropName,
+        entry.extension_cdxPropValue,
+      );
+    }
+  }
+  return propertyMap;
+}
+
+describe("convertCycloneDxToSpdx", () => {
+  it("converts a CycloneDX BOM into SPDX 3.0.1 JSON-LD", () => {
+    const spdxJson = convertCycloneDxToSpdx(sampleBom(), {
+      projectName: "demo-app",
+    });
+    assert.strictEqual(spdxJson["@context"], SPDX_JSONLD_CONTEXT);
+    assert.ok(Array.isArray(spdxJson["@graph"]));
+    assert.ok(
+      spdxJson["@graph"].some((element) => element.type === "SpdxDocument"),
+    );
+    assert.ok(
+      spdxJson["@graph"].some((element) => element.type === "Relationship"),
+    );
+    assert.deepStrictEqual(spdxJson["@graph"][0].createdBy, [
+      "https://github.com/cdxgen/cdxgen",
+    ]);
+  });
+
+  it("produces an export accepted by the bundled validator", () => {
+    const spdxJson = convertCycloneDxToSpdx(sampleBom(), {
+      projectName: "demo-app",
+    });
+    assert.strictEqual(validateSpdx(spdxJson), true);
+  });
+
+  it("converts CycloneDX 1.6 BOMs to valid SPDX 3.0.1 JSON-LD", () => {
+    const bom16 = sampleBom();
+    bom16.specVersion = 1.6;
+    const spdxJson = convertCycloneDxToSpdx(bom16, {
+      projectName: "demo-app",
+    });
+    assert.strictEqual(validateSpdx(spdxJson), true);
+  });
+
+  it("converts CycloneDX 1.7 BOMs to valid SPDX 3.0.1 JSON-LD", () => {
+    const bom17 = sampleBom();
+    bom17.specVersion = 1.7;
+    const spdxJson = convertCycloneDxToSpdx(bom17, {
+      projectName: "demo-app",
+    });
+    assert.strictEqual(validateSpdx(spdxJson), true);
+  });
+
+  it("preserves advanced CycloneDX data in SPDX extension fields", () => {
+    const spdxJson = convertCycloneDxToSpdx(sampleBom(), {
+      projectName: "demo-app",
+    });
+    const packageElement = spdxJson["@graph"].find(
+      (element) => element.software_packageUrl === "pkg:npm/lodash@4.17.21",
+    );
+    assert.ok(packageElement);
+    assert.ok(Array.isArray(packageElement.externalRef));
+    assert.strictEqual(
+      packageElement.externalRef[0].externalRefType,
+      "altWebPage",
+    );
+    const packageExtensionProperties = getExtensionPropertyMap(packageElement);
+    assert.strictEqual(
+      packageElement.extension[0].type,
+      "extension_CdxPropertiesExtension",
+    );
+    assert.strictEqual(
+      packageExtensionProperties.get("properties.cdx:npm:hasInstallScript"),
+      "true",
+    );
+    assert.strictEqual(
+      packageExtensionProperties.get("hashes"),
+      '[{"algorithm":"SHA-256","hashValue":"abc123","normalizedAlgorithm":"sha256"},{"algorithm":"BLAKE2s","hashValue":"def456"}]',
+    );
+    assert.strictEqual(
+      packageExtensionProperties.get("author"),
+      "Legacy Author",
+    );
+    assert.strictEqual(
+      packageExtensionProperties.get("authors"),
+      '[{"name":"Lodash Author","email":"author@lodash.com"}]',
+    );
+    assert.strictEqual(
+      packageExtensionProperties.get("publisher"),
+      "OpenJS Foundation",
+    );
+    assert.strictEqual(
+      packageExtensionProperties.get("maintainers"),
+      '[{"name":"Lodash Maintainer"}]',
+    );
+    assert.strictEqual(
+      packageExtensionProperties.get("tags"),
+      '["utility","js"]',
+    );
+    assert.strictEqual(
+      packageExtensionProperties.get("licenses"),
+      '[{"license":{"id":"MIT"}}]',
+    );
+    const documentElement = spdxJson["@graph"].find(
+      (element) => element.type === "SpdxDocument",
+    );
+    assert.ok(documentElement);
+    const documentExtensionProperties =
+      getExtensionPropertyMap(documentElement);
+    assert.strictEqual(
+      documentElement.profileConformance.includes("extension"),
+      true,
+    );
+    assert.strictEqual(
+      documentExtensionProperties.get(
+        "metadataProperties.cdx:bom:componentTypes",
+      ),
+      "library",
+    );
+    assert.strictEqual(
+      documentExtensionProperties.get("formulation"),
+      JSON.stringify(sampleBom().formulation),
+    );
+  });
+
+  it("omits document-level SPDX extensions while package-level metadata still enables the extension profile", () => {
+    const spdxJson = convertCycloneDxToSpdx(minimalBom(), {
+      projectName: "demo-app",
+    });
+    const packageElement = spdxJson["@graph"].find(
+      (element) => element.software_packageUrl === "pkg:npm/left-pad@1.3.0",
+    );
+    const documentElement = spdxJson["@graph"].find(
+      (element) => element.type === "SpdxDocument",
+    );
+    assert.ok(packageElement);
+    assert.ok(documentElement);
+    assert.strictEqual(documentElement.extension, undefined);
+    assert.strictEqual(
+      documentElement.profileConformance.includes("extension"),
+      true,
+    );
+    assert.strictEqual(
+      getExtensionPropertyMap(packageElement).get("bomRef"),
+      "pkg:npm/left-pad@1.3.0",
+    );
+  });
+
+  it("uses component bom-ref as document name fallback before version", () => {
+    const bom = sampleBom();
+    delete bom.metadata.component.name;
+    const spdxJson = convertCycloneDxToSpdx(bom);
+    const documentElement = spdxJson["@graph"].find(
+      (element) => element.type === "SpdxDocument",
+    );
+    assert.ok(documentElement);
+    assert.strictEqual(documentElement.name, "pkg:generic/demo-app@1.0.0");
+  });
+
+  it("rejects malformed SPDX exports", () => {
+    const spdxJson = convertCycloneDxToSpdx(sampleBom(), {
+      projectName: "demo-app",
+    });
+    spdxJson["@context"] = "https://example.com/not-spdx";
+    assert.strictEqual(validateSpdx(spdxJson), false);
+  });
+
+  it("rejects SPDX relationships with non-string from references", () => {
+    const spdxJson = convertCycloneDxToSpdx(sampleBom(), {
+      projectName: "demo-app",
+    });
+    const relationship = spdxJson["@graph"].find(
+      (element) => element.type === "Relationship",
+    );
+    relationship.from = [relationship.from];
+    assert.strictEqual(validateSpdx(spdxJson), false);
+  });
+
+  it("rejects SPDX exports with malformed extension entries", () => {
+    const spdxJson = convertCycloneDxToSpdx(sampleBom(), {
+      projectName: "demo-app",
+    });
+    const packageElement = spdxJson["@graph"].find(
+      (element) => element.software_packageUrl === "pkg:npm/lodash@4.17.21",
+    );
+    delete packageElement.extension[0].type;
+    assert.strictEqual(validateSpdx(spdxJson), false);
+  });
+
+  it("uses the official JSON-LD compact extension terms", () => {
+    const spdxJson = convertCycloneDxToSpdx(sampleBom(), {
+      projectName: "demo-app",
+    });
+    const documentElement = spdxJson["@graph"].find(
+      (element) => element.type === "SpdxDocument",
+    );
+    assert.ok(documentElement);
+    assert.strictEqual(
+      documentElement.extension[0].type,
+      "extension_CdxPropertiesExtension",
+    );
+    assert.strictEqual(
+      documentElement.extension[0].extension_cdxProperty[0].type,
+      "extension_CdxPropertyEntry",
+    );
+    assert.strictEqual(
+      typeof documentElement.extension[0].extension_cdxProperty[0]
+        .extension_cdxPropName,
+      "string",
+    );
+    assert.strictEqual(
+      typeof documentElement.extension[0].extension_cdxProperty[0]
+        .extension_cdxPropValue,
+      "string",
+    );
+  });
+});

package/lib/validator/bomValidator.js

@@ -2,14 +2,55 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 
 import Ajv from "ajv";
+import Ajv2020 from "ajv/dist/2020.js";
 import addFormats from "ajv-formats";
 import { PackageURL } from "packageurl-js";
 
 import { thoughtLog } from "../helpers/logger.js";
 import { DEBUG_MODE, dirNameStr, isPartialTree } from "../helpers/utils.js";
+import {
+  SPDX_JSONLD_CONTEXT,
+  SPDX_SPEC_VERSION,
+} from "../stages/postgen/spdxConverter.js";
 
 const dirName = dirNameStr;
 const PLACEHOLDER_COMPONENT_NAMES = new Set(["app", "application", "project"]);
+const SPDX_EXPORT_TYPES = new Set([
+  "CreationInfo",
+  "Relationship",
+  "SpdxDocument",
+  "software_File",
+  "software_Package",
+]);
+let spdxExportSchemaValidator;
+
+const getSpdxElementId = (element) => element?.spdxId || element?.["@id"];
+
+const getSpdxExportSchemaValidator = () => {
+  if (spdxExportSchemaValidator !== undefined) {
+    return spdxExportSchemaValidator;
+  }
+  try {
+    const spdxExportSchema = JSON.parse(
+      readFileSync(join(dirName, "data", "spdx-export.schema.json"), "utf-8"),
+    );
+    const ajv = new Ajv2020({
+      strict: false,
+      logger: false,
+      verbose: true,
+      code: {
+        source: true,
+        lines: true,
+        optimize: true,
+      },
+    });
+    addFormats(ajv);
+    spdxExportSchemaValidator = ajv.compile(spdxExportSchema);
+  } catch (_error) {
+    spdxExportSchemaValidator = null;
+  }
+  return spdxExportSchemaValidator;
+};
 
 /**
  * Validate the generated bom using jsonschema
@@ -81,6 +122,197 @@ export const validateBom = (bomJson) => {
   );
 };
 
+/**
+ * Validate the generated SPDX export.
+ *
+ * @param {object|string} spdxJson SPDX json object
+ * @returns {boolean} true if the SPDX export is valid
+ */
+export const validateSpdx = (spdxJson) => {
+  if (!spdxJson) {
+    return true;
+  }
+  if (typeof spdxJson === "string" || spdxJson instanceof String) {
+    spdxJson = JSON.parse(spdxJson);
+  }
+  const spdxDocument = (spdxJson?.["@graph"] || []).find(
+    (element) => element?.type === "SpdxDocument",
+  );
+  const validateSchema = getSpdxExportSchemaValidator();
+  if (!validateSchema) {
+    console.log("The bundled SPDX export schema is empty or malformed.");
+    return false;
+  }
+  if (!validateSchema(spdxJson)) {
+    console.log(
+      `SPDX 3.0.1 schema validation failed${spdxDocument?.name ? ` for ${spdxDocument.name}` : ""}`,
+    );
+    console.log(validateSchema.errors);
+    return false;
+  }
+  const errorList = [];
+  if (spdxJson?.["@context"] !== SPDX_JSONLD_CONTEXT) {
+    errorList.push(`@context must be '${SPDX_JSONLD_CONTEXT}'.`);
+  }
+  if (!Array.isArray(spdxJson?.["@graph"]) || !spdxJson["@graph"].length) {
+    errorList.push("@graph must be a non-empty array.");
+  }
+  const ids = new Set();
+  const knownRefs = new Set();
+  let creationInfoCount = 0;
+  let documentCount = 0;
+  let usesExtensionProfile = false;
+  for (const element of spdxJson?.["@graph"] || []) {
+    if (!SPDX_EXPORT_TYPES.has(element?.type)) {
+      errorList.push(`Unsupported SPDX export type '${element?.type}'.`);
+    }
+    const elementId = getSpdxElementId(element);
+    if (!elementId || typeof elementId !== "string") {
+      errorList.push(
+        `Missing SPDX identifier for type '${element?.type || "unknown"}'.`,
+      );
+      continue;
+    }
+    if (ids.has(elementId)) {
+      errorList.push(`Duplicate SPDX identifier '${elementId}'.`);
+    }
+    ids.add(elementId);
+    knownRefs.add(elementId);
+    if (Array.isArray(element?.extension) && element.extension.length) {
+      usesExtensionProfile = true;
+    }
+    switch (element.type) {
+      case "CreationInfo":
+        creationInfoCount += 1;
+        if (element.specVersion !== SPDX_SPEC_VERSION) {
+          errorList.push(
+            `CreationInfo '${elementId}' has unexpected specVersion '${element.specVersion}'.`,
+          );
+        }
+        if (!Array.isArray(element.createdBy) || !element.createdBy.length) {
+          errorList.push(`CreationInfo '${elementId}' must include createdBy.`);
+        }
+        if (!element.created) {
+          errorList.push(`CreationInfo '${elementId}' must include created.`);
+        }
+        break;
+      case "SpdxDocument":
+        documentCount += 1;
+        if (!element.creationInfo) {
+          errorList.push(
+            `SpdxDocument '${elementId}' must include creationInfo.`,
+          );
+        }
+        if (!Array.isArray(element.element) || !element.element.length) {
+          errorList.push(
+            `SpdxDocument '${elementId}' must include element refs.`,
+          );
+        }
+        if (
+          element.rootElement &&
+          (!Array.isArray(element.rootElement) || !element.rootElement.length)
+        ) {
+          errorList.push(
+            `SpdxDocument '${elementId}' rootElement must be a non-empty array when present.`,
+          );
+        }
+        break;
+      case "Relationship":
+        if (
+          !element.creationInfo ||
+          !element.from ||
+          typeof element.from !== "string"
+        ) {
+          errorList.push(
+            `Relationship '${elementId}' must include creationInfo and from.`,
+          );
+        }
+        if (!element.to || !Array.isArray(element.to) || !element.to.length) {
+          errorList.push(`Relationship '${elementId}' must include to refs.`);
+        }
+        if (element.relationshipType !== "dependsOn") {
+          errorList.push(
+            `Relationship '${elementId}' has unsupported relationshipType '${element.relationshipType}'.`,
+          );
+        }
+        break;
+      case "software_File":
+      case "software_Package":
+        if (!element.creationInfo || !element.name) {
+          errorList.push(
+            `${element.type} '${elementId}' must include creationInfo and name.`,
+          );
+        }
+        break;
+      default:
+        break;
+    }
+  }
+  if (creationInfoCount !== 1) {
+    errorList.push(
+      `Expected exactly one CreationInfo, found ${creationInfoCount}.`,
+    );
+  }
+  if (documentCount !== 1) {
+    errorList.push(
+      `Expected exactly one SpdxDocument, found ${documentCount}.`,
+    );
+  }
+  for (const element of spdxJson?.["@graph"] || []) {
+    const elementId = getSpdxElementId(element);
+    if (element.creationInfo && !knownRefs.has(element.creationInfo)) {
+      errorList.push(
+        `Element '${elementId || "unknown"}' references unknown creationInfo '${element.creationInfo}'.`,
+      );
+    }
+    if (Array.isArray(element.element)) {
+      for (const ref of element.element) {
+        if (!knownRefs.has(ref)) {
+          errorList.push(
+            `SpdxDocument '${elementId || "unknown"}' references unknown element '${ref}'.`,
+          );
+        }
+      }
+    }
+    if (Array.isArray(element.rootElement)) {
+      for (const ref of element.rootElement) {
+        if (!knownRefs.has(ref)) {
+          errorList.push(
+            `SpdxDocument '${elementId || "unknown"}' references unknown rootElement '${ref}'.`,
+          );
+        }
+      }
+    }
+    if (typeof element.from === "string" && !knownRefs.has(element.from)) {
+      errorList.push(
+        `Relationship '${elementId || "unknown"}' references unknown from '${element.from}'.`,
+      );
+    }
+    if (Array.isArray(element.to)) {
+      for (const ref of element.to) {
+        if (!knownRefs.has(ref)) {
+          errorList.push(
+            `Relationship '${elementId || "unknown"}' references unknown to '${ref}'.`,
+          );
+        }
+      }
+    }
+  }
+  if (usesExtensionProfile) {
+    if (!spdxDocument?.profileConformance?.includes("extension")) {
+      errorList.push(
+        `SpdxDocument '${spdxDocument?.spdxId || "unknown"}' must declare the extension profile when extension data is present.`,
+      );
+    }
+  }
+  if (errorList.length > 0) {
+    console.log("SPDX 3.0.1 validation failed");
+    console.log(errorList);
+    return false;
+  }
+  return true;
+};
+
 /**
  * Validate the metadata object
  *

package/lib/validator/bomValidator.poku.js

@@ -0,0 +1,70 @@
+import esmock from "esmock";
+import { assert, describe, it } from "poku";
+import sinon from "sinon";
+
+describe("validateSpdx()", () => {
+  it("lazy-loads the bundled SPDX export schema on first validation call", async () => {
+    const readFileSyncStub = sinon
+      .stub()
+      .returns(
+        '{"type":"object","properties":{"@context":{"const":"https://spdx.org/rdf/3.0.1/spdx-context.jsonld"},"@graph":{"type":"array"}}}',
+      );
+    const { validateSpdx } = await esmock("./bomValidator.js", {
+      "node:fs": {
+        readFileSync: readFileSyncStub,
+      },
+      "../helpers/utils.js": {
+        DEBUG_MODE: false,
+        dirNameStr: "/tmp",
+        isPartialTree: sinon.stub().returns(false),
+      },
+      "../stages/postgen/spdxConverter.js": {
+        SPDX_JSONLD_CONTEXT: "https://spdx.org/rdf/3.0.1/spdx-context.jsonld",
+        SPDX_SPEC_VERSION: "3.0.1",
+      },
+    });
+
+    sinon.assert.notCalled(readFileSyncStub);
+    assert.strictEqual(
+      validateSpdx({
+        "@context": "https://spdx.org/rdf/3.0.1/spdx-context.jsonld",
+        "@graph": [],
+      }),
+      false,
+    );
+    sinon.assert.calledOnce(readFileSyncStub);
+  });
+
+  it("caches the bundled SPDX export schema between validation calls", async () => {
+    const readFileSyncStub = sinon
+      .stub()
+      .returns(
+        '{"type":"object","properties":{"@context":{"const":"https://spdx.org/rdf/3.0.1/spdx-context.jsonld"},"@graph":{"type":"array"}}}',
+      );
+    const { validateSpdx } = await esmock("./bomValidator.js", {
+      "node:fs": {
+        readFileSync: readFileSyncStub,
+      },
+      "../helpers/utils.js": {
+        DEBUG_MODE: false,
+        dirNameStr: "/tmp",
+        isPartialTree: sinon.stub().returns(false),
+      },
+      "../stages/postgen/spdxConverter.js": {
+        SPDX_JSONLD_CONTEXT: "https://spdx.org/rdf/3.0.1/spdx-context.jsonld",
+        SPDX_SPEC_VERSION: "3.0.1",
+      },
+    });
+
+    validateSpdx({
+      "@context": "https://spdx.org/rdf/3.0.1/spdx-context.jsonld",
+      "@graph": [],
+    });
+    validateSpdx({
+      "@context": "https://spdx.org/rdf/3.0.1/spdx-context.jsonld",
+      "@graph": [],
+    });
+
+    sinon.assert.calledOnce(readFileSyncStub);
+  });
+});