@cyclonedx/cdxgen 12.3.3 → 12.4.0

package/lib/audit/index.poku.js

@@ -20,6 +20,7 @@ import {
   finalizeAuditReport,
   groupAuditResults,
   loadInputBoms,
+  runDirectBomAuditFromBoms,
 } from "./index.js";
 import {
   formatPredictiveAnnotations,
@@ -179,6 +180,7 @@ describe("runAuditFromBoms()", () => {
 
     assert.strictEqual(report.summary.totalTargets, 1);
     assert.deepStrictEqual(collectAuditTargetsStub.firstCall.args[1], {
+      allowlistFile: undefined,
       maxTargets: 50,
       prioritizeDirectRuntime: true,
       scope: "required",
@@ -192,6 +194,266 @@ describe("runAuditFromBoms()", () => {
     );
     assert.strictEqual(progressEvents[1].type, "run:start");
   });
+
+  it("supports dry-run predictive audit planning without cloning targets", async () => {
+    const collectAuditTargetsStub = sinon.stub().returns({
+      skipped: [],
+      stats: {
+        availableTargets: 1,
+        nonRequiredTargets: 0,
+        requiredTargets: 1,
+        trustedTargets: 0,
+        trustedTargetsExcluded: 0,
+        truncatedTargets: 0,
+      },
+      targets: [
+        {
+          name: "core",
+          namespace: "acme",
+          purl: "pkg:npm/acme/core@1.0.0",
+          required: true,
+          type: "npm",
+          version: "1.0.0",
+        },
+      ],
+    });
+    const enrichInputBomsWithRegistryMetadataStub = sinon.stub().resolves();
+    const recordActivityStub = sinon.stub();
+    const { runAuditFromBoms: mockedRunAuditFromBoms } = await esmock(
+      "./index.js",
+      {
+        "../cli/index.js": {
+          createBom: sinon.stub(),
+        },
+        "../helpers/bomUtils.js": {
+          getNonCycloneDxErrorMessage: sinon.stub(),
+          isCycloneDxBom: () => true,
+        },
+        "../helpers/logger.js": { thoughtLog: sinon.stub() },
+        "../helpers/provenanceUtils.js": {
+          hasRegistryProvenanceEvidenceProperties: () => false,
+          hasTrustedPublishingProperties: () => false,
+        },
+        "../helpers/source.js": {
+          cleanupSourceDir: sinon.stub(),
+          findGitRefForPurlVersion: sinon.stub().returns(undefined),
+          hardenedGitCommand: sinon.stub(),
+          resolveGitUrlFromPurl: sinon.stub(),
+          resolvePurlSourceDirectory: sinon.stub(),
+          sanitizeRemoteUrlForLogs: (value) => value,
+        },
+        "../helpers/utils.js": {
+          dirNameStr: path.resolve("."),
+          getTmpDir: () => os.tmpdir(),
+          isDryRun: true,
+          recordActivity: recordActivityStub,
+          safeExistsSync: (filePath) => existsSync(filePath),
+          safeMkdirSync: (filePath, options) => mkdirSync(filePath, options),
+          safeMkdtempSync: sinon.stub(),
+          safeRmSync: sinon.stub(),
+          safeWriteSync: sinon.stub(),
+        },
+        "../stages/postgen/auditBom.js": {
+          auditBom: sinon.stub().resolves([]),
+        },
+        "../stages/postgen/postgen.js": {
+          postProcess: sinon.stub().callsFake((bomNSData) => bomNSData),
+        },
+        "./targets.js": {
+          collectAuditTargets: collectAuditTargetsStub,
+          enrichInputBomsWithRegistryMetadata:
+            enrichInputBomsWithRegistryMetadataStub,
+          normalizePackageName: (value) =>
+            (value || "").toLowerCase().replace(/[-_.]+/g, "-"),
+        },
+      },
+    );
+
+    const report = await mockedRunAuditFromBoms(
+      [
+        {
+          bomJson: {
+            bomFormat: "CycloneDX",
+            components: [],
+            specVersion: "1.7",
+            version: 1,
+          },
+          source: "bom.json",
+        },
+      ],
+      {},
+    );
+
+    assert.strictEqual(report.dryRun, true);
+    assert.strictEqual(report.summary.predictiveDryRun, true);
+    assert.strictEqual(report.summary.totalTargets, 1);
+    assert.strictEqual(report.summary.scannedTargets, 0);
+    assert.strictEqual(report.summary.skippedTargets, 1);
+    assert.strictEqual(report.results[0].status, "skipped");
+    assert.match(
+      report.results[0].assessment.reasons[0],
+      /skipped registry metadata fetches/i,
+    );
+    sinon.assert.notCalled(enrichInputBomsWithRegistryMetadataStub);
+    sinon.assert.calledWithMatch(recordActivityStub, {
+      kind: "audit",
+      reason: sinon.match(/skipped registry metadata fetches/i),
+      target: "predictive-dependency-audit",
+    });
+  });
+});
+
+describe("runDirectBomAuditFromBoms()", () => {
+  it("throws when no BOM inputs are provided", async () => {
+    await assert.rejects(
+      runDirectBomAuditFromBoms([], {}),
+      /No CycloneDX BOM inputs were found/,
+    );
+  });
+
+  it("defaults OBOM-like saved BOMs to the obom-runtime rule category", async () => {
+    const auditBomStub = sinon.stub().resolves([
+      {
+        category: "obom-runtime",
+        message: "Mount '/dev/shm' is missing noexec.",
+        ruleId: "OBOM-LNX-018",
+        severity: "high",
+      },
+    ]);
+    const { runDirectBomAuditFromBoms: mockedRunDirectBomAuditFromBoms } =
+      await esmock("./index.js", {
+        "../stages/postgen/auditBom.js": {
+          auditBom: auditBomStub,
+          isObomLikeBom: () => true,
+        },
+      });
+
+    const report = await mockedRunDirectBomAuditFromBoms(
+      [
+        {
+          bomJson: {
+            bomFormat: "CycloneDX",
+            metadata: {
+              lifecycles: [{ phase: "operations" }],
+            },
+            specVersion: "1.7",
+            version: 1,
+          },
+          source: "saved-obom.json",
+        },
+      ],
+      {
+        minSeverity: "low",
+      },
+    );
+
+    assert.strictEqual(auditBomStub.callCount, 1);
+    assert.deepStrictEqual(auditBomStub.firstCall.args[1], {
+      bomAuditCategories: "obom-runtime",
+      bomAuditMinSeverity: "low",
+      bomAuditRulesDir: undefined,
+    });
+    assert.strictEqual(report.auditMode, "direct");
+    assert.strictEqual(report.summary.totalFindings, 1);
+    assert.strictEqual(report.summary.findingsBySeverity.high, 1);
+  });
+
+  it("defaults HBOM-like saved BOMs to the HBOM rule categories", async () => {
+    const auditBomStub = sinon.stub().resolves([
+      {
+        category: "hbom-security",
+        message: "Storage component 'Main SSD' is reported as unencrypted",
+        ruleId: "HBS-001",
+        severity: "high",
+      },
+    ]);
+    const { runDirectBomAuditFromBoms: mockedRunDirectBomAuditFromBoms } =
+      await esmock("./index.js", {
+        "../stages/postgen/auditBom.js": {
+          auditBom: auditBomStub,
+          isHbomLikeBom: () => true,
+          isObomLikeBom: () => false,
+        },
+      });
+
+    const report = await mockedRunDirectBomAuditFromBoms(
+      [
+        {
+          bomJson: {
+            bomFormat: "CycloneDX",
+            metadata: {
+              component: {
+                properties: [
+                  {
+                    name: "cdx:hbom:platform",
+                    value: "darwin",
+                  },
+                ],
+                type: "device",
+              },
+            },
+            properties: [
+              {
+                name: "cdx:hbom:collectorProfile",
+                value: "darwin-arm64",
+              },
+            ],
+            specVersion: "1.7",
+            version: 1,
+          },
+          source: "saved-hbom.json",
+        },
+      ],
+      {
+        minSeverity: "low",
+      },
+    );
+
+    assert.strictEqual(auditBomStub.callCount, 1);
+    assert.deepStrictEqual(auditBomStub.firstCall.args[1], {
+      bomAuditCategories: "hbom-security,hbom-performance,hbom-compliance",
+      bomAuditMinSeverity: "low",
+      bomAuditRulesDir: undefined,
+    });
+    assert.strictEqual(report.auditMode, "direct");
+    assert.strictEqual(report.summary.totalFindings, 1);
+    assert.strictEqual(report.summary.findingsBySeverity.high, 1);
+  });
+
+  it("honors explicit categories and custom rules for direct BOM audit", async () => {
+    const auditBomStub = sinon.stub().resolves([]);
+    const { runDirectBomAuditFromBoms: mockedRunDirectBomAuditFromBoms } =
+      await esmock("./index.js", {
+        "../stages/postgen/auditBom.js": {
+          auditBom: auditBomStub,
+          isObomLikeBom: () => false,
+        },
+      });
+
+    await mockedRunDirectBomAuditFromBoms(
+      [
+        {
+          bomJson: {
+            bomFormat: "CycloneDX",
+            specVersion: "1.7",
+            version: 1,
+          },
+          source: "saved-bom.json",
+        },
+      ],
+      {
+        categories: ["obom-runtime", "rootfs-hardening"],
+        minSeverity: "medium",
+        rulesDir: "/tmp/custom-rules",
+      },
+    );
+
+    assert.deepStrictEqual(auditBomStub.firstCall.args[1], {
+      bomAuditCategories: "obom-runtime,rootfs-hardening",
+      bomAuditMinSeverity: "medium",
+      bomAuditRulesDir: "/tmp/custom-rules",
+    });
+  });
 });
 
 describe("finalizeAuditReport()", () => {
@@ -426,6 +688,49 @@ describe("finalizeAuditReport()", () => {
     );
   });
 
+  it("returns exit code 3 for direct BOM audit findings at the fail threshold", () => {
+    const finalized = finalizeAuditReport(
+      {
+        auditMode: "direct",
+        inputs: ["saved-obom.json"],
+        results: [
+          {
+            findings: [
+              {
+                description: "Temporary mounts should carry noexec.",
+                message: "Mount '/dev/shm' is missing noexec.",
+                ruleId: "OBOM-LNX-018",
+                severity: "high",
+              },
+            ],
+            source: "saved-obom.json",
+          },
+        ],
+        summary: {
+          bomsWithFindings: 1,
+          findingsBySeverity: {
+            critical: 0,
+            high: 1,
+            low: 0,
+            medium: 0,
+          },
+          inputBomCount: 1,
+          maxSeverity: "high",
+          totalFindings: 1,
+        },
+      },
+      {
+        failSeverity: "high",
+        minSeverity: "low",
+        report: "console",
+      },
+    );
+
+    assert.strictEqual(finalized.exitCode, 3);
+    assert.match(finalized.output, /\/dev\/shm/);
+    assert.match(finalized.output, /Mount '\/dev\/shm' is missing noexec/);
+  });
+
   it("includes synthetic SARIF results when a target fails before findings are produced", () => {
     const rendered = renderAuditReport(
       "sarif",
@@ -689,6 +994,33 @@ describe("finalizeAuditReport()", () => {
     assert.match(rendered, /No dependencies require your attention right now/);
     assert.match(rendered, /configured severity threshold \('low'\)/);
   });
+
+  it("explains predictive audit planning limits in dry-run mode", () => {
+    const rendered = renderConsoleReport(
+      {
+        dryRun: true,
+        results: [],
+        summary: {
+          erroredTargets: 0,
+          groupedResultCount: 0,
+          inputBomCount: 1,
+          predictiveDryRun: true,
+          scannedTargets: 0,
+          skippedTargets: 2,
+          totalTargets: 2,
+        },
+      },
+      {
+        minSeverity: "low",
+      },
+    );
+
+    assert.match(
+      rendered,
+      /Dry-run mode only planned predictive audit targets/i,
+    );
+    assert.match(rendered, /Re-run without --dry-run/i);
+  });
 });
 
 describe("groupAuditResults()", () => {

package/lib/audit/reporters.js

@@ -1,6 +1,7 @@
 import { buildAnnotationText } from "../helpers/annotationFormatter.js";
 import { table } from "../helpers/table.js";
 import { getTimestamp } from "../helpers/utils.js";
+import { renderBomAuditConsoleReport } from "../stages/postgen/auditBom.js";
 import { severityMeetsThreshold } from "./scoring.js";
 
 const SARIF_VERSION = "2.1.0";
@@ -21,6 +22,18 @@ function filterResults(results, minSeverity) {
   );
 }
 
+function filterDirectFindingEntries(report, minSeverity) {
+  const entries = [];
+  for (const result of report?.results || []) {
+    for (const finding of result?.findings || []) {
+      if (severityMeetsThreshold(finding?.severity || "none", minSeverity)) {
+        entries.push({ finding, result });
+      }
+    }
+  }
+  return entries;
+}
+
 function effectiveResults(report) {
   return report.groupedResults?.length
     ? report.groupedResults
@@ -50,6 +63,97 @@ function severityToSarifLevel(severity) {
   }
 }
 
+function directBomFindingLocations(finding, result) {
+  const bomRef =
+    finding?.location?.bomRef ||
+    finding?.location?.purl ||
+    result?.serialNumber ||
+    result?.source;
+  if (finding?.location?.file) {
+    return [
+      {
+        physicalLocation: {
+          artifactLocation: {
+            uri: finding.location.file,
+          },
+        },
+        logicalLocations: bomRef
+          ? [{ fullyQualifiedName: bomRef, kind: "package" }]
+          : undefined,
+      },
+    ];
+  }
+  if (bomRef) {
+    return [
+      {
+        logicalLocations: [{ fullyQualifiedName: bomRef, kind: "package" }],
+      },
+    ];
+  }
+  return [
+    {
+      logicalLocations: [{ fullyQualifiedName: "cdx-audit", kind: "tool" }],
+    },
+  ];
+}
+
+function deriveDirectBomSarifRules(entries) {
+  const rulesById = new Map();
+  for (const { finding } of entries) {
+    if (rulesById.has(finding.ruleId)) {
+      continue;
+    }
+    rulesById.set(finding.ruleId, {
+      id: finding.ruleId,
+      name: finding.name || finding.ruleId,
+      shortDescription: {
+        text: finding.name || finding.ruleId,
+      },
+      fullDescription: {
+        text: finding.description || finding.name || finding.ruleId,
+      },
+      defaultConfiguration: {
+        level: severityToSarifLevel(finding.severity),
+      },
+      help: finding.mitigation
+        ? {
+            markdown: `**Remediation:** ${finding.mitigation}`,
+            text: finding.mitigation,
+          }
+        : undefined,
+      properties: {
+        attackTactics: finding.attackTactics,
+        attackTechniques: finding.attackTechniques,
+        category: finding.category,
+        engine: "cdx-audit-direct-bom",
+        tags: attackTags(finding),
+      },
+    });
+  }
+  return [...rulesById.values()];
+}
+
+function directBomFindingToSarifResult(finding, result) {
+  return {
+    level: severityToSarifLevel(finding?.severity),
+    locations: directBomFindingLocations(finding, result),
+    message: {
+      text: finding?.message || finding?.description || finding?.ruleId,
+    },
+    properties: {
+      attackTactics: finding?.attackTactics,
+      attackTechniques: finding?.attackTechniques,
+      category: finding?.category,
+      description: finding?.description,
+      evidence: finding?.evidence,
+      inputBom: result?.source,
+      mitigation: finding?.mitigation,
+      severity: finding?.severity,
+    },
+    ruleId: finding?.ruleId || AUDIT_ERROR_RULE_ID,
+  };
+}
+
 function splitCsv(value) {
   return String(value || "")
     .split(",")
@@ -481,6 +585,105 @@ export function renderJsonReport(report) {
   return `${JSON.stringify(report, null, 2)}\n`;
 }
 
+/**
+ * Render a direct BOM audit report for terminal output.
+ *
+ * @param {object} report aggregate direct audit report
+ * @param {object} options render options
+ * @returns {string} console report text
+ */
+export function renderDirectBomConsoleReport(report, options = {}) {
+  const minSeverity = options.minSeverity || "low";
+  const visibleResults = (report?.results || [])
+    .map((result) => ({
+      ...result,
+      findings: (result.findings || []).filter((finding) =>
+        severityMeetsThreshold(finding?.severity || "none", minSeverity),
+      ),
+    }))
+    .filter((result) => result.findings.length > 0);
+  if (report?.results?.length === 1) {
+    if (visibleResults.length > 0) {
+      return `${renderBomAuditConsoleReport(visibleResults[0].findings)}\n`;
+    }
+    return [
+      "cdx-audit — direct BOM policy audit",
+      "",
+      `Input BOMs: ${report?.summary?.inputBomCount || 0}`,
+      `Findings: ${report?.summary?.totalFindings || 0}`,
+      "",
+      `No direct BOM findings met or exceeded the configured severity threshold ('${minSeverity}').`,
+    ]
+      .join("\n")
+      .concat("\n");
+  }
+  const lines = [];
+  lines.push("cdx-audit — direct BOM policy audit");
+  lines.push("");
+  lines.push(`Input BOMs: ${report?.summary?.inputBomCount || 0}`);
+  lines.push(`BOMs with findings: ${report?.summary?.bomsWithFindings || 0}`);
+  lines.push(`Findings: ${report?.summary?.totalFindings || 0}`);
+  lines.push("");
+  if (!visibleResults.length) {
+    lines.push(
+      `No direct BOM findings met or exceeded the configured severity threshold ('${minSeverity}').`,
+    );
+    return `${lines.join("\n")}\n`;
+  }
+  for (const result of visibleResults) {
+    lines.push(`Input BOM: ${result.source}`);
+    lines.push(renderBomAuditConsoleReport(result.findings));
+    lines.push("");
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Render a direct BOM audit report as SARIF 2.1.0 output.
+ *
+ * @param {object} report aggregate direct audit report
+ * @param {object} [options] render options
+ * @returns {string} SARIF output
+ */
+export function renderDirectBomSarifReport(report, options = {}) {
+  const minSeverity = options.minSeverity || "low";
+  const entries = filterDirectFindingEntries(report, minSeverity);
+  const sarifResults = entries.map(({ finding, result }) =>
+    directBomFindingToSarifResult(finding, result),
+  );
+  const toolName = report?.tool?.name || "cdx-audit";
+  const toolVersion = report?.tool?.version || "v12";
+  const log = {
+    $schema: SARIF_SCHEMA,
+    version: SARIF_VERSION,
+    runs: [
+      {
+        tool: {
+          driver: {
+            informationUri: "https://cdxgen.github.io/cdxgen/",
+            name: toolName,
+            rules: deriveDirectBomSarifRules(entries),
+            version: toolVersion,
+          },
+        },
+        invocations: [
+          {
+            executionSuccessful: true,
+          },
+        ],
+        properties: {
+          auditMode: report?.auditMode,
+          generatedAt: report?.generatedAt,
+          inputs: report?.inputs || [],
+          summary: report?.summary,
+        },
+        results: sarifResults,
+      },
+    ],
+  };
+  return `${JSON.stringify(log, null, 2)}\n`;
+}
+
 /**
  * Render an audit report for terminal output.
  *
@@ -514,6 +717,16 @@ export function renderConsoleReport(report, options = {}) {
     lines.push(
       `No predictive findings met or exceeded the configured severity threshold ('${minSeverity}').`,
     );
+    if (report.summary?.predictiveDryRun) {
+      lines.push(
+        "Dry-run mode only planned predictive audit targets. Registry metadata fetches, upstream repository cloning, and child SBOM generation were intentionally skipped.",
+      );
+      if (report.summary.totalTargets > 0) {
+        lines.push(
+          "Re-run without --dry-run to analyze the planned targets with the predictive dependency audit.",
+        );
+      }
+    }
     if (report.summary.erroredTargets > 0) {
       lines.push(
         "Some targets could not be fully analyzed, so review the recorded analysis errors before treating this rollup as complete.",
@@ -546,6 +759,15 @@ export function renderConsoleReport(report, options = {}) {
  * @returns {string} rendered report
  */
 export function renderAuditReport(reportType, report, options = {}) {
+  if (report?.auditMode === "direct") {
+    if ((reportType || "console") === "json") {
+      return renderJsonReport(report);
+    }
+    if ((reportType || "console") === "sarif") {
+      return renderDirectBomSarifReport(report, options);
+    }
+    return renderDirectBomConsoleReport(report, options);
+  }
   if ((reportType || "console") === "json") {
     return renderJsonReport(report);
   }