@cdxgen/cdxgen 13.1.0 → 13.3.0

package/bin/cdxgen.js

@@ -19,6 +19,7 @@ import { parse as _load } from "yaml";
 import yargs from "yargs";
 import { hideBin } from "yargs/helpers";
 
+import { getExactAiInventoryType } from "../lib/cli/bomAssembly.js";
 import {
   applyAdvancedOptions as applyAdvancedOptionsImpl,
   buildOptionsFromArgs,
@@ -71,7 +72,11 @@ import {
   setDryRunMode,
   shouldRunPredictiveBomAudit,
 } from "../lib/ecosystems/utils.js";
-import { signBom, verifyBom } from "../lib/helpers/bomSigner.js";
+import {
+  generateSigningKeyPair,
+  signBom,
+  verifyBom,
+} from "../lib/helpers/bomSigner.js";
 import {
   createOutputPlan,
   getOutputDirectory,
@@ -80,7 +85,6 @@ import {
   DEFAULT_CDX_SPEC_VERSION,
   getSupportedCycloneDxComponentTypes,
   isCycloneDxBom,
-  isCycloneDxComponentTypeEnabled,
   normalizeCycloneDxComponentTypeFilter,
   toCycloneDxSpecVersionString,
 } from "../lib/inventory/bomUtils.js";
@@ -123,7 +127,10 @@ import {
 } from "../lib/inventory/source.js";
 import { executeOsQuery } from "../lib/managers/binary.js";
 import { getBomWithOras } from "../lib/managers/oci.js";
-import { postProcess } from "../lib/stages/postgen/postgen.js";
+import {
+  applyEvidenceBasedFilter,
+  postProcess,
+} from "../lib/stages/postgen/postgen.js";
 import { convertCycloneDxToSpdx } from "../lib/stages/postgen/spdxConverter.js";
 import { auditEnvironment } from "../lib/stages/pregen/envAudit.js";
 import { prepareEnv } from "../lib/stages/pregen/pregen.js";
@@ -160,6 +167,11 @@ for (const configPattern of PROJECT_CONFIG_FILENAMES) {
         `Config file '${configPath}' sets '${foundKey}'. Verify this is intentional.`,
       );
     }
+    for (const propertyName of sanitized.reservedProperties) {
+      console.warn(
+        `\x1b[1;35mConfig file '${configPath}' sets the metadata property '${propertyName}', whose namespace cdxgen reserves for its own findings. Ignoring it. Pass the property with --metadata-property if this is intentional.\x1b[0m`,
+      );
+    }
   } catch (_e) {
     console.log("Invalid config file", configPath);
   }
@@ -248,6 +260,16 @@ const args = _yargs
     description:
       "Perform deep searches for components. Useful while scanning C/C++ apps, live OS and oci images.",
   })
+  .option("cmake-cache", {
+    type: "string",
+    description:
+      "Path to the CMakeCache.txt of a configured C/C++ build. Overrides the lookup under build/, out/ and cmake-build-*/.",
+  })
+  .option("compile-commands", {
+    type: "string",
+    description:
+      "Path to the compile_commands.json of a C/C++ build, or a directory holding one. atom then parses each file with its build's include paths, macros and language. Overrides the lookup in the project root, build/, out/, builddir/ and cmake-build-*/, which is skipped in secure mode.",
+  })
   .option("git-branch", {
     description: "Git branch to clone when the source is a git URL or purl",
     type: "string",
@@ -395,7 +417,7 @@ const args = _yargs
   .option("generate-key-and-sign", {
     type: "boolean",
     description:
-      "Generate an RSA public/private key pair and then sign the generated SBOM using JSON Web Signatures.",
+      "Generate a public/private key pair for SBOM_SIGN_ALGORITHM (RS512 by default) and then sign the generated SBOM using the JSON Signature Format (JSF).",
   })
   .option("server", {
     type: "boolean",
@@ -561,6 +583,11 @@ const args = _yargs
     default: false,
     description: "Disable default ignore lists during scanning.",
   })
+  .option("caxa-app-dir", {
+    type: "string",
+    description:
+      "Directory of the app a caxa binary extracts. With -t caxa, also records the native tools, the vendored PHP, Ruby and Java packages, and the npm integrity hashes found there.",
+  })
   .option("export-proto", {
     type: "boolean",
     default: false,
@@ -601,6 +628,12 @@ const args = _yargs
     default: false,
     description: "Synthesize custom LicenseRef IDs for unresolved licenses.",
   })
+  .option("metadata-property", {
+    description:
+      "Custom property to add to the BOM metadata, as name=value. Repeat the flag for several properties. Combined with the properties of the CDXGEN_METADATA_PROPERTIES environment variable and of a config file.",
+    nargs: 1,
+    type: "array",
+  })
   .option("standard", {
     description:
       "The list of standards which may consist of regulations, industry or organizational-specific standards, maturity models, best practices, or any other requirements which can be evaluated against or attested to.",
@@ -1043,6 +1076,7 @@ const { options, warnings: phase3Warnings } = buildOptionsFromArgs(args, {
   userSetSpecVersion,
   isDryRun,
   isSecureMode,
+  projectConfig: config,
 });
 // Exit status reserved for the introspection CI gate: the BOM was generated
 // and written, but its introspection score missed the configured threshold.
@@ -1406,6 +1440,8 @@ const checkPermissions = (filePath, options) => {
   return true;
 };
 
+let warnedAboutSigningAlgorithm = false;
+
 const needsBomSigning = ({ generateKeyAndSign }) =>
   generateKeyAndSign ||
   (() => {
@@ -1423,11 +1459,19 @@ const needsBomSigning = ({ generateKeyAndSign }) =>
         sensitive: true,
       },
     );
-    return (
-      sbomSignAlgorithm &&
-      sbomSignAlgorithm !== "none" &&
-      ((sbomSignPrivateKey && safeExistsSync(sbomSignPrivateKey)) ||
-        sbomSignPrivateKeyBase64)
+    const keyConfigured = Boolean(
+      sbomSignPrivateKey || sbomSignPrivateKeyBase64,
+    );
+    if (keyConfigured && !sbomSignAlgorithm && !warnedAboutSigningAlgorithm) {
+      warnedAboutSigningAlgorithm = true;
+      console.warn(
+        "SBOM_SIGN_PRIVATE_KEY is set without SBOM_SIGN_ALGORITHM, so the BOM is not signed. Set SBOM_SIGN_ALGORITHM (for example RS512) to sign it, or SBOM_SIGN_ALGORITHM=none to silence this warning.",
+      );
+    }
+    // A configured key file that is missing counts as a signing request, so
+    // that signing fails loudly instead of being skipped.
+    return Boolean(
+      sbomSignAlgorithm && sbomSignAlgorithm !== "none" && keyConfigured,
     );
   })();
 
@@ -1436,28 +1480,20 @@ const stringifyJson = (jsonPayload, jsonPretty) =>
     ? jsonPayload
     : JSON.stringify(jsonPayload, null, jsonPretty ? 2 : null);
 
-const writeCycloneDxOutput = (jsonFile, bomJson, options) => {
-  const jsonPayload = stringifyJson(bomJson, options.jsonPretty);
-  safeWriteSync(jsonFile, jsonPayload);
-  if (jsonFile.endsWith("bom.json")) {
-    thoughtLog(
-      `Let's save the file to "${jsonFile}". Should I suggest the '.cdx.json' file extension for better semantics?`,
-    );
-  } else {
-    thoughtLog(`Let's save the file to "${jsonFile}".`);
-  }
-  if (!jsonPayload || !needsBomSigning(options)) {
-    return jsonPayload;
-  }
-  if (isDryRun) {
-    recordActivity({
-      kind: "sign",
-      reason: "Dry run mode skips BOM signing and key generation.",
-      status: "blocked",
-      target: jsonFile,
-    });
-    return jsonPayload;
-  }
+const SIGNING_HINT =
+  "Check that the private key is in PEM format and that SBOM_SIGN_ALGORITHM matches its key type.";
+
+/**
+ * Signs a CycloneDX payload with the configured or generated key.
+ *
+ * @param {string} jsonPayload Serialized CycloneDX BOM
+ * @param {string|undefined} keyDir Directory for --generate-key-and-sign keys
+ * @param {string} target Output the signed BOM is written to (for the activity log)
+ * @param {Object} options CLI options
+ * @returns {Object} Signed BOM
+ * @throws {Error} When signing was requested but cannot be completed
+ */
+const signCycloneDxPayload = (jsonPayload, keyDir, target, options) => {
   const sbomSignAlgorithm = readEnvironmentVariable("SBOM_SIGN_ALGORITHM");
   const sbomSignPrivateKey = readEnvironmentVariable("SBOM_SIGN_PRIVATE_KEY", {
     sensitive: true,
@@ -1472,29 +1508,20 @@ const writeCycloneDxOutput = (jsonFile, bomJson, options) => {
   const sbomSignPublicKeyBase64 = readEnvironmentVariable(
     "SBOM_SIGN_PUBLIC_KEY_BASE64",
   );
-  let alg = sbomSignAlgorithm || "RS512";
-  if (alg.includes("none")) {
-    alg = "RS512";
-  }
+  const alg = sbomSignAlgorithm || "RS512";
   let privateKeyToUse;
   let jwkPublicKey;
   let publicKeyFile;
   if (options.generateKeyAndSign) {
-    const jdirName = dirname(jsonFile);
-    publicKeyFile = join(jdirName, "public.key");
-    const privateKeyFile = join(jdirName, "private.key");
-    const privateKeyB64File = join(jdirName, "private.key.base64");
-    const { privateKey, publicKey } = crypto.generateKeyPairSync("rsa", {
-      modulusLength: 4096,
-      publicKeyEncoding: {
-        type: "spki",
-        format: "pem",
-      },
-      privateKeyEncoding: {
-        type: "pkcs8",
-        format: "pem",
-      },
-    });
+    if (!keyDir) {
+      throw new Error(
+        "--generate-key-and-sign needs a file output (-o) to write the generated keys next to.",
+      );
+    }
+    publicKeyFile = join(keyDir, "public.key");
+    const privateKeyFile = join(keyDir, "private.key");
+    const privateKeyB64File = join(keyDir, "private.key.base64");
+    const { privateKey, publicKey } = generateSigningKeyPair(alg);
     safeWriteSync(publicKeyFile, publicKey);
     safeWriteSync(privateKeyFile, privateKey);
     safeWriteSync(
@@ -1511,69 +1538,129 @@ const writeCycloneDxOutput = (jsonFile, bomJson, options) => {
     jwkPublicKey = crypto.createPublicKey(publicKey).export({ format: "jwk" });
   } else {
     if (sbomSignPrivateKey) {
+      if (!safeExistsSync(sbomSignPrivateKey)) {
+        throw new Error(
+          `The SBOM_SIGN_PRIVATE_KEY file '${sbomSignPrivateKey}' was not found.`,
+        );
+      }
       recordSensitiveFileRead(sbomSignPrivateKey, {
         label: "SBOM signing private key",
       });
-      privateKeyToUse = fs.readFileSync(sbomSignPrivateKey, "utf8");
+      privateKeyToUse = fs.readFileSync(sbomSignPrivateKey);
     } else if (sbomSignPrivateKeyBase64) {
-      privateKeyToUse = Buffer.from(
-        sbomSignPrivateKeyBase64,
-        "base64",
-      ).toString("utf8");
+      privateKeyToUse = Buffer.from(sbomSignPrivateKeyBase64, "base64");
     }
     if (sbomSignPublicKey && safeExistsSync(sbomSignPublicKey)) {
       jwkPublicKey = crypto
         .createPublicKey(fs.readFileSync(sbomSignPublicKey, "utf8"))
         .export({ format: "jwk" });
     } else if (sbomSignPublicKeyBase64) {
-      jwkPublicKey = Buffer.from(sbomSignPublicKeyBase64, "base64").toString(
-        "utf8",
+      jwkPublicKey = crypto
+        .createPublicKey(Buffer.from(sbomSignPublicKeyBase64, "base64"))
+        .export({ format: "jwk" });
+    }
+  }
+  thoughtLog(`Signing the BOM for "${target}".`);
+  const signedBom = signBom(JSON.parse(jsonPayload), {
+    privateKey: privateKeyToUse,
+    algorithm: alg,
+    publicKeyJwk: jwkPublicKey,
+    mode: readEnvironmentVariable("SBOM_SIGN_MODE") || "replace",
+    signComponents: true,
+    signServices: true,
+    signAnnotations: true,
+  });
+  if (publicKeyFile) {
+    if (!verifyBom(signedBom, fs.readFileSync(publicKeyFile, "utf8"))) {
+      throw new Error(
+        `The new signature does not verify with ${publicKeyFile}.`,
       );
     }
+    console.log(
+      "SBOM signature is verifiable natively with the public key and the algorithm",
+      publicKeyFile,
+      alg,
+    );
+  }
+  recordActivity({
+    kind: "sign",
+    status: "completed",
+    target,
+  });
+  return signedBom;
+};
+
+/**
+ * Signs the BOM for an output when signing is configured. A failure is
+ * recorded and returned so that the caller can stop with a non-zero exit
+ * instead of publishing an unsigned BOM.
+ *
+ * @returns {{ bomJson: Object, jsonPayload: string, signingError?: Error }}
+ */
+const signForOutput = (bomJson, jsonPayload, keyDir, target, options) => {
+  if (!jsonPayload || !needsBomSigning(options)) {
+    return { bomJson, jsonPayload };
+  }
+  if (isDryRun) {
+    recordActivity({
+      kind: "sign",
+      reason: "Dry run mode skips BOM signing and key generation.",
+      status: "blocked",
+      target,
+    });
+    return { bomJson, jsonPayload };
   }
   try {
-    const bomJsonUnsignedObj = JSON.parse(jsonPayload);
-    const signOptions = {
-      privateKey: privateKeyToUse,
-      algorithm: alg,
-      publicKeyJwk: jwkPublicKey,
-      mode: readEnvironmentVariable("SBOM_SIGN_MODE") || "replace",
-      signComponents: true,
-      signServices: true,
-      signAnnotations: true,
+    const signedBom = signCycloneDxPayload(
+      jsonPayload,
+      keyDir,
+      target,
+      options,
+    );
+    return {
+      bomJson: signedBom,
+      jsonPayload: JSON.stringify(
+        signedBom,
+        null,
+        options.jsonPretty ? 2 : null,
+      ),
     };
-    thoughtLog(`Signing the BOM file "${jsonFile}".`);
+  } catch (err) {
     recordActivity({
       kind: "sign",
-      status: "completed",
-      target: jsonFile,
+      reason: err.message,
+      status: "failed",
+      target,
     });
-    const signedBom = signBom(bomJsonUnsignedObj, signOptions);
-    safeWriteSync(
-      jsonFile,
-      JSON.stringify(signedBom, null, options.jsonPretty ? 2 : null),
-    );
-    if (publicKeyFile) {
-      const publicKeyStr = fs.readFileSync(publicKeyFile, "utf8");
-      const signatureVerification = verifyBom(signedBom, publicKeyStr);
-      if (signatureVerification) {
-        console.log(
-          "SBOM signature is verifiable natively with the public key and the algorithm",
-          publicKeyFile,
-          alg,
-        );
-      } else {
-        console.log("SBOM signature verification was unsuccessful");
-        console.log("Check if the public key was exported in PEM format");
-      }
-    }
-  } catch (ex) {
-    console.log("SBOM signing was unsuccessful:", ex.message);
-    console.log(
-      "Check if the private key was exported in PEM format and the algorithm is JSF-compliant.",
+    return { bomJson, jsonPayload, signingError: err };
+  }
+};
+
+const reportSigningFailure = (signingError, target) => {
+  console.error(`SBOM signing was unsuccessful: ${signingError.message}`);
+  console.error(SIGNING_HINT);
+  if (target !== "stdout") {
+    console.error(`The BOM at '${target}' was written without a signature.`);
+  }
+};
+
+const writeCycloneDxOutput = (jsonFile, bomJson, options) => {
+  const result = signForOutput(
+    bomJson,
+    stringifyJson(bomJson, options.jsonPretty),
+    dirname(jsonFile),
+    jsonFile,
+    options,
+  );
+  safeWriteSync(jsonFile, result.jsonPayload);
+  if (jsonFile.endsWith("bom.json")) {
+    thoughtLog(
+      `Let's save the file to "${jsonFile}". Should I suggest the '.cdx.json' file extension for better semantics?`,
     );
+  } else {
+    thoughtLog(`Let's save the file to "${jsonFile}".`);
   }
-  return jsonPayload;
+  return result;
 };
 
 /**
@@ -1601,7 +1688,14 @@ const writeCycloneDxOutput = (jsonFile, bomJson, options) => {
   }
   let sourcePath = filePath;
   let purlResolution;
-  const directHuggingFaceSource = normalizeHuggingFaceReference(sourcePath);
+  // Direct HuggingFace interpretation of the source path is opt-in: bare
+  // `owner/repo`-shaped values are ordinary relative paths (eg: repotests/
+  // sveltejs-realworld) unless an AI inventory type such as `-t ai` is
+  // explicitly selected. Unambiguous purls and huggingface.co URLs always
+  // resolve.
+  const directHuggingFaceSource = normalizeHuggingFaceReference(sourcePath, {
+    explicitOnly: getExactAiInventoryType(options) !== "ai",
+  });
   if (isDryRun && directHuggingFaceSource) {
     recordActivity({
       kind: "read",
@@ -2044,27 +2138,11 @@ const writeCycloneDxOutput = (jsonFile, bomJson, options) => {
       });
       const evinserModule = await import("../lib/evinser/evinser.js");
       options.projectType = options.projectType || ["java"];
-      const evinseOptions = {
-        _: args._,
-        input: internalCycloneDxInputPath || options.output,
-        output: options.evinseOutput,
-        language: options.projectType,
-        skipMavenCollector: false,
-        force: false,
-        withReachables: options.deep,
-        usagesSlicesFile: options.usagesSlicesFile,
-        dataFlowSlicesFile: options.dataFlowSlicesFile,
-        reachablesSlicesFile: options.reachablesSlicesFile,
-        semanticsSlicesFile: options.semanticsSlicesFile,
-        openapiSpecFile: options.openapiSpecFile,
-        componentType: options.componentType,
-        includeCrypto:
-          options.includeCrypto &&
-          isCycloneDxComponentTypeEnabled("cryptographic-asset", options),
-        specVersion: options.specVersion,
-        profile: options.profile,
-        jsonPretty: options.jsonPretty,
-      };
+      const evinseOptions = evinserModule.buildEvinseOptions(
+        options,
+        args,
+        internalCycloneDxInputPath || options.output,
+      );
       const dbObjMap = await evinserModule.prepareDB(evinseOptions);
       if (dbObjMap) {
         const sliceArtefacts = await evinserModule.analyzeProject(
@@ -2075,7 +2153,9 @@ const writeCycloneDxOutput = (jsonFile, bomJson, options) => {
           sliceArtefacts,
           evinseOptions,
         );
-        bomNSData.bomJson = evinseJson;
+        // The scope filter is deferred until here so the analyzers get to
+        // prove that an optional dependency is actually used.
+        bomNSData.bomJson = applyEvidenceBasedFilter(evinseJson, options);
         if (options.print && evinseJson) {
           printOccurrences(evinseJson);
           printCallStack(evinseJson);
@@ -2151,10 +2231,27 @@ const writeCycloneDxOutput = (jsonFile, bomJson, options) => {
   }
   if (outputIsStdout) {
     if (!isDryRun && bomNSData.bomJson) {
-      const payload =
-        outputPlan.formats.has("spdx") && bomNSData.spdxJson
-          ? stringifyJson(bomNSData.spdxJson, options.jsonPretty)
-          : stringifyJson(bomNSData.bomJson, options.jsonPretty);
+      let payload;
+      if (outputPlan.formats.has("spdx") && bomNSData.spdxJson) {
+        payload = stringifyJson(bomNSData.spdxJson, options.jsonPretty);
+      } else {
+        const result = signForOutput(
+          bomNSData.bomJson,
+          stringifyJson(bomNSData.bomJson, options.jsonPretty),
+          undefined,
+          "stdout",
+          options,
+        );
+        if (result.signingError) {
+          reportSigningFailure(result.signingError, "stdout");
+          if (cleanup) {
+            cleanupSourceDir(srcDir);
+          }
+          process.exit(1);
+        }
+        bomNSData.bomJson = result.bomJson;
+        payload = result.jsonPayload;
+      }
       process.stdout.write(payload);
     } else if (isDryRun) {
       recordActivity({
@@ -2169,11 +2266,20 @@ const writeCycloneDxOutput = (jsonFile, bomJson, options) => {
     (typeof options.output === "string" || options.output instanceof String)
   ) {
     if (!isDryRun && outputPlan.outputs.cyclonedx && bomNSData.bomJson) {
-      writeCycloneDxOutput(
+      const result = writeCycloneDxOutput(
         outputPlan.outputs.cyclonedx,
         bomNSData.bomJson,
         options,
       );
+      if (result.signingError) {
+        reportSigningFailure(result.signingError, outputPlan.outputs.cyclonedx);
+        if (cleanup) {
+          cleanupSourceDir(srcDir);
+        }
+        process.exit(1);
+      }
+      // Later consumers, such as the Dependency-Track upload, get the signed BOM.
+      bomNSData.bomJson = result.bomJson;
       if (bomNSData.nsMapping && Object.keys(bomNSData.nsMapping).length) {
         const nsFile = `${outputPlan.outputs.cyclonedx}.map`;
         safeWriteSync(nsFile, JSON.stringify(bomNSData.nsMapping));
@@ -2204,7 +2310,22 @@ const writeCycloneDxOutput = (jsonFile, bomJson, options) => {
     if (outputPlan.formats.has("spdx") && bomNSData?.spdxJson) {
       console.log(stringifyJson(bomNSData.spdxJson, options.jsonPretty));
     } else if (bomNSData.bomJson) {
-      console.log(stringifyJson(bomNSData.bomJson, options.jsonPretty));
+      const result = signForOutput(
+        bomNSData.bomJson,
+        stringifyJson(bomNSData.bomJson, options.jsonPretty),
+        undefined,
+        "stdout",
+        options,
+      );
+      if (result.signingError) {
+        reportSigningFailure(result.signingError, "stdout");
+        if (cleanup) {
+          cleanupSourceDir(srcDir);
+        }
+        process.exit(1);
+      }
+      bomNSData.bomJson = result.bomJson;
+      console.log(result.jsonPayload);
     } else {
       console.log("Unable to produce BOM for", filePath);
       console.log("Try running the command with -t <type> or -r argument");

package/bin/evinse.js

@@ -45,6 +45,8 @@ const args = yargs(hideBin(process.argv))
     choices: [
       "java",
       "jar",
+      "kotlin",
+      "kt",
       "js",
       "ts",
       "javascript",
@@ -87,6 +89,11 @@ const args = yargs(hideBin(process.argv))
     default: false,
     type: "boolean",
   })
+  .option("compile-commands", {
+    description:
+      "Path to the compile_commands.json of a C/C++ build, or a directory holding one, for atom to parse each file as its build does. Overrides the lookup in the project root, build/, out/, builddir/ and cmake-build-*/, which is skipped in secure mode.",
+    type: "string",
+  })
   .option("golem-command", {
     description: "Use a specific golem binary for Go Evinse analysis.",
     default: readEnvironmentVariable("GOLEM_CMD"),