@cdxgen/cdxgen 0.0.1 → 13.0.0

package/lib/helpers/annotationFormatter.js

@@ -0,0 +1,84 @@
+const MAX_DETAIL_LINES = 12;
+const MAX_PROPERTY_ROWS = 40;
+const MAX_CELL_LENGTH = 160;
+
+function truncateText(value, maxLength = MAX_CELL_LENGTH) {
+  const normalized = String(value ?? "").trim();
+  if (normalized.length <= maxLength) {
+    return normalized;
+  }
+  return `${normalized.slice(0, Math.max(0, maxLength - 1)).trimEnd()}…`;
+}
+
+function escapeMarkdownText(value) {
+  return truncateText(value)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/([\\`*_{}\[\]()#+!|])/g, "\\$1")
+    .replace(/\r?\n/g, "<br>")
+    .trim();
+}
+
+function escapeMarkdownCell(value) {
+  return escapeMarkdownText(value);
+}
+
+/**
+ * Format annotation properties as a markdown table for CycloneDX annotations.
+ *
+ * @param {{ name: string, value: string }[]} properties annotation properties
+ * @returns {string} markdown table text
+ */
+export function propertiesToMarkdownTable(properties) {
+  if (!properties?.length) {
+    return "";
+  }
+  const lines = ["| Property | Value |", "| --- | --- |"];
+  const normalizedProperties = [...properties]
+    .filter((property) => property?.name || property?.value)
+    .sort((left, right) =>
+      `${left?.name || ""}\u0000${left?.value || ""}`.localeCompare(
+        `${right?.name || ""}\u0000${right?.value || ""}`,
+      ),
+    )
+    .slice(0, MAX_PROPERTY_ROWS);
+  for (const property of normalizedProperties) {
+    lines.push(
+      `| ${escapeMarkdownCell(property?.name)} | ${escapeMarkdownCell(property?.value)} |`,
+    );
+  }
+  if ((properties?.length || 0) > normalizedProperties.length) {
+    lines.push(
+      `| _truncated_ | ${properties.length - normalizedProperties.length} more properties omitted |`,
+    );
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Build production-ready markdown annotation text.
+ *
+ * @param {string} message leading message text
+ * @param {{ name: string, value: string }[]} properties annotation properties
+ * @param {string[]} [details] optional detail lines shown before the table
+ * @returns {string} annotation text
+ */
+export function buildAnnotationText(message, properties, details = []) {
+  const lines = [
+    message,
+    ...details.filter(Boolean).slice(0, MAX_DETAIL_LINES),
+  ].map(escapeMarkdownText);
+  if (details.filter(Boolean).length > MAX_DETAIL_LINES) {
+    lines.push(
+      escapeMarkdownText(
+        `${details.filter(Boolean).length - MAX_DETAIL_LINES} more details omitted`,
+      ),
+    );
+  }
+  const markdownTable = propertiesToMarkdownTable(properties);
+  if (markdownTable) {
+    lines.push("", markdownTable);
+  }
+  return lines.join("\n");
+}

package/lib/helpers/bomSigner.js

@@ -0,0 +1,312 @@
+import crypto from "node:crypto";
+
+/**
+ * Lightweight, deterministic JSON Canonicalizer (similar to RFC 8785).
+ * Required by JSF to ensure the signature payload remains identical across systems.
+ *
+ * @param {any} value - The JSON object/value to canonicalize
+ * @returns {string} - Canonicalized JSON string
+ */
+function canonicalize(value) {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (Array.isArray(value)) {
+    return `[${value.map(canonicalize).join(",")}]`;
+  }
+  const keys = Object.keys(value).sort();
+  let str = "{";
+  for (let i = 0; i < keys.length; i++) {
+    if (i > 0) str += ",";
+    str += `${JSON.stringify(keys[i])}:${canonicalize(value[keys[i]])}`;
+  }
+  str += "}";
+  return str;
+}
+
+/**
+ * Creates a JSF-compliant signature block.
+ *
+ * @param {Object} payload - The object to sign (e.g., BOM, component)
+ * @param {string|Buffer|crypto.KeyObject} privateKey - The signing key
+ * @param {string} alg - JSF algorithm identifier
+ * @param {Object} [publicKeyJwk] - Optional JWK representation of the public key
+ * @param {string} keyId - Key ID
+ *
+ * @returns {Object} - JSF signature block
+ */
+function createSignatureBlock(
+  payload,
+  privateKey,
+  alg,
+  publicKeyJwk = null,
+  keyId = null,
+) {
+  // Exclude existing signatures from the canonicalized payload as per JSF
+  const { signature, ...dataToSign } = payload;
+  const canonicalData = canonicalize(dataToSign);
+
+  let hashAlg;
+  const signOptions = { key: privateKey };
+
+  // Handle HMAC (Symmetric)
+  if (alg.startsWith("HS")) {
+    const hash = alg.replace("HS", "sha");
+    const value = crypto
+      .createHmac(hash, privateKey)
+      .update(canonicalData, "utf8")
+      .digest("base64url");
+    const block = { algorithm: alg, value };
+    if (publicKeyJwk) {
+      block.publicKey = publicKeyJwk;
+    }
+    if (keyId) {
+      block.keyId = keyId;
+    }
+    return block;
+  }
+
+  // Handle Asymmetric Algorithms
+  if (alg.startsWith("RS")) {
+    hashAlg = alg.replace("RS", "SHA");
+  } else if (alg.startsWith("PS")) {
+    hashAlg = alg.replace("PS", "SHA");
+    signOptions.padding = crypto.constants.RSA_PKCS1_PSS_PADDING;
+    signOptions.saltLength = crypto.constants.RSA_PSS_SALTLEN_AUTO;
+  } else if (alg.startsWith("ES")) {
+    hashAlg = alg.replace("ES", "SHA");
+    // Standard JWA format requires IEEE P1363 (R || S) instead of ASN.1 DER
+    signOptions.dsaEncoding = "ieee-p1363";
+  } else if (alg === "Ed25519" || alg === "Ed448") {
+    // Native EdDSA algorithms do not require a separate hash algorithm definition
+    hashAlg = null;
+  } else {
+    throw new Error(`Unsupported JSF algorithm: ${alg}`);
+  }
+  const sigBuffer = crypto.sign(
+    hashAlg,
+    Buffer.from(canonicalData, "utf8"),
+    signOptions,
+  );
+  const block = { algorithm: alg, value: sigBuffer.toString("base64url") };
+  if (publicKeyJwk) {
+    block.publicKey = publicKeyJwk;
+  }
+  if (keyId) {
+    block.keyId = keyId;
+  }
+  return block;
+}
+
+/**
+ * Appends or replaces a signature on a target object based on the configured mode.
+ */
+function addSignature(target, sigBlock, mode) {
+  if (!target.signature) {
+    target.signature = sigBlock;
+    return;
+  }
+  if (mode === "chain") {
+    if (target.signature.chain) {
+      target.signature.chain.push(sigBlock);
+    } else if (target.signature.signers) {
+      throw new Error("Cannot mix signature chains and multi-signers.");
+    } else {
+      target.signature = { chain: [target.signature, sigBlock] };
+    }
+  } else if (mode === "signers") {
+    if (target.signature.signers) {
+      target.signature.signers.push(sigBlock);
+    } else if (target.signature.chain) {
+      throw new Error("Cannot mix signature chains and multi-signers.");
+    } else {
+      target.signature = { signers: [target.signature, sigBlock] };
+    }
+  } else {
+    target.signature = sigBlock;
+  }
+}
+
+/**
+ * Recursively applies signatures to the BOM and its granular components.
+ *
+ * @param {Object} bomJson - CycloneDX BOM Object
+ * @param {Object} options - Signing options { privateKey, algorithm, mode, ... }
+ * @returns {Object} - Signed BOM Object
+ */
+export function signBom(bomJson, options = {}) {
+  const {
+    privateKey,
+    algorithm = "RS512",
+    publicKeyJwk = null,
+    keyId = null,
+    mode = "replace", // Supports: 'replace', 'chain', 'signers'
+    signComponents = true,
+    signServices = true,
+    signAnnotations = true,
+  } = options;
+
+  if (!privateKey) {
+    throw new Error("privateKey is required for signing");
+  }
+  if (signComponents && Array.isArray(bomJson.components)) {
+    for (const comp of bomJson.components) {
+      addSignature(
+        comp,
+        createSignatureBlock(comp, privateKey, algorithm, publicKeyJwk, keyId),
+        mode,
+      );
+    }
+  }
+  if (signServices && Array.isArray(bomJson.services)) {
+    for (const svc of bomJson.services) {
+      addSignature(
+        svc,
+        createSignatureBlock(svc, privateKey, algorithm, publicKeyJwk, keyId),
+        mode,
+      );
+    }
+  }
+  if (signAnnotations && Array.isArray(bomJson.annotations)) {
+    for (const ann of bomJson.annotations) {
+      addSignature(
+        ann,
+        createSignatureBlock(ann, privateKey, algorithm, publicKeyJwk, keyId),
+        mode,
+      );
+    }
+  }
+  addSignature(
+    bomJson,
+    createSignatureBlock(bomJson, privateKey, algorithm, publicKeyJwk, keyId),
+    mode,
+  );
+  return bomJson;
+}
+
+/**
+ * Validates a single JSF signature block against the payload.
+ *
+ * @param {Object} payload - The payload to verify
+ * @param {string|crypto.KeyObject} publicKey - The public key corresponding to the signature
+ * @param {Object} sigBlock Signature
+ *
+ * @returns {boolean|Object} - Signature block if signature is valid. False otherwise.
+ */
+function verifySignatureBlock(payload, publicKey, sigBlock) {
+  const { signature, ...dataToVerify } = payload;
+  const canonicalData = canonicalize(dataToVerify);
+
+  const { algorithm: alg, value } = sigBlock;
+
+  if (alg.startsWith("HS")) {
+    const hash = alg.replace("HS", "sha");
+    const expected = crypto
+      .createHmac(hash, publicKey)
+      .update(canonicalData, "utf8")
+      .digest("base64url");
+    const isValid = expected === value;
+    return isValid ? sigBlock : false;
+  }
+
+  const verifyOptions = { key: publicKey };
+  let hashAlg;
+
+  if (alg.startsWith("RS")) {
+    hashAlg = alg.replace("RS", "SHA");
+  } else if (alg.startsWith("PS")) {
+    hashAlg = alg.replace("PS", "SHA");
+    verifyOptions.padding = crypto.constants.RSA_PKCS1_PSS_PADDING;
+    verifyOptions.saltLength = crypto.constants.RSA_PSS_SALTLEN_AUTO;
+  } else if (alg.startsWith("ES")) {
+    hashAlg = alg.replace("ES", "SHA");
+    verifyOptions.dsaEncoding = "ieee-p1363";
+  } else if (alg === "Ed25519" || alg === "Ed448") {
+    hashAlg = null;
+  } else {
+    console.warn(`${alg} is unknown.`);
+    return false;
+  }
+
+  const isValid = crypto.verify(
+    hashAlg,
+    Buffer.from(canonicalData, "utf8"),
+    verifyOptions,
+    Buffer.from(value, "base64url"),
+  );
+  return isValid ? sigBlock : false;
+}
+
+/**
+ * Verifies the integrity of a specific element node (e.g., BOM root, Component, Service, Annotation).
+ * Resolves standard JSF signatures, multisignature (signers), and chains.
+ *
+ * @param {Object} node - The BOM or granular object to verify
+ * @param {string|crypto.KeyObject} publicKey - The public key corresponding to the signature
+ * @returns {boolean|Object} - Signature block if signature is valid. False otherwise.
+ */
+export function verifyNode(node, publicKey) {
+  if (!node?.signature) {
+    return false;
+  }
+  const sigTarget = node.signature;
+  if (sigTarget.signers) {
+    for (const sig of sigTarget.signers) {
+      const match = verifySignatureBlock(node, publicKey, sig);
+      if (match) {
+        return match;
+      }
+    }
+    return false;
+  }
+  if (sigTarget.chain) {
+    for (const sig of sigTarget.chain) {
+      const match = verifySignatureBlock(node, publicKey, sig);
+      if (match) {
+        return match;
+      }
+    }
+    return false;
+  }
+  return verifySignatureBlock(node, publicKey, sigTarget);
+}
+
+/**
+ * Verifies the integrity of a BOM's top-level signature, as well as nested components, services, and annotations.
+ * Returns true only if the root signature is valid AND all signed nested elements are valid.
+ *
+ * @param {Object} bom - CycloneDX BOM Object
+ * @param {string|crypto.KeyObject} publicKey - The public key corresponding to the signature
+ * @returns {boolean|Object} - Signature block if signature is valid. False otherwise.
+ */
+export function verifyBom(bom, publicKey) {
+  if (!bom?.signature) {
+    return false;
+  }
+  const rootMatch = verifyNode(bom, publicKey);
+  if (!rootMatch) {
+    return false;
+  }
+  if (Array.isArray(bom.components)) {
+    for (const comp of bom.components) {
+      if (comp.signature && !verifyNode(comp, publicKey)) {
+        return false;
+      }
+    }
+  }
+  if (Array.isArray(bom.services)) {
+    for (const svc of bom.services) {
+      if (svc.signature && !verifyNode(svc, publicKey)) {
+        return false;
+      }
+    }
+  }
+  if (Array.isArray(bom.annotations)) {
+    for (const ann of bom.annotations) {
+      if (ann.signature && !verifyNode(ann, publicKey)) {
+        return false;
+      }
+    }
+  }
+  return rootMatch;
+}

package/lib/helpers/exportUtils.js

@@ -0,0 +1,160 @@
+import path from "node:path";
+
+const SUPPORTED_EXPORT_FORMATS = new Set(["cyclonedx", "spdx"]);
+const EXPORT_FORMAT_ALIASES = {
+  cdx: "cyclonedx",
+  cyclonedx: "cyclonedx",
+  spdx: "spdx",
+  "spdx-json": "spdx",
+  spdx3: "spdx",
+  "spdx3-json": "spdx",
+};
+
+/**
+ * Normalize the requested export formats.
+ *
+ * @param {string|string[]|undefined|null} format Raw format value
+ * @returns {string[]} Normalized export formats
+ */
+export function normalizeOutputFormats(format) {
+  if (format === undefined || format === null || format === "") {
+    return [];
+  }
+  const values = Array.isArray(format) ? format : [format];
+  const normalized = new Set();
+  for (const value of values) {
+    if (!value) {
+      continue;
+    }
+    for (const token of `${value}`.split(",")) {
+      const normalizedToken = EXPORT_FORMAT_ALIASES[token.trim().toLowerCase()];
+      if (normalizedToken && SUPPORTED_EXPORT_FORMATS.has(normalizedToken)) {
+        normalized.add(normalizedToken);
+      }
+    }
+  }
+  return Array.from(normalized);
+}
+
+/**
+ * Derive the SPDX output path from a base output path.
+ *
+ * @param {string} outputPath Output path
+ * @returns {string} SPDX output path
+ */
+export function deriveSpdxOutputPath(outputPath) {
+  if (!outputPath) {
+    return "bom.spdx.json";
+  }
+  if (outputPath.endsWith(".spdx.json")) {
+    return outputPath;
+  }
+  if (outputPath.endsWith(".cdx.bin")) {
+    return outputPath.replace(/\.cdx\.bin$/u, ".spdx.json");
+  }
+  if (outputPath.endsWith(".cdx.json")) {
+    return outputPath.replace(/\.cdx\.json$/u, ".spdx.json");
+  }
+  if (outputPath.endsWith(".cdx")) {
+    return outputPath.replace(/\.cdx$/u, ".spdx.json");
+  }
+  if (outputPath.endsWith(".proto")) {
+    return outputPath.replace(/\.proto$/u, ".spdx.json");
+  }
+  if (outputPath.endsWith(".json")) {
+    return outputPath.replace(/\.json$/u, ".spdx.json");
+  }
+  return `${outputPath}.spdx.json`;
+}
+
+/**
+ * Derive the CycloneDX output path from a base output path.
+ *
+ * @param {string} outputPath Output path
+ * @returns {string} CycloneDX output path
+ */
+export function deriveCycloneDxOutputPath(outputPath) {
+  if (!outputPath) {
+    return "bom.json";
+  }
+  if (outputPath.endsWith(".spdx.json")) {
+    return outputPath.replace(/\.spdx\.json$/u, ".cdx.json");
+  }
+  return outputPath;
+}
+
+/**
+ * Derive the output path for a CycloneDX BOM converted to another spec version.
+ *
+ * The spec version is inserted ahead of the existing extension so the source
+ * BOM is never overwritten, and the extension is preserved so a protobuf input
+ * keeps producing a protobuf-suffixed name.
+ *
+ * @param {string} inputPath Input BOM path
+ * @param {string} specVersion Target CycloneDX spec version
+ * @returns {string} Converted CycloneDX output path
+ */
+export function deriveSpecVersionOutputPath(inputPath, specVersion) {
+  const suffix = `${specVersion}`.replace(/\./gu, "_");
+  if (!inputPath) {
+    return `bom-${suffix}.json`;
+  }
+  for (const extension of [".cdx.bin", ".cdx.json", ".spdx.json"]) {
+    if (inputPath.endsWith(extension)) {
+      return `${inputPath.slice(0, -extension.length)}-${suffix}${extension}`;
+    }
+  }
+  const extension = path.extname(inputPath);
+  if (extension) {
+    return `${inputPath.slice(0, -extension.length)}-${suffix}${extension}`;
+  }
+  return `${inputPath}-${suffix}.json`;
+}
+
+/**
+ * Determine the final output plan for the requested export formats.
+ *
+ * @param {object} options CLI options
+ * @returns {{ formats: Set<string>, outputs: Record<string, string>, explicitFormat: boolean }} Output plan
+ */
+export function createOutputPlan(options) {
+  const explicitFormat =
+    options?.format !== undefined &&
+    options?.format !== null &&
+    options?.format !== "";
+  const requestedFormats = normalizeOutputFormats(options?.format);
+  const outputPath = options?.output || "bom.json";
+  const formats = new Set(
+    requestedFormats.length
+      ? requestedFormats
+      : [outputPath.endsWith(".spdx.json") ? "spdx" : "cyclonedx"],
+  );
+  const outputs = {};
+  if (formats.has("cyclonedx")) {
+    outputs.cyclonedx =
+      outputPath.endsWith(".spdx.json") && formats.size > 1
+        ? deriveCycloneDxOutputPath(outputPath)
+        : outputPath;
+  }
+  if (formats.has("spdx")) {
+    if (!formats.has("cyclonedx") || outputPath.endsWith(".spdx.json")) {
+      outputs.spdx =
+        outputPath === "bom.json"
+          ? deriveSpdxOutputPath(outputPath)
+          : outputPath;
+    } else {
+      outputs.spdx = deriveSpdxOutputPath(outputPath);
+    }
+  }
+  return { formats, outputs, explicitFormat };
+}
+
+/**
+ * Return the output directory for a planned export path.
+ *
+ * @param {string} outputPath Output path
+ * @returns {string} Output directory
+ */
+export function getOutputDirectory(outputPath) {
+  return path.dirname(outputPath);
+}

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

@@ -0,0 +1,117 @@
+import { Buffer } from "node:buffer";
+
+import { hasDangerousUnicode } from "../../core/activity.js";
+
+/**
+ * Returns the Dependency-Track BOM API URL as a sanitized URL object.
+ *
+ * @param {string} serverUrl Dependency-Track server URL
+ * @returns {URL | undefined} API URL to submit BOM payload
+ */
+export function getDependencyTrackBomApiUrl(serverUrl) {
+  const rawServerUrl = `${serverUrl || ""}`.trim();
+  if (!rawServerUrl || hasDangerousUnicode(rawServerUrl)) {
+    return undefined;
+  }
+  let parsedUrl;
+  try {
+    parsedUrl = new URL(rawServerUrl);
+  } catch {
+    return undefined;
+  }
+  if (!["http:", "https:"].includes(parsedUrl.protocol)) {
+    return undefined;
+  }
+  if (!parsedUrl.hostname || hasDangerousUnicode(parsedUrl.hostname)) {
+    return undefined;
+  }
+  parsedUrl.username = "";
+  parsedUrl.password = "";
+  parsedUrl.search = "";
+  parsedUrl.hash = "";
+  parsedUrl.pathname = `${parsedUrl.pathname.replace(/\/+$/, "")}/api/v1/bom`;
+  return parsedUrl;
+}
+
+/**
+ * Returns the Dependency-Track BOM API URL string.
+ *
+ * @param {string} serverUrl Dependency-Track server URL
+ * @returns {string | undefined} API URL to submit BOM payload
+ */
+export function getDependencyTrackBomUrl(serverUrl) {
+  return getDependencyTrackBomApiUrl(serverUrl)?.toString();
+}
+
+/**
+ * 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;
+}