@cdxgen/cdxgen 0.0.1 → 13.0.1

package/bin/convert.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+
+import fs from "node:fs";
+import { dirname } from "node:path";
+import process from "node:process";
+
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+
+import { installConsoleShim, restoreConsole } from "../lib/core/ui.js";
+import {
+  retrieveCdxgenVersion,
+  safeExistsSync,
+  safeMkdirSync,
+  safeWriteSync,
+} from "../lib/ecosystems/utils.js";
+import {
+  deriveSpdxOutputPath,
+  deriveSpecVersionOutputPath,
+} from "../lib/helpers/exportUtils.js";
+import {
+  getNonCycloneDxErrorMessage,
+  isCycloneDxBom,
+  toCycloneDxSpecVersionString,
+} from "../lib/inventory/bomUtils.js";
+import {
+  importProtobomModule,
+  isProtoBomPath,
+} from "../lib/inventory/protobomLoader.js";
+import { sortBomCollections } from "../lib/stages/postgen/sortBom.js";
+import { convertCycloneDxToSpdx } from "../lib/stages/postgen/spdxConverter.js";
+import {
+  applySpecVersionCompatibility,
+  collectFieldPaths,
+} from "../lib/stages/postgen/specVersionCompat.js";
+import { validateBom, validateSpdx } from "../lib/validator/bomValidator.js";
+
+// cdxgen bundles CycloneDX JSON schemas for these versions only, so a
+// conversion to any other version is written without a schema check.
+const VALIDATABLE_SPEC_VERSIONS = new Set(["1.6", "1.7", "2.0"]);
+
+const _yargs = yargs(hideBin(process.argv));
+
+const args = _yargs
+  .option("input", {
+    alias: "i",
+    default: "bom.json",
+    description: "Input CycloneDX BOM JSON or protobuf file.",
+  })
+  .option("output", {
+    alias: "o",
+    description:
+      "Output file. Defaults to <input>.spdx.json, or <input>-<to>.<ext> when --to names a CycloneDX version.",
+  })
+  .option("to", {
+    default: "spdx",
+    description:
+      "Conversion target. 'spdx' exports SPDX 3.0.1 JSON-LD. A CycloneDX spec version (1.5, 1.6, 1.7) cross-converts the BOM to that version instead.",
+  })
+  .option("validate", {
+    type: "boolean",
+    default: true,
+    description:
+      "Validate the converted output against its schema. Pass --no-validate to skip.",
+  })
+  .option("json-pretty", {
+    type: "boolean",
+    default: false,
+    description: "Pretty-print generated JSON output.",
+  })
+  .completion("completion", "Generate bash/zsh completion")
+  .epilogue("for documentation, visit https://cdxgen.github.io/cdxgen")
+  .scriptName("cdx-convert")
+  .version(retrieveCdxgenVersion())
+  .help()
+  .wrap(Math.min(120, yargs().terminalWidth())).argv;
+
+// stdout carries the payload and nothing else; every diagnostic goes to the
+// live region's stream. Without the shim a `--print`/`--json` document shares
+// stdout with progress messages and cannot be piped into a parser.
+installConsoleShim();
+process.once("exit", restoreConsole);
+
+const loadCycloneDxBom = async (inputPath) => {
+  if (!safeExistsSync(inputPath)) {
+    console.error(`Input file '${inputPath}' not found.`);
+    process.exit(1);
+  }
+  const isProtoInput = isProtoBomPath(inputPath);
+  try {
+    if (isProtoInput) {
+      const { readBinary } = await importProtobomModule(
+        "cdx-convert",
+        "protobuf BOM input",
+      );
+      return readBinary(inputPath, true);
+    }
+    return JSON.parse(fs.readFileSync(inputPath, "utf8"));
+  } catch (error) {
+    const inputType = isProtoInput ? "protobuf" : "JSON";
+    console.error(
+      `Failed to parse '${inputPath}' as CycloneDX ${inputType}: ${error.message}`,
+    );
+    process.exit(1);
+  }
+};
+
+const ensureOutputParent = (outputPath) => {
+  const outputParent = dirname(outputPath);
+  if (outputParent && outputParent !== "." && !safeExistsSync(outputParent)) {
+    safeMkdirSync(outputParent, { recursive: true });
+  }
+};
+
+const targetSpecVersion = toCycloneDxSpecVersionString(args.to);
+const isSpdxTarget = `${args.to}`.trim().toLowerCase() === "spdx";
+if (!isSpdxTarget && !targetSpecVersion) {
+  console.error(
+    `Unsupported conversion target '${args.to}'. Pass --to spdx for an SPDX 3.0.1 export, or a CycloneDX spec version such as 1.5, 1.6, or 1.7.`,
+  );
+  process.exit(1);
+}
+
+const bomJson = await loadCycloneDxBom(args.input);
+
+if (!isCycloneDxBom(bomJson)) {
+  console.error(getNonCycloneDxErrorMessage(bomJson, "cdx-convert"));
+  process.exit(1);
+}
+const cdxSpecVersion = toCycloneDxSpecVersionString(bomJson?.specVersion);
+
+if (isSpdxTarget) {
+  if (!["1.6", "1.7"].includes(cdxSpecVersion)) {
+    console.error(
+      `Unsupported CycloneDX specVersion '${bomJson?.specVersion}'. cdx-convert currently supports CycloneDX 1.6 or 1.7 input and exports SPDX 3.0.1.`,
+    );
+    process.exit(1);
+  }
+
+  const spdxJson = convertCycloneDxToSpdx(bomJson, args);
+  if (!spdxJson) {
+    console.error("Conversion failed: unable to generate SPDX output.");
+    process.exit(1);
+  }
+
+  if (args.validate && !validateSpdx(spdxJson)) {
+    console.error("SPDX validation failed for the converted output.");
+    process.exit(1);
+  }
+
+  const outputPath = args.output || deriveSpdxOutputPath(args.input);
+  ensureOutputParent(outputPath);
+  safeWriteSync(
+    outputPath,
+    JSON.stringify(spdxJson, null, args.jsonPretty ? 2 : null),
+  );
+  console.log(`Successfully converted '${args.input}' to '${outputPath}'.`);
+} else {
+  const outputPath =
+    args.output || deriveSpecVersionOutputPath(args.input, targetSpecVersion);
+  if (outputPath === args.input) {
+    console.error(
+      `Refusing to overwrite the input BOM '${args.input}'. Pass an explicit -o.`,
+    );
+    process.exit(1);
+  }
+
+  // The same normalizer the postgen stage applies to freshly generated BOMs, so
+  // `cdx-convert --to 1.6` and `cdxgen --spec-version 1.6` agree on the result.
+  const sourceFieldPaths = collectFieldPaths(bomJson);
+  const convertedBomJson = applySpecVersionCompatibility(bomJson, {
+    specVersion: targetSpecVersion,
+  });
+  sortBomCollections(convertedBomJson);
+
+  const retainedFieldPaths = collectFieldPaths(convertedBomJson);
+  const removedFieldPaths = [...sourceFieldPaths]
+    .filter((fieldPath) => !retainedFieldPaths.has(fieldPath))
+    .sort();
+  if (removedFieldPaths.length) {
+    console.warn(
+      `Converting to CycloneDX ${targetSpecVersion} dropped ${removedFieldPaths.length} field path(s) that version does not define:`,
+    );
+    for (const fieldPath of removedFieldPaths) {
+      console.warn(`  - ${fieldPath}`);
+    }
+  }
+
+  if (args.validate) {
+    if (VALIDATABLE_SPEC_VERSIONS.has(targetSpecVersion)) {
+      if (!(await validateBom(convertedBomJson))) {
+        console.error(
+          `CycloneDX ${targetSpecVersion} validation failed for the converted output.`,
+        );
+        process.exit(1);
+      }
+    } else {
+      console.warn(
+        `Skipping schema validation: cdxgen bundles CycloneDX schemas for ${[...VALIDATABLE_SPEC_VERSIONS].join(", ")} only.`,
+      );
+    }
+  }
+
+  ensureOutputParent(outputPath);
+  if (isProtoBomPath(outputPath)) {
+    const { writeBinary } = await importProtobomModule(
+      "cdx-convert",
+      "protobuf BOM output",
+    );
+    writeBinary(convertedBomJson, outputPath, targetSpecVersion);
+  } else {
+    safeWriteSync(
+      outputPath,
+      JSON.stringify(convertedBomJson, null, args.jsonPretty ? 2 : null),
+    );
+  }
+  console.log(
+    `Successfully converted '${args.input}' from CycloneDX ${cdxSpecVersion} to CycloneDX ${targetSpecVersion} at '${outputPath}'.`,
+  );
+}

package/bin/evinse.js

@@ -0,0 +1,353 @@
+#!/usr/bin/env node
+// Evinse (Evinse Verification Is Nearly SBOM Evidence)
+
+import fs from "node:fs";
+import process from "node:process";
+
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+
+import { readEnvironmentVariable } from "../lib/core/activity.js";
+import { safeExistsSync } from "../lib/ecosystems/utils.js";
+import {
+  analyzeProject,
+  createEvinseFile,
+  prepareDB,
+} from "../lib/evinser/evinser.js";
+import {
+  getNonCycloneDxErrorMessage,
+  isCycloneDxBom,
+} from "../lib/inventory/bomUtils.js";
+import {
+  printCallStack,
+  printOccurrences,
+  printReachables,
+  printServices,
+} from "../lib/inventory/display.js";
+import { validateBom } from "../lib/validator/bomValidator.js";
+
+const args = yargs(hideBin(process.argv))
+  .env("EVINSE")
+  .option("input", {
+    alias: "i",
+    description: "Input SBOM file. Default bom.json",
+    default: "bom.json",
+  })
+  .option("output", {
+    alias: "o",
+    description: "Output file. Default bom.evinse.json",
+    default: "bom.evinse.json",
+  })
+  .option("language", {
+    alias: "l",
+    description: "Application language",
+    default: "java",
+    choices: [
+      "java",
+      "jar",
+      "js",
+      "ts",
+      "javascript",
+      "nodejs",
+      "py",
+      "python",
+      "android",
+      "go",
+      "golang",
+      "rust",
+      "rs",
+      "rust-lang",
+      "csharp",
+      "cs",
+      "c",
+      "cpp",
+      "dotnet",
+      "php",
+      "swift",
+      "ios",
+      "ruby",
+      "scala",
+      "vb",
+      "vbnet",
+      "visualbasic",
+      "f#",
+      "fs",
+      "fsharp",
+    ],
+  })
+  .option("profile", {
+    description:
+      "Evidence profile. The research profile enables data-flow and crypto analysis where supported.",
+    default: "generic",
+    choices: ["generic", "research"],
+  })
+  .option("deep", {
+    description:
+      "Enable deeper evidence collection. For Go, this enables Golem data-flow with performance safeguards so crypto flows can be captured.",
+    default: false,
+    type: "boolean",
+  })
+  .option("golem-command", {
+    description: "Use a specific golem binary for Go Evinse analysis.",
+    default: readEnvironmentVariable("GOLEM_CMD"),
+  })
+  .option("golem-callgraph", {
+    description: "Golem call graph mode for Go Evinse analysis.",
+    choices: ["none", "static", "cha", "rta", "vta"],
+    default: "static",
+  })
+  .option("golem-dataflow", {
+    description:
+      "Golem data-flow mode for Go Evinse analysis. Defaults to all with --with-data-flow, research profile, or --deep, and none otherwise.",
+    choices: ["none", "security", "crypto", "all"],
+    default: "all",
+  })
+  .option("golem-dataflow-callgraph", {
+    description:
+      "Golem call graph mode used only for data-flow dynamic summary replay.",
+    default: "static",
+    choices: ["none", "static", "cha", "rta", "vta"],
+  })
+  .option("golem-dataflow-patterns", {
+    description: "Custom Golem data-flow pattern JSON file.",
+  })
+  .option("golem-dataflow-pattern-packs", {
+    description:
+      "Comma-separated Golem data-flow pattern packs: all, base, http, frameworks, data, filesystem, process, crypto, native, config, cloud.",
+  })
+  .option("golem-dataflow-max-slices", {
+    description: "Maximum Golem data-flow slices to emit.",
+    type: "number",
+  })
+  .option("golem-dataflow-workers", {
+    description:
+      "Golem data-flow worker count. Defaults to a capped CPU count for predictable performance.",
+    type: "number",
+  })
+  .option("golem-dataflow-large-repo-functions", {
+    description:
+      "Function count at which Golem large-repo data-flow safeguards apply.",
+    type: "number",
+  })
+  .option("golem-dataflow-max-function-instructions", {
+    description:
+      "Skip Golem per-function data-flow materialization above this SSA instruction count in large repos.",
+    type: "number",
+  })
+  .option("golem-dataflow-max-trace-nodes", {
+    description: "Maximum ordered Golem data-flow node IDs retained per trace.",
+    type: "number",
+  })
+  .option("golem-dataflow-max-trace-edges", {
+    description: "Maximum ordered Golem data-flow edge IDs retained per trace.",
+    type: "number",
+  })
+  .option("golem-dataflow-skip-generated", {
+    description: "Skip generated files during Golem data-flow analysis.",
+    type: "boolean",
+  })
+  .option("golem-dataflow-skip-tests", {
+    description:
+      "Skip test/example/benchmark files during Golem data-flow analysis.",
+    type: "boolean",
+  })
+  .option("golem-max-procs", {
+    description:
+      "Maximum Go scheduler threads for Golem. Defaults to a capped CPU count when data-flow is enabled.",
+    type: "number",
+  })
+  .option("golem-memory-limit", {
+    description: "Optional Golem Go soft memory limit such as 4GiB or 800MiB.",
+  })
+  .option("golem-progress", {
+    description: "Emit coarse Golem progress logs to stderr during analysis.",
+    default: false,
+    type: "boolean",
+  })
+  .option("golem-patterns", {
+    description: "Comma-separated go/packages patterns for golem.",
+    default: "./...",
+  })
+  .option("golem-tags", {
+    description: "Comma-separated Go build tags for golem.",
+  })
+  .option("golem-tests", {
+    description: "Include Go test variants in golem analysis.",
+    default: false,
+    type: "boolean",
+  })
+  .option("rusi-command", {
+    description: "Use a specific rusi binary for Rust Evinse analysis.",
+    default: readEnvironmentVariable("RUSI_CMD"),
+  })
+  .option("rusi-mode", {
+    description: "Rusi analysis mode.",
+    choices: ["analyze", "cryptos"],
+    default: "analyze",
+  })
+  .option("rusi-backend", {
+    description: "Rusi analysis backend.",
+    choices: ["stable", "compiler"],
+    default: "stable",
+  })
+  .option("rusi-toolchain", {
+    description:
+      "Rust toolchain for the Rusi compiler backend (e.g., auto, nightly, stable).",
+    default: "auto",
+  })
+  .option("rusi-callgraph", {
+    description: "Rusi call graph mode.",
+    choices: ["none", "static"],
+    default: "static",
+  })
+  .option("rusi-dataflow", {
+    description:
+      "Rusi data-flow mode. Defaults to security with --with-data-flow, research profile, or --deep, and none otherwise.",
+    choices: ["none", "security", "security-deps"],
+  })
+  .option("rusi-patterns", {
+    description: "Custom Rusi data-flow pattern JSON file.",
+  })
+  .option("force", {
+    description: "Force creation of the database",
+    default: false,
+    type: "boolean",
+  })
+  .option("skip-maven-collector", {
+    description:
+      "Skip collecting jars from maven and gradle caches. Can speedup re-runs if the data was cached previously.",
+    default: false,
+    type: "boolean",
+  })
+  .option("with-deep-jar-collector", {
+    description:
+      "Enable collection of all jars from maven cache directory. Useful to improve the recall for callstack evidence.",
+    default: false,
+    type: "boolean",
+  })
+  .option("annotate", {
+    description: "Include contents of atom slices as annotations",
+    default: false,
+    type: "boolean",
+  })
+  .option("with-data-flow", {
+    description: "Enable inter-procedural data-flow slicing.",
+    default: false,
+    type: "boolean",
+  })
+  .option("with-reachables", {
+    description:
+      "Enable auto-tagged reachable slicing. Requires SBOM generated with --deep mode.",
+    default: false,
+    type: "boolean",
+  })
+  .option("exclude", {
+    alias: "exclude-regex",
+    description:
+      "Additional glob pattern(s) to ignore during Atom evidence generation.",
+    nargs: 1,
+    type: "array",
+  })
+  .option("no-ignore", {
+    type: "boolean",
+    default: false,
+    description: "Disable default ignore lists during scanning.",
+  })
+  .option("usages-slices-file", {
+    description: "Use an existing usages slices file.",
+    default: "usages.slices.json",
+  })
+  .option("data-flow-slices-file", {
+    description: "Use an existing data-flow slices file.",
+    default: "data-flow.slices.json",
+  })
+  .option("reachables-slices-file", {
+    description: "Use an existing reachables slices file.",
+    default: "reachables.slices.json",
+  })
+  .option("semantics-slices-file", {
+    description: "Use an existing semantics slices file.",
+    default: "semantics.slices.json",
+  })
+  .option("openapi-spec-file", {
+    description: "Use an existing openapi specification file (SaaSBOM).",
+    default: "openapi.json",
+  })
+  .option("print", {
+    alias: "p",
+    type: "boolean",
+    description: "Print the evidences as table",
+  })
+  .example([
+    [
+      "$0 -i bom.json -o bom.evinse.json -l java .",
+      "Generate a Java SBOM with evidence for the current directory",
+    ],
+    [
+      "$0 -i bom.json -o bom.evinse.json -l java --with-reachables .",
+      "Generate a Java SBOM with occurrence and reachable evidence for the current directory",
+    ],
+    [
+      "$0 -i bom.json -o bom.evinse.json -l rust --with-data-flow --rusi-backend compiler .",
+      "Generate a Rust SBOM with Rusi data-flow and compiler-backed evidence",
+    ],
+  ])
+  .completion("completion", "Generate bash/zsh completion")
+  .epilogue("for documentation, visit https://cdxgen.github.io/cdxgen")
+  .scriptName("evinse")
+  .version()
+  .help("h")
+  .alias("h", "help")
+  .wrap(Math.min(120, yargs().terminalWidth())).argv;
+
+const evinseArt = `
+███████╗██╗   ██╗██╗███╗   ██╗███████╗███████╗
+██╔════╝██║   ██║██║████╗  ██║██╔════╝██╔════╝
+█████╗  ██║   ██║██║██╔██╗ ██║███████╗█████╗
+██╔══╝  ╚██╗ ██╔╝██║██║╚██╗██║╚════██║██╔══╝
+███████╗ ╚████╔╝ ██║██║ ╚████║███████║███████╗
+╚══════╝  ╚═══╝  ╚═╝╚═╝  ╚═══╝╚══════╝╚══════╝
+`;
+
+if (readEnvironmentVariable("CDXGEN_NODE_OPTIONS")) {
+  process.env.NODE_OPTIONS = `${process.env.NODE_OPTIONS || ""} ${process.env.CDXGEN_NODE_OPTIONS}`;
+}
+
+console.log(evinseArt);
+function ensureCycloneDxInput(inputFile) {
+  if (!safeExistsSync(inputFile)) {
+    return;
+  }
+  let bomJson;
+  try {
+    bomJson = JSON.parse(fs.readFileSync(inputFile, "utf8"));
+  } catch (error) {
+    console.error(`Unable to parse '${inputFile}' as JSON: ${error.message}`);
+    process.exit(1);
+  }
+  if (!isCycloneDxBom(bomJson)) {
+    console.error(getNonCycloneDxErrorMessage(bomJson, "evinse"));
+    process.exit(1);
+  }
+}
+ensureCycloneDxInput(args.input);
+(async () => {
+  // First, prepare the database by cataloging jars and other libraries
+  const dbObjMap = await prepareDB(args);
+  if (dbObjMap) {
+    // Analyze the project using atom. Convert package namespaces to purl using the db
+    const sliceArtefacts = await analyzeProject(dbObjMap, args);
+    // Create the SBOM with Evidence
+    const bomJson = createEvinseFile(sliceArtefacts, args);
+    // Validate our final SBOM
+    if (!(await validateBom(bomJson))) {
+      process.exit(1);
+    }
+    if (args.print) {
+      printOccurrences(bomJson);
+      printCallStack(bomJson);
+      printReachables(sliceArtefacts);
+      printServices(bomJson);
+    }
+  }
+})();