@cdxgen/cdxgen 13.6.0 → 13.7.0

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 {