@cyclonedx/cdxgen 12.1.5 → 12.2.0

package/lib/stages/postgen/auditBom.js

@@ -0,0 +1,197 @@
+/**
+ * Post-generation BOM audit orchestrator
+ * Evaluates security rules against CI/CD and dependency data in the BOM
+ */
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { table } from "table";
+
+import {
+  DEBUG_MODE,
+  getTimestamp,
+  safeExistsSync,
+} from "../../helpers/utils.js";
+import { evaluateRules, loadRules } from "./ruleEngine.js";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const BUILTIN_RULES_DIR = join(__dirname, "..", "..", "..", "data", "rules");
+const CODE_BLOCK = "```";
+
+/**
+ * Audit BOM formulation section using JSONata-powered rule engine
+ * @param {Object} bomJson - Generated CycloneDX BOM
+ * @param {Object} options - CLI options
+ * @returns {Promise<Array>} Array of audit findings
+ */
+export async function auditBom(bomJson, options) {
+  if (!bomJson) {
+    return [];
+  }
+  const findings = [];
+  const rules = await loadRules(BUILTIN_RULES_DIR);
+  if (options.bomAuditRulesDir && safeExistsSync(options.bomAuditRulesDir)) {
+    const userRulesDir = resolve(options.bomAuditRulesDir);
+    const userRules = await loadRules(userRulesDir);
+    if (DEBUG_MODE) {
+      console.log(`Loaded ${userRules.length} user rules from ${userRulesDir}`);
+    }
+    rules.push(...userRules);
+  }
+  if (rules.length === 0) {
+    if (DEBUG_MODE) {
+      console.log("No audit rules loaded; formulation audit skipped");
+    }
+    return findings;
+  }
+  let activeRules = rules;
+  if (options.bomAuditCategories) {
+    const categories = options.bomAuditCategories
+      .split(",")
+      .map((c) => c.trim())
+      .filter(Boolean);
+    if (categories.length > 0) {
+      activeRules = rules.filter((r) => categories.includes(r.category));
+      if (DEBUG_MODE) {
+        console.log(
+          `Filtering rules by categories: ${categories.join(", ")} (${activeRules.length} active)`,
+        );
+      }
+    }
+  }
+  const allFindings = await evaluateRules(activeRules, bomJson);
+  if (options.bomAuditMinSeverity) {
+    const minSeverity = options.bomAuditMinSeverity.toLowerCase();
+    const severityThreshold = { low: 0, medium: 1, high: 2, critical: 3 };
+    const threshold = severityThreshold[minSeverity] ?? 0;
+    findings.push(
+      ...allFindings.filter((f) => severityThreshold[f.severity] >= threshold),
+    );
+  } else {
+    findings.push(...allFindings);
+  }
+  if (DEBUG_MODE) {
+    console.log(
+      `Formulation audit complete: ${findings.length} finding(s) from ${activeRules.length} rule(s)`,
+    );
+  }
+
+  return findings;
+}
+
+/**
+ * Format findings for console output with color-coded severity
+ */
+export function formatConsoleOutput(findings) {
+  if (!findings?.length) {
+    return "";
+  }
+  const config = {
+    columnDefault: { wrapWord: true, width: 100 },
+    columns: [
+      { width: 10 },
+      { width: 35 },
+      { width: 50 },
+      { width: 50 },
+      { width: 60 },
+    ],
+    header: {
+      alignment: "center",
+      content: "BOM Audit Findings\nGenerated with \u2665  by cdxgen",
+    },
+  };
+  const data = [["Rule", "Message", "Description", "Ref", "File"]];
+  for (const f of findings) {
+    const line = [];
+    line.push(f.ruleId);
+    line.push(f.message);
+    line.push(f.description || "");
+    line.push(f.location?.purl || f.location?.bomRef || "");
+    line.push(f.location?.file || "");
+    data.push(line);
+  }
+  console.log(table(data, config));
+}
+
+/**
+ * Convert findings to CycloneDX annotations
+ */
+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?.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);
+        properties.push({
+          name: `cdx:audit:evidence:${key}`,
+          value: propValue,
+        });
+      }
+    }
+    return {
+      subjects,
+      annotator: {
+        component: cdxgenAnnotator[0],
+      },
+      timestamp: getTimestamp(),
+      text: `${f.message}\n${CODE_BLOCK}\n${JSON.stringify(properties)}\n${CODE_BLOCK}`,
+    };
+  });
+}
+
+/**
+ * Check if any findings meet the severity threshold for secure mode failure
+ */
+export function hasCriticalFindings(findings, options) {
+  if (!findings?.length) {
+    return false;
+  }
+  const failSeverity = options.bomAuditFailSeverity || "high";
+  const severityOrder = { low: 0, medium: 1, high: 2, critical: 3 };
+  const threshold = severityOrder[failSeverity] ?? severityOrder.high;
+  return findings.some((f) => (severityOrder[f.severity] ?? 0) >= threshold);
+}

package/lib/stages/postgen/auditBom.poku.js

@@ -0,0 +1,378 @@
+import { join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { assert, describe, it } from "poku";
+
+import {
+  auditBom,
+  formatAnnotations,
+  hasCriticalFindings,
+} from "./auditBom.js";
+import { evaluateRule, evaluateRules, loadRules } from "./ruleEngine.js";
+
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const RULES_DIR = join(__dirname, "..", "..", "..", "data", "rules");
+
+function makeBom(components = [], workflows = []) {
+  return {
+    bomFormat: "CycloneDX",
+    specVersion: "1.6",
+    serialNumber: "urn:uuid:test-bom",
+    metadata: {
+      tools: {
+        components: [
+          {
+            type: "application",
+            name: "cdxgen",
+            version: "11.0.0",
+            "bom-ref": "pkg:npm/%40cyclonedx/cdxgen@11.0.0",
+          },
+        ],
+      },
+      component: {
+        name: "test-project",
+        type: "application",
+        "bom-ref": "pkg:npm/test-project@1.0.0",
+      },
+    },
+    components,
+    formulation: workflows.length ? [{ workflows }] : undefined,
+  };
+}
+
+function makeComponent(name, version, properties) {
+  return {
+    type: "library",
+    name,
+    version,
+    purl: `pkg:npm/${name}@${version}`,
+    "bom-ref": `pkg:npm/${name}@${version}`,
+    properties: properties.map(([k, v]) => ({ name: k, value: v })),
+  };
+}
+
+describe("loadRules", () => {
+  it("should load built-in rules from the data/rules directory", async () => {
+    const rules = await loadRules(RULES_DIR);
+    assert.ok(rules.length > 0, "Should load at least one rule");
+    for (const rule of rules) {
+      assert.ok(rule.id, "Each rule must have an id");
+      assert.ok(rule.condition, "Each rule must have a condition");
+      assert.ok(rule.message, "Each rule must have a message");
+      assert.ok(
+        ["critical", "high", "medium", "low"].includes(rule.severity),
+        `Rule ${rule.id} severity must be valid`,
+      );
+    }
+  });
+
+  it("should return empty array for non-existent directory", async () => {
+    const rules = await loadRules("/tmp/non-existent-rules-dir-12345");
+    assert.deepStrictEqual(rules, []);
+  });
+
+  it("should load rules with all required fields", async () => {
+    const rules = await loadRules(RULES_DIR);
+    const ciRules = rules.filter((r) => r.category === "ci-permission");
+    assert.ok(ciRules.length > 0, "Should have CI permission rules");
+    const depRules = rules.filter((r) => r.category === "dependency-source");
+    assert.ok(depRules.length > 0, "Should have dependency source rules");
+    const intRules = rules.filter((r) => r.category === "package-integrity");
+    assert.ok(intRules.length > 0, "Should have package integrity rules");
+  });
+});
+
+describe("evaluateRule", () => {
+  it("should detect unpinned action with write permissions (CI-001)", async () => {
+    const rules = await loadRules(RULES_DIR);
+    const rule = rules.find((r) => r.id === "CI-001");
+    assert.ok(rule, "CI-001 rule should exist");
+
+    const bom = makeBom([
+      makeComponent("actions/setup-node", "v3", [
+        ["cdx:github:action:isShaPinned", "false"],
+        ["cdx:github:workflow:hasWritePermissions", "true"],
+        ["cdx:github:action:uses", "actions/setup-node@v3"],
+        ["cdx:github:action:versionPinningType", "tag"],
+      ]),
+    ]);
+
+    const findings = await evaluateRule(rule, bom);
+    assert.ok(findings.length > 0, "Should find unpinned action");
+    assert.strictEqual(findings[0].ruleId, "CI-001");
+    assert.strictEqual(findings[0].severity, "high");
+  });
+
+  it("should not flag SHA-pinned actions for CI-001", async () => {
+    const rules = await loadRules(RULES_DIR);
+    const rule = rules.find((r) => r.id === "CI-001");
+
+    const bom = makeBom([
+      makeComponent("actions/setup-node", "v3", [
+        ["cdx:github:action:isShaPinned", "true"],
+        ["cdx:github:workflow:hasWritePermissions", "true"],
+        ["cdx:github:action:uses", "actions/setup-node@abc123"],
+      ]),
+    ]);
+
+    const findings = await evaluateRule(rule, bom);
+    assert.strictEqual(
+      findings.length,
+      0,
+      "SHA-pinned action should not trigger",
+    );
+  });
+
+  it("should detect npm install script from non-registry source (PKG-001)", async () => {
+    const rules = await loadRules(RULES_DIR);
+    const rule = rules.find((r) => r.id === "PKG-001");
+    assert.ok(rule, "PKG-001 rule should exist");
+
+    const bom = makeBom([
+      makeComponent("sketchy-pkg", "1.0.0", [
+        ["cdx:npm:hasInstallScript", "true"],
+        ["cdx:npm:isRegistryDependency", "false"],
+      ]),
+    ]);
+
+    const findings = await evaluateRule(rule, bom);
+    assert.ok(findings.length > 0, "Should detect install script risk");
+    assert.strictEqual(findings[0].severity, "high");
+  });
+
+  it("should detect npm name mismatch (INT-002)", async () => {
+    const rules = await loadRules(RULES_DIR);
+    const rule = rules.find((r) => r.id === "INT-002");
+    assert.ok(rule, "INT-002 rule should exist");
+
+    const bom = makeBom([
+      makeComponent("suspicious-pkg", "1.0.0", [
+        [
+          "cdx:npm:nameMismatchError",
+          "Expected 'real-pkg', found 'suspicious-pkg'",
+        ],
+      ]),
+    ]);
+
+    const findings = await evaluateRule(rule, bom);
+    assert.ok(findings.length > 0, "Should detect name mismatch");
+    assert.strictEqual(findings[0].severity, "high");
+  });
+
+  it("should detect yanked Ruby gem (INT-004)", async () => {
+    const rules = await loadRules(RULES_DIR);
+    const rule = rules.find((r) => r.id === "INT-004");
+    assert.ok(rule, "INT-004 rule should exist");
+
+    const bom = makeBom([
+      {
+        type: "library",
+        name: "bad-gem",
+        version: "0.5.0",
+        purl: "pkg:gem/bad-gem@0.5.0",
+        "bom-ref": "pkg:gem/bad-gem@0.5.0",
+        properties: [{ name: "cdx:gem:yanked", value: "true" }],
+      },
+    ]);
+
+    const findings = await evaluateRule(rule, bom);
+    assert.ok(findings.length > 0, "Should detect yanked gem");
+    assert.strictEqual(findings[0].severity, "high");
+  });
+
+  it("should return empty findings when no components match", async () => {
+    const rules = await loadRules(RULES_DIR);
+    const rule = rules.find((r) => r.id === "CI-001");
+
+    const bom = makeBom([]);
+    const findings = await evaluateRule(rule, bom);
+    assert.strictEqual(findings.length, 0, "No components means no findings");
+  });
+});
+
+describe("evaluateRules", () => {
+  it("should sort findings by severity (high before medium before low)", async () => {
+    const rules = await loadRules(RULES_DIR);
+    const bom = makeBom([
+      makeComponent("actions/checkout", "v3", [
+        ["cdx:github:action:isShaPinned", "false"],
+        ["cdx:github:workflow:hasWritePermissions", "true"],
+        ["cdx:github:action:uses", "actions/checkout@v3"],
+        ["cdx:github:action:versionPinningType", "tag"],
+      ]),
+      makeComponent("deprecated-go-mod", "1.0.0", [
+        ["cdx:go:deprecated", "use other-module instead"],
+      ]),
+    ]);
+
+    const findings = await evaluateRules(rules, bom);
+    if (findings.length >= 2) {
+      const severityOrder = { critical: 0, high: 1, medium: 2, low: 3 };
+      for (let i = 1; i < findings.length; i++) {
+        const prev = severityOrder[findings[i - 1].severity] ?? 4;
+        const curr = severityOrder[findings[i].severity] ?? 4;
+        assert.ok(
+          prev <= curr,
+          `Finding ${i - 1} severity (${findings[i - 1].severity}) should be >= severity of finding ${i} (${findings[i].severity})`,
+        );
+      }
+    }
+  });
+});
+
+describe("auditBom", () => {
+  it("should run audit and return findings", async () => {
+    const bom = makeBom([
+      makeComponent("actions/setup-node", "v3", [
+        ["cdx:github:action:isShaPinned", "false"],
+        ["cdx:github:workflow:hasWritePermissions", "true"],
+        ["cdx:github:action:uses", "actions/setup-node@v3"],
+        ["cdx:github:action:versionPinningType", "tag"],
+      ]),
+    ]);
+
+    const findings = await auditBom(bom, {});
+    assert.ok(findings.length > 0, "Should find at least one issue");
+  });
+
+  it("should return empty array for null bom", async () => {
+    const findings = await auditBom(null, {});
+    assert.deepStrictEqual(findings, []);
+  });
+
+  it("should filter by category", async () => {
+    const bom = makeBom([
+      makeComponent("actions/setup-node", "v3", [
+        ["cdx:github:action:isShaPinned", "false"],
+        ["cdx:github:workflow:hasWritePermissions", "true"],
+        ["cdx:github:action:uses", "actions/setup-node@v3"],
+        ["cdx:github:action:versionPinningType", "tag"],
+      ]),
+      makeComponent("sketchy-pkg", "1.0.0", [
+        ["cdx:npm:hasInstallScript", "true"],
+        ["cdx:npm:isRegistryDependency", "false"],
+      ]),
+    ]);
+
+    const ciOnly = await auditBom(bom, {
+      bomAuditCategories: "ci-permission",
+    });
+    for (const f of ciOnly) {
+      assert.strictEqual(f.category, "ci-permission");
+    }
+  });
+
+  it("should filter by minimum severity", async () => {
+    const bom = makeBom([
+      makeComponent("actions/setup-node", "v3", [
+        ["cdx:github:action:isShaPinned", "false"],
+        ["cdx:github:workflow:hasWritePermissions", "true"],
+        ["cdx:github:action:uses", "actions/setup-node@v3"],
+        ["cdx:github:action:versionPinningType", "tag"],
+      ]),
+    ]);
+
+    const highOnly = await auditBom(bom, {
+      bomAuditMinSeverity: "high",
+    });
+    for (const f of highOnly) {
+      assert.strictEqual(f.severity, "high");
+    }
+  });
+});
+
+describe("formatAnnotations", () => {
+  it("should create CycloneDX annotations from findings", () => {
+    const bom = makeBom([]);
+    const findings = [
+      {
+        ruleId: "CI-001",
+        name: "Unpinned action",
+        severity: "high",
+        category: "ci-permission",
+        message: "Unpinned GitHub Action detected",
+        mitigation: "Pin to SHA",
+      },
+    ];
+    const annotations = formatAnnotations(findings, bom);
+    assert.strictEqual(annotations.length, 1);
+    assert.ok(
+      annotations[0].text.startsWith("Unpinned GitHub Action detected"),
+    );
+    assert.ok(
+      annotations[0].annotator.component,
+      "Annotation should have annotator component",
+    );
+    assert.ok(annotations[0].subjects.includes(bom.serialNumber));
+  });
+
+  it("should return empty array when cdxgen tool component is missing", () => {
+    const bom = {
+      serialNumber: "urn:uuid:test",
+      metadata: { tools: { components: [] } },
+      components: [],
+    };
+    const findings = [
+      {
+        ruleId: "CI-001",
+        severity: "high",
+        category: "ci-permission",
+        message: "test",
+      },
+    ];
+    const annotations = formatAnnotations(findings, bom);
+    assert.deepStrictEqual(annotations, []);
+  });
+
+  it("should return empty array when metadata.tools is undefined", () => {
+    const bom = {
+      serialNumber: "urn:uuid:test",
+      metadata: {},
+      components: [],
+    };
+    const annotations = formatAnnotations(
+      [{ ruleId: "X", severity: "low", category: "test", message: "test" }],
+      bom,
+    );
+    assert.deepStrictEqual(annotations, []);
+  });
+});
+
+describe("hasCriticalFindings", () => {
+  it("should return true when high severity findings exist", () => {
+    const findings = [{ severity: "high" }];
+    assert.ok(hasCriticalFindings(findings, {}));
+  });
+
+  it("should return false when only low severity findings exist", () => {
+    const findings = [{ severity: "low" }];
+    assert.ok(!hasCriticalFindings(findings, {}));
+  });
+
+  it("should use threshold semantics (at or above)", () => {
+    const findings = [{ severity: "high" }];
+    // medium threshold should catch high findings
+    assert.ok(
+      hasCriticalFindings(findings, { bomAuditFailSeverity: "medium" }),
+    );
+    // high threshold should catch high findings
+    assert.ok(hasCriticalFindings(findings, { bomAuditFailSeverity: "high" }));
+    // critical threshold should NOT catch high findings
+    assert.ok(
+      !hasCriticalFindings(findings, { bomAuditFailSeverity: "critical" }),
+    );
+  });
+
+  it("should respect custom fail severity for medium", () => {
+    const findings = [{ severity: "medium" }];
+    assert.ok(
+      hasCriticalFindings(findings, { bomAuditFailSeverity: "medium" }),
+    );
+    assert.ok(!hasCriticalFindings(findings, { bomAuditFailSeverity: "high" }));
+  });
+
+  it("should return false for empty findings", () => {
+    assert.ok(!hasCriticalFindings([], {}));
+    assert.ok(!hasCriticalFindings(null, {}));
+  });
+});

package/lib/stages/postgen/postgen.js

@@ -4,6 +4,8 @@ import process from "node:process";
 
 import { PackageURL } from "packageurl-js";
 
+import { mergeDependencies } from "../../helpers/depsUtils.js";
+import { addFormulationSection } from "../../helpers/formulationParsers.js";
 import { thoughtLog } from "../../helpers/logger.js";
 import {
   DEBUG_MODE,
@@ -41,6 +43,44 @@ function relativeDir(d, options) {
   return d;
 }
 
+/**
+ * Attach the CycloneDX formulation section to an already-built BOM JSON object.
+ *
+ * This is intentionally called once, from {@link postProcess}, so that the
+ * formulation section is added exactly once regardless of how many per-language
+ * `buildBomNSData` calls were made during BOM generation.
+ *
+ * @param {Object} bomJson       The assembled BOM JSON object (mutated in place).
+ * @param {Object} options       CLI options.
+ * @param {string} filePath      File path.
+ * @param {Array}  [formulationList]  Optional language-specific formulation
+ *                               data (e.g. from Pixi) carried on `bomNSData`.
+ * @returns {Object} The same `bomJson` with `formulation` populated.
+ */
+function applyFormulation(bomJson, options, filePath, formulationList) {
+  if (
+    !options.includeFormulation ||
+    options.specVersion < 1.5 ||
+    !bomJson ||
+    bomJson.formulation !== undefined
+  ) {
+    return bomJson;
+  }
+  const context = formulationList?.length ? { formulationList } : {};
+  const formulationData = addFormulationSection(filePath, options, context);
+  if (!formulationData) {
+    return bomJson;
+  }
+  bomJson.formulation = formulationData.formulation;
+  if (formulationData.dependencies?.length) {
+    bomJson.dependencies = mergeDependencies(
+      bomJson.dependencies || [],
+      formulationData.dependencies,
+    );
+  }
+  return bomJson;
+}
+
 /**
  * Filter and enhance BOM post generation.
  *
@@ -49,7 +89,7 @@ function relativeDir(d, options) {
  *
  * @returns {Object} Modified bomNSData
  */
-export function postProcess(bomNSData, options) {
+export function postProcess(bomNSData, options, filePath) {
   let jsonPayload = bomNSData.bomJson;
   if (
     typeof bomNSData.bomJson === "string" ||
@@ -61,6 +101,12 @@ export function postProcess(bomNSData, options) {
   bomNSData.bomJson = filterBom(jsonPayload, options);
   bomNSData.bomJson = applyStandards(bomNSData.bomJson, options);
   bomNSData.bomJson = applyMetadata(bomNSData.bomJson, options);
+  bomNSData.bomJson = applyFormulation(
+    bomNSData.bomJson,
+    options,
+    filePath,
+    bomNSData.formulationList,
+  );
   // Support for automatic annotations
   if (options.specVersion >= 1.6) {
     bomNSData.bomJson = annotate(bomNSData.bomJson, options);
@@ -494,6 +540,13 @@ export function cleanupEnv(_options) {
   }
 }
 
+/**
+ * Removes the cdxgen temporary directory if it was created inside the system
+ * temp directory (as indicated by `CDXGEN_TMP_DIR`). No-ops when the variable
+ * is unset or points outside the system temp directory.
+ *
+ * @returns {void}
+ */
 export function cleanupTmpDir() {
   if (process.env?.CDXGEN_TMP_DIR?.startsWith(getTmpDir())) {
     rmSync(process.env.CDXGEN_TMP_DIR, { recursive: true, force: true });