@cdxgen/cdxgen 13.6.0 → 13.7.0

package/bin/sign.js

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
 
+import crypto from "node:crypto";
 import fs from "node:fs";
 import process from "node:process";
 
@@ -10,14 +11,23 @@ import {
   readEnvironmentVariable,
   retrieveCdxgenVersion,
   safeExistsSync,
+  safeWriteSync,
 } from "../lib/ecosystems/utils.js";
 import {
   checkSignatureEntries,
   displayValue,
   signBom,
 } from "../lib/helpers/bomSigner.js";
+import {
+  countersignJss,
+  removeJssSignatures,
+  selectJssAlgorithmForKey,
+  signJssBom,
+  verifyJss,
+} from "../lib/helpers/jssSigner.js";
 import {
   getNonCycloneDxErrorMessage,
+  isCycloneDx20SpecVersion,
   isCycloneDxBom,
 } from "../lib/inventory/bomUtils.js";
 import { parseStrictJson } from "../lib/parsers/strictJson.js";
@@ -41,16 +51,18 @@ const args = _yargs
   })
   .option("algorithm", {
     alias: "a",
-    default: readEnvironmentVariable("SBOM_SIGN_ALGORITHM") || "RS512",
+    default: readEnvironmentVariable("SBOM_SIGN_ALGORITHM"),
+    defaultDescription:
+      "SBOM_SIGN_ALGORITHM, else RS512 for JSF (1.x) or derived from the key for JSS (2.0)",
     description:
-      "JSF Signature Algorithm (e.g., RS512, ES256, Ed25519). It must match the key type.",
+      "Signature algorithm (e.g., RS512, ES256, Ed25519). It must match the key type. For a CycloneDX 2.0 (JSS) document it defaults to ES256/ES384/ES512 by curve, RS256 for rsa, PS256 for rsa-pss, Ed25519 or Ed448.",
   })
   .option("mode", {
     alias: "m",
     default: readEnvironmentVariable("SBOM_SIGN_MODE") || "replace",
     choices: ["replace", "signers", "chain"],
     description:
-      "Signature mode. Use 'signers' for multi-signing, 'chain' for sequential chaining.",
+      "Signature mode. Use 'signers' for multi-signing, 'chain' for sequential chaining. At 2.0 (JSS), 'replace' removes every existing JSS signature, 'signers' appends a root signature (X.590 clause 7.1), and 'chain' countersigns the only root signature (X.590 clause 7.2).",
   })
   .option("verify-existing-with", {
     type: "array",
@@ -149,6 +161,9 @@ if (args.privateKey) {
 
 function hasAnySignature(bomJson) {
   if (bomJson.signature) return true;
+  // CycloneDX 2.0 carries JSS signatures in `signatures` lists.
+  if (Array.isArray(bomJson.signatures) && bomJson.signatures.length)
+    return true;
   if (
     Array.isArray(bomJson.components) &&
     bomJson.components.some((c) => c.signature)
@@ -234,6 +249,189 @@ function checkExistingSignatures(bomJson) {
   );
 }
 
+function signJsfDocument(bomJson) {
+  const jsfAlgorithm = args.algorithm || "RS512";
+  checkExistingSignatures(bomJson);
+  const signedBom = signBom(bomJson, {
+    privateKey: privateKeyContent,
+    algorithm: jsfAlgorithm,
+    embedPublicKey: args.embedPublicKey,
+    embedPublicKeyNested: false,
+    keyId: args.keyId,
+    mode: args.mode,
+    signComponents: args.signComponents,
+    signServices: args.signServices,
+    signAnnotations: args.signAnnotations,
+  });
+
+  const outputPath = args.output || args.input;
+  safeWriteSync(outputPath, JSON.stringify(signedBom, null, null));
+
+  console.log(`Successfully signed BOM and saved to '${outputPath}'`);
+  console.log(
+    `Mode: ${args.mode} | Algorithm: ${jsfAlgorithm}${args.keyId ? ` | KeyId: ${args.keyId}` : ""}`,
+  );
+  const rootSignature = signedBom.signature;
+  const newEntry =
+    rootSignature?.signers?.at(-1) ??
+    rootSignature?.chain?.at(-1) ??
+    rootSignature;
+  if (
+    args.embedPublicKey &&
+    !String(jsfAlgorithm).startsWith("HS") &&
+    newEntry?.publicKey === undefined
+  ) {
+    console.warn(
+      "Warning: this key type has no JWK form, so the public key was not embedded in the signature.",
+    );
+  }
+  return signedBom;
+}
+
+// A JSS (X.590) countersignature of the only root entry vouches for that
+// entry and its chain, so every object of the chain must verify (as for a
+// JSF chain). A new root entry covers the same content as the existing ones,
+// so the existing signatures must pass the cdx-verify policy: at least one
+// entry verifies, no entry that names a given key fails, and every
+// countersignature verifies.
+function checkExistingJssSignatures(bomJson) {
+  const chain = args.mode === "chain";
+  const keys = (args.verifyExistingWith || []).map((keyFile) => {
+    if (!safeExistsSync(keyFile)) {
+      throw new Error(`Public key file '${keyFile}' not found.`);
+    }
+    return fs.readFileSync(keyFile, "utf8");
+  });
+  const verdict = keys.length
+    ? verifyJss(bomJson, { publicKeys: keys })
+    : undefined;
+  const results = verdict
+    ? verdict.results
+    : bomJson.signatures.map((entry, index) => ({
+        path: `signatures[${index}]`,
+        algorithm: entry?.algorithm,
+        status: "untrusted",
+        reason: "no --verify-existing-with key was given",
+      }));
+  const unverified = results.filter((result) => result.status !== "verified");
+  if (chain ? !unverified.length : verdict?.valid) {
+    return;
+  }
+  const someVerified = unverified.length < results.length;
+  const details = unverified.map(
+    (result) =>
+      `  - ${result.path} (${displayValue(result.algorithm)}): ${result.reason || "not verified"}`,
+  );
+  if (args.allowUnverifiedHistory) {
+    console.warn(
+      [
+        chain
+          ? `Warning: countersigning a JSS signature chain with ${unverified.length} unverified signature object(s):`
+          : someVerified
+            ? `Warning: appending a JSS signature although ${unverified.length} existing signature object(s) failed verification:`
+            : `Warning: appending a JSS signature although none of the ${unverified.length} existing signature object(s) verified:`,
+        ...details,
+      ].join("\n"),
+    );
+    return;
+  }
+  throw new Error(
+    [
+      chain
+        ? `the countersignature would vouch for ${unverified.length} existing JSS signature object(s) that could not be verified:`
+        : someVerified
+          ? "the existing JSS signatures do not pass verification, so cdx-verify would reject the signed document:"
+          : `none of the ${unverified.length} existing JSS signature object(s) could be verified, so the content may have changed since it was signed:`,
+      ...details,
+      "Pass --verify-existing-with <public key> for each earlier signer, or --allow-unverified-history to sign anyway.",
+    ].join("\n"),
+  );
+}
+
+/**
+ * Signs a CycloneDX 2.0 document with JSS (ITU-T X.590).
+ *
+ * - replace: every existing JSS signature is removed (with a warning that
+ *   names how many), then the root and the nested members are signed;
+ * - signers: a root entry is appended. X.590 clause 7.1.2 removes the
+ *   existing entries before canonicalizing, so they stay valid;
+ * - chain: the only root entry is countersigned (X.590 clause 7.2). A JSF
+ *   chain entry covers every earlier entry, while a JSS countersignature
+ *   covers only the entry it countersigns, so the two agree only when the
+ *   root has a single entry; otherwise chain mode is refused.
+ *
+ * Nested members are signed only when no root signature is kept: signing
+ * them changes content the existing root entries cover.
+ */
+function signJssDocument(bomJson) {
+  if (args.embedPublicKey === false) {
+    throw new Error(
+      "--no-embed-public-key is not supported for CycloneDX 2.0 (JSS): X.590 clause 6.2.1 requires public_key, public_cert_chain, cert_url or thumbprint in every signature object, and cdx-sign writes public_key.",
+    );
+  }
+  if (args.keyId !== undefined) {
+    console.warn(
+      "Warning: --key-id is not used for CycloneDX 2.0 (JSS) signatures, which identify the key by public_key.",
+    );
+  }
+  let privateKey;
+  try {
+    privateKey = crypto.createPrivateKey(privateKeyContent);
+  } catch (error) {
+    throw new Error(`Unable to load the JSS signing key: ${error.message}`);
+  }
+  const algorithm = args.algorithm || selectJssAlgorithmForKey(privateKey);
+  const rootEntries = Array.isArray(bomJson.signatures)
+    ? bomJson.signatures
+    : [];
+  const appending = args.mode !== "replace" && rootEntries.length > 0;
+  const nestedFlags = [
+    ["components", args.signComponents],
+    ["services", args.signServices],
+    ["annotations", args.signAnnotations],
+  ];
+  if (appending) {
+    const requested = nestedFlags.find(([, value]) => value === true);
+    if (requested) {
+      throw new Error(
+        `Cannot sign ${requested[0]} while appending a ${args.mode} JSS signature, because that changes content covered by the existing root signature(s). Sign the root only (for example, --no-sign-${requested[0]}), or use --mode replace.`,
+      );
+    }
+    if (args.mode === "chain" && rootEntries.length !== 1) {
+      throw new Error(
+        `--mode chain is not supported for JSS when the BOM has ${rootEntries.length} root signatures: an X.590 clause 7.2 countersignature covers only the entry it countersigns, while a chain entry must cover every earlier entry. Use --mode signers to append a root signature.`,
+      );
+    }
+    checkExistingJssSignatures(bomJson);
+  }
+  // At 2.0 the nested members (inventories, their components, compositions
+  // and annotations) are signed together; any --no-sign-* signs the root
+  // only.
+  const deep = !appending && nestedFlags.every(([, value]) => value !== false);
+  const signOptions = { algorithm, privateKey };
+  let signedBom;
+  let label = args.mode;
+  if (args.mode === "replace") {
+    const { bom, removed } = removeJssSignatures(bomJson);
+    if (removed) {
+      console.warn(
+        `Replacing ${removed} existing JSS signature(s) (--mode replace). Use --mode signers to keep them.`,
+      );
+    }
+    signedBom = signJssBom(bom, { ...signOptions, deep });
+  } else if (appending && args.mode === "chain") {
+    signedBom = countersignJss(bomJson, { ...signOptions, index: 0 });
+    label = "chain (X.590 clause 7.2 countersignature)";
+  } else {
+    signedBom = signJssBom(bomJson, { ...signOptions, deep });
+    if (args.mode === "chain") {
+      label = "chain (first signature)";
+    }
+  }
+  console.log(`Mode: ${label} | Format: JSS | Algorithm: ${algorithm}`);
+  return signedBom;
+}
+
 try {
   const bomJson = parseStrictJson(fs.readFileSync(args.input));
   if (!isCycloneDxBom(bomJson)) {
@@ -243,39 +441,18 @@ try {
 
   let signedBom = bomJson;
   if (hasPrivateKey && privateKeyContent) {
-    checkExistingSignatures(bomJson);
-    signedBom = signBom(bomJson, {
-      privateKey: privateKeyContent,
-      algorithm: args.algorithm,
-      embedPublicKey: args.embedPublicKey,
-      embedPublicKeyNested: false,
-      keyId: args.keyId,
-      mode: args.mode,
-      signComponents: args.signComponents,
-      signServices: args.signServices,
-      signAnnotations: args.signAnnotations,
-    });
-
-    const outputPath = args.output || args.input;
-    fs.writeFileSync(outputPath, JSON.stringify(signedBom, null, null));
-
-    console.log(`Successfully signed BOM and saved to '${outputPath}'`);
-    console.log(
-      `Mode: ${args.mode} | Algorithm: ${args.algorithm}${args.keyId ? ` | KeyId: ${args.keyId}` : ""}`,
-    );
-    const rootSignature = signedBom.signature;
-    const newEntry =
-      rootSignature?.signers?.at(-1) ??
-      rootSignature?.chain?.at(-1) ??
-      rootSignature;
     if (
-      args.embedPublicKey &&
-      !String(args.algorithm).startsWith("HS") &&
-      newEntry?.publicKey === undefined
+      isCycloneDx20SpecVersion(bomJson.specVersion) ||
+      bomJson.specFormat !== undefined
     ) {
-      console.warn(
-        "Warning: this key type has no JWK form, so the public key was not embedded in the signature.",
-      );
+      // A CycloneDX 2.0 document signs with JSS (ITU-T X.590); the JSF
+      // signer below is 1.x only.
+      signedBom = signJssDocument(bomJson);
+      const jssOutputPath = args.output || args.input;
+      safeWriteSync(jssOutputPath, JSON.stringify(signedBom, null, null));
+      console.log(`Successfully signed BOM and saved to '${jssOutputPath}'`);
+    } else {
+      signedBom = signJsfDocument(bomJson);
     }
   } else {
     if (!hasAnySignature(bomJson)) {

package/bin/tracebom.js

@@ -13,7 +13,12 @@ import {
   retrieveCdxgenVersion,
   safeWriteSync,
 } from "../lib/ecosystems/utils.js";
-import { DEFAULT_CDX_SPEC_VERSION } from "../lib/inventory/bomUtils.js";
+import {
+  DEFAULT_CDX_SPEC_VERSION,
+  isCycloneDx20SpecVersion,
+} from "../lib/inventory/bomUtils.js";
+import { renderCycloneDx20 } from "../lib/inventory/cyclonedx20.js";
+import { hardwareRenderContext } from "../lib/inventory/hbomLoader.js";
 import { applySpecVersionCompatibility } from "../lib/stages/postgen/specVersionCompat.js";
 
 const _yargs = yargs(hideBin(process.argv));
@@ -339,10 +344,20 @@ const options = {
     process.exit(1);
   }
   // tracebom skips postProcess, so the downgrade to an older --spec-version
-  // (for example dropping the 1.7 algorithmFamily of traced crypto) runs here.
+  // (for example dropping the 1.7 algorithmFamily of traced crypto) runs here,
+  // and a 2.0 target renders the document with the postgen renderer.
   applySpecVersionCompatibility(bomJson, options);
+  const serviceCount = bomJson?.services?.length || 0;
+  const componentCount = bomJson?.components?.length || 0;
+  const outputBomJson = isCycloneDx20SpecVersion(options.specVersion)
+    ? renderCycloneDx20(bomJson, await hardwareRenderContext(bomJson))
+    : bomJson;
 
-  const jsonPayload = JSON.stringify(bomJson, null, DEBUG_MODE ? 2 : null);
+  const jsonPayload = JSON.stringify(
+    outputBomJson,
+    null,
+    DEBUG_MODE ? 2 : null,
+  );
 
   if (args.print) {
     // The document is the payload, so it bypasses the console shim.
@@ -350,9 +365,6 @@ const options = {
   }
 
   safeWriteSync(options.output, jsonPayload);
-
-  const serviceCount = bomJson?.services?.length || 0;
-  const componentCount = bomJson?.components?.length || 0;
   const summaryParts = [
     `SBOM written to ${options.output}`,
     `${componentCount} component(s)`,

package/bin/validate.js

@@ -19,6 +19,7 @@ import process from "node:process";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 
+import { thoughtLog } from "../lib/core/logger.js";
 import { installConsoleShim, restoreConsole } from "../lib/core/ui.js";
 import {
   dirNameStr,
@@ -32,6 +33,7 @@ import {
   getNonCycloneDxErrorMessage,
   isCycloneDxBom,
 } from "../lib/inventory/bomUtils.js";
+import { formatReadLossNotice } from "../lib/inventory/cyclonedx20.js";
 import {
   importProtobomModule,
   isProtoBomPath,
@@ -80,12 +82,12 @@ const args = _yargs
     alias: "b",
     type: "string",
     description:
-      "Comma-separated list of compliance benchmark aliases to include in the scorecards (scvs, scvs-l1, scvs-l2, scvs-l3, cra). Defaults to all.",
+      "Comma-separated list of compliance benchmark aliases to include in the scorecards (scvs, scvs-l1, scvs-l2, scvs-l3, cra, cisa, cisa-ai). Defaults to all.",
   })
   .option("categories", {
     type: "string",
     description:
-      "Comma-separated list of compliance rule categories to evaluate (compliance-scvs, compliance-cra). Defaults to all.",
+      "Comma-separated list of compliance rule categories to evaluate (compliance-scvs, compliance-cra, compliance-cisa, compliance-cisa-ai). Defaults to all.",
   })
   .option("min-severity", {
     type: "string",
@@ -323,7 +325,20 @@ try {
 writeOrPrint(output, args.reportFile);
 
 for (const e of report.validationErrors || []) {
-  console.error(`cdx-validate: ${e.stage} validation threw: ${e.message}`);
+  console.error(
+    e.stage === "read"
+      ? `cdx-validate: ${e.message}`
+      : `cdx-validate: ${e.stage} validation threw: ${e.message}`,
+  );
+}
+// The deep checks and compliance rules read the 1.x-shaped model of a 2.0
+// input; the losses name the parts of the input they never saw. stderr,
+// because stdout may carry the json or sarif report.
+if (report.readLosses?.length) {
+  console.error(formatReadLossNotice(report.readLosses));
+  for (const loss of report.readLosses) {
+    thoughtLog(`cdx-validate 2.0 loss at ${loss.pointer}: ${loss.reason}`);
+  }
 }
 
 const { shouldFail: fail, reason } = shouldFail(report, {

package/bin/verify.js

@@ -19,8 +19,10 @@ import {
   loadVerificationKey,
   verifyBomSignatures,
 } from "../lib/helpers/bomSigner.js";
+import { verifyJssBom } from "../lib/helpers/jssSigner.js";
 import {
   getNonCycloneDxErrorMessage,
+  isCycloneDx20SpecVersion,
   isCycloneDxBom,
 } from "../lib/inventory/bomUtils.js";
 import { isProtoBomPath } from "../lib/inventory/protobomLoader.js";
@@ -45,30 +47,30 @@ const args = _yargs
     type: "array",
     string: true,
     description:
-      "Trusted public key in PEM format. Repeat to trust several keys; a signature entry verifies when one of them verifies it.",
+      "Trusted public key in PEM format. Repeat to trust several keys; a signature entry verifies when one of them verifies it. CycloneDX 2.0 (JSS) documents need at least one: the public_key embedded in a JSS entry is never trusted on its own, and an entry whose public_key is one of these keys must verify with it.",
   })
   .option("secret-key", {
     type: "string",
     description:
-      "File holding the shared secret for HMAC (HS256, HS384, HS512) signatures. HMAC signatures are only accepted with this option.",
+      "File holding the shared secret for HMAC (HS256, HS384, HS512) signatures. HMAC signatures are only accepted with this option. Not supported for CycloneDX 2.0 (JSS) documents.",
   })
   .option("deep", {
     type: "boolean",
     default: true,
     description:
-      "Strictly verify all nested component, service, and annotation signatures against the provided keys. Pass --no-deep to verify only the root signature.",
+      "Strictly verify all nested component, service, and annotation signatures against the provided keys (at 2.0: inventories, their components, compositions, and annotations). Pass --no-deep to verify only the root signature.",
   })
   .option("require-all", {
     type: "boolean",
     default: false,
     description:
-      "Require every entry of a signers or chain signature to verify with one of the keys, instead of at least one.",
+      "Require every entry of a signers or chain signature to verify with one of the keys, instead of at least one. At 2.0 every JSS signature object, countersignatures included, must verify with one of the keys, and every key must verify a root signature object.",
   })
   .option("allow-nested-only", {
     type: "boolean",
     default: false,
     description:
-      "Accept a BOM without a root signature when every component, service, and annotation carries a signature that verifies. No signature then covers the other members of the BOM.",
+      "Accept a BOM without a root signature when every component, service, and annotation carries a signature that verifies (at 2.0: every inventory, inventory component, composition, and annotation). No signature then covers the other members of the BOM.",
   })
   .completion("completion", "Generate bash/zsh completion")
   .epilogue("for documentation, visit https://cdxgen.github.io/cdxgen")
@@ -159,6 +161,16 @@ if (!isCycloneDxBom(bomJson)) {
   console.log(getNonCycloneDxErrorMessage(bomJson, "cdx-verify"));
   process.exit(1);
 }
+// A CycloneDX 2.0 document carries JSS signatures (ITU-T X.590).
+const isJssBom =
+  isCycloneDx20SpecVersion(bomJson.specVersion) ||
+  bomJson.specFormat !== undefined;
+if (isJssBom && args.secretKey) {
+  console.log(
+    "--secret-key is not supported for CycloneDX 2.0 (JSS) signatures: X.590 clause 6.2.2 says HMAC algorithms SHOULD NOT be used, and cdx-verify does not verify them. Pass the signer's --public-key instead.",
+  );
+  process.exit(1);
+}
 
 const verificationKeys = [];
 for (const keyFile of args.secretKey ? [args.secretKey] : publicKeyFiles) {
@@ -205,6 +217,102 @@ function printRejections(node) {
   }
 }
 
+function describeJssResult(result) {
+  const role = result.depth > 0 ? "countersignature" : "signature";
+  return `${result.path} ${role} (${displayValue(result.algorithm)})`;
+}
+
+function printJssResults(results, prefix = "") {
+  for (const result of results) {
+    if (result.status === "verified") {
+      console.log(
+        `  ✓ ${prefix}${describeJssResult(result)} verified with key #${result.keyIndex + 1}: ${publicKeyFiles[result.keyIndex]}`,
+      );
+    } else {
+      console.log(
+        `  - ${prefix}${describeJssResult(result)} ${result.status}: ${result.reason || "not verified"}`,
+      );
+    }
+  }
+}
+
+if (isJssBom) {
+  // JSS verification (X.590 clause 8.1, countersignatures clause 7.2) with
+  // the trusted --public-key values only (clause 8.1.3 "fetch it from a
+  // trusted source"); the same --deep, --require-all and
+  // --allow-nested-only policy as the JSF path below.
+  let jssReport;
+  try {
+    jssReport = verifyJssBom(bomJson, {
+      publicKeys: verificationKeys,
+      deep: args.deep,
+      requireAll: args.requireAll,
+      allowNestedOnly: args.allowNestedOnly,
+    });
+  } catch (error) {
+    console.log(`JSS verification failed: ${error.message}`);
+    process.exit(1);
+  }
+  for (const error of jssReport.errors) {
+    console.log(error);
+  }
+  if (args.requireAll && jssReport.root) {
+    jssReport.root.keysMatched.forEach((matched, index) => {
+      if (!matched) {
+        console.log(`  - key #${index + 1}: ${publicKeyFiles[index]}`);
+      }
+    });
+  }
+  if (jssReport.root) {
+    console.log(
+      jssReport.root.valid
+        ? "BOM JSS signatures:"
+        : "BOM signature is invalid!",
+    );
+    for (const reason of jssReport.root.reasons) {
+      console.log(`  - ${reason}`);
+    }
+    printJssResults(jssReport.root.results);
+  } else if (!args.allowNestedOnly) {
+    console.log(
+      "Pass --allow-nested-only to accept a BOM whose inventories, components, compositions, and annotations are all signed.",
+    );
+  }
+  const invalidNested = jssReport.nested.filter((item) => !item.valid);
+  for (const item of invalidNested) {
+    console.log(`${item.path} signature is invalid!`);
+    for (const reason of item.reasons) {
+      console.log(`  - ${reason}`);
+    }
+    printJssResults(item.results);
+  }
+  if (invalidNested.length) {
+    console.log("One or more nested signatures are invalid!");
+    if (jssReport.root?.valid) {
+      console.log(
+        "The root signature verifies with this key. Nested signatures belong to the party that created them, so pass --no-deep to verify only the root signature with this key.",
+      );
+    }
+  }
+  if (!jssReport.valid) {
+    process.exit(1);
+  }
+  const unverified = [
+    ...jssReport.results,
+    ...jssReport.nested.flatMap((item) => item.results),
+  ].filter((result) => result.status !== "verified");
+  if (unverified.length) {
+    console.log(
+      `Warning: ${unverified.length} JSS signature object(s) did not verify with the given key(s). Pass --require-all to fail in that case.`,
+    );
+  }
+  if (!jssReport.root) {
+    console.log(`✓ ${jssReport.nested.length} nested signature(s) are valid!`);
+  }
+  console.log("JSS signature(s) verified successfully.");
+  process.exit(0);
+}
+
 const report = verifyBomSignatures(bomJson, verificationKeys, {
   deep: args.deep,
   allowNestedOnly: args.allowNestedOnly,