@cyclonedx/cdxgen 12.1.5 → 12.2.0

package/lib/validator/reporters/annotations.js

@@ -0,0 +1,121 @@
+/**
+ * CycloneDX annotation reporter — embeds findings as `annotations[]` entries
+ * on a copy of the input BOM. Can be reused by `bom-audit`.
+ *
+ * CycloneDX supports the annotation schema from spec version 1.5 onward.
+ */
+
+import { DEBUG_MODE, getTimestamp } from "../../helpers/utils.js";
+
+const SUPPORTED_FROM = 1.5;
+const CODE_BLOCK = "```";
+
+/**
+ * Render a set of findings into CycloneDX annotations.
+ *
+ * @param {Array<object>} findings Finding objects emitted by the validator or auditBom engine.
+ * @param {object} bomJson Full CycloneDX BOM (needed for annotator/subject wiring).
+ * @returns {Array<object>} CycloneDX annotation objects.
+ */
+export function buildAnnotations(findings, bomJson) {
+  if (!findings?.length || !bomJson) {
+    return [];
+  }
+  const specVersion = Number.parseFloat(bomJson.specVersion);
+  if (Number.isNaN(specVersion) || specVersion < SUPPORTED_FROM) {
+    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 [];
+  }
+  const subjects = [bomJson.serialNumber];
+  const timestamp = getTimestamp();
+  return findings.map((f) => {
+    const properties = [
+      { name: "cdx:validate:engine", value: f.engine || "compliance" },
+      { name: "cdx:validate:ruleId", value: f.ruleId },
+      { name: "cdx:validate:status", value: f.status },
+      { name: "cdx:validate:severity", value: f.severity },
+    ];
+    if (f.standard) {
+      properties.push({ name: "cdx:validate:standard", value: f.standard });
+    }
+    if (f.standardRefs?.length) {
+      properties.push({
+        name: "cdx:validate:standardRefs",
+        value: f.standardRefs.join(","),
+      });
+    }
+    if (f.category) {
+      properties.push({ name: "cdx:validate:category", value: f.category });
+    }
+    if (f.mitigation) {
+      properties.push({ name: "cdx:validate:mitigation", value: f.mitigation });
+    }
+    if (f.scvsLevels?.length) {
+      properties.push({
+        name: "cdx:validate:scvsLevels",
+        value: f.scvsLevels.join(","),
+      });
+    }
+    if (f.evidence && typeof f.evidence === "object") {
+      for (const [key, value] of Object.entries(f.evidence)) {
+        properties.push({
+          name: `cdx:validate:evidence:${key}`,
+          value:
+            typeof value === "object" ? JSON.stringify(value) : String(value),
+        });
+      }
+    }
+    return {
+      subjects,
+      annotator: {
+        component: cdxgenAnnotator[0],
+      },
+      timestamp,
+      text: `${f.message}\n${CODE_BLOCK}\n${JSON.stringify(properties)}\n${CODE_BLOCK}`,
+    };
+  });
+}
+
+/**
+ * Produce a new BOM object with findings embedded as annotations. The caller
+ * is responsible for writing the result to disk.
+ *
+ * @param {object} bomJson
+ * @param {Array<object>} findings
+ * @returns {object}
+ */
+export function renderBom(bomJson, findings) {
+  if (!bomJson) {
+    return bomJson;
+  }
+  const annotations = buildAnnotations(findings, bomJson);
+  const next = { ...bomJson };
+  next.annotations = [...(bomJson.annotations || []), ...annotations];
+  return next;
+}
+
+/**
+ * Convenience wrapper matching the signature of the other reporters. The
+ * second argument expects `{ bomJson }` because annotations are BOM-shaped,
+ * not report-shaped.
+ *
+ * @param {object} report Output of validateBomAdvanced().
+ * @param {object} options
+ * @param {object} options.bomJson The BOM to annotate.
+ * @returns {string} JSON string of the annotated BOM.
+ */
+export function render(report, options = {}) {
+  const { bomJson } = options;
+  const annotated = renderBom(bomJson, report.findings || []);
+  return JSON.stringify(annotated, null, null);
+}

package/lib/validator/reporters/console.js

@@ -0,0 +1,149 @@
+/**
+ * Console reporter — renders findings and benchmark scorecards as tables.
+ * Uses the existing `table` dependency (already a cdxgen runtime dependency).
+ */
+
+import { table } from "table";
+
+const SEVERITY_ICONS = {
+  critical: "⛔",
+  high: "🔴",
+  medium: "🟠",
+  low: "🟡",
+  info: "🔵",
+};
+
+/**
+ * @param {object} f Finding
+ * @returns {string}
+ */
+function severityIcon(f) {
+  return SEVERITY_ICONS[f.severity] || "·";
+}
+
+/**
+ * Produce a human-readable summary of findings.
+ *
+ * @param {Array<object>} findings
+ * @param {object} [options]
+ * @returns {string}
+ */
+export function formatFindings(findings, options = {}) {
+  if (!findings || findings.length === 0) {
+    return "No findings.";
+  }
+  const data = [["", "Rule", "Status", "Severity", "Standard", "Message"]];
+  for (const f of findings) {
+    data.push([
+      severityIcon(f),
+      f.ruleId,
+      f.status,
+      f.severity,
+      (f.standardRefs || []).join(", ") || f.standard || "",
+      f.message,
+    ]);
+  }
+  const config = {
+    columnDefault: { wrapWord: true },
+    columns: [
+      { width: 2 },
+      { width: 15 },
+      { width: 8 },
+      { width: 10 },
+      { width: 20 },
+      { width: 60 },
+    ],
+    header: {
+      alignment: "center",
+      content: options.title || "cdx-validate findings",
+    },
+  };
+  return table(data, config);
+}
+
+/**
+ * Produce a scorecard table for benchmark reports.
+ *
+ * @param {Array<object>} reports
+ * @returns {string}
+ */
+export function formatBenchmarks(reports) {
+  if (!reports || reports.length === 0) {
+    return "";
+  }
+  const data = [
+    ["Benchmark", "Controls", "Pass", "Fail", "Manual", "Automatable score"],
+  ];
+  for (const r of reports) {
+    data.push([
+      r.name,
+      String(r.totalControls),
+      String(r.pass),
+      String(r.fail),
+      String(r.manual),
+      `${r.scorePct}% (${r.pass}/${r.automatable})`,
+    ]);
+  }
+  const config = {
+    columnDefault: { wrapWord: true },
+    columns: [
+      { width: 40 },
+      { width: 8 },
+      { width: 6 },
+      { width: 6 },
+      { width: 8 },
+      { width: 24 },
+    ],
+    header: {
+      alignment: "center",
+      content: "cdx-validate benchmark scorecards",
+    },
+  };
+  return table(data, config);
+}
+
+/**
+ * Produce a compact one-line summary for CI logs.
+ *
+ * @param {object} summary
+ * @returns {string}
+ */
+export function formatSummary(summary) {
+  return [
+    `schemaValid=${summary.schemaValid}`,
+    `deepValid=${summary.deepValid}`,
+    `pass=${summary.pass}`,
+    `fail=${summary.fail}`,
+    `manual=${summary.manual}`,
+    `errors=${summary.errors}`,
+  ].join("  ");
+}
+
+/**
+ * Render the full report as a single string.
+ *
+ * @param {object} report Output of validateBomAdvanced().
+ * @returns {string}
+ */
+export function render(report) {
+  const pieces = [];
+  pieces.push(formatSummary(report.summary));
+  if (report.benchmarks?.length) {
+    pieces.push(formatBenchmarks(report.benchmarks));
+  }
+  const actionable = report.findings.filter(
+    (f) => f.status === "fail" || f.severity === "critical",
+  );
+  if (actionable.length) {
+    pieces.push(formatFindings(actionable, { title: "Failing controls" }));
+  }
+  const manual = report.findings.filter((f) => f.status === "manual");
+  if (manual.length) {
+    pieces.push(
+      formatFindings(manual, {
+        title: `Manual review required (${manual.length})`,
+      }),
+    );
+  }
+  return pieces.filter(Boolean).join("\n");
+}

package/lib/validator/reporters/index.js

@@ -0,0 +1,41 @@
+/**
+ * Reporter registry — dispatches to the requested reporter.
+ *
+ * Reporters are intentionally kept as independent modules so they can also be
+ * consumed by the BOM audit engine or future validators.
+ */
+
+import * as annotations from "./annotations.js";
+import * as consoleReporter from "./console.js";
+import * as json from "./json.js";
+import * as sarif from "./sarif.js";
+
+/**
+ * Map of reporter name → module.
+ */
+export const reporters = {
+  console: consoleReporter,
+  json,
+  sarif,
+  annotations,
+};
+
+/**
+ * Render a validation report using the named reporter.
+ *
+ * @param {string} name   Reporter identifier.
+ * @param {object} report Output of validateBomAdvanced().
+ * @param {object} [opts] Reporter-specific options.
+ * @returns {string}
+ */
+export function render(name, report, opts) {
+  const reporter = reporters[(name || "console").toLowerCase()];
+  if (!reporter) {
+    throw new Error(
+      `Unknown reporter '${name}'. Expected one of: ${Object.keys(reporters).join(", ")}.`,
+    );
+  }
+  return reporter.render(report, opts);
+}
+
+export { annotations, consoleReporter as console, json, sarif };

package/lib/validator/reporters/json.js

@@ -0,0 +1,37 @@
+/**
+ * JSON reporter — emits a stable, documented structure for programmatic use.
+ * No dependencies.
+ */
+
+/**
+ * @param {object} report Output of validateBomAdvanced().
+ * @param {object} [_options] Unused
+ * @returns {string}
+ */
+export function render(report, _options = {}) {
+  const payload = {
+    schemaValid: report.schemaValid,
+    deepValid: report.deepValid,
+    signatureVerified: report.signatureVerified ?? null,
+    summary: report.summary,
+    benchmarks: report.benchmarks || [],
+    findings: (report.findings || []).map((f) => ({
+      ruleId: f.ruleId,
+      name: f.name,
+      description: f.description,
+      engine: f.engine,
+      standard: f.standard,
+      standardRefs: f.standardRefs,
+      scvsLevels: f.scvsLevels,
+      category: f.category,
+      status: f.status,
+      severity: f.severity,
+      automatable: f.automatable,
+      message: f.message,
+      mitigation: f.mitigation,
+      locations: f.locations || [],
+      evidence: f.evidence || null,
+    })),
+  };
+  return JSON.stringify(payload, null, null);
+}

package/lib/validator/reporters/sarif.js

@@ -0,0 +1,184 @@
+/**
+ * SARIF 2.1.0 reporter — renders findings as a SARIF log suitable for upload
+ * to GitHub code scanning or any other SARIF-aware consumer.
+ *
+ * No external dependencies. Spec: https://docs.oasis-open.org/sarif/sarif/v2.1.0/
+ */
+
+const SARIF_VERSION = "2.1.0";
+const SARIF_SCHEMA =
+  "https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/Schemata/sarif-schema-2.1.0.json";
+
+/**
+ * Map internal severity → SARIF `level` property.
+ *
+ * @param {string} severity
+ * @returns {"error" | "warning" | "note"}
+ */
+function severityToLevel(severity) {
+  switch (severity) {
+    case "critical":
+    case "high":
+      return "error";
+    case "medium":
+      return "warning";
+    default:
+      return "note";
+  }
+}
+
+/**
+ * Convert an internal location to a SARIF physicalLocation block. Returns null
+ * when there is no file context — the caller will fall back to a synthetic
+ * location.
+ *
+ * @param {object} loc
+ * @returns {object | null}
+ */
+function toSarifLocation(loc) {
+  if (!loc) return null;
+  if (loc.file) {
+    return {
+      physicalLocation: {
+        artifactLocation: { uri: loc.file },
+      },
+      logicalLocations: loc.bomRef
+        ? [{ fullyQualifiedName: loc.bomRef, kind: "package" }]
+        : undefined,
+    };
+  }
+  if (loc.purl || loc.bomRef) {
+    return {
+      logicalLocations: [
+        {
+          fullyQualifiedName: loc.purl || loc.bomRef,
+          kind: "package",
+        },
+      ],
+    };
+  }
+  return null;
+}
+
+/**
+ * Build the SARIF `rules` array from a catalogue of rule descriptors.
+ *
+ * @param {Array<object>} findings
+ * @returns {Array<object>}
+ */
+function deriveRules(findings) {
+  const byId = new Map();
+  for (const f of findings) {
+    if (byId.has(f.ruleId)) continue;
+    byId.set(f.ruleId, {
+      id: f.ruleId,
+      name: f.name || f.ruleId,
+      shortDescription: { text: f.name || f.ruleId },
+      fullDescription: {
+        text: f.description || f.name || f.ruleId,
+      },
+      defaultConfiguration: { level: severityToLevel(f.severity) },
+      properties: {
+        category: f.category,
+        standard: f.standard,
+        standardRefs: f.standardRefs || [],
+        scvsLevels: f.scvsLevels || [],
+        automatable: f.automatable !== false,
+        engine: f.engine,
+      },
+      help: f.mitigation
+        ? {
+            text: f.mitigation,
+            markdown: `**Remediation:** ${f.mitigation}`,
+          }
+        : undefined,
+    });
+  }
+  return [...byId.values()];
+}
+
+/**
+ * Convert one finding into a SARIF result.
+ *
+ * @param {object} f
+ * @returns {object}
+ */
+function toSarifResult(f) {
+  const locations = (f.locations || []).map(toSarifLocation).filter(Boolean);
+  if (locations.length === 0) {
+    locations.push({
+      logicalLocations: [{ fullyQualifiedName: f.ruleId, kind: "rule" }],
+    });
+  }
+  const result = {
+    ruleId: f.ruleId,
+    level: severityToLevel(f.severity),
+    message: { text: f.message || f.name || f.ruleId },
+    locations,
+    properties: {
+      status: f.status,
+      severity: f.severity,
+      standard: f.standard,
+      standardRefs: f.standardRefs || [],
+      scvsLevels: f.scvsLevels || [],
+      automatable: f.automatable !== false,
+      engine: f.engine,
+    },
+  };
+  if (f.evidence && typeof f.evidence === "object") {
+    result.properties.evidence = f.evidence;
+  }
+  return result;
+}
+
+/**
+ * Render a validation report as SARIF.
+ *
+ * @param {object} report Output of validateBomAdvanced().
+ * @param {object} [options]
+ * @param {string} [options.toolName]    Override driver name.
+ * @param {string} [options.toolVersion] Driver version to embed.
+ * @param {boolean} [options.includeManual] Include manual-review findings (default false).
+ * @returns {string}
+ */
+export function render(report, options = {}) {
+  const {
+    toolName = "cdx-validate",
+    toolVersion = "v12",
+    includeManual = false,
+  } = options;
+  const findings = (report.findings || []).filter((f) =>
+    includeManual ? true : f.status !== "manual",
+  );
+  const log = {
+    $schema: SARIF_SCHEMA,
+    version: SARIF_VERSION,
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: toolName,
+            version: toolVersion,
+            informationUri: "https://cdxgen.github.io/cdxgen/",
+            rules: deriveRules(findings),
+          },
+        },
+        invocations: [
+          {
+            executionSuccessful:
+              report.summary?.fail === 0 && report.schemaValid !== false,
+          },
+        ],
+        results: findings.map(toSarifResult),
+        properties: {
+          schemaValid: report.schemaValid,
+          deepValid: report.deepValid,
+          signatureVerified: report.signatureVerified ?? null,
+          summary: report.summary,
+          benchmarks: report.benchmarks || [],
+        },
+      },
+    ],
+  };
+  return JSON.stringify(log, null, null);
+}

package/lib/validator/reporters.poku.js

@@ -0,0 +1,150 @@
+import { assert, describe, it } from "poku";
+
+import { buildAnnotations } from "./reporters/annotations.js";
+import { render } from "./reporters/index.js";
+
+function sampleReport() {
+  return {
+    schemaValid: true,
+    deepValid: true,
+    signatureVerified: null,
+    summary: {
+      total: 2,
+      pass: 0,
+      fail: 1,
+      manual: 1,
+      errors: 1,
+      warnings: 0,
+      schemaValid: true,
+      deepValid: true,
+    },
+    benchmarks: [
+      {
+        id: "scvs-l1",
+        name: "OWASP SCVS Level 1",
+        standard: "SCVS",
+        totalControls: 2,
+        pass: 0,
+        fail: 1,
+        manual: 1,
+        automatable: 1,
+        scorePct: 0,
+        controls: [],
+      },
+    ],
+    findings: [
+      {
+        engine: "compliance",
+        ruleId: "SCVS-2.4",
+        name: "SBOM is signed",
+        description: "SBOM must be signed.",
+        standard: "SCVS",
+        standardRefs: ["SCVS-2.4"],
+        scvsLevels: ["L2", "L3"],
+        category: "compliance-scvs",
+        status: "fail",
+        severity: "high",
+        automatable: true,
+        message: "BOM is not signed.",
+        mitigation: "Use cdx-sign.",
+        locations: [{ file: "bom.json" }],
+        evidence: { reason: "no-signature" },
+      },
+      {
+        engine: "compliance",
+        ruleId: "SCVS-1.5",
+        name: "Manual procurement check",
+        description: "Manual.",
+        standard: "SCVS",
+        standardRefs: ["SCVS-1.5"],
+        scvsLevels: ["L2", "L3"],
+        category: "compliance-scvs",
+        status: "manual",
+        severity: "info",
+        automatable: false,
+        message: "Manual review.",
+        locations: [],
+        evidence: null,
+      },
+    ],
+  };
+}
+
+describe("reporter dispatcher", () => {
+  it("throws for unknown reporter", () => {
+    assert.throws(() => render("xml", sampleReport()), /Unknown reporter/);
+  });
+
+  it("console reporter renders a non-empty string", () => {
+    const out = render("console", sampleReport());
+    assert.ok(typeof out === "string");
+    assert.match(out, /cdx-validate/);
+    assert.match(out, /SCVS-2\.4/);
+  });
+
+  it("json reporter emits stable schema", () => {
+    const out = render("json", sampleReport());
+    const parsed = JSON.parse(out);
+    assert.strictEqual(parsed.schemaValid, true);
+    assert.strictEqual(parsed.benchmarks.length, 1);
+    assert.strictEqual(parsed.findings.length, 2);
+    assert.strictEqual(parsed.findings[0].ruleId, "SCVS-2.4");
+  });
+
+  it("sarif reporter emits valid 2.1.0 structure", () => {
+    const out = render("sarif", sampleReport(), {
+      toolName: "cdx-validate",
+      toolVersion: "1.2.3",
+    });
+    const parsed = JSON.parse(out);
+    assert.strictEqual(parsed.version, "2.1.0");
+    assert.strictEqual(parsed.runs[0].tool.driver.name, "cdx-validate");
+    assert.strictEqual(parsed.runs[0].tool.driver.version, "1.2.3");
+    // Manual findings are hidden by default.
+    assert.strictEqual(parsed.runs[0].results.length, 1);
+    assert.strictEqual(parsed.runs[0].results[0].ruleId, "SCVS-2.4");
+    assert.strictEqual(parsed.runs[0].results[0].level, "error");
+    // Driver rules must be unique and reference the only remaining finding.
+    assert.strictEqual(parsed.runs[0].tool.driver.rules.length, 1);
+  });
+
+  it("sarif reporter can include manual findings when requested", () => {
+    const out = render("sarif", sampleReport(), { includeManual: true });
+    const parsed = JSON.parse(out);
+    assert.strictEqual(parsed.runs[0].results.length, 2);
+  });
+
+  it("annotations reporter returns the BOM with annotations appended", () => {
+    const bomJson = {
+      bomFormat: "CycloneDX",
+      specVersion: "1.6",
+      serialNumber: "urn:uuid:1b671687-395b-41f5-a30f-a58921a69b79",
+      metadata: {
+        tools: {
+          components: [
+            { type: "application", name: "cdxgen", version: "12.0.0" },
+          ],
+        },
+        component: { name: "demo", "bom-ref": "demo", type: "application" },
+      },
+      components: [{ name: "demo", "bom-ref": "demo", type: "library" }],
+    };
+    const out = render("annotations", sampleReport(), { bomJson });
+    const parsed = JSON.parse(out);
+    assert.ok(Object.keys(parsed?.annotations));
+    assert.strictEqual(parsed.annotations.length, 2);
+    const first = parsed.annotations[0];
+    assert.ok(first.subjects[0].includes(bomJson.serialNumber));
+    assert.ok(first.annotator);
+  });
+
+  it("annotations reporter skips when spec version is below 1.5", () => {
+    const bomJson = {
+      bomFormat: "CycloneDX",
+      specVersion: "1.4",
+      metadata: { component: { name: "old" } },
+    };
+    const ann = buildAnnotations(sampleReport().findings, bomJson);
+    assert.strictEqual(Object.keys(ann).length, 0);
+  });
+});