@cdxgen/cdxgen 13.0.1 → 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,
@@ -779,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(", ")}`,
@@ -887,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") ||
@@ -3296,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`,
+    );
+  }
+}

package/lib/stages/postgen/auditBom.js

@@ -6,16 +6,21 @@ import { join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { DEBUG_MODE } from "../../core/activity.js";
-import { getTimestamp, safeExistsSync } from "../../core/fs.js";
-import { buildAnnotationText } from "../../helpers/annotationFormatter.js";
+import { safeExistsSync } from "../../core/fs.js";
 import { collectAiOversight } from "../../inventory/aiOversightCollector.js";
 import { collectAiProvenance } from "../../inventory/aiProvenanceCollector.js";
 import {
   expandBomAuditCategories,
+  OPT_IN_BOM_AUDIT_CATEGORIES,
   validateBomAuditCategories,
 } from "../../inventory/auditCategories.js";
 import { isHbomLikeBom as isHbomLikeBomDocument } from "../../inventory/hbomAnalysis.js";
 import { table } from "../../inventory/table.js";
+import {
+  buildDocumentAnnotation,
+  evidenceProperties,
+  warnMissingAnnotator,
+} from "./annotationBuilder.js";
 import { evaluateRules, loadRules } from "./ruleEngine.js";
 
 const __dirname = fileURLToPath(new URL(".", import.meta.url));
@@ -53,6 +58,12 @@ async function loadConfiguredBomAuditRules(options = {}) {
         );
       }
     }
+  } else {
+    // Without explicit categories every loaded rule would activate, so rules
+    // belonging to opt-in-only categories are removed here.
+    activeRules = rules.filter(
+      (r) => !OPT_IN_BOM_AUDIT_CATEGORIES.includes(r.category),
+    );
   }
   return {
     activeRules,
@@ -369,89 +380,75 @@ export function formatAnnotations(findings, bomJson) {
   if (!findings?.length) {
     return [];
   }
-  const cdxgenAnnotator =
-    bomJson?.metadata?.tools?.components?.filter((c) => c.name === "cdxgen") ||
-    [];
-  if (!cdxgenAnnotator.length) {
-    if (DEBUG_MODE) {
-      console.warn(
-        "Cannot create audit annotations: cdxgen tool component not found in metadata",
-      );
-    }
-    return [];
-  }
-  return findings.map((f) => {
-    const subjects = [bomJson.serialNumber];
-    const properties = [
-      { name: "cdx:audit:ruleId", value: f.ruleId },
-      { name: "cdx:audit:severity", value: f.severity },
-      { name: "cdx:audit:category", value: f.category },
-    ];
-    if (f.name) {
-      properties.push({ name: "cdx:audit:name", value: f.name });
-    }
-    if (f.mitigation) {
-      properties.push({ name: "cdx:audit:mitigation", value: f.mitigation });
-    }
-    if (f.attackTactics?.length) {
-      properties.push({
-        name: "cdx:audit:attack:tactics",
-        value: f.attackTactics.join(","),
-      });
-    }
-    if (f.attackTechniques?.length) {
-      properties.push({
-        name: "cdx:audit:attack:techniques",
-        value: f.attackTechniques.join(","),
-      });
-    }
-    if (f.standards && typeof f.standards === "object") {
-      for (const [standardName, entries] of Object.entries(f.standards)) {
+  let warnedMissingAnnotator = false;
+  return findings
+    .map((f) => {
+      const properties = [
+        { name: "cdx:audit:ruleId", value: f.ruleId },
+        { name: "cdx:audit:severity", value: f.severity },
+        { name: "cdx:audit:category", value: f.category },
+      ];
+      if (f.name) {
+        properties.push({ name: "cdx:audit:name", value: f.name });
+      }
+      if (f.mitigation) {
+        properties.push({ name: "cdx:audit:mitigation", value: f.mitigation });
+      }
+      if (f.attackTactics?.length) {
         properties.push({
-          name: `cdx:audit:standards:${standardName}`,
-          value: Array.isArray(entries) ? entries.join(",") : String(entries),
+          name: "cdx:audit:attack:tactics",
+          value: f.attackTactics.join(","),
         });
       }
-    }
-    if (f?.location?.purl) {
-      properties.push({
-        name: "cdx:audit:location:purl",
-        value: f.location.purl,
-      });
-    }
-    if (f.location?.file) {
-      properties.push({
-        name: "cdx:audit:location:file",
-        value: f.location.file,
-      });
-    }
-    if (f.location?.bomRef) {
-      properties.push({
-        name: "cdx:audit:location:bomRef",
-        value: f.location.bomRef,
-      });
-    }
-    if (f.evidence && typeof f.evidence === "object") {
-      for (const [key, value] of Object.entries(f.evidence)) {
-        const propValue =
-          typeof value === "object" ? JSON.stringify(value) : String(value);
+      if (f.attackTechniques?.length) {
         properties.push({
-          name: `cdx:audit:evidence:${key}`,
-          value: propValue,
+          name: "cdx:audit:attack:techniques",
+          value: f.attackTechniques.join(","),
         });
       }
-    }
-    return {
-      subjects,
-      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 audit ran.
-      timestamp: bomJson.metadata?.timestamp || getTimestamp(),
-      text: buildAnnotationText(f.message, properties),
-    };
-  });
+      if (f.standards && typeof f.standards === "object") {
+        for (const [standardName, entries] of Object.entries(f.standards)) {
+          properties.push({
+            name: `cdx:audit:standards:${standardName}`,
+            value: Array.isArray(entries) ? entries.join(",") : String(entries),
+          });
+        }
+      }
+      if (f?.location?.purl) {
+        properties.push({
+          name: "cdx:audit:location:purl",
+          value: f.location.purl,
+        });
+      }
+      if (f.location?.file) {
+        properties.push({
+          name: "cdx:audit:location:file",
+          value: f.location.file,
+        });
+      }
+      if (f.location?.bomRef) {
+        properties.push({
+          name: "cdx:audit:location:bomRef",
+          value: f.location.bomRef,
+        });
+      }
+      properties.push(...evidenceProperties("cdx:audit", f.evidence));
+      return buildDocumentAnnotation({
+        bomJson,
+        message: f.message,
+        properties,
+      });
+    })
+    .filter((annotation) => {
+      if (!annotation) {
+        if (!warnedMissingAnnotator) {
+          warnMissingAnnotator("audit");
+          warnedMissingAnnotator = true;
+        }
+        return false;
+      }
+      return true;
+    });
 }
 
 /**