@cdxgen/cdxgen 0.0.1 → 13.0.1

package/bin/validate.js

@@ -0,0 +1,268 @@
+#!/usr/bin/env node
+
+/**
+ * cdx-validate CLI — structural, deep, and compliance validation for
+ * CycloneDX SBOMs.
+ *
+ * Exit codes:
+ *   0 — all checks pass (or no findings >= --fail-severity).
+ *   1 — configuration error (bad input, missing file, unknown reporter).
+ *   2 — schema validation failed (in --strict mode).
+ *   3 — compliance findings at or above --fail-severity.
+ *   4 — signature verification was requested and failed.
+ */
+
+import fs from "node:fs";
+import { dirname, join } from "node:path";
+import process from "node:process";
+
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+
+import {
+  dirNameStr,
+  retrieveCdxgenVersion,
+  safeExistsSync,
+  safeMkdirSync,
+  safeWriteSync,
+} from "../lib/ecosystems/utils.js";
+import {
+  getNonCycloneDxErrorMessage,
+  isCycloneDxBom,
+} from "../lib/inventory/bomUtils.js";
+import {
+  importProtobomModule,
+  isProtoBomPath,
+} from "../lib/inventory/protobomLoader.js";
+import { getBomWithOras } from "../lib/managers/oci.js";
+import { shouldFail, validateBomAdvanced } from "../lib/validator/index.js";
+import { render as renderReport } from "../lib/validator/reporters/index.js";
+
+const _yargs = yargs(hideBin(process.argv));
+
+const args = _yargs
+  .option("input", {
+    alias: "i",
+    default: "bom.json",
+    description: "Input SBOM JSON or protobuf file, or an OCI reference.",
+  })
+  .option("platform", {
+    description:
+      "Platform to use when resolving an OCI reference (passed to oras).",
+  })
+  .option("report", {
+    alias: "r",
+    default: "console",
+    choices: ["console", "json", "sarif", "annotations"],
+    description: "Output format.",
+  })
+  .option("report-file", {
+    alias: "o",
+    description:
+      "Write the report to this file. Defaults to stdout. Required for the 'annotations' reporter when you want to save the annotated BOM.",
+  })
+  .option("schema", {
+    type: "boolean",
+    default: true,
+    description:
+      "Run the CycloneDX JSON-schema validation. Pass --no-schema to skip.",
+  })
+  .option("deep", {
+    type: "boolean",
+    default: true,
+    description:
+      "Run the deep purl/ref/metadata checks from lib/validator/bomValidator.js. Pass --no-deep to skip.",
+  })
+  .option("benchmark", {
+    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.",
+  })
+  .option("categories", {
+    type: "string",
+    description:
+      "Comma-separated list of compliance rule categories to evaluate (compliance-scvs, compliance-cra). Defaults to all.",
+  })
+  .option("min-severity", {
+    type: "string",
+    default: "info",
+    choices: ["info", "low", "medium", "high", "critical"],
+    description:
+      "Drop findings below this severity from the output (benchmark scoring is unaffected).",
+  })
+  .option("fail-severity", {
+    type: "string",
+    default: "high",
+    choices: ["info", "low", "medium", "high", "critical"],
+    description:
+      "Exit with code 3 when any failing finding is at or above this severity.",
+  })
+  .option("include-manual", {
+    type: "boolean",
+    default: true,
+    description:
+      "Include non-automatable manual-review findings in the output. Pass --no-include-manual to hide them.",
+  })
+  .option("include-pass", {
+    type: "boolean",
+    default: false,
+    description:
+      "Include passing findings in the output (useful for audits). Defaults to false.",
+  })
+  .option("public-key", {
+    description:
+      "Path to a PEM public key. When set, cdx-validate also verifies the BOM signature.",
+  })
+  .option("require-signature", {
+    type: "boolean",
+    default: false,
+    description:
+      "Exit non-zero (4) when --public-key is provided but signature verification fails.",
+  })
+  .option("strict", {
+    type: "boolean",
+    default: false,
+    description:
+      "Treat a failing schema or deep validation as a non-zero exit (code 2).",
+  })
+  .completion("completion", "Generate bash/zsh completion")
+  .epilogue("for documentation, visit https://cdxgen.github.io/cdxgen")
+  .scriptName("cdx-validate")
+  .version(retrieveCdxgenVersion())
+  .help()
+  .wrap(Math.min(120, yargs().terminalWidth())).argv;
+
+async function loadBom(input, platform) {
+  if (safeExistsSync(input)) {
+    try {
+      if (isProtoBomPath(input)) {
+        const { readBinary } = await importProtobomModule(
+          "cdx-validate",
+          "protobuf BOM input",
+        );
+        return readBinary(input, true);
+      }
+      return JSON.parse(fs.readFileSync(input, "utf8"));
+    } catch (err) {
+      console.error(`Failed to parse ${input}: ${err.message}`);
+      process.exit(1);
+    }
+  }
+  if (
+    input.includes(":") ||
+    input.includes("docker") ||
+    input.includes("ghcr")
+  ) {
+    const bom = await getBomWithOras(input, platform);
+    if (bom) return bom;
+  }
+  console.error(`Input '${input}' is not a readable SBOM.`);
+  process.exit(1);
+  return undefined;
+}
+
+function loadPublicKey(path) {
+  if (!path) return null;
+  if (!safeExistsSync(path)) {
+    console.error(`Public key '${path}' not found.`);
+    process.exit(1);
+  }
+  return fs.readFileSync(path, "utf8");
+}
+
+function splitCsv(value) {
+  if (!value) return undefined;
+  return value
+    .split(",")
+    .map((v) => v.trim())
+    .filter(Boolean);
+}
+
+function writeOrPrint(content, outputPath) {
+  if (!outputPath) {
+    process.stdout.write(`${content}\n`);
+    return;
+  }
+  const parent = dirname(outputPath);
+  if (parent && !safeExistsSync(parent)) {
+    safeMkdirSync(parent, { recursive: true });
+  }
+  safeWriteSync(outputPath, content);
+}
+
+function isLocalProtoBomInput(input) {
+  if (!safeExistsSync(input)) {
+    return false;
+  }
+  return isProtoBomPath(input);
+}
+
+const bomJson = await loadBom(args.input, args.platform);
+const publicKeyStr = loadPublicKey(args.publicKey);
+const inputIsLocalProtoBom = isLocalProtoBomInput(args.input);
+if (!isCycloneDxBom(bomJson)) {
+  console.error(getNonCycloneDxErrorMessage(bomJson, "cdx-validate"));
+  process.exit(1);
+}
+
+if (inputIsLocalProtoBom && publicKeyStr) {
+  console.error(
+    "cdx-validate: protobuf BOM input does not currently preserve JSF signature blocks. Verify signatures against the source JSON BOM instead.",
+  );
+  process.exit(args.requireSignature ? 4 : 1);
+}
+
+const report = await validateBomAdvanced(bomJson, {
+  schema: args.schema,
+  deep: args.deep,
+  benchmarks: splitCsv(args.benchmark),
+  categories: splitCsv(args.categories),
+  minSeverity: args.minSeverity,
+  includeManual: args.includeManual,
+  includePass: args.includePass,
+  publicKey: publicKeyStr || undefined,
+});
+
+let output;
+try {
+  const { version: pkgVersion } = JSON.parse(
+    fs.readFileSync(join(dirNameStr, "package.json"), "utf8"),
+  );
+  output = renderReport(args.report, report, {
+    bomJson,
+    toolName: "cdx-validate",
+    toolVersion: pkgVersion,
+    pretty: true,
+  });
+} catch (err) {
+  console.error(err.message);
+  process.exit(1);
+}
+
+writeOrPrint(output, args.reportFile);
+
+const { shouldFail: fail, reason } = shouldFail(report, {
+  failSeverity: args.failSeverity,
+  strict: args.strict,
+  requireSignature: Boolean(args.requireSignature && publicKeyStr),
+});
+
+if (report.signatureVerified === false && args.requireSignature) {
+  console.error(
+    `cdx-validate: signature verification failed — ${report.signatureDetails?.error || "no matching key"}.`,
+  );
+  process.exit(4);
+}
+
+if (args.strict && report.schemaValid === false) {
+  console.error("cdx-validate: schema validation failed.");
+  process.exit(2);
+}
+
+if (fail) {
+  console.error(`cdx-validate: ${reason}`);
+  process.exit(3);
+}
+
+process.exit(0);

package/bin/verify.js

@@ -0,0 +1,189 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import { join } from "node:path";
+import process from "node:process";
+
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+
+import { readEnvironmentVariable } from "../lib/core/activity.js";
+import {
+  dirNameStr,
+  retrieveCdxgenVersion,
+  safeExistsSync,
+} from "../lib/ecosystems/utils.js";
+import { verifyNode } from "../lib/helpers/bomSigner.js";
+import {
+  getNonCycloneDxErrorMessage,
+  isCycloneDxBom,
+} from "../lib/inventory/bomUtils.js";
+import { isProtoBomPath } from "../lib/inventory/protobomLoader.js";
+import { getBomWithOras } from "../lib/managers/oci.js";
+
+const dirName = dirNameStr;
+
+const _yargs = yargs(hideBin(process.argv));
+
+const args = _yargs
+  .option("input", {
+    alias: "i",
+    default: "bom.json",
+    description:
+      "Input CycloneDX JSON or protobuf BOM to verify. Default bom.json",
+  })
+  .option("platform", {
+    description: "The platform to validate. No default",
+  })
+  .option("public-key", {
+    default: "public.key",
+    description: "Public key in PEM format. Default public.key",
+  })
+  .option("deep", {
+    type: "boolean",
+    default: true,
+    description:
+      "Strictly verify all nested component, service, and annotation signatures against the provided public key. Pass --no-deep to verify only the root signature.",
+  })
+  .completion("completion", "Generate bash/zsh completion")
+  .epilogue("for documentation, visit https://cdxgen.github.io/cdxgen")
+  .scriptName("cdx-verify")
+  .version(retrieveCdxgenVersion())
+  .help(false)
+  .option("help", {
+    alias: "h",
+    type: "boolean",
+    description: "Show help",
+  })
+  .wrap(Math.min(120, yargs().terminalWidth())).argv;
+
+if (args.help) {
+  console.log(`${retrieveCdxgenVersion()}\n`);
+  _yargs.showHelp();
+  process.exit(0);
+}
+
+if (args.version) {
+  const packageJsonAsString = fs.readFileSync(
+    join(dirName, "..", "package.json"),
+    "utf-8",
+  );
+  const packageJson = JSON.parse(packageJsonAsString);
+
+  console.log(packageJson.version);
+  process.exit(0);
+}
+
+if (readEnvironmentVariable("CDXGEN_NODE_OPTIONS")) {
+  process.env.NODE_OPTIONS = `${process.env.NODE_OPTIONS || ""} ${process.env.CDXGEN_NODE_OPTIONS}`;
+}
+
+async function getBom(args) {
+  if (safeExistsSync(args.input)) {
+    if (isProtoBomPath(args.input)) {
+      console.log(
+        "cdx-verify: protobuf BOM input does not currently preserve JSF signature blocks. Verify signatures against the source JSON BOM instead.",
+      );
+      process.exit(1);
+    }
+    try {
+      return JSON.parse(fs.readFileSync(args.input, "utf8"));
+    } catch (error) {
+      console.log(`Failed to parse '${args.input}': ${error.message}`);
+      process.exit(1);
+    }
+  }
+  if (
+    args.input.includes(":") ||
+    args.input.includes("docker") ||
+    args.input.includes("ghcr")
+  ) {
+    return await getBomWithOras(args.input, args.platform);
+  }
+  return undefined;
+}
+
+const bomJson = await getBom(args);
+
+if (!bomJson) {
+  console.log(`${args.input} is invalid!`);
+  process.exit(1);
+}
+if (!isCycloneDxBom(bomJson)) {
+  console.log(getNonCycloneDxErrorMessage(bomJson, "cdx-verify"));
+  process.exit(1);
+}
+
+if (bomJson && !safeExistsSync(args.publicKey)) {
+  console.log("Public key for signature verification is missing!");
+  process.exit(1);
+}
+
+const publicKeyStr = fs.readFileSync(args.publicKey, "utf8");
+
+let rootMatch = null;
+if (bomJson.signature) {
+  rootMatch = verifyNode(bomJson, publicKeyStr);
+}
+
+const verifyNested = args.deep || !bomJson.signature;
+let hasInvalidNested = false;
+let checkedNested = 0;
+
+if (verifyNested) {
+  for (const comp of bomJson.components || []) {
+    if (comp.signature) {
+      checkedNested++;
+      if (!verifyNode(comp, publicKeyStr)) {
+        console.log(
+          `Component '${comp["bom-ref"] || comp.name}' signature is invalid!`,
+        );
+        hasInvalidNested = true;
+      }
+    }
+  }
+  for (const svc of bomJson.services || []) {
+    if (svc.signature) {
+      checkedNested++;
+      if (!verifyNode(svc, publicKeyStr)) {
+        console.log(
+          `Service '${svc["bom-ref"] || svc.name}' signature is invalid!`,
+        );
+        hasInvalidNested = true;
+      }
+    }
+  }
+  for (const ann of bomJson.annotations || []) {
+    if (ann.signature) {
+      checkedNested++;
+      if (!verifyNode(ann, publicKeyStr)) {
+        console.log(
+          `Annotation '${ann["bom-ref"] || ann.subject}' signature is invalid!`,
+        );
+        hasInvalidNested = true;
+      }
+    }
+  }
+}
+
+if (hasInvalidNested) {
+  console.log("One or more nested signatures are invalid!");
+  process.exit(1);
+}
+
+if (bomJson.signature) {
+  if (rootMatch) {
+    const identifier = rootMatch.keyId
+      ? `KeyId: '${rootMatch.keyId}'`
+      : `Algorithm: '${rootMatch.algorithm}'`;
+    console.log(`✓ Signature is valid! (Matched ${identifier})`);
+  } else {
+    console.log("BOM signature is invalid!");
+    process.exit(1);
+  }
+} else if (checkedNested > 0 && !hasInvalidNested) {
+  console.log(`✓ ${checkedNested} nested signature(s) are valid!`);
+} else {
+  console.log("No valid signatures found to verify!");
+  process.exit(1);
+}