@cyclonedx/cdxgen 12.1.5 → 12.2.0

package/lib/{helpers/validator.js → validator/bomValidator.js}

@@ -5,8 +5,8 @@ import Ajv from "ajv";
 import addFormats from "ajv-formats";
 import { PackageURL } from "packageurl-js";
 
-import { thoughtLog } from "./logger.js";
-import { DEBUG_MODE, dirNameStr, isPartialTree } from "./utils.js";
+import { thoughtLog } from "../helpers/logger.js";
+import { DEBUG_MODE, dirNameStr, isPartialTree } from "../helpers/utils.js";
 
 const dirName = dirNameStr;
 const PLACEHOLDER_COMPONENT_NAMES = new Set(["app", "application", "project"]);
@@ -194,51 +194,53 @@ export const validatePurls = (bomJson) => {
         }
       } else {
         try {
-          const purlObj = PackageURL.fromString(comp.purl);
-          if (purlObj.type && purlObj.type !== purlObj.type.toLowerCase()) {
-            warningsList.push(
-              `purl type is not normalized to lower case ${comp.purl}`,
-            );
-          }
-          if (
-            ["npm", "golang"].includes(purlObj.type) &&
-            purlObj.name.includes("%2F") &&
-            !purlObj.namespace
-          ) {
-            errorList.push(
-              `purl does not include namespace but includes encoded slash in name for npm type. ${comp.purl}`,
-            );
-          }
-          // Catch the trivy version hack that removes the epoch from version
-          const qualifiers = purlObj.qualifiers || {};
-          if (
-            Object.keys(qualifiers).length &&
-            [
-              "cargo",
-              "cocoapods",
-              "composer",
-              "cran",
-              "github",
-              "golang",
-              "hackage",
-              "nuget",
-              "opam",
-              "pub",
-              "qpkg",
-              "swift",
-            ].includes(purlObj.type)
-          ) {
-            warningsList.push(
-              `Qualifiers are usually not expected for the PURL type: ${purlObj.type}. Purl: ${comp.purl}, Qualifiers: ${Object.keys(qualifiers).join(", ")}.`,
-            );
-          }
-          if (
-            qualifiers.epoch &&
-            !comp.version.startsWith(`${qualifiers.epoch}:`)
-          ) {
-            errorList.push(
-              `'${comp.name}' version '${comp.version}' doesn't include epoch '${qualifiers.epoch}'.`,
-            );
+          if (comp.purl) {
+            const purlObj = PackageURL.fromString(comp.purl);
+            if (purlObj.type && purlObj.type !== purlObj.type.toLowerCase()) {
+              warningsList.push(
+                `purl type is not normalized to lower case ${comp.purl}`,
+              );
+            }
+            if (
+              ["npm", "golang"].includes(purlObj.type) &&
+              purlObj.name.includes("%2F") &&
+              !purlObj.namespace
+            ) {
+              errorList.push(
+                `purl does not include namespace but includes encoded slash in name for npm type. ${comp.purl}`,
+              );
+            }
+            // Catch the trivy version hack that removes the epoch from version
+            const qualifiers = purlObj.qualifiers || {};
+            if (
+              Object.keys(qualifiers).length &&
+              [
+                "cargo",
+                "cocoapods",
+                "composer",
+                "cran",
+                "github",
+                "golang",
+                "hackage",
+                "nuget",
+                "opam",
+                "pub",
+                "qpkg",
+                "swift",
+              ].includes(purlObj.type)
+            ) {
+              warningsList.push(
+                `SPEC VIOLATION: Qualifiers are not expected for ${purlObj.type} type. Purl: ${comp.purl}, Qualifier(s): ${Object.keys(qualifiers).join(", ")}.`,
+              );
+            }
+            if (
+              qualifiers.epoch &&
+              !comp.version.startsWith(`${qualifiers.epoch}:`)
+            ) {
+              errorList.push(
+                `'${comp.name}' version '${comp.version}' doesn't include epoch '${qualifiers.epoch}'.`,
+              );
+            }
           }
         } catch (_ex) {
           errorList.push(`Invalid purl ${comp.purl}`);
@@ -283,6 +285,25 @@ const buildRefs = (bomJson) => {
         refMap[comp["bom-ref"]] = true;
       }
     }
+    if (bomJson?.formulation) {
+      for (const aformulation of bomJson.formulation) {
+        if (aformulation?.components?.length) {
+          for (const formComp of aformulation.components) {
+            refMap[formComp["bom-ref"]] = true;
+          }
+        }
+        if (aformulation?.workflows?.length) {
+          for (const formWf of aformulation.workflows) {
+            refMap[formWf["bom-ref"]] = true;
+            if (formWf?.tasks?.length) {
+              for (const atask of formWf.tasks) {
+                refMap[atask["bom-ref"]] = true;
+              }
+            }
+          }
+        }
+      }
+    }
   }
   return refMap;
 };
@@ -392,6 +413,8 @@ export function validateProps(bomJson) {
   let lacksProperties = false;
   let lacksEvidence = false;
   let lacksRelativePath = false;
+  let npmComponentsWithoutTarball = 0;
+  let npmComponentsWithTarball = 0;
   if (
     !["application", "framework", "library"].includes(
       bomJson?.metadata?.component?.type,
@@ -400,6 +423,28 @@ export function validateProps(bomJson) {
     return true;
   }
   if (bomJson?.components) {
+    const npmPkgs =
+      bomJson.components?.filter((c) => c.purl?.startsWith("pkg:npm")) || [];
+    const nativeByName = new Set(
+      npmPkgs
+        .filter((c) =>
+          c.properties?.some(
+            (p) => p.name === "cdx:npm:native_addon" && p.value === "true",
+          ),
+        )
+        .map((c) => c.name),
+    );
+    const suspicious = npmPkgs.filter(
+      (c) =>
+        (c.name.includes("native") || c.name.includes("bindings")) &&
+        !nativeByName.has(c.name) &&
+        !c.properties?.some((p) => p.name === "cdx:npm:native_addon"),
+    );
+    if (suspicious.length > 0 && DEBUG_MODE) {
+      warningsList.push(
+        `Found ${suspicious.length} packages with native-sounding names but no native_addon flag: ${suspicious.map((c) => c.name).join(", ")}. May need deeper inspection.`,
+      );
+    }
     for (const comp of bomJson.components) {
       if (!["library", "framework"].includes(comp.type)) {
         continue;
@@ -411,6 +456,16 @@ export function validateProps(bomJson) {
       ) {
         continue;
       }
+      if (comp.purl?.startsWith("pkg:npm")) {
+        const hasDistributionRef = comp.externalReferences?.some(
+          (ref) => ref.type === "distribution" && ref.url,
+        );
+        if (hasDistributionRef) {
+          npmComponentsWithTarball++;
+        } else {
+          npmComponentsWithoutTarball++;
+        }
+      }
       if (!comp.properties) {
         if (!lacksProperties) {
           warningsList.push(`${comp["bom-ref"]} lacks properties.`);
@@ -453,6 +508,11 @@ export function validateProps(bomJson) {
       }
     }
   }
+  if (npmComponentsWithoutTarball > 0 && npmComponentsWithTarball === 0) {
+    warningsList.push(
+      `Found ${npmComponentsWithoutTarball} pkg:npm components without externalReferences.distribution. Please file a bug, if your package-lock.json or pnpm-lock.yaml includes the tarball url.`,
+    );
+  }
   if (lacksRelativePath) {
     warningsList.push(
       "BOM includes absolute paths for properties like SrcFile.",

package/lib/validator/complianceEngine.js

@@ -0,0 +1,241 @@
+/**
+ * Orchestrates evaluation of internal compliance rule packs (SCVS + CRA) and
+ * aggregates results into per-benchmark scorecards.
+ *
+ * This module is deliberately independent of the CycloneDX BOM audit engine
+ * (lib/stages/postgen/auditBom.js). The two engines share similar *Finding*
+ * output shape so reporters can consume either source uniformly.
+ */
+
+import {
+  getAllComplianceRules,
+  getCraRules,
+  getScvsRules,
+} from "./complianceRules.js";
+
+/**
+ * Benchmark alias → rule filter.
+ * Aliases are resolved case-insensitively on the CLI.
+ */
+const BENCHMARKS = {
+  scvs: {
+    id: "scvs",
+    name: "OWASP SCVS (all levels)",
+    standard: "SCVS",
+    filter: (rules) => rules.filter((r) => r.standard === "SCVS"),
+    // All SCVS rules are considered for overall score regardless of level.
+    levelPredicate: () => true,
+  },
+  "scvs-l1": {
+    id: "scvs-l1",
+    name: "OWASP SCVS Level 1",
+    standard: "SCVS",
+    filter: (rules) =>
+      rules.filter(
+        (r) => r.standard === "SCVS" && r.scvsLevels?.includes("L1"),
+      ),
+    levelPredicate: (rule) => rule.scvsLevels?.includes("L1"),
+  },
+  "scvs-l2": {
+    id: "scvs-l2",
+    name: "OWASP SCVS Level 2",
+    standard: "SCVS",
+    filter: (rules) =>
+      rules.filter(
+        (r) => r.standard === "SCVS" && r.scvsLevels?.includes("L2"),
+      ),
+    levelPredicate: (rule) => rule.scvsLevels?.includes("L2"),
+  },
+  "scvs-l3": {
+    id: "scvs-l3",
+    name: "OWASP SCVS Level 3",
+    standard: "SCVS",
+    filter: (rules) =>
+      rules.filter(
+        (r) => r.standard === "SCVS" && r.scvsLevels?.includes("L3"),
+      ),
+    levelPredicate: (rule) => rule.scvsLevels?.includes("L3"),
+  },
+  cra: {
+    id: "cra",
+    name: "EU Cyber Resilience Act (SBOM expectations)",
+    standard: "CRA",
+    filter: (rules) => rules.filter((r) => r.standard === "CRA"),
+    levelPredicate: () => true,
+  },
+};
+
+/**
+ * Resolve a benchmark alias (case-insensitive). Returns null when unknown.
+ *
+ * @param {string} alias
+ * @returns {object | null}
+ */
+export function resolveBenchmark(alias) {
+  if (typeof alias !== "string") return null;
+  return BENCHMARKS[alias.trim().toLowerCase()] || null;
+}
+
+/**
+ * List all known benchmark aliases in a stable display order.
+ *
+ * @returns {Array<object>}
+ */
+export function listBenchmarks() {
+  return Object.values(BENCHMARKS);
+}
+
+/**
+ * Evaluate one rule against the BOM and return a Finding-shaped object.
+ *
+ * Rules are pure synchronous functions, but we wrap them in try/catch so one
+ * bad rule cannot fail the entire run.
+ *
+ * @param {object} rule
+ * @param {object} bomJson
+ * @returns {object} Finding
+ */
+export function evaluateRule(rule, bomJson) {
+  let result;
+  try {
+    result = rule.evaluate(bomJson);
+  } catch (err) {
+    result = {
+      status: "fail",
+      message: `Rule evaluation threw: ${err?.message || err}`,
+    };
+  }
+  const {
+    status = "fail",
+    message,
+    mitigation,
+    locations,
+    evidence,
+  } = result || {};
+  // Non-automatable rules always emit `info` severity regardless of status.
+  const severity =
+    rule.automatable === false
+      ? "info"
+      : status === "fail"
+        ? rule.severity || "medium"
+        : status === "manual"
+          ? "info"
+          : "info";
+  return {
+    engine: "compliance",
+    ruleId: rule.id,
+    name: rule.name,
+    description: rule.description,
+    category: rule.category,
+    standard: rule.standard,
+    standardRefs: rule.standardRefs || [rule.id],
+    scvsLevels: rule.scvsLevels || [],
+    automatable: rule.automatable !== false,
+    status,
+    severity,
+    message: message || rule.name,
+    mitigation: mitigation || rule.mitigation,
+    locations: Array.isArray(locations) ? locations : [],
+    evidence: evidence && typeof evidence === "object" ? evidence : null,
+  };
+}
+
+/**
+ * Evaluate every rule in the catalog, or a filtered subset.
+ *
+ * @param {object} bomJson CycloneDX BOM
+ * @param {object} [opts]
+ * @param {Array<string>} [opts.categories] Filter to these category values.
+ * @param {Array<string>} [opts.benchmarks] Only run rules from these benchmark aliases.
+ * @returns {Array<object>} Findings (one per rule)
+ */
+export function evaluateAll(bomJson, opts = {}) {
+  let rules = getAllComplianceRules();
+  if (Array.isArray(opts.categories) && opts.categories.length > 0) {
+    const wanted = new Set(opts.categories.map((c) => c.toLowerCase()));
+    rules = rules.filter((r) => wanted.has((r.category || "").toLowerCase()));
+  }
+  if (Array.isArray(opts.benchmarks) && opts.benchmarks.length > 0) {
+    const selected = new Set();
+    for (const alias of opts.benchmarks) {
+      const bench = resolveBenchmark(alias);
+      if (bench) {
+        for (const r of bench.filter(rules)) {
+          selected.add(r.id);
+        }
+      }
+    }
+    rules = rules.filter((r) => selected.has(r.id));
+  }
+  return rules.map((r) => evaluateRule(r, bomJson));
+}
+
+/**
+ * Produce a scorecard for a single benchmark against a set of already-evaluated
+ * findings. Scoring rules:
+ *   - pass      counts as 1 / 1.
+ *   - fail      counts as 0 / 1.
+ *   - manual    is excluded from the percentage but counted separately.
+ *
+ * This mirrors how OWASP SCVS publishes results: automatable controls score a
+ * percentage, manual controls are reported so reviewers can address them.
+ *
+ * @param {object} benchmark Result of resolveBenchmark
+ * @param {Array<object>} findings Full set of findings from evaluateAll
+ * @returns {object}
+ */
+export function scoreBenchmark(benchmark, findings) {
+  const catalog = benchmark.filter(getAllComplianceRules());
+  const byId = new Map(findings.map((f) => [f.ruleId, f]));
+  const controls = [];
+  let pass = 0;
+  let failed = 0;
+  let manual = 0;
+  for (const rule of catalog) {
+    const f = byId.get(rule.id) || evaluateRule(rule, {});
+    controls.push({
+      id: rule.id,
+      name: rule.name,
+      standardRefs: rule.standardRefs,
+      status: f.status,
+      severity: f.severity,
+      automatable: rule.automatable !== false,
+      message: f.message,
+    });
+    if (f.status === "pass") pass += 1;
+    else if (f.status === "fail") failed += 1;
+    else manual += 1;
+  }
+  const automatable = pass + failed;
+  const scorePct =
+    automatable === 0 ? 0 : Math.round((pass / automatable) * 100);
+  return {
+    id: benchmark.id,
+    name: benchmark.name,
+    standard: benchmark.standard,
+    totalControls: catalog.length,
+    pass,
+    fail: failed,
+    manual,
+    automatable,
+    scorePct,
+    controls,
+  };
+}
+
+/**
+ * Build scorecards for each requested benchmark. When no benchmarks are
+ * specified, returns scorecards for every built-in benchmark alias.
+ *
+ * @param {Array<object>} findings
+ * @param {Array<string>} [requestedAliases]
+ * @returns {Array<object>}
+ */
+export function buildBenchmarkReports(findings, requestedAliases) {
+  const aliases = requestedAliases?.length
+    ? requestedAliases.map((a) => resolveBenchmark(a)).filter(Boolean)
+    : Object.values(BENCHMARKS);
+  return aliases.map((b) => scoreBenchmark(b, findings));
+}
+
+export { getAllComplianceRules, getCraRules, getScvsRules };

package/lib/validator/complianceEngine.poku.js

@@ -0,0 +1,168 @@
+import { assert, describe, it } from "poku";
+
+import {
+  buildBenchmarkReports,
+  evaluateAll,
+  evaluateRule,
+  listBenchmarks,
+  resolveBenchmark,
+  scoreBenchmark,
+} from "./complianceEngine.js";
+import { getAllComplianceRules } from "./complianceRules.js";
+
+function richBom() {
+  return {
+    bomFormat: "CycloneDX",
+    specVersion: "1.6",
+    serialNumber: "urn:uuid:1b671687-395b-41f5-a30f-a58921a69b79",
+    metadata: {
+      timestamp: "2024-02-02T00:00:00Z",
+      tools: {
+        components: [
+          { type: "application", name: "cdxgen", version: "12.0.0" },
+        ],
+      },
+      component: {
+        name: "demo",
+        version: "1.0.0",
+        type: "application",
+        "bom-ref": "pkg:generic/demo@1.0.0",
+      },
+      supplier: {
+        name: "Acme",
+        contact: [{ email: "psirt@example.com" }],
+      },
+    },
+    components: [
+      {
+        type: "library",
+        name: "lodash",
+        version: "4.17.21",
+        purl: "pkg:npm/lodash@4.17.21",
+        "bom-ref": "pkg:npm/lodash@4.17.21",
+        licenses: [{ license: { id: "MIT" } }],
+        hashes: [{ alg: "SHA-256", content: "x" }],
+        copyright: "© OpenJS",
+      },
+    ],
+    dependencies: [
+      { ref: "pkg:generic/demo@1.0.0", dependsOn: ["pkg:npm/lodash@4.17.21"] },
+    ],
+  };
+}
+
+describe("complianceEngine.resolveBenchmark/listBenchmarks", () => {
+  it("resolves known aliases case-insensitively", () => {
+    for (const alias of ["scvs", "scvs-l1", "SCVS-L2", "cra"]) {
+      const b = resolveBenchmark(alias);
+      assert.ok(b, `expected resolution for ${alias}`);
+      assert.ok(typeof b.filter === "function");
+    }
+  });
+  it("returns null for unknown aliases", () => {
+    assert.strictEqual(resolveBenchmark("ntia"), null);
+    assert.strictEqual(resolveBenchmark(null), null);
+    assert.strictEqual(resolveBenchmark(42), null);
+  });
+  it("listBenchmarks exposes all aliases", () => {
+    const ids = listBenchmarks().map((b) => b.id);
+    assert.ok(ids.includes("scvs"));
+    assert.ok(ids.includes("scvs-l1"));
+    assert.ok(ids.includes("scvs-l2"));
+    assert.ok(ids.includes("scvs-l3"));
+    assert.ok(ids.includes("cra"));
+  });
+});
+
+describe("complianceEngine.evaluateRule", () => {
+  it("marks non-automatable rules as info severity regardless of status", () => {
+    const rule = getAllComplianceRules().find((r) => r.automatable === false);
+    const f = evaluateRule(rule, richBom());
+    assert.strictEqual(f.severity, "info");
+    assert.strictEqual(f.status, "manual");
+    assert.strictEqual(f.automatable, false);
+  });
+
+  it("converts a throwing rule into a fail finding", () => {
+    const broken = {
+      id: "TEST-001",
+      name: "broken",
+      description: "",
+      standard: "SCVS",
+      standardRefs: ["TEST-001"],
+      category: "x",
+      severity: "high",
+      scvsLevels: [],
+      automatable: true,
+      evaluate: () => {
+        throw new Error("boom");
+      },
+    };
+    const f = evaluateRule(broken, {});
+    assert.strictEqual(f.status, "fail");
+    assert.match(f.message, /boom/);
+  });
+});
+
+describe("complianceEngine.evaluateAll", () => {
+  it("returns one finding per rule with no filters", () => {
+    const findings = evaluateAll(richBom());
+    assert.strictEqual(findings.length, getAllComplianceRules().length);
+  });
+
+  it("filters by category", () => {
+    const cra = evaluateAll(richBom(), { categories: ["compliance-cra"] });
+    assert.ok(cra.length > 0);
+    for (const f of cra) {
+      assert.strictEqual(f.category, "compliance-cra");
+    }
+  });
+
+  it("filters by benchmark alias", () => {
+    const l1 = evaluateAll(richBom(), { benchmarks: ["scvs-l1"] });
+    for (const f of l1) {
+      assert.ok(f.scvsLevels.includes("L1"));
+    }
+    assert.ok(l1.length < getAllComplianceRules().length);
+  });
+});
+
+describe("complianceEngine.scoreBenchmark", () => {
+  it("computes per-benchmark pass/fail/manual totals", () => {
+    const findings = evaluateAll(richBom());
+    const cra = resolveBenchmark("cra");
+    const report = scoreBenchmark(cra, findings);
+    assert.strictEqual(report.id, "cra");
+    assert.strictEqual(
+      report.totalControls,
+      report.pass + report.fail + report.manual,
+    );
+    assert.ok(report.scorePct >= 0 && report.scorePct <= 100);
+    // On the rich BOM every CRA rule should pass.
+    assert.strictEqual(report.fail, 0);
+    assert.strictEqual(report.scorePct, 100);
+  });
+
+  it("scores 0% when all automatable rules fail", () => {
+    const scvs = resolveBenchmark("scvs-l1");
+    const empty = { bomFormat: "CycloneDX", specVersion: "1.6" };
+    const findings = evaluateAll(empty);
+    const report = scoreBenchmark(scvs, findings);
+    assert.ok(report.fail > 0);
+    assert.ok(report.scorePct < 100);
+  });
+});
+
+describe("complianceEngine.buildBenchmarkReports", () => {
+  it("returns every benchmark when none requested", () => {
+    const findings = evaluateAll(richBom());
+    const reports = buildBenchmarkReports(findings);
+    assert.strictEqual(reports.length, listBenchmarks().length);
+  });
+  it("returns only requested benchmarks and skips unknown aliases", () => {
+    const findings = evaluateAll(richBom());
+    const reports = buildBenchmarkReports(findings, ["scvs-l1", "unknown"]);
+    assert.strictEqual(reports.length, 1);
+    assert.strictEqual(reports[0].id, "scvs-l1");
+  });
+});