@cdxgen/cdxgen 13.0.0 → 13.1.0

package/lib/managers/binary.js

@@ -18,6 +18,7 @@ import {
   recordActivity,
   recordSymlinkResolution,
 } from "../core/activity.js";
+import { recordDegradation } from "../core/buildLedger.js";
 import { extractPathEnv } from "../core/env.js";
 import {
   getTmpDir,
@@ -37,7 +38,13 @@ import {
   extractToolRefs,
 } from "../inventory/evidenceUtils.js";
 import { createGtfoBinsProperties } from "../inventory/gtfobins.js";
-import { OS_DISTRO_ALIAS, readOsRelease } from "../inventory/osinfo.js";
+import {
+  canonicalDistroQualifier,
+  isCleanDistroQualifier,
+  OS_DISTRO_ALIAS,
+  OS_NAMESPACE_ALIAS,
+  readOsRelease,
+} from "../inventory/osinfo.js";
 import {
   collectExecutables,
   collectSharedLibs,
@@ -57,13 +64,6 @@ import { getDirs } from "./containerutils.js";
 
 const isWin = _platform() === "win32";
 const OS_PURL_TYPES = ["deb", "apk", "rpm", "alpm", "qpkg"];
-// Canonical distro vendor namespace. Trivy emits pkg:rpm/alma/... but the
-// vulnerability feeds (AppThreat vuln-list / dep-scan) key AlmaLinux under
-// "almalinux"; align so the purls match. Rocky is emitted as "rocky" already.
-const OS_DISTRO_NAMESPACE_ALIAS = {
-  alma: "almalinux",
-  "rocky-linux": "rocky",
-};
 const pluginRuntime = setPluginsPathEnv(resolveCdxgenPlugins());
 const platform = pluginRuntime.platform;
 const CDXGEN_PLUGINS_DIR = pluginRuntime.pluginsDir;
@@ -555,6 +555,173 @@ export function executeSourcekitten(args) {
   return undefined;
 }
 
+/**
+ * Canonicalise the distro vendor namespace of an OS package component
+ * produced by trivy, regardless of whether trivy expressed the vendor via the
+ * purl namespace or the component group (it is inconsistent between
+ * packages). e.g. pkg:rpm/alma/... -> pkg:rpm/almalinux/... and
+ * pkg:rpm/cbl-mariner/... -> pkg:rpm/azure-linux/... so the purls match the
+ * vulnerability feeds. Also aligns the ``distro`` qualifier vendor prefix
+ * (alma-9.8 -> almalinux-9.8, mariner-2.0 -> azure-linux-2.0), including
+ * spellings that disagree with the namespace, and rebuilds ``group`` and
+ * ``bom-ref`` from the rewritten purl.
+ *
+ * The namespace table is OS_NAMESPACE_ALIAS from lib/inventory/osinfo.js so
+ * the trivy path and the os-release path (getDistroInfo) cannot drift apart.
+ *
+ * A `distro` qualifier that is not purl-safe (trivy emits Amazon Linux as
+ * `amazon-2023.12.20260727+(Amazon Linux)`) is replaced with the os-release
+ * derived value, or dropped when there is none: an unusable qualifier
+ * invalidates the purl and fails validation for the whole BOM.
+ *
+ * @param {Object} comp trivy OS package component (mutated in place)
+ * @param {Object} purlObj parsed PackageURL of comp.purl (mutated in place)
+ * @param {string} name component package name (basename form)
+ * @param {string} group component group derived from the trivy component name
+ * @param {string} [distroId] canonical os-release distro id, e.g. "amazon-2023"
+ * @returns {string} the canonicalised group
+ */
+export function canonicaliseOsPackageNamespace(
+  comp,
+  purlObj,
+  name,
+  group,
+  distroId,
+) {
+  if (!purlObj || !OS_PURL_TYPES.includes(purlObj.type)) {
+    return group;
+  }
+  const os_ns = purlObj.namespace || group || "";
+  const os_ns_alias = OS_NAMESPACE_ALIAS[os_ns];
+  const distroQual = purlObj.qualifiers?.distro;
+  let canonicalDistroQual = distroQual;
+  if (os_ns_alias && distroQual?.startsWith(`${os_ns}-`)) {
+    canonicalDistroQual = `${os_ns_alias}-${distroQual.slice(os_ns.length + 1)}`;
+  }
+  canonicalDistroQual = canonicalDistroQualifier(canonicalDistroQual);
+  if (canonicalDistroQual && !isCleanDistroQualifier(canonicalDistroQual)) {
+    canonicalDistroQual = isCleanDistroQualifier(distroId)
+      ? distroId
+      : undefined;
+  }
+  if (!os_ns_alias && canonicalDistroQual === distroQual) {
+    return group;
+  }
+  group = os_ns_alias || purlObj.namespace || group || "";
+  comp.group = group;
+  purlObj.namespace = group;
+  if (canonicalDistroQual !== distroQual) {
+    if (canonicalDistroQual) {
+      purlObj.qualifiers.distro = canonicalDistroQual;
+    } else {
+      delete purlObj.qualifiers.distro;
+    }
+  }
+  comp.purl = build({
+    type: purlObj.type,
+    namespace: purlObj.namespace || null,
+    name: name,
+    version: purlObj.version || null,
+    qualifiers: purlObj.qualifiers || null,
+    subpath: purlObj.subpath || null,
+  });
+  comp["bom-ref"] = decodeURIComponent(comp.purl);
+  return group;
+}
+
+/**
+ * Repair a `distro` qualifier that cannot survive purl parsing, in place.
+ *
+ * trivy stamps Amazon Linux with the full pretty version — the qualifier
+ * arrives as `distro=amazon-2023.12.20260727+%28Amazon+Linux%29`, whose spaces
+ * and parentheses `Purl.parse` rejects outright ("Invalid character in
+ * qualifier distro"). The component then bypasses every canonicalisation below
+ * (they all need a parsed purl) and reaches the BOM verbatim, where schema
+ * validation fails and the *entire* SBOM is discarded — an Amazon Linux scan
+ * produces no output at all today.
+ *
+ * The release is already known from os-release, so the unusable value is
+ * swapped for it; with no usable replacement the qualifier is dropped, since a
+ * missing qualifier costs one matching hint while an invalid one costs the
+ * whole document.
+ *
+ * @param {Object} comp component whose purl may carry an unusable qualifier
+ * @param {string} [distroId] canonical os-release distro id, e.g. "amazon-2023"
+ * @returns {Object} the same component
+ */
+export function repairOsComponentPurl(comp, distroId) {
+  const purl = comp?.purl;
+  if (!purl?.includes("distro=")) {
+    return comp;
+  }
+  const match = /([?&]distro=)([^&]*)/.exec(purl);
+  if (!match) {
+    return comp;
+  }
+  let decoded = match[2];
+  try {
+    decoded = decodeURIComponent(match[2].replace(/\+/g, " "));
+  } catch (_err) {
+    // A value that cannot even be decoded is definitely not purl-safe
+  }
+  if (isCleanDistroQualifier(decoded)) {
+    return comp;
+  }
+  const replacement = isCleanDistroQualifier(distroId)
+    ? `${match[1]}${distroId}`
+    : "";
+  comp.purl = purl.replace(match[0], replacement).replace(/\?&/, "?");
+  if (comp.purl.endsWith("?")) {
+    comp.purl = comp.purl.slice(0, -1);
+  }
+  comp["bom-ref"] = decodeURIComponent(comp.purl);
+  return comp;
+}
+
+/**
+ * Drop source-package shadow components that duplicate a real installed
+ * package, in place.
+ *
+ * A shadow is emitted whenever an rpm/deb declares a source name different
+ * from its own (bzip2-libs -> bzip2) so that scanners keying on source names
+ * still match. When the source package is *itself* installed at the same
+ * version, the shadow's purl is identical to the real component's and the two
+ * collapse in trimComponents() — which keeps whichever was seen first and
+ * never merges `tags`. Seen-first is trivy's listing order, so the outcome is
+ * arbitrary: when the shadow wins, a genuinely installed package is reported
+ * with `tags: ["source"]` and identity confidence 0, the very marker the
+ * shadow carries so consumers can filter shadows out. That turns a real
+ * package into a filtered-away one.
+ *
+ * Dropping the redundant shadow is loss-free: it duplicates the real
+ * component's purl (so nothing that matches on purl changes) and its bom-ref
+ * is byte-identical, so no dependency reference can dangle.
+ *
+ * @param {Array} pkgList component list, mutated in place
+ * @returns {Array} the same list, for convenience
+ */
+export function dropRedundantSourceComponents(pkgList) {
+  if (!Array.isArray(pkgList) || !pkgList.length) {
+    return pkgList;
+  }
+  const installedPurls = new Set();
+  for (const comp of pkgList) {
+    if (comp?.purl && !comp?.tags?.includes("source")) {
+      installedPurls.add(comp.purl);
+    }
+  }
+  if (!installedPurls.size) {
+    return pkgList;
+  }
+  for (let i = pkgList.length - 1; i >= 0; i--) {
+    const comp = pkgList[i];
+    if (comp?.tags?.includes("source") && installedPurls.has(comp.purl)) {
+      pkgList.splice(i, 1);
+    }
+  }
+  return pkgList;
+}
+
 /**
  * Get the packages installed in the container image filesystem.
  *
@@ -613,6 +780,16 @@ export async function getOSPackages(src, imageConfig, options = {}) {
           .filter(Boolean),
       ),
     ).sort();
+    if (binPaths.length) {
+      recordDegradation("binary.paths.inferred", {
+        ecosystem: "generic",
+        tool: "trivy",
+        impact: "none",
+        path: src,
+        detail:
+          "The image config carried no PATH, so executable directories were inferred by scanning the filesystem.",
+      });
+    }
     if (DEBUG_MODE && binPaths.length) {
       console.log(
         `Falling back to inferred binary paths for ${src}: ${binPaths.join(", ")}`,
@@ -721,9 +898,14 @@ export async function getOSPackages(src, imageConfig, options = {}) {
             }
           }
           break;
+        case "alpaquita":
+          purl_type = "apk";
+          break;
         default:
           if (distro_id_like.includes("debian")) {
             purl_type = "deb";
+          } else if (distro_id_like.includes("alpine")) {
+            purl_type = "apk";
           } else if (
             distro_id_like.includes("rhel") ||
             distro_id_like.includes("centos") ||
@@ -739,6 +921,11 @@ export async function getOSPackages(src, imageConfig, options = {}) {
           distro_codename = OS_DISTRO_ALIAS[distro_id];
         }
       }
+      // Canonicalise the distro qualifier vendor (e.g. "mariner-2.0" ->
+      // "azure-linux-2.0") so every spelling of one release yields a single
+      // qualifier value. This runs before distro_id is used to overwrite
+      // trivy's own qualifier below.
+      distro_id = canonicalDistroQualifier(distro_id);
       const tmpDependencies = {};
       tools = enrichToolComponents(
         (Array.isArray(tmpBom?.metadata?.tools)
@@ -768,42 +955,23 @@ export async function getOSPackages(src, imageConfig, options = {}) {
             comp.group = group;
             comp.name = name;
             const modularityLabel = extractModularityLabel(comp);
+            repairOsComponentPurl(comp, distro_id);
             try {
               purlObj = Purl.parse(comp.purl);
               purlObj.qualifiers = purlObj.qualifiers || {};
             } catch (_err) {
               // continue regardless of error
             }
-            // Canonicalise the distro vendor namespace for every OS component,
-            // regardless of whether trivy expressed the vendor via the purl
-            // namespace or the component group (it is inconsistent between
-            // packages). e.g. pkg:rpm/alma/... -> pkg:rpm/almalinux/... so the
-            // purls match the vulnerability feeds. Also aligns the ``distro``
-            // qualifier vendor prefix (alma-9.8 -> almalinux-9.8).
-            if (purlObj && OS_PURL_TYPES.includes(purlObj.type)) {
-              const os_ns = purlObj.namespace || group || "";
-              const os_ns_alias = OS_DISTRO_NAMESPACE_ALIAS[os_ns];
-              if (os_ns_alias) {
-                group = os_ns_alias;
-                comp.group = os_ns_alias;
-                purlObj.namespace = os_ns_alias;
-                const distroQual = purlObj.qualifiers?.distro;
-                if (distroQual?.startsWith(`${os_ns}-`)) {
-                  purlObj.qualifiers.distro = `${os_ns_alias}-${distroQual.slice(
-                    os_ns.length + 1,
-                  )}`;
-                }
-                comp.purl = build({
-                  type: purlObj.type,
-                  namespace: os_ns_alias || null,
-                  name: name,
-                  version: purlObj.version || null,
-                  qualifiers: purlObj.qualifiers || null,
-                  subpath: purlObj.subpath || null,
-                });
-                comp["bom-ref"] = decodeURIComponent(comp.purl);
-              }
-            }
+            // Canonicalise the distro vendor namespace (see
+            // canonicaliseOsPackageNamespace) before any later bom-ref
+            // rebuild so the rewritten purl, group and bom-ref stay in sync.
+            group = canonicaliseOsPackageNamespace(
+              comp,
+              purlObj,
+              name,
+              group,
+              distro_id,
+            );
             if (
               group === "" &&
               purlObj &&
@@ -812,8 +980,7 @@ export async function getOSPackages(src, imageConfig, options = {}) {
               try {
                 if (purlObj?.namespace && purlObj.namespace !== "") {
                   group =
-                    OS_DISTRO_NAMESPACE_ALIAS[purlObj.namespace] ||
-                    purlObj.namespace;
+                    OS_NAMESPACE_ALIAS[purlObj.namespace] || purlObj.namespace;
                   comp.group = group;
                   purlObj.namespace = group;
                 }
@@ -1107,6 +1274,7 @@ export async function getOSPackages(src, imageConfig, options = {}) {
       }
     }
   }
+  dropRedundantSourceComponents(pkgList);
   const rootfsRepositoryInventory = await collectRootfsRepositoryInventory(
     src,
     options,
@@ -3144,6 +3312,14 @@ export function getDotnetSlices(src, slicesFile) {
       "You must install or update .NET to run this application",
     )
   ) {
+    recordDegradation("dotnet.sdk.missing", {
+      ecosystem: "csharp",
+      tool: "dotnet",
+      impact: "components",
+      command: `dosai ${args.join(" ")}`,
+      detail:
+        "dosai reported that no .NET SDK is installed, so dotnet-related evidence for this image is incomplete.",
+    });
     console.log(
       "Dotnet SDK is not installed. Please use the cdxgen dotnet container images to generate slices for this project.",
     );

package/lib/managers/docker.js

@@ -21,6 +21,7 @@ import {
   recordDecisionActivity,
   recordSensitiveFileRead,
 } from "../core/activity.js";
+import { deferFailOnError } from "../core/deferredExit.js";
 import { extractPathEnv } from "../core/env.js";
 import {
   getAllFiles,
@@ -1407,7 +1408,11 @@ export const extractTar = async (fullImageName, dir, options) => {
     } else if (DEBUG_MODE) {
       console.log(err.code, "is not handled yet in extractTar method.");
     }
-    options.failOnError && process.exit(1);
+    deferFailOnError(options, {
+      ecosystem: "container",
+      tool: "docker",
+      detail: "extracting the image archive failed",
+    });
     return false;
   }
 };
@@ -1598,10 +1603,18 @@ export const exportArchive = async (fullImageName, options = {}) => {
       return exportData;
     }
     console.log(`Unable to extract image archive to ${tempDir}`);
-    options.failOnError && process.exit(1);
+    deferFailOnError(options, {
+      ecosystem: "container",
+      tool: "docker",
+      detail: "the image archive could not be extracted",
+    });
   } catch (_err) {
     // ignore
-    options.failOnError && process.exit(1);
+    deferFailOnError(options, {
+      ecosystem: "container",
+      tool: "docker",
+      detail: "the image archive could not be extracted",
+    });
   }
   return undefined;
 };
@@ -1686,7 +1699,11 @@ export const extractFromManifest = async (
           }
         } else {
           console.log(err);
-          options.failOnError && process.exit(1);
+          deferFailOnError(options, {
+            ecosystem: "container",
+            tool: "docker",
+            detail: "reading the image manifest failed",
+          });
         }
       }
     }
@@ -1713,7 +1730,11 @@ export const extractFromManifest = async (
           ? join(allLayersExplodedDir, lastLayerConfig.config.WorkingDir)
           : "";
       } catch (_err) {
-        options.failOnError && process.exit(1);
+        deferFailOnError(options, {
+          ecosystem: "container",
+          tool: "docker",
+          detail: "reading the image manifest failed",
+        });
       }
     }
   }

package/lib/server/server.js

@@ -520,7 +520,7 @@ const start = (options) => {
         ensureAiProvenanceProperties(bomNSData.bomJson, reqOptions);
         await ensureAiOversightProperties(bomNSData.bomJson, reqOptions);
       }
-      bomNSData = postProcess(
+      bomNSData = await postProcess(
         bomNSData,
         { ...reqOptions, executeOsQuery },
         srcDir,

package/lib/stages/postgen/annotationBuilder.js

@@ -0,0 +1,97 @@
+/**
+ * Shared assembly of CycloneDX document-level annotations.
+ *
+ * Two postgen features attach findings to the BOM document as annotations
+ * whose `subjects` is the BOM serial number: the BOM audit's rule findings and
+ * the build introspection's remediations. Both describe the document rather
+ * than a component, both are annotated by the cdxgen tool component from
+ * metadata, and both carry the document's own timestamp because an annotation
+ * describes the document it is attached to. The structured facts travel as
+ * `name`/`value` pairs rendered into the annotation text, one `:evidence:<key>`
+ * entry per evidence item.
+ */
+
+import { DEBUG_MODE } from "../../core/activity.js";
+import { getTimestamp } from "../../core/fs.js";
+import { buildAnnotationText } from "../../helpers/annotationFormatter.js";
+
+/**
+ * Find the cdxgen tool component that annotates the document.
+ *
+ * @param {Object} bomJson CycloneDX BOM
+ * @returns {Object[]} The cdxgen tool components, empty when metadata carries none.
+ */
+function findCdxgenAnnotator(bomJson) {
+  return (
+    bomJson?.metadata?.tools?.components?.filter((c) => c.name === "cdxgen") ||
+    []
+  );
+}
+
+/**
+ * Flatten an evidence object into `:evidence:<key>` property entries. Nested
+ * values are serialized as JSON so every property value stays a string.
+ *
+ * @param {string} propertyNamePrefix Property namespace, e.g. "cdx:audit".
+ * @param {Object} evidence Arbitrary key/value evidence facts.
+ * @returns {{name: string, value: string}[]} Property entries.
+ */
+export function evidenceProperties(propertyNamePrefix, evidence) {
+  const properties = [];
+  if (evidence && typeof evidence === "object") {
+    for (const [key, value] of Object.entries(evidence)) {
+      const propValue =
+        typeof value === "object" ? JSON.stringify(value) : String(value);
+      properties.push({
+        name: `${propertyNamePrefix}:evidence:${key}`,
+        value: propValue,
+      });
+    }
+  }
+  return properties;
+}
+
+/**
+ * Build one document-level annotation. Returns undefined when the BOM carries
+ * no cdxgen tool component to annotate with; the caller decides whether that
+ * is worth a warning.
+ *
+ * @param {Object} params Annotation inputs.
+ * @param {Object} params.bomJson CycloneDX BOM the annotation describes.
+ * @param {string} params.message Leading annotation sentence.
+ * @param {{name: string, value: string}[]} params.properties Structured facts rendered into the annotation text.
+ * @returns {Object|undefined} CycloneDX annotation, or undefined without an annotator.
+ */
+export function buildDocumentAnnotation({ bomJson, message, properties }) {
+  const cdxgenAnnotator = findCdxgenAnnotator(bomJson);
+  if (!cdxgenAnnotator.length) {
+    return undefined;
+  }
+  return {
+    subjects: [bomJson.serialNumber],
+    annotator: {
+      component: cdxgenAnnotator[0],
+    },
+    // An annotation describes the document it is attached to, so it carries
+    // that document's timestamp rather than the moment the annotation was
+    // built.
+    timestamp: bomJson.metadata?.timestamp || getTimestamp(),
+    text: buildAnnotationText(message, properties),
+  };
+}
+
+/**
+ * Warn that a document could not be annotated because it carries no cdxgen
+ * tool component. Suppressed outside debug mode, where the missing annotator
+ * is an expected shape for foreign BOMs.
+ *
+ * @param {string} feature Feature that wanted to annotate.
+ * @returns {void}
+ */
+export function warnMissingAnnotator(feature) {
+  if (DEBUG_MODE) {
+    console.warn(
+      `Cannot create ${feature} annotations: cdxgen tool component not found in metadata`,
+    );
+  }
+}