@cyclonedx/cdxgen 12.2.0 → 12.3.0

package/lib/audit/scoring.js

@@ -0,0 +1,310 @@
+import {
+  hasRegistryProvenanceEvidenceProperties,
+  hasTrustedPublishingProperties,
+} from "../helpers/provenanceUtils.js";
+
+export const SEVERITY_ORDER = {
+  none: -1,
+  low: 0,
+  medium: 1,
+  high: 2,
+  critical: 3,
+};
+
+const BASE_FINDING_WEIGHT = {
+  low: 4,
+  medium: 10,
+  high: 18,
+  critical: 30,
+};
+
+const CATEGORY_WEIGHT = {
+  "ci-permission": 12,
+  "dependency-source": 8,
+  "package-integrity": 6,
+};
+
+const RULE_SPECIFIC_WEIGHT = {
+  "CI-019": 16,
+  "INT-009": 14,
+};
+
+const PRIORITY_CORROBORATION_RULES = new Set(["CI-019", "INT-009"]);
+
+/**
+ * Clamp a number into a fixed range.
+ *
+ * @param {number} value input number
+ * @param {number} min minimum value
+ * @param {number} max maximum value
+ * @returns {number} clamped number
+ */
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+
+/**
+ * Retrieve a custom property value from a target descriptor.
+ *
+ * @param {object} target audit target
+ * @param {string} propertyName property name
+ * @returns {string | undefined} property value
+ */
+function getTargetProperty(target, propertyName) {
+  return target?.properties?.find((property) => property.name === propertyName)
+    ?.value;
+}
+
+/**
+ * Convert a numeric confidence score into a human readable label.
+ *
+ * @param {number} confidence confidence score
+ * @returns {string} confidence label
+ */
+export function confidenceLabel(confidence) {
+  if (confidence >= 0.85) {
+    return "high";
+  }
+  if (confidence >= 0.6) {
+    return "medium";
+  }
+  return "low";
+}
+
+/**
+ * Check if a severity meets the given threshold.
+ *
+ * @param {string} severity severity to compare
+ * @param {string} threshold threshold severity
+ * @returns {boolean} true if severity is at or above threshold
+ */
+export function severityMeetsThreshold(severity, threshold) {
+  const resolvedSeverity = SEVERITY_ORDER[severity] ?? SEVERITY_ORDER.none;
+  const resolvedThreshold = SEVERITY_ORDER[threshold] ?? SEVERITY_ORDER.low;
+  return resolvedSeverity >= resolvedThreshold;
+}
+
+/**
+ * Conservatively score predictive supply-chain risk for a single target.
+ *
+ * High and critical require corroboration across categories and strong findings,
+ * which keeps false positives low.
+ *
+ * @param {object[]} findings post-generation audit findings
+ * @param {object} target target metadata
+ * @param {object} context additional scan context
+ * @returns {object} conservative risk assessment
+ */
+export function scoreTargetRisk(findings, target, context = {}) {
+  if (!Array.isArray(findings) || findings.length === 0) {
+    const explicitReason =
+      context?.skipReason ||
+      context?.scanErrorReason ||
+      context?.errorMessage ||
+      (context?.scanError
+        ? `Predictive audit for '${target.purl}' could not complete successfully.`
+        : `${target.type} package '${target.purl}' did not trigger any predictive audit rules.`);
+    return {
+      categoryCounts: {},
+      confidence: 0.35,
+      confidenceLabel: "low",
+      distinctCategoryCount: 0,
+      findingsCount: 0,
+      formulationSignalCount: 0,
+      reasons: [explicitReason],
+      score: 0,
+      severity: "none",
+      strongSignalCount: 0,
+    };
+  }
+  const categoryCounts = {};
+  const attackTactics = new Set();
+  const attackTechniques = new Set();
+  const distinctCategories = new Set();
+  const matchedPriorityRules = new Set();
+  let score = 0;
+  let strongSignalCount = 0;
+  let ciSignalCount = 0;
+  let formulationSignalCount = 0;
+  let priorityCorroborationCount = 0;
+  for (const finding of findings) {
+    const findingSeverity = finding?.severity || "low";
+    const findingCategory = finding?.category || "unknown";
+    let findingScore = BASE_FINDING_WEIGHT[findingSeverity] ?? 4;
+    findingScore += CATEGORY_WEIGHT[findingCategory] ?? 4;
+    findingScore += RULE_SPECIFIC_WEIGHT[finding?.ruleId] ?? 0;
+    if (findingCategory === "ci-permission") {
+      ciSignalCount += 1;
+      findingScore += 8;
+    }
+    if (
+      finding?.ruleId?.startsWith("CI-") ||
+      finding?.location?.file?.includes(".github/workflows")
+    ) {
+      formulationSignalCount += 1;
+      findingScore += 8;
+    }
+    if (["high", "critical"].includes(findingSeverity)) {
+      strongSignalCount += 1;
+    }
+    if (PRIORITY_CORROBORATION_RULES.has(finding?.ruleId)) {
+      priorityCorroborationCount += 1;
+      matchedPriorityRules.add(finding.ruleId);
+    }
+    (finding?.attackTactics || finding?.attack?.tactics || []).forEach((id) => {
+      if (id) {
+        attackTactics.add(id);
+      }
+    });
+    (finding?.attackTechniques || finding?.attack?.techniques || []).forEach(
+      (id) => {
+        if (id) {
+          attackTechniques.add(id);
+        }
+      },
+    );
+    categoryCounts[findingCategory] =
+      (categoryCounts[findingCategory] || 0) + 1;
+    distinctCategories.add(findingCategory);
+    score += findingScore;
+  }
+  score += Math.max(0, distinctCategories.size - 1) * 8;
+  score += Math.max(0, strongSignalCount - 1) * 10;
+  score += Math.max(0, formulationSignalCount - 1) * 6;
+
+  const hasTrustedPublishing = hasTrustedPublishingProperties(
+    target?.properties,
+  );
+  const hasProvenanceEvidence = hasRegistryProvenanceEvidenceProperties(
+    target?.properties,
+  );
+  const hasVerifiedPublisher =
+    getTargetProperty(target, "cdx:pypi:uploaderVerified") === "true";
+  let provenanceDiscount = 0;
+  if (hasProvenanceEvidence) {
+    provenanceDiscount += 4;
+  }
+  if (hasTrustedPublishing) {
+    provenanceDiscount += 6;
+  }
+  if (hasVerifiedPublisher) {
+    provenanceDiscount += 2;
+  }
+  score -= Math.min(provenanceDiscount, 10);
+  if (score < 0) {
+    score = 0;
+  }
+
+  const effectiveStrongSignalCount =
+    strongSignalCount + priorityCorroborationCount;
+
+  let confidence = 0.45;
+  if (context?.resolution?.repoUrl) {
+    confidence += 0.15;
+  }
+  if (target?.version) {
+    confidence += 0.1;
+  }
+  if (context?.versionMatched) {
+    confidence += 0.1;
+  }
+  if (context?.bomJson?.formulation?.length) {
+    confidence += 0.15;
+  }
+  if (context?.sourceDirectoryConfidence === "high") {
+    confidence += 0.05;
+  }
+  if (context?.sourceDirectoryConfidence === "low") {
+    confidence -= 0.1;
+  }
+  if (context?.scanError) {
+    confidence -= 0.35;
+  }
+  if (!context?.resolution?.repoUrl) {
+    confidence -= 0.2;
+  }
+  confidence = clamp(confidence, 0.05, 0.95);
+
+  let severity = "low";
+  if (score >= 84) {
+    severity = "critical";
+  } else if (score >= 52) {
+    severity = "high";
+  } else if (score >= 24) {
+    severity = "medium";
+  }
+
+  if (
+    severity === "critical" &&
+    (effectiveStrongSignalCount < 3 ||
+      distinctCategories.size < 2 ||
+      ciSignalCount < 1 ||
+      confidence < 0.85)
+  ) {
+    severity = "high";
+  }
+  if (
+    severity === "high" &&
+    (effectiveStrongSignalCount < 2 ||
+      distinctCategories.size < 2 ||
+      confidence < 0.65)
+  ) {
+    severity = "medium";
+  }
+  if (context?.scanError && severityMeetsThreshold(severity, "high")) {
+    severity = "medium";
+  }
+
+  const reasons = [];
+  if (ciSignalCount > 0) {
+    reasons.push(
+      `${ciSignalCount} GitHub Actions or privileged workflow signal(s) increased the predictive risk score.`,
+    );
+  }
+  if (distinctCategories.size > 1) {
+    reasons.push(
+      `${distinctCategories.size} distinct rule categories corroborated the package risk posture.`,
+    );
+  }
+  if (strongSignalCount > 0) {
+    reasons.push(
+      `${strongSignalCount} strong finding(s) were observed across the generated source SBOM.`,
+    );
+  }
+  if (priorityCorroborationCount > 0) {
+    reasons.push(
+      `${priorityCorroborationCount} high-confidence compound rule(s) received additional predictive weight (${Array.from(matchedPriorityRules).join(", ")}).`,
+    );
+  }
+  if (attackTactics.size > 0 || attackTechniques.size > 0) {
+    reasons.push(
+      `${attackTactics.size} ATT&CK tactic(s) and ${attackTechniques.size} ATT&CK technique(s) were implicated by the audit findings.`,
+    );
+  }
+  if (hasTrustedPublishing || hasProvenanceEvidence || hasVerifiedPublisher) {
+    reasons.push(
+      "Registry provenance or trusted-publishing evidence reduced the final predictive score.",
+    );
+  }
+  if (reasons.length === 0) {
+    reasons.push(
+      `Findings remained isolated, so severity stayed conservative for '${target.purl}'.`,
+    );
+  }
+
+  return {
+    categoryCounts,
+    attackTacticCount: attackTactics.size,
+    attackTechniqueCount: attackTechniques.size,
+    confidence,
+    confidenceLabel: confidenceLabel(confidence),
+    distinctCategoryCount: distinctCategories.size,
+    findingsCount: findings.length,
+    formulationSignalCount,
+    priorityCorroborationCount,
+    reasons,
+    score,
+    severity,
+    strongSignalCount,
+  };
+}

package/lib/audit/scoring.poku.js

@@ -0,0 +1,341 @@
+import { assert, describe, it } from "poku";
+
+import {
+  confidenceLabel,
+  scoreTargetRisk,
+  severityMeetsThreshold,
+} from "./scoring.js";
+
+const baseTarget = {
+  name: "left-pad",
+  purl: "pkg:npm/left-pad@1.3.0",
+  type: "npm",
+  version: "1.3.0",
+};
+
+describe("confidenceLabel()", () => {
+  it("maps numeric confidence to the expected buckets", () => {
+    assert.strictEqual(confidenceLabel(0.2), "low");
+    assert.strictEqual(confidenceLabel(0.7), "medium");
+    assert.strictEqual(confidenceLabel(0.9), "high");
+  });
+});
+
+describe("severityMeetsThreshold()", () => {
+  it("compares severities in the expected order", () => {
+    assert.strictEqual(severityMeetsThreshold("high", "medium"), true);
+    assert.strictEqual(severityMeetsThreshold("low", "high"), false);
+    assert.strictEqual(severityMeetsThreshold("none", "low"), false);
+  });
+});
+
+describe("scoreTargetRisk()", () => {
+  it("keeps a single strong signal at medium to reduce false positives", () => {
+    const findings = [
+      {
+        attackTactics: ["TA0001", "TA0004"],
+        attackTechniques: ["T1195.001"],
+        category: "ci-permission",
+        location: {
+          file: ".github/workflows/release.yml",
+        },
+        message: "Unpinned privileged action",
+        ruleId: "CI-001",
+        severity: "high",
+      },
+    ];
+
+    const assessment = scoreTargetRisk(findings, baseTarget, {
+      bomJson: {
+        formulation: [{}],
+      },
+      resolution: {
+        repoUrl: "https://github.com/example/repo",
+      },
+      sourceDirectoryConfidence: "high",
+      versionMatched: true,
+    });
+
+    assert.strictEqual(assessment.severity, "medium");
+    assert.strictEqual(assessment.attackTacticCount, 2);
+    assert.strictEqual(assessment.attackTechniqueCount, 1);
+    assert.ok(assessment.score > 0);
+    assert.match(assessment.reasons.join(" "), /ATT&CK tactic/i);
+  });
+
+  it("escalates to high only when independent signals corroborate the risk", () => {
+    const findings = [
+      {
+        category: "ci-permission",
+        location: {
+          file: ".github/workflows/release.yml",
+        },
+        message: "Unpinned privileged action",
+        ruleId: "CI-001",
+        severity: "high",
+      },
+      {
+        category: "dependency-source",
+        location: {
+          purl: baseTarget.purl,
+        },
+        message: "Install script from non-registry source",
+        ruleId: "PKG-001",
+        severity: "high",
+      },
+    ];
+
+    const assessment = scoreTargetRisk(findings, baseTarget, {
+      bomJson: {
+        formulation: [{}],
+      },
+      resolution: {
+        repoUrl: "https://github.com/example/repo",
+      },
+      sourceDirectoryConfidence: "high",
+      versionMatched: true,
+    });
+
+    assert.strictEqual(assessment.severity, "high");
+    assert.strictEqual(assessment.distinctCategoryCount, 2);
+  });
+
+  it("requires multiple corroborated strong signals before allowing critical", () => {
+    const findings = [
+      {
+        category: "ci-permission",
+        location: {
+          file: ".github/workflows/release.yml",
+        },
+        message: "Untrusted interpolation in shell step",
+        ruleId: "CI-007",
+        severity: "critical",
+      },
+      {
+        category: "dependency-source",
+        location: {
+          purl: baseTarget.purl,
+        },
+        message: "Install script from non-registry source",
+        ruleId: "PKG-001",
+        severity: "high",
+      },
+      {
+        category: "package-integrity",
+        location: {
+          purl: baseTarget.purl,
+        },
+        message: "Name mismatch",
+        ruleId: "INT-002",
+        severity: "high",
+      },
+    ];
+
+    const assessment = scoreTargetRisk(findings, baseTarget, {
+      bomJson: {
+        formulation: [{ workflows: [] }],
+      },
+      resolution: {
+        repoUrl: "https://github.com/example/repo",
+      },
+      sourceDirectoryConfidence: "high",
+      versionMatched: true,
+    });
+
+    assert.strictEqual(assessment.severity, "critical");
+    assert.ok(assessment.confidence >= 0.85);
+  });
+
+  it("downgrades severity when the scan encountered an error", () => {
+    const findings = [
+      {
+        category: "ci-permission",
+        location: {
+          file: ".github/workflows/release.yml",
+        },
+        message: "Untrusted interpolation in shell step",
+        ruleId: "CI-007",
+        severity: "critical",
+      },
+      {
+        category: "dependency-source",
+        location: {
+          purl: baseTarget.purl,
+        },
+        message: "Install script from non-registry source",
+        ruleId: "PKG-001",
+        severity: "high",
+      },
+    ];
+
+    const assessment = scoreTargetRisk(findings, baseTarget, {
+      bomJson: {
+        formulation: [{ workflows: [] }],
+      },
+      resolution: {
+        repoUrl: "https://github.com/example/repo",
+      },
+      scanError: true,
+      sourceDirectoryConfidence: "low",
+      versionMatched: false,
+    });
+
+    assert.strictEqual(assessment.severity, "medium");
+  });
+
+  it("reduces the final score when trusted publishing evidence is present", () => {
+    const findings = [
+      {
+        category: "dependency-source",
+        location: {
+          purl: baseTarget.purl,
+        },
+        message: "Install script from non-registry source",
+        ruleId: "PKG-001",
+        severity: "high",
+      },
+    ];
+
+    const withoutProvenance = scoreTargetRisk(findings, baseTarget, {
+      resolution: {
+        repoUrl: "https://github.com/example/repo",
+      },
+      versionMatched: true,
+    });
+    const withProvenance = scoreTargetRisk(
+      findings,
+      {
+        ...baseTarget,
+        properties: [
+          {
+            name: "cdx:npm:provenanceUrl",
+            value: "https://registry.npmjs.org/-/npm/v1/attestations/example",
+          },
+          { name: "cdx:npm:trustedPublishing", value: "true" },
+        ],
+      },
+      {
+        resolution: {
+          repoUrl: "https://github.com/example/repo",
+        },
+        versionMatched: true,
+      },
+    );
+
+    assert.ok(withProvenance.score < withoutProvenance.score);
+    assert.match(
+      withProvenance.reasons.join(" "),
+      /trusted-publishing evidence/i,
+    );
+  });
+
+  it("reduces the final score when direct provenance evidence properties are present", () => {
+    const findings = [
+      {
+        category: "dependency-source",
+        location: {
+          purl: baseTarget.purl,
+        },
+        message: "Install script from non-registry source",
+        ruleId: "PKG-001",
+        severity: "high",
+      },
+    ];
+
+    const withoutEvidence = scoreTargetRisk(findings, baseTarget, {
+      resolution: {
+        repoUrl: "https://github.com/example/repo",
+      },
+      versionMatched: true,
+    });
+    const withEvidence = scoreTargetRisk(
+      findings,
+      {
+        ...baseTarget,
+        properties: [
+          {
+            name: "cdx:npm:provenanceKeyId",
+            value: "sigstore-key",
+          },
+        ],
+      },
+      {
+        resolution: {
+          repoUrl: "https://github.com/example/repo",
+        },
+        versionMatched: true,
+      },
+    );
+
+    assert.ok(withEvidence.score < withoutEvidence.score);
+  });
+
+  it("keeps isolated CI-019 findings conservative despite the rule-specific bonus", () => {
+    const findings = [
+      {
+        category: "ci-permission",
+        location: {
+          file: ".github/workflows/dispatch.yml",
+        },
+        message: "Fork-aware dispatch chain",
+        ruleId: "CI-019",
+        severity: "critical",
+      },
+    ];
+
+    const assessment = scoreTargetRisk(findings, baseTarget, {
+      bomJson: {
+        formulation: [{ workflows: [] }],
+      },
+      resolution: {
+        repoUrl: "https://github.com/example/repo",
+      },
+      sourceDirectoryConfidence: "high",
+      versionMatched: true,
+    });
+
+    assert.strictEqual(assessment.severity, "medium");
+    assert.ok(assessment.priorityCorroborationCount >= 1);
+  });
+
+  it("escalates CI-019 plus INT-009 to critical at high confidence", () => {
+    const findings = [
+      {
+        category: "ci-permission",
+        location: {
+          file: ".github/workflows/dispatch.yml",
+        },
+        message: "Fork-aware dispatch chain",
+        ruleId: "CI-019",
+        severity: "critical",
+      },
+      {
+        category: "package-integrity",
+        location: {
+          purl: baseTarget.purl,
+        },
+        message: "Obfuscated install hook",
+        ruleId: "INT-009",
+        severity: "critical",
+      },
+    ];
+
+    const assessment = scoreTargetRisk(findings, baseTarget, {
+      bomJson: {
+        formulation: [{ workflows: [] }],
+      },
+      resolution: {
+        repoUrl: "https://github.com/example/repo",
+      },
+      sourceDirectoryConfidence: "high",
+      versionMatched: true,
+    });
+
+    assert.strictEqual(assessment.severity, "critical");
+    assert.ok(assessment.priorityCorroborationCount >= 2);
+    assert.match(
+      assessment.reasons.join(" "),
+      /high-confidence compound rule/i,
+    );
+  });
+});