@cdxgen/cdxgen 0.0.1 → 13.0.1

package/lib/validator/index.js

@@ -0,0 +1,246 @@
+/**
+ * cdx-validate orchestrator.
+ *
+ * Combines cdxgen's existing structural validation
+ * ({@link ./bomValidator.js}) with the compliance rule packs in
+ * {@link ./complianceEngine.js} and (optionally) signature verification from
+ * {@link ../helpers/bomSigner.js}.
+ *
+ * This module exposes a single high-level function, `validateBomAdvanced`,
+ * and helpers to classify the result. It does *not* perform any I/O: the CLI
+ * wrapper (`bin/validate.js`) is responsible for reading the input BOM.
+ */
+
+import { verifyNode } from "../helpers/bomSigner.js";
+import {
+  validateBom,
+  validateMetadata,
+  validateProps,
+  validatePurls,
+  validateRefs,
+} from "./bomValidator.js";
+import { buildBenchmarkReports, evaluateAll } from "./complianceEngine.js";
+
+/**
+ * Map of severity names to numeric ordering used for severity threshold
+ * comparisons.
+ *
+ * @type {Object<string, number>}
+ */
+const SEVERITY_ORDER = { info: 0, low: 1, medium: 2, high: 3, critical: 4 };
+
+/**
+ * Compute the summary block of the report.
+ *
+ * @param {Array<object>} findings
+ * @returns {object}
+ */
+function summarize(findings) {
+  let pass = 0;
+  let failed = 0;
+  let manual = 0;
+  let errors = 0;
+  let warnings = 0;
+  for (const f of findings) {
+    if (f.status === "pass") pass += 1;
+    else if (f.status === "fail") failed += 1;
+    else if (f.status === "manual") manual += 1;
+    if (
+      f.status === "fail" &&
+      (f.severity === "high" || f.severity === "critical")
+    ) {
+      errors += 1;
+    } else if (f.status === "fail") {
+      warnings += 1;
+    }
+  }
+  return {
+    total: findings.length,
+    pass,
+    fail: failed,
+    manual,
+    errors,
+    warnings,
+    schemaValid: true,
+    deepValid: true,
+  };
+}
+
+/**
+ * Filter findings by minimum severity and optional status inclusion rules.
+ *
+ * @param {Array<object>} findings
+ * @param {object} opts
+ * @param {string} [opts.minSeverity]    "info"..."critical".
+ * @param {boolean} [opts.includeManual]  When false, drop manual findings from
+ *                                        the final array (they are still in
+ *                                        the benchmark scorecards).
+ * @param {boolean} [opts.includePass]    When false, drop pass findings.
+ * @returns {Array<object>}
+ */
+function filterFindings(findings, opts) {
+  const min = SEVERITY_ORDER[(opts.minSeverity || "info").toLowerCase()] ?? 0;
+  return findings.filter((f) => {
+    if (!opts.includeManual && f.status === "manual") return false;
+    if (!opts.includePass && f.status === "pass") return false;
+    return (SEVERITY_ORDER[f.severity] ?? 0) >= min;
+  });
+}
+
+/**
+ * Validate a BOM.
+ *
+ * Validation is done in JavaScript. `cdxrs validate` is deliberately not used:
+ * it rejects BOMs the JS validator accepts and reports its findings on stdout
+ * rather than through the bridge, which turns a disagreement between the two
+ * implementations into an unexplained non-zero exit.
+ *
+ * **No failure mode may abort SBOM generation.**
+ *
+ * @param {object} bomJson Parsed CycloneDX BOM.
+ * @returns {Promise<{ valid: boolean, source: "js", findings: null }>}
+ */
+export async function validateGeneratedBom(bomJson) {
+  const valid = (await validateBom(bomJson)) !== false;
+  return { valid, source: "js", findings: null };
+}
+
+/**
+ * Run schema + deep validation checks from the existing validator helpers and
+ * capture their boolean results without letting them blow up the process.
+ *
+ * @param {object} bomJson
+ * @param {object} opts
+ * @returns {Promise<{ schemaValid: boolean, deepValid: boolean }>}
+ */
+async function runSchemaAndDeep(bomJson, opts) {
+  let schemaValid = true;
+  let deepValid = true;
+  if (opts.schema !== false) {
+    try {
+      schemaValid = (await validateBom(bomJson)) !== false;
+    } catch (err) {
+      schemaValid = false;
+      if (opts.onError) opts.onError("schema", err);
+    }
+  }
+  if (opts.deep !== false) {
+    try {
+      deepValid =
+        validateMetadata(bomJson) !== false &&
+        validatePurls(bomJson) !== false &&
+        validateRefs(bomJson) !== false &&
+        validateProps(bomJson) !== false;
+    } catch (err) {
+      deepValid = false;
+      if (opts.onError) opts.onError("deep", err);
+    }
+  }
+  return { schemaValid, deepValid };
+}
+
+/**
+ * Run structural + compliance validation against a parsed BOM.
+ *
+ * @param {object} bomJson Parsed CycloneDX JSON BOM.
+ * @param {object} [options]
+ * @param {boolean} [options.schema]            Run JSON-Schema validation (default true).
+ * @param {boolean} [options.deep]              Run purl/ref/metadata deep checks (default true).
+ * @param {Array<string>} [options.benchmarks]  Aliases to include in the scorecards (default: all).
+ * @param {Array<string>} [options.categories]  Restrict compliance rules to these categories.
+ * @param {string} [options.minSeverity]        Minimum severity for returned findings.
+ * @param {boolean} [options.includeManual]     Include manual-review findings (default true).
+ * @param {boolean} [options.includePass]       Include passing findings (default false).
+ * @param {string} [options.publicKey]          If set, verify the BOM signature.
+ * @returns {{
+ *   schemaValid: boolean,
+ *   deepValid: boolean,
+ *   signatureVerified: boolean | null,
+ *   signatureDetails: object | null,
+ *   findings: Array<object>,
+ *   allFindings: Array<object>,
+ *   benchmarks: Array<object>,
+ *   summary: object
+ * }}
+ */
+export async function validateBomAdvanced(bomJson, options = {}) {
+  const { schemaValid, deepValid } = await runSchemaAndDeep(bomJson, options);
+  const allFindings = evaluateAll(bomJson, {
+    categories: options.categories,
+    benchmarks: options.benchmarks,
+  });
+  const benchmarks = buildBenchmarkReports(allFindings, options.benchmarks);
+  const filtered = filterFindings(allFindings, {
+    minSeverity: options.minSeverity || "info",
+    includeManual: options.includeManual !== false,
+    includePass: options.includePass === true,
+  });
+  let signatureVerified = null;
+  let signatureDetails = null;
+  if (options.publicKey && bomJson?.signature) {
+    try {
+      const match = verifyNode(bomJson, options.publicKey);
+      signatureVerified = Boolean(match);
+      signatureDetails = match || null;
+    } catch (err) {
+      signatureVerified = false;
+      signatureDetails = { error: err?.message || String(err) };
+    }
+  } else if (options.publicKey) {
+    // Public key provided but BOM has no signature.
+    signatureVerified = false;
+    signatureDetails = { error: "BOM has no signature block." };
+  }
+  const summary = summarize(allFindings);
+  summary.schemaValid = schemaValid;
+  summary.deepValid = deepValid;
+  return {
+    schemaValid,
+    deepValid,
+    signatureVerified,
+    signatureDetails,
+    findings: filtered,
+    allFindings,
+    benchmarks,
+    summary,
+  };
+}
+
+/**
+ * Decide whether a report should trigger a non-zero CLI exit.
+ *
+ * @param {object} report
+ * @param {object} opts
+ * @param {string} [opts.failSeverity] Severity level at or above which failing findings are considered a failure (default "high").
+ * @param {boolean} [opts.strict]      When true, failing on any `fail` status regardless of severity, and a failing schema/deep validation also counts.
+ * @param {boolean} [opts.requireSignature] Require a valid signature when verification was requested.
+ * @returns {{ shouldFail: boolean, reason: string | null }}
+ */
+export function shouldFail(report, opts = {}) {
+  if (opts.requireSignature && report.signatureVerified === false) {
+    return { shouldFail: true, reason: "Signature verification failed." };
+  }
+  if (opts.strict && report.schemaValid === false) {
+    return { shouldFail: true, reason: "Schema validation failed." };
+  }
+  if (opts.strict && report.deepValid === false) {
+    return { shouldFail: true, reason: "Deep validation failed." };
+  }
+  const threshold =
+    SEVERITY_ORDER[(opts.failSeverity || "high").toLowerCase()] ??
+    SEVERITY_ORDER.high;
+  for (const f of report.allFindings || []) {
+    if (f.status !== "fail") continue;
+    const sev = SEVERITY_ORDER[f.severity] ?? 0;
+    if (sev >= threshold) {
+      return {
+        shouldFail: true,
+        reason: `Rule ${f.ruleId} failed with severity ${f.severity}.`,
+      };
+    }
+  }
+  return { shouldFail: false, reason: null };
+}
+
+export { buildBenchmarkReports, evaluateAll } from "./complianceEngine.js";
+export { SEVERITY_ORDER };

package/lib/validator/reporters/annotations.js

@@ -0,0 +1,142 @@
+/**
+ * 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 } from "../../core/activity.js";
+import { getTimestamp } from "../../core/fs.js";
+import { buildAnnotationText } from "../../helpers/annotationFormatter.js";
+
+const SUPPORTED_FROM = 1.5;
+
+function buildFindingDetails(f) {
+  const details = [
+    `Severity: ${f.severity || "unknown"}`,
+    f.category ? `Category: ${f.category}` : undefined,
+    f.status ? `Status: ${f.status}` : undefined,
+    f.mitigation ? `Mitigation: ${f.mitigation}` : undefined,
+  ];
+  if (f.evidence && typeof f.evidence === "object") {
+    for (const [key, value] of Object.entries(f.evidence).slice(0, 6)) {
+      details.push(
+        `Evidence — ${key}: ${typeof value === "object" ? JSON.stringify(value) : String(value)}`,
+      );
+    }
+  }
+  return details.filter(Boolean);
+}
+
+/**
+ * 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];
+  // An annotation describes the document it is attached to, so it carries that
+  // document's timestamp. Annotating the same BOM therefore yields the same
+  // annotations however long after generation it happens.
+  const timestamp = bomJson.metadata?.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: buildAnnotationText(f.message, properties, buildFindingDetails(f)),
+    };
+  });
+}
+
+/**
+ * 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,160 @@
+/**
+ * Console reporter — renders findings and benchmark scorecards as tables.
+ * Uses cdxgen's internal table helper for lightweight rendering.
+ */
+
+import { table } from "../../inventory/table.js";
+
+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})`,
+      }),
+    );
+    if (
+      manual.some((finding) =>
+        finding?.mitigation?.includes(
+          "cdx-audit --bom bom.json --scope required",
+        ),
+      )
+    ) {
+      pieces.push(
+        "Tip: some manual SCVS controls can be supported with predictive audit evidence. Run `cdx-audit --bom bom.json --scope required` against the same SBOM and review the flagged repositories, workflows, provenance, and publishing signals.",
+      );
+    }
+  }
+  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);
+}