@cdxgen/cdxgen 13.1.0 → 13.3.0

package/lib/stages/postgen/postgen.js

@@ -22,6 +22,7 @@ import {
 } from "../../core/fs.js";
 import { thoughtLog } from "../../core/logger.js";
 import { dirNameStr } from "../../core/paths.js";
+import { sanitizeBomPropertyValue } from "../../core/propertySanitizer.js";
 import { CDXGEN_TOOL_GROUP, CDXGEN_TOOL_NAME } from "../../core/state.js";
 import {
   AI_INVENTORY_PROJECT_TYPES,
@@ -565,11 +566,21 @@ export async function postProcess(bomNSData, options, filePath) {
   bomNSData.bomJson = applyMetadata(bomNSData.bomJson, options);
   bomNSData.bomJson = applyLicenseEnhancement(bomNSData.bomJson, options);
   bomNSData.bomJson = applyContainerInventoryMetadata(bomNSData.bomJson);
+  const buildOnlyComponents = extractBuildOnlyComponents(
+    bomNSData.bomJson,
+    options,
+  );
   bomNSData.bomJson = applyFormulation(
     bomNSData.bomJson,
     options,
     filePath,
-    bomNSData.formulationList,
+    buildOnlyComponents.length
+      ? [...(bomNSData.formulationList || []), ...buildOnlyComponents]
+      : bomNSData.formulationList,
+  );
+  bomNSData.bomJson = applyBuildOnlyFormulation(
+    bomNSData.bomJson,
+    buildOnlyComponents,
   );
   bomNSData.bomJson = applyReleaseNotes(bomNSData.bomJson, options, filePath);
   bomNSData.bomJson = applyComponentTypeFilter(bomNSData.bomJson, options);
@@ -731,24 +742,18 @@ function applyReleaseNotes(bomJson, options, filePath) {
  */
 export function applyMetadata(bomJson, options) {
   if (!bomJson?.components) {
-    return bomJson;
+    return applyCustomMetadataProperties(bomJson, options);
   }
   const bomPkgTypes = new Set();
   const bomPkgNamespaces = new Set();
   const bomSrcFiles = new Set();
-  for (const comp of bomJson.components) {
-    if (comp.purl) {
-      try {
-        const purlObj = Purl.parse(comp.purl);
-        if (purlObj?.type) {
-          bomPkgTypes.add(purlObj.type);
-        }
-        if (purlObj?.namespace) {
-          bomPkgNamespaces.add(purlObj.namespace);
-        }
-      } catch (_e) {
-        // ignore
-      }
+  // Collect the manifests a component was identified from, rewriting any
+  // absolute path to a relative one as a side effect. Shared by the components
+  // and by metadata.component, which a collector such as the ruby one describes
+  // from the project's own gemspec (discussion 4410).
+  const collectSrcFiles = (comp) => {
+    if (!comp) {
+      return;
     }
     if (comp.properties) {
       for (const aprop of comp.properties) {
@@ -780,6 +785,10 @@ export function applyMetadata(bomJson, options) {
           Array.isArray(aidentityEvidence.methods)
         ) {
           for (const amethod of aidentityEvidence.methods) {
+            // `value` is optional: an attestation, for one, names no file.
+            if (typeof amethod?.value !== "string") {
+              continue;
+            }
             const rdir = relativeDir(amethod.value, options);
             if (
               comp.type !== "file" &&
@@ -796,7 +805,24 @@ export function applyMetadata(bomJson, options) {
         }
       }
     }
+  };
+  for (const comp of bomJson.components) {
+    if (comp.purl) {
+      try {
+        const purlObj = Purl.parse(comp.purl);
+        if (purlObj?.type) {
+          bomPkgTypes.add(purlObj.type);
+        }
+        if (purlObj?.namespace) {
+          bomPkgNamespaces.add(purlObj.namespace);
+        }
+      } catch (_e) {
+        // ignore
+      }
+    }
+    collectSrcFiles(comp);
   }
+  collectSrcFiles(bomJson.metadata?.component);
   if (!bomJson.metadata.properties) {
     bomJson.metadata.properties = [];
   }
@@ -852,6 +878,43 @@ export function applyMetadata(bomJson, options) {
       thoughtLog("BOM lacks package manifest details. Please help us improve!");
     }
   }
+  return applyCustomMetadataProperties(bomJson, options);
+}
+
+/**
+ * Add the metadata properties the user asked for on the command line, in the
+ * environment, or in a config file (discussion 4391), after whatever the scan
+ * itself discovered. They never replace a discovered property: the scan's own
+ * names, such as `cdx:bom:componentSrcFiles`, keep their values. A BOM without
+ * components still gets them.
+ *
+ * @param {Object} bomJson BOM JSON Object
+ * @param {Object} options CLI options, with `metadataProperties` as
+ *   `[{name, value}]`
+ *
+ * @returns {Object} BOM JSON Object
+ */
+function applyCustomMetadataProperties(bomJson, options) {
+  if (!bomJson?.metadata || !options?.metadataProperties?.length) {
+    return bomJson;
+  }
+  bomJson.metadata.properties = bomJson.metadata.properties || [];
+  for (const aprop of options.metadataProperties) {
+    if (!aprop?.name?.length || aprop.value === undefined) {
+      continue;
+    }
+    const value = sanitizeBomPropertyValue(aprop.name, `${aprop.value}`);
+    if (!value?.length) {
+      continue;
+    }
+    if (
+      !bomJson.metadata.properties.some(
+        (p) => p.name === aprop.name && p.value === value,
+      )
+    ) {
+      bomJson.metadata.properties.push({ name: aprop.name, value });
+    }
+  }
   return bomJson;
 }
 
@@ -964,6 +1027,154 @@ function getIdentityTechniques(comp) {
   return techniques;
 }
 
+/**
+ * Ensure the components moved out of the assembly have landed in the
+ * formulation section.
+ *
+ * With `--include-formulation` they were handed to the full formulation pass.
+ * Without it there is no formulation section, so a minimal one is created for
+ * them alone: moving a component out of `components[]` and then dropping it
+ * would lose it from the document.
+ *
+ * @param {Object} bomJson BOM JSON object
+ * @param {Object[]} buildOnlyComponents Components removed from `components[]`
+ *
+ * @returns {Object} The same `bomJson`
+ */
+function applyBuildOnlyFormulation(bomJson, buildOnlyComponents) {
+  if (!buildOnlyComponents?.length || !bomJson) {
+    return bomJson;
+  }
+  const alreadyPlaced = (bomJson.formulation || []).some((formula) =>
+    formula?.components?.some((comp) =>
+      buildOnlyComponents.some((moved) => moved["bom-ref"] === comp["bom-ref"]),
+    ),
+  );
+  if (alreadyPlaced) {
+    return bomJson;
+  }
+  if (!bomJson.formulation) {
+    bomJson.formulation = [];
+  }
+  bomJson.formulation.push({
+    "bom-ref": `${bomJson.metadata?.component?.["bom-ref"] || "cdxgen"}#build-dependencies`,
+    components: buildOnlyComponents,
+  });
+  return bomJson;
+}
+
+/**
+ * Report whether a component exists only to produce the build, rather than
+ * being part of the delivered assembly. A cargo build dependency and a
+ * proc-macro crate are both marked with `cdx:cargo:hostOnly`.
+ *
+ * @param {Object} comp Component
+ * @returns {boolean} True for a build-time-only component
+ */
+function isBuildOnlyComponent(comp) {
+  return !!comp?.properties?.some(
+    (property) =>
+      property.name === "cdx:cargo:hostOnly" && property.value === "true",
+  );
+}
+
+/**
+ * Move the build-time-only components out of `components[]`, which describes
+ * the delivered assembly, and hand them to the formulation section, which is
+ * where CycloneDX describes how the assembly was produced.
+ *
+ * Their bom-refs stay valid because the formulation components live in the same
+ * document, so the dependency graph is left intact. `formulation` exists from
+ * CycloneDX 1.5, so an older document keeps them in `components[]` with their
+ * `cdx:cargo:hostOnly` marker rather than losing them.
+ *
+ * @param {Object} bomJson BOM JSON object
+ * @param {Object} options CLI options
+ *
+ * @returns {Object[]} The components removed from `components[]`
+ */
+export function extractBuildOnlyComponents(bomJson, options) {
+  if (options?.specVersion < 1.5 || !bomJson?.components?.length) {
+    return [];
+  }
+  const buildOnlyComponents = [];
+  const retainedComponents = [];
+  for (const comp of bomJson.components) {
+    if (isBuildOnlyComponent(comp)) {
+      buildOnlyComponents.push(comp);
+    } else {
+      retainedComponents.push(comp);
+    }
+  }
+  if (buildOnlyComponents.length) {
+    bomJson.components = retainedComponents;
+  }
+  return buildOnlyComponents;
+}
+
+/**
+ * Report whether a component carries evidence that it is actually used: an
+ * occurrence in the analyzed sources, or a frame in a callstack.
+ *
+ * @param {Object} comp Component
+ * @returns {boolean} True when usage evidence is attached
+ */
+function hasUsageEvidence(comp) {
+  if (comp?.evidence?.occurrences?.length) {
+    return true;
+  }
+  return !!comp?.evidence?.callstack?.frames?.length;
+}
+
+/**
+ * Re-apply the `--required-only` filter once the evidence stage has attached
+ * occurrence and callstack data.
+ *
+ * A manifest can only say that a dependency is optional; the evidence says
+ * whether it is reached. A component the analyzers observed in the sources is
+ * promoted to `required` so it survives the filter, while an optional component
+ * with no observed usage is dropped as before. A component scoped `excluded` -
+ * a dev or test dependency - keeps that scope: an occurrence inside the test
+ * sources is not evidence that it ships.
+ *
+ * @param {Object} bomJson BOM JSON object carrying evidence
+ * @param {Object} options CLI options
+ *
+ * @returns {Object} Filtered BOM JSON
+ */
+export function applyEvidenceBasedFilter(bomJson, options) {
+  if (!options?.requiredOnly || !bomJson?.components?.length) {
+    return bomJson;
+  }
+  if (!(options.evidence || options.includeCrypto)) {
+    return bomJson;
+  }
+  for (const comp of bomJson.components) {
+    if (!hasUsageEvidence(comp)) {
+      continue;
+    }
+    if (!comp.properties) {
+      comp.properties = [];
+    }
+    const observed = comp.evidence?.occurrences?.length
+      ? "occurrence"
+      : "callstack";
+    if (
+      !comp.properties.some(
+        (property) => property.name === "cdx:evidence:usage",
+      )
+    ) {
+      comp.properties.push({ name: "cdx:evidence:usage", value: observed });
+    }
+    if (comp.scope === "optional") {
+      comp.scope = "required";
+    }
+  }
+  // `evidenceFilterStage` tells filterBom that the evidence is in hand, so the
+  // scope filter it deferred earlier must run now.
+  return filterBom(bomJson, { ...options, evidenceFilterStage: true });
+}
+
 /**
  * Filter BOM based on options
  *
@@ -983,6 +1194,15 @@ export function filterBom(bomJson, options) {
   const allowedComponentTypes = new Set(
     normalizeCycloneDxComponentTypeFilter(options?.componentType),
   );
+  // Evidence generation runs after this stage, so dropping the optional
+  // components here would deny the analyzers the chance to prove that one is
+  // used. The scope filter is re-applied by applyEvidenceBasedFilter once the
+  // occurrence and callstack evidence is attached.
+  const deferRequiredOnly = !!(
+    options.requiredOnly &&
+    !options.evidenceFilterStage &&
+    (options.evidence || options.includeCrypto)
+  );
   for (const comp of bomJson.components) {
     if (shouldExcludeInventoryType(comp, options)) {
       filtered = true;
@@ -1025,6 +1245,7 @@ export function filterBom(bomJson, options) {
     }
     if (
       options.requiredOnly &&
+      !deferRequiredOnly &&
       comp.scope &&
       ["optional", "excluded"].includes(comp.scope)
     ) {
@@ -1335,7 +1556,7 @@ export function annotate(bomJson, options) {
     for (const dep of bomJson.dependencies) {
       const newRef = `${bomLinkPrefix}${stripBomLink(bomJson.serialNumber, bomJson.version, dep.ref)}`;
       const newDependsOn = [];
-      for (const adon of dep.dependsOn) {
+      for (const adon of dep.dependsOn || []) {
         newDependsOn.push(
           `${bomLinkPrefix}${stripBomLink(bomJson.serialNumber, bomJson.version, adon)}`,
         );