@cdxgen/cdxgen 13.5.0 → 13.7.0

package/lib/audit/index.js

@@ -30,6 +30,10 @@ import {
   getNonCycloneDxErrorMessage,
   isCycloneDxBom,
 } from "../inventory/bomUtils.js";
+import {
+  formatReadLossNotice,
+  loadBomForAnalysis,
+} from "../inventory/cyclonedx20.js";
 import {
   collectPolicyViolations,
   loadPolicy,
@@ -122,10 +126,14 @@ const PYTHON_OBFUSCATION_PATTERN =
 const PYTHON_SETUP_CMDCLASS_PATTERN = /\bcmdclass\s*=/i;
 
 /**
- * Read and validate a CycloneDX BOM file.
+ * Read and validate a CycloneDX BOM file. A CycloneDX 2.0 document is read
+ * into cdxgen's internal 1.x-shaped model, so the audit rules keep reading
+ * `components`, `bom-ref` and `metadata.component`; the number of losses
+ * the read reported is printed once on stderr, with the details in
+ * thoughtLog.
  *
  * @param {string} bomPath BOM file path
- * @returns {object} parsed CycloneDX BOM
+ * @returns {object} parsed CycloneDX BOM in the 1.x shape
  */
 export function loadBomFile(bomPath) {
   const resolvedPath = resolve(bomPath);
@@ -138,7 +146,21 @@ export function loadBomFile(bomPath) {
   if (!isCycloneDxBom(bomJson)) {
     throw new Error(getNonCycloneDxErrorMessage(bomJson, "cdx-audit"));
   }
-  return bomJson;
+  let analysis;
+  try {
+    analysis = loadBomForAnalysis(bomJson);
+  } catch (error) {
+    throw new Error(`Failed to read ${resolvedPath}: ${error.message}`);
+  }
+  const { internalBom, losses } = analysis;
+  if (losses.length) {
+    // stderr: stdout carries the --report json/sarif payload.
+    console.warn(formatReadLossNotice(losses));
+    for (const loss of losses) {
+      thoughtLog(`cdx-audit 2.0 loss at ${loss.pointer}: ${loss.reason}`);
+    }
+  }
+  return internalBom;
 }
 
 /**

package/lib/cli/bomAssembly.js

@@ -25,6 +25,7 @@ import {
   CDXGEN_VERSION,
   frameworksList,
 } from "../core/state.js";
+import { getExecutedTools } from "../core/toolRegistry.js";
 import {
   isPkgTypeOnlyImport,
   setNpmCleanedVersionProperty,
@@ -60,7 +61,7 @@ import {
 } from "../inventory/purl.js";
 import { repairPurl } from "../inventory/sbomDocument.js";
 import { getLicenses } from "../inventory/spdx.js";
-import { getBinaryBom } from "../managers/binary.js";
+import { getBinaryBom, getPluginToolComponents } from "../managers/binary.js";
 import { isValidIriReference } from "../parsers/iri.js";
 
 /**
@@ -293,10 +294,85 @@ function anchorDetectedParent(
   return anchored;
 }
 
+/**
+ * Builds the tool components for the external helpers and build tools this
+ * run executed, from the run-scoped registry (issue #598). Bundled plugin
+ * helpers are enriched with the manifest component of the plugin package that
+ * ships them, so the plugin package's version and identity travel with the
+ * helper. Empty when the run spawned nothing external, which keeps such BOMs
+ * byte-identical to the previous behaviour.
+ *
+ * @returns {object[]} Sorted CycloneDX tool components
+ */
+export const buildExternalToolComponents = () => {
+  const recordedTools = getExecutedTools();
+  if (!recordedTools.length) {
+    return [];
+  }
+  const recordedNames = recordedTools.map((tool) => tool.name);
+  const pluginComponents = getPluginToolComponents(recordedNames);
+  const pluginByName = new Map(
+    pluginComponents.map((component) => [component.name, component]),
+  );
+  const components = [];
+  for (const tool of recordedTools) {
+    const pluginComponent = pluginByName.get(tool.name);
+    if (pluginComponent?.["bom-ref"]) {
+      components.push(pluginComponent);
+      continue;
+    }
+    const component = {
+      type: "application",
+      name: tool.name,
+    };
+    if (tool.version) {
+      component.version = tool.version;
+    }
+    components.push(component);
+  }
+  return components;
+};
+
+/**
+ * Drops the executed tools that are already present: a tool whose bom-ref or
+ * name matches an explicitly passed context tool, or whose bom-ref an earlier
+ * executed tool already carries (several bundled helpers can share one plugin
+ * package component). The context tools themselves are never touched.
+ *
+ * @param {object[]} contextTools Tool components passed in by the caller
+ * @param {object[]} executedTools Tool components from the run's registry
+ * @returns {object[]} The executed tools to append
+ */
+const newExecutedTools = (contextTools, executedTools) => {
+  const seenRefs = new Set();
+  const seenNames = new Set();
+  for (const component of contextTools) {
+    if (component?.["bom-ref"]) {
+      seenRefs.add(component["bom-ref"]);
+    }
+    if (component?.name) {
+      seenNames.add(component.name);
+    }
+  }
+  const unique = [];
+  for (const component of executedTools) {
+    const ref = component["bom-ref"];
+    if ((ref && seenRefs.has(ref)) || seenNames.has(component.name)) {
+      continue;
+    }
+    if (ref) {
+      seenRefs.add(ref);
+    }
+    unique.push(component);
+  }
+  return unique;
+};
+
 /**
  * Assembles the `metadata.tools` block, including the cdxgen tool entry and,
  * for spec versions prior to 1.5, the legacy tools array. For spec version
- * 1.6+ the author field is converted to the authors array.
+ * 1.6+ the author field is converted to the authors array. The tools this run
+ * executed follow the context tools, sorted by name, and cdxgen comes last.
  *
  * @param {object} options CLI options
  * @param {object} [context={}] Additional context carrying existing components
@@ -304,6 +380,7 @@ function anchorDetectedParent(
  *   tools array (1.4) or a components array with tool components (1.5+)
  */
 export const addToolsSection = (options, context = {}) => {
+  const externalTools = buildExternalToolComponents();
   if (options.specVersion === 1.4) {
     return [
       {
@@ -311,6 +388,11 @@ export const addToolsSection = (options, context = {}) => {
         name: "cdxgen",
         version: CDXGEN_VERSION,
       },
+      ...newExecutedTools([], externalTools).map((tool) =>
+        tool.version
+          ? { name: tool.name, version: tool.version }
+          : { name: tool.name },
+      ),
     ];
   }
   let components = [];
@@ -331,6 +413,7 @@ export const addToolsSection = (options, context = {}) => {
   } else if (tools && Object.keys(tools).length && tools.components) {
     components = components.concat(tools.components);
   }
+  components = components.concat(newExecutedTools(components, externalTools));
   const cdxToolComponent = {
     group: CDXGEN_TOOL_GROUP,
     name: CDXGEN_TOOL_NAME,
@@ -524,7 +607,13 @@ export function addMetadata(parentComponent = {}, options = {}, context = {}) {
           // We cannot use purl or bom-ref here since they would not match
           // purl - could have application on one side and a different type
           // bom-ref could have qualifiers on one side
-          if (fullName !== parentFullName) {
+          // A purl subpath marks a separate project that declares the
+          // parent's coordinates, such as a second Maven project or a Gradle
+          // subproject with the same group, name and version.
+          const separateProject =
+            comp.purl?.includes("#") &&
+            comp.purl.split("#")[1] !== parentComponent.purl?.split("#")[1];
+          if (fullName !== parentFullName || separateProject) {
             if (!comp["bom-ref"]) {
               comp["bom-ref"] = `pkg:${comp.type}/${decodeURIComponent(
                 fullName,
@@ -1024,6 +1113,65 @@ export function hasNpmBinCommandEvidence(allImports, pkg) {
   return false;
 }
 
+/**
+ * Return a CycloneDX organisational entity built from a collector-supplied
+ * supplier or manufacturer, or undefined when the value is not a well-formed
+ * entity.
+ *
+ * An entity needs a non-empty string name. When a url is present it must be
+ * an array of valid IRI references; any other shape (a single string, an
+ * array holding non-strings) drops the entity so the BOM stays schema
+ * valid. Each contact is reduced to its string name, email and phone, and a
+ * contact with none of them is left out. The entity bom-ref is not copied,
+ * because CycloneDX 1.4 does not allow it there.
+ *
+ * @param {Object} entity Collector-supplied organisational entity
+ * @returns {Object|undefined} Organisational entity, or undefined
+ */
+export function toOrganizationalEntity(entity) {
+  if (!entity || typeof entity !== "object" || Array.isArray(entity)) {
+    return undefined;
+  }
+  if (typeof entity.name !== "string" || !entity.name.trim().length) {
+    return undefined;
+  }
+  const result = { name: entity.name.trim() };
+  if (entity.url !== undefined) {
+    if (
+      !Array.isArray(entity.url) ||
+      !entity.url.every(
+        (u) => typeof u === "string" && u.length && isValidIriReference(u),
+      )
+    ) {
+      return undefined;
+    }
+    if (entity.url.length) {
+      result.url = [...entity.url];
+    }
+  }
+  if (Array.isArray(entity.contact)) {
+    const contacts = [];
+    for (const contact of entity.contact) {
+      if (!contact || typeof contact !== "object" || Array.isArray(contact)) {
+        continue;
+      }
+      const reduced = {};
+      for (const field of ["name", "email", "phone"]) {
+        if (typeof contact[field] === "string" && contact[field].trim()) {
+          reduced[field] = contact[field].trim();
+        }
+      }
+      if (Object.keys(reduced).length) {
+        contacts.push(reduced);
+      }
+    }
+    if (contacts.length) {
+      result.contact = contacts;
+    }
+  }
+  return result;
+}
+
 /**
  * Given the specified package, create a CycloneDX component and add it to the list.
  */
@@ -1103,7 +1251,9 @@ export function addComponent(
     const description = pkg.description || undefined;
     let compScope = pkg.scope;
     let isTypeOnlyPkg = false;
-    if (allImports) {
+    // addEvidenceForImports flags an installed version that none of the
+    // project's imports resolve to; its name matching an import is no use.
+    if (allImports && !pkg._npmImportsResolveElsewhere) {
       const impPkgs = Object.keys(allImports);
       const hasBinCommandEvidence = hasNpmBinCommandEvidence(allImports, pkg);
       if (
@@ -1192,6 +1342,24 @@ export function addComponent(
       delete component.swhid;
     }
     processHashes(pkg, component);
+    // A collector that resolved the organisations behind a component keeps
+    // them here: the AI collectors record the Hugging Face namespace that
+    // published a model or dataset as the supplier, and the organisation
+    // that created a model as the manufacturer. The supplier is a valid
+    // component field in every spec version cdxgen emits; the manufacturer
+    // arrived in CycloneDX 1.6. Only a well-formed organisational entity is
+    // copied, so a collector that puts a string url or a build string on the
+    // package cannot make the BOM fail schema validation.
+    const supplier = toOrganizationalEntity(pkg.supplier);
+    if (supplier) {
+      component.supplier = supplier;
+    }
+    if (options.specVersion >= 1.6) {
+      const manufacturer = toOrganizationalEntity(pkg.manufacturer);
+      if (manufacturer) {
+        component.manufacturer = manufacturer;
+      }
+    }
     // Upgrade authors section
     if (options.specVersion >= 1.6 && component.author) {
       const authorsList = [];

package/lib/cli/cliOptions.js

@@ -94,20 +94,35 @@ const POST_BUILD_SUPPORTED_PROJECT_TYPES = new Set([
 // ---------------------------------------------------------------------------
 
 /**
- * The formulation privacy notice, shared by every path that turns formulation
- * collection on automatically: the warning about emails and secrets is
- * identical whichever caller adds the section.
+ * The notice for formulation that cdxgen turned on by itself. It names what
+ * turned formulation on, and, when the BOM is submitted to a server, the
+ * warning also names that server, as it does for an explicit
+ * --include-formulation.
  *
+ * @param {object} options The options object
+ * @param {string} reasons What turned formulation on, such as "CI=true"
  * @returns {OptionsWarning} The notice.
  */
-function formulationPrivacyNotice() {
+function autoFormulationNotice(options, reasons) {
+  if (options.serverUrl) {
+    return {
+      level: "warn",
+      message: `WARNING: Automatically collecting formulation information for ${reasons}. The formulation section may include sensitive data such as emails and secrets. This data will be submitted to '${options.serverUrl}' automatically. Pass --no-include-formulation to leave it out.`,
+    };
+  }
   return {
     level: "info",
-    message:
-      "NOTE: Automatically collecting formulation information. The section may include sensitive data such as emails and secrets.\nPlease review the generated SBOM before distribution or LLM training.",
+    message: `NOTE: Automatically collecting formulation information for ${reasons}. The section may include sensitive data such as emails and secrets. Pass --no-include-formulation to leave it out.\nPlease review the generated SBOM before distribution or LLM training.`,
   };
 }
 
+/**
+ * Options objects whose formulation notes were already reported, so the CLI,
+ * which applies the advanced options twice, prints each note once.
+ */
+const formulationRefusalNoted = new WeakSet();
+const secureFormulationNoteNoted = new WeakSet();
+
 /**
  * Check whether a value was explicitly provided by the user (i.e., is not
  * the yargs default). Yargs always populates default values, so we cannot
@@ -400,6 +415,28 @@ function resolveIntrospectOption(args, argv) {
     : undefined;
 }
 
+/**
+ * Whether the operator explicitly refused formulation with
+ * `--no-include-formulation`, `--include-formulation=false` or
+ * `CDXGEN_INCLUDE_FORMULATION=false`.
+ *
+ * @param {string[]} argv Raw command-line arguments the parser was given.
+ * @returns {boolean} True when formulation was refused explicitly.
+ */
+function isFormulationRefused(argv) {
+  return (
+    operatorOptionChoice("include-formulation", {
+      argv,
+      boolean: true,
+      env: {
+        CDXGEN_INCLUDE_FORMULATION: readEnvironmentVariable(
+          "CDXGEN_INCLUDE_FORMULATION",
+        ),
+      },
+    }) === false
+  );
+}
+
 export function buildInitialOptions(
   args,
   { filePath, isRemoteOrPurl, argv = process.argv, projectConfig },
@@ -427,6 +464,11 @@ export function buildInitialOptions(
     // explicit --no-introspect stays `false` and beats both, while an
     // unmentioned flag stays undefined so a profile can still enable it.
     introspect: resolveIntrospectOption(args, argv),
+    // An explicit --no-include-formulation (or CDXGEN_INCLUDE_FORMULATION
+    // set to false) is the operator's refusal, which no automatic trigger
+    // such as CI=true, a profile, obom or cbom may override. The yargs
+    // default is also false, so only the raw arguments tell them apart.
+    includeFormulationRefused: isFormulationRefused(argv) || undefined,
     // License normalization and enrichment are on by default; the only escape
     // hatch is the corresponding environment variable.
     licenseEnhance:
@@ -439,6 +481,10 @@ export function buildInitialOptions(
       readEnvironmentVariable("CDXGEN_LICENSE_REF") === "true",
   });
 
+  // A command default such as aibom's does not outrank the refusal either.
+  if (res.includeFormulationRefused) {
+    res.includeFormulation = false;
+  }
   if (res.licenseEnhance !== undefined) {
     process.env.CDXGEN_LICENSE_ENHANCE = String(res.licenseEnhance);
   }
@@ -628,6 +674,8 @@ export function applyPostConstructionOverrides(options, context) {
  * @param {object} options    The options object
  * @param {object} [context]
  * @param {boolean} [context.isSecureMode]  Whether cdxgen runs in secure mode
+ * @param {string} [context.invokedCommandName] Binary name (e.g. "cbom"),
+ *                                              which can turn on formulation
  * @returns {OptionsWarning[]} Warnings for the caller
  */
 export function applyAdvancedOptions(options, context = {}) {
@@ -635,6 +683,7 @@ export function applyAdvancedOptions(options, context = {}) {
   const warnings = [];
   const isHbomOnly = isHbomOnlyProjectTypes(options.projectType);
   const includeFormulationBeforeProfiles = options.includeFormulation === true;
+  const formulationRefused = options.includeFormulationRefused === true;
   const introspectExplicitlyDisabled = options.introspect === false;
 
   // --- Profile expansion -------------------------------------------------
@@ -672,7 +721,7 @@ export function applyAdvancedOptions(options, context = {}) {
       options.introspectAnnotate = options.introspectAnnotate !== false;
       // The ledger's own record of what ran; formulation is where a consumer
       // looks for the build environment the SBOM was produced in.
-      options.includeFormulation = !isHbomOnly;
+      options.includeFormulation = !isHbomOnly && !formulationRefused;
       options.evidence = true;
       break;
     case "ml-tiny":
@@ -752,17 +801,67 @@ export function applyAdvancedOptions(options, context = {}) {
     });
   }
 
-  // --- BOM audit → auto-formulation --------------------------------------
-  const introspectProfileAddsFormulation =
-    options.profile === "introspect" && !includeFormulationBeforeProfiles;
-  if (options.bomAudit || introspectProfileAddsFormulation) {
-    if (isHbomOnly) {
-      // HBOM-only: skip formulation
+  // --- Auto-formulation: BOM audit, profiles, CI, obom and cbom ----------
+  // Formulation is included without a flag when a BOM audit reads it, when
+  // the research or introspect profile runs, in CI (CI=true), and for obom
+  // (an OS project type such as os, linux or windows) and cbom output
+  // (cdxgen#859). These runs are where the build environment and inputs are
+  // wanted next to the inventory. Formulation does not supply the CISA 2026
+  // generation context element: CISA-MIN-004 reads metadata.lifecycles.
+  // An explicit --no-include-formulation wins over every trigger.
+  const profileAddsFormulation =
+    ["research", "introspect"].includes(options.profile) &&
+    !includeFormulationBeforeProfiles;
+  const autoFormulationReasons = [];
+  if (options.bomAudit) {
+    autoFormulationReasons.push("a BOM audit");
+  }
+  if (profileAddsFormulation) {
+    autoFormulationReasons.push(`the ${options.profile} profile`);
+  }
+  if ((readEnvironmentVariable("CI") || "").toLowerCase() === "true") {
+    autoFormulationReasons.push("CI=true");
+  }
+  if (hasOsProjectType(options.projectType)) {
+    autoFormulationReasons.push("an OS project type");
+  }
+  if (`${context.invokedCommandName || ""}`.includes("cbom")) {
+    autoFormulationReasons.push("the cbom command");
+  }
+  if (autoFormulationReasons.length && !isHbomOnly) {
+    const reasons = autoFormulationReasons.join(", ");
+    if (formulationRefused) {
+      options.includeFormulation = false;
+      if (!formulationRefusalNoted.has(options)) {
+        formulationRefusalNoted.add(options);
+        warnings.push({
+          level: "info",
+          message: `NOTE: Formulation stays off because it was refused explicitly (--no-include-formulation, --include-formulation=false or CDXGEN_INCLUDE_FORMULATION=false), although ${reasons} would include it.`,
+        });
+      }
     } else if (!options.includeFormulation) {
-      warnings.push(formulationPrivacyNotice());
-      options.includeFormulation = true;
-    } else if (introspectProfileAddsFormulation) {
-      warnings.push(formulationPrivacyNotice());
+      if (options.serverUrl && secureMode) {
+        // Secure mode refuses to submit formulation to a server, so an
+        // automatic default must not turn a secure run into a failed one.
+        if (!secureFormulationNoteNoted.has(options)) {
+          secureFormulationNoteNoted.add(options);
+          warnings.push({
+            level: "info",
+            message: `NOTE: Formulation is not collected automatically for ${reasons} because secure mode does not submit formulation to '${options.serverUrl}'. Pass --include-formulation to request it.`,
+          });
+        }
+      } else {
+        warnings.push(autoFormulationNotice(options, reasons));
+        options.includeFormulation = true;
+      }
+    } else if (profileAddsFormulation) {
+      warnings.push(autoFormulationNotice(options, reasons));
+    }
+    // Formulation that no flag asked for leaves out the scanning host's
+    // certificates, authorized keys and keychain items (see
+    // addFormulationSection).
+    if (options.includeFormulation && !includeFormulationBeforeProfiles) {
+      options.formulationAutomatic = true;
     }
   }
 
@@ -795,6 +894,8 @@ export function applyAdvancedOptions(options, context = {}) {
  * @param {object} [context.projectConfig]     Sanitized config file contents,
  *                                             whose metadata properties merge
  *                                             with the other sources'
+ * @param {string[]} [context.argv]            Raw command-line arguments,
+ *                                             process.argv when absent
  * @returns {{ options: object, warnings: OptionsWarning[] }}
  */
 export function buildOptionsFromArgs(args, context) {
@@ -805,6 +906,7 @@ export function buildOptionsFromArgs(args, context) {
     userSetSpecVersion,
     isDryRun = false,
     projectConfig,
+    argv,
   } = context;
 
   const expandedArgs = applyCommandNameDefaults(args, invokedCommandName);
@@ -812,6 +914,7 @@ export function buildOptionsFromArgs(args, context) {
     filePath,
     isRemoteOrPurl,
     projectConfig,
+    ...(argv ? { argv } : {}),
   });
   const phase3Warnings = applyPostConstructionOverrides(options, {
     invokedCommandName,
@@ -820,6 +923,7 @@ export function buildOptionsFromArgs(args, context) {
   });
   const phase4Warnings = applyAdvancedOptions(options, {
     isSecureMode: context.isSecureMode,
+    invokedCommandName,
   });
 
   return {