@cyclonedx/cdxgen 12.2.1 → 12.3.0

package/lib/audit/targets.js

@@ -0,0 +1,260 @@
+import { PackageURL } from "packageurl-js";
+
+import { hasTrustedPublishingProperties } from "../helpers/provenanceUtils.js";
+
+const SUPPORTED_PURL_TYPES = new Set(["npm", "pypi"]);
+const NON_REQUIRED_SCOPES = new Set(["excluded", "optional"]);
+
+/**
+ * Normalize predictive audit target selection options.
+ *
+ * @param {number | object | undefined} options selector options or legacy maxTargets value
+ * @returns {{
+ *   maxTargets: number | undefined,
+ *   scope: string | undefined,
+ *   trusted: "exclude" | "include" | "only",
+ * }} normalized options
+ */
+function normalizeTargetSelectionOptions(options) {
+  if (typeof options === "number") {
+    return {
+      maxTargets: options,
+      scope: undefined,
+      trusted: "exclude",
+    };
+  }
+  return {
+    maxTargets: options?.maxTargets,
+    scope: options?.scope === "required" ? "required" : undefined,
+    trusted:
+      options?.trusted === "only"
+        ? "only"
+        : options?.trusted === "include"
+          ? "include"
+          : "exclude",
+  };
+}
+
+/**
+ * Determine whether a CycloneDX component scope should be treated as required.
+ *
+ * Missing scope is treated as required to match the main BOM filtering flow.
+ *
+ * @param {string | undefined} scope component scope
+ * @returns {boolean} true when the component is required for predictive audit selection
+ */
+export function isRequiredComponentScope(scope) {
+  if (!scope || typeof scope !== "string") {
+    return true;
+  }
+  return !NON_REQUIRED_SCOPES.has(scope.toLowerCase());
+}
+
+function normalizeComponentScope(scope) {
+  if (!scope || typeof scope !== "string") {
+    return undefined;
+  }
+  return scope.toLowerCase();
+}
+
+function mergeTargetScope(existingTarget, nextTarget) {
+  const mergedRequired = Boolean(
+    existingTarget.required || nextTarget.required,
+  );
+  const existingScope = normalizeComponentScope(existingTarget.scope);
+  const nextScope = normalizeComponentScope(nextTarget.scope);
+  if (mergedRequired) {
+    return existingScope === "required" || nextScope === "required"
+      ? "required"
+      : existingScope || nextScope;
+  }
+  return existingScope === "optional" || nextScope === "optional"
+    ? "optional"
+    : existingScope || nextScope;
+}
+
+/**
+ * Normalize package names for safe matching and grouping.
+ *
+ * @param {string | undefined} packageName package name
+ * @returns {string} normalized package name
+ */
+export function normalizePackageName(packageName) {
+  if (!packageName || typeof packageName !== "string") {
+    return "";
+  }
+  return packageName.toLowerCase().replace(/[-_.]+/g, "-");
+}
+
+/**
+ * Extract npm and PyPI package-url targets from a CycloneDX BOM.
+ *
+ * @param {object} bomJson CycloneDX BOM
+ * @param {string} sourceName source BOM path or label
+ * @param {number | object | undefined} [options] selector options
+ * @returns {{ targets: object[], skipped: object[] }} extracted targets and skipped components
+ */
+export function extractPurlTargetsFromBom(bomJson, sourceName, options) {
+  const selectorOptions = normalizeTargetSelectionOptions(options);
+  const targets = [];
+  const skipped = [];
+  const components = Array.isArray(bomJson?.components)
+    ? bomJson.components
+    : [];
+  for (const component of components) {
+    const componentScope = normalizeComponentScope(component?.scope);
+    if (
+      selectorOptions.scope === "required" &&
+      !isRequiredComponentScope(componentScope)
+    ) {
+      continue;
+    }
+    const componentPurl = component?.purl;
+    if (!componentPurl) {
+      continue;
+    }
+    let purlObj;
+    try {
+      purlObj = PackageURL.fromString(componentPurl);
+    } catch {
+      skipped.push({
+        reason: "invalid-purl",
+        source: sourceName,
+        purl: componentPurl,
+        bomRef: component?.["bom-ref"],
+        name: component?.name,
+      });
+      continue;
+    }
+    if (!SUPPORTED_PURL_TYPES.has(purlObj.type)) {
+      skipped.push({
+        reason: "unsupported-ecosystem",
+        source: sourceName,
+        purl: componentPurl,
+        bomRef: component?.["bom-ref"],
+        name: component?.name,
+        type: purlObj.type,
+      });
+      continue;
+    }
+    targets.push({
+      bomRef: component?.["bom-ref"],
+      name: purlObj.name,
+      namespace: purlObj.namespace,
+      purl: componentPurl,
+      properties: Array.isArray(component?.properties)
+        ? component.properties.map((property) => ({ ...property }))
+        : [],
+      qualifiers: purlObj.qualifiers,
+      required: isRequiredComponentScope(componentScope),
+      scope: componentScope,
+      source: sourceName,
+      trustedPublishing: hasTrustedPublishingProperties(component?.properties),
+      type: purlObj.type,
+      version: purlObj.version,
+    });
+  }
+  return { skipped, targets };
+}
+
+/**
+ * Merge targets across many BOMs by purl.
+ *
+ * @param {{ source: string, bomJson: object }[]} inputBoms input BOMs
+ * @param {number | object | undefined} [options] selector options or a legacy maxTargets value
+ * @returns {{
+ *   skipped: object[],
+ *   stats: {
+ *     availableTargets: number,
+ *     nonRequiredTargets: number,
+ *     requiredTargets: number,
+ *     trustedTargets: number,
+ *     trustedTargetsExcluded: number,
+ *     truncatedTargets: number,
+ *   },
+ *   targets: object[],
+ * }} merged targets and skipped components
+ */
+export function collectAuditTargets(inputBoms, options) {
+  const selectorOptions = normalizeTargetSelectionOptions(options);
+  const skipped = [];
+  const targetMap = new Map();
+  for (const inputBom of inputBoms) {
+    const extracted = extractPurlTargetsFromBom(
+      inputBom.bomJson,
+      inputBom.source,
+      selectorOptions,
+    );
+    skipped.push(...extracted.skipped);
+    for (const target of extracted.targets) {
+      const existing = targetMap.get(target.purl);
+      if (existing) {
+        existing.required = Boolean(existing.required || target.required);
+        existing.scope = mergeTargetScope(existing, target);
+        existing.trustedPublishing = Boolean(
+          existing.trustedPublishing || target.trustedPublishing,
+        );
+        existing.sources.add(target.source);
+        if (target.bomRef) {
+          existing.bomRefs.add(target.bomRef);
+        }
+        for (const property of target.properties || []) {
+          const alreadyPresent = existing.properties.some(
+            (existingProperty) =>
+              existingProperty.name === property.name &&
+              existingProperty.value === property.value,
+          );
+          if (!alreadyPresent) {
+            existing.properties.push(property);
+          }
+        }
+        continue;
+      }
+      targetMap.set(target.purl, {
+        ...target,
+        bomRefs: new Set(target.bomRef ? [target.bomRef] : []),
+        sources: new Set([target.source]),
+      });
+    }
+  }
+  let targets = [...targetMap.values()].map((target) => ({
+    ...target,
+    bomRefs: [...target.bomRefs].sort(),
+    normalizedName: normalizePackageName(target.name),
+    sources: [...target.sources].sort(),
+  }));
+  targets.sort((left, right) => left.purl.localeCompare(right.purl));
+  const trustedTargets = targets.filter((target) => target.trustedPublishing);
+  if (selectorOptions.trusted === "only") {
+    targets = trustedTargets;
+  } else if (selectorOptions.trusted === "exclude") {
+    targets = targets.filter((target) => !target.trustedPublishing);
+  }
+  const requiredTargets = targets.filter((target) => target.required);
+  const nonRequiredTargets = targets.filter((target) => !target.required);
+  const availableTargets = targets.length;
+  if (
+    typeof selectorOptions.maxTargets === "number" &&
+    selectorOptions.maxTargets > 0
+  ) {
+    targets = [...requiredTargets, ...nonRequiredTargets].slice(
+      0,
+      selectorOptions.maxTargets,
+    );
+  }
+  return {
+    skipped,
+    stats: {
+      availableTargets,
+      nonRequiredTargets: nonRequiredTargets.length,
+      requiredTargets: requiredTargets.length,
+      trustedTargets: trustedTargets.length,
+      trustedTargetsExcluded:
+        selectorOptions.trusted === "exclude" ? trustedTargets.length : 0,
+      truncatedTargets: Math.max(0, availableTargets - targets.length),
+    },
+    targets,
+  };
+}
+
+export { SUPPORTED_PURL_TYPES };

package/lib/audit/targets.poku.js

@@ -0,0 +1,331 @@
+import { assert, describe, it } from "poku";
+
+import {
+  collectAuditTargets,
+  extractPurlTargetsFromBom,
+  isRequiredComponentScope,
+  normalizePackageName,
+} from "./targets.js";
+
+function makeBom(components) {
+  return {
+    bomFormat: "CycloneDX",
+    components,
+    specVersion: "1.6",
+  };
+}
+
+describe("normalizePackageName()", () => {
+  it("normalizes Python-style package separators", () => {
+    assert.strictEqual(
+      normalizePackageName("My_Package.Name"),
+      "my-package-name",
+    );
+  });
+});
+
+describe("extractPurlTargetsFromBom()", () => {
+  it("extracts only npm and pypi purls", () => {
+    const bom = makeBom([
+      {
+        "bom-ref": "pkg:npm/left-pad@1.3.0",
+        name: "left-pad",
+        properties: [
+          { name: "cdx:npm:trustedPublishing", value: "true" },
+          { name: "cdx:npm:provenanceKeyId", value: "sigstore-key" },
+        ],
+        purl: "pkg:npm/left-pad@1.3.0",
+      },
+      {
+        "bom-ref": "pkg:pypi/requests@2.32.3",
+        name: "requests",
+        purl: "pkg:pypi/requests@2.32.3",
+      },
+      {
+        "bom-ref": "pkg:gem/rails@8.0.0",
+        name: "rails",
+        purl: "pkg:gem/rails@8.0.0",
+      },
+    ]);
+
+    const extracted = extractPurlTargetsFromBom(bom, "bom.json");
+
+    assert.strictEqual(extracted.targets.length, 2);
+    assert.strictEqual(extracted.skipped.length, 1);
+    assert.strictEqual(extracted.targets[0].type, "npm");
+    assert.strictEqual(
+      extracted.targets[0].properties[0].name,
+      "cdx:npm:trustedPublishing",
+    );
+    assert.strictEqual(
+      extracted.targets[0].properties[1].name,
+      "cdx:npm:provenanceKeyId",
+    );
+    assert.strictEqual(extracted.targets[1].type, "pypi");
+    assert.strictEqual(extracted.skipped[0].reason, "unsupported-ecosystem");
+  });
+
+  it("records invalid purls as skipped entries", () => {
+    const bom = makeBom([
+      {
+        "bom-ref": "bad-ref",
+        name: "broken",
+        purl: "not-a-purl",
+      },
+    ]);
+
+    const extracted = extractPurlTargetsFromBom(bom, "broken.json");
+
+    assert.strictEqual(extracted.targets.length, 0);
+    assert.strictEqual(extracted.skipped.length, 1);
+    assert.strictEqual(extracted.skipped[0].reason, "invalid-purl");
+  });
+});
+
+describe("isRequiredComponentScope()", () => {
+  it("treats missing scope as required and excludes optional/excluded scopes", () => {
+    assert.strictEqual(isRequiredComponentScope(undefined), true);
+    assert.strictEqual(isRequiredComponentScope("required"), true);
+    assert.strictEqual(isRequiredComponentScope("optional"), false);
+    assert.strictEqual(isRequiredComponentScope("excluded"), false);
+  });
+});
+
+describe("collectAuditTargets()", () => {
+  it("deduplicates targets across multiple BOMs while preserving sources", () => {
+    const inputBoms = [
+      {
+        bomJson: makeBom([
+          {
+            "bom-ref": "pkg:npm/left-pad@1.3.0",
+            name: "left-pad",
+            properties: [{ name: "cdx:npm:trustedPublishing", value: "true" }],
+            purl: "pkg:npm/left-pad@1.3.0",
+          },
+        ]),
+        source: "one.json",
+      },
+      {
+        bomJson: makeBom([
+          {
+            "bom-ref": "pkg:npm/left-pad@1.3.0",
+            name: "left-pad",
+            properties: [{ name: "cdx:npm:publisher", value: "octo" }],
+            purl: "pkg:npm/left-pad@1.3.0",
+          },
+          {
+            "bom-ref": "pkg:pypi/requests@2.32.3",
+            name: "requests",
+            purl: "pkg:pypi/requests@2.32.3",
+          },
+        ]),
+        source: "two.json",
+      },
+    ];
+
+    const collected = collectAuditTargets(inputBoms, { trusted: "include" });
+
+    assert.strictEqual(collected.targets.length, 2);
+    const npmTarget = collected.targets.find((target) => target.type === "npm");
+    assert.deepStrictEqual(npmTarget.sources, ["one.json", "two.json"]);
+    assert.strictEqual(npmTarget.bomRefs.length, 1);
+    assert.strictEqual(npmTarget.properties.length, 2);
+  });
+
+  it("respects maxTargets when supplied", () => {
+    const inputBoms = [
+      {
+        bomJson: makeBom([
+          {
+            "bom-ref": "pkg:npm/a@1.0.0",
+            name: "a",
+            purl: "pkg:npm/a@1.0.0",
+          },
+          {
+            "bom-ref": "pkg:npm/b@1.0.0",
+            name: "b",
+            purl: "pkg:npm/b@1.0.0",
+          },
+        ]),
+        source: "limit.json",
+      },
+    ];
+
+    const collected = collectAuditTargets(inputBoms, 1);
+
+    assert.strictEqual(collected.targets.length, 1);
+  });
+
+  it("filters predictive audit targets to required scope when requested", () => {
+    const inputBoms = [
+      {
+        bomJson: makeBom([
+          {
+            "bom-ref": "pkg:npm/core@1.0.0",
+            name: "core",
+            purl: "pkg:npm/core@1.0.0",
+            scope: "required",
+          },
+          {
+            "bom-ref": "pkg:npm/transitive@1.0.0",
+            name: "transitive",
+            purl: "pkg:npm/transitive@1.0.0",
+          },
+          {
+            "bom-ref": "pkg:npm/optional-addon@1.0.0",
+            name: "optional-addon",
+            purl: "pkg:npm/optional-addon@1.0.0",
+            scope: "optional",
+          },
+          {
+            "bom-ref": "pkg:pypi/unused@1.0.0",
+            name: "unused",
+            purl: "pkg:pypi/unused@1.0.0",
+            scope: "excluded",
+          },
+        ]),
+        source: "required.json",
+      },
+    ];
+
+    const collected = collectAuditTargets(inputBoms, { scope: "required" });
+
+    assert.deepStrictEqual(
+      collected.targets.map((target) => target.purl),
+      ["pkg:npm/core@1.0.0", "pkg:npm/transitive@1.0.0"],
+    );
+    assert.strictEqual(collected.stats.requiredTargets, 2);
+    assert.strictEqual(collected.stats.nonRequiredTargets, 0);
+  });
+
+  it("prioritizes required targets before optional ones when maxTargets is set", () => {
+    const inputBoms = [
+      {
+        bomJson: makeBom([
+          {
+            "bom-ref": "pkg:npm/a-optional@1.0.0",
+            name: "a-optional",
+            purl: "pkg:npm/a-optional@1.0.0",
+            scope: "optional",
+          },
+          {
+            "bom-ref": "pkg:npm/z-required@1.0.0",
+            name: "z-required",
+            purl: "pkg:npm/z-required@1.0.0",
+            scope: "required",
+          },
+        ]),
+        source: "priority.json",
+      },
+    ];
+
+    const collected = collectAuditTargets(inputBoms, { maxTargets: 1 });
+
+    assert.strictEqual(collected.targets.length, 1);
+    assert.strictEqual(collected.targets[0].purl, "pkg:npm/z-required@1.0.0");
+    assert.strictEqual(collected.stats.truncatedTargets, 1);
+  });
+
+  it("excludes trusted-publishing-backed targets by default", () => {
+    const inputBoms = [
+      {
+        bomJson: makeBom([
+          {
+            "bom-ref": "pkg:npm/trusted@1.0.0",
+            name: "trusted",
+            properties: [
+              {
+                name: "cdx:npm:trustedPublishing",
+                value: "true",
+              },
+            ],
+            purl: "pkg:npm/trusted@1.0.0",
+            scope: "required",
+          },
+          {
+            "bom-ref": "pkg:npm/plain@1.0.0",
+            name: "plain",
+            purl: "pkg:npm/plain@1.0.0",
+            scope: "required",
+          },
+        ]),
+        source: "trusted.json",
+      },
+    ];
+
+    const collected = collectAuditTargets(inputBoms);
+
+    assert.deepStrictEqual(
+      collected.targets.map((target) => target.purl),
+      ["pkg:npm/plain@1.0.0"],
+    );
+    assert.strictEqual(collected.stats.trustedTargets, 1);
+    assert.strictEqual(collected.stats.trustedTargetsExcluded, 1);
+  });
+
+  it("includes trusted-publishing-backed targets when explicitly requested", () => {
+    const inputBoms = [
+      {
+        bomJson: makeBom([
+          {
+            "bom-ref": "pkg:npm/trusted@1.0.0",
+            name: "trusted",
+            properties: [
+              {
+                name: "cdx:npm:trustedPublishing",
+                value: "true",
+              },
+            ],
+            purl: "pkg:npm/trusted@1.0.0",
+          },
+          {
+            "bom-ref": "pkg:pypi/plain@1.0.0",
+            name: "plain",
+            purl: "pkg:pypi/plain@1.0.0",
+          },
+        ]),
+        source: "include-trusted.json",
+      },
+    ];
+
+    const collected = collectAuditTargets(inputBoms, { trusted: "include" });
+
+    assert.strictEqual(collected.targets.length, 2);
+    assert.strictEqual(collected.stats.trustedTargetsExcluded, 0);
+  });
+
+  it("can restrict predictive audit targets to only trusted-publishing-backed packages", () => {
+    const inputBoms = [
+      {
+        bomJson: makeBom([
+          {
+            "bom-ref": "pkg:npm/trusted@1.0.0",
+            name: "trusted",
+            properties: [
+              {
+                name: "cdx:npm:trustedPublishing",
+                value: "true",
+              },
+            ],
+            purl: "pkg:npm/trusted@1.0.0",
+          },
+          {
+            "bom-ref": "pkg:npm/plain@1.0.0",
+            name: "plain",
+            purl: "pkg:npm/plain@1.0.0",
+          },
+        ]),
+        source: "only-trusted.json",
+      },
+    ];
+
+    const collected = collectAuditTargets(inputBoms, { trusted: "only" });
+
+    assert.deepStrictEqual(
+      collected.targets.map((target) => target.purl),
+      ["pkg:npm/trusted@1.0.0"],
+    );
+    assert.strictEqual(collected.stats.availableTargets, 1);
+    assert.strictEqual(collected.stats.trustedTargets, 1);
+  });
+});