@cyclonedx/cdxgen 12.3.3 → 12.4.0

package/lib/audit/targets.js

@@ -1,7 +1,11 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
 import { PackageURL } from "packageurl-js";
 
 import { hasTrustedPublishingProperties } from "../helpers/provenanceUtils.js";
 import {
+  dirNameStr,
   getCratesMetadata,
   getNpmMetadata,
   getPyMetadata,
@@ -9,13 +13,126 @@ import {
 
 const SUPPORTED_PURL_TYPES = new Set(["cargo", "npm", "pypi"]);
 const NON_REQUIRED_SCOPES = new Set(["excluded", "optional"]);
+const BUILTIN_PREDICTIVE_AUDIT_ALLOWLIST = Object.freeze(
+  loadAllowlistPrefixes(
+    join(dirNameStr, "data", "predictive-audit-allowlist.json"),
+    "built-in predictive audit allowlist",
+  ),
+);
+
+function normalizeAllowlistPrefix(prefix) {
+  if (typeof prefix !== "string") {
+    return undefined;
+  }
+  const normalizedPrefix = prefix.trim().toLowerCase();
+  return normalizedPrefix.startsWith("pkg:") ? normalizedPrefix : undefined;
+}
+
+function normalizeAllowlistPrefixes(prefixes) {
+  return [
+    ...new Set((prefixes || []).map(normalizeAllowlistPrefix).filter(Boolean)),
+  ];
+}
+
+function parseAllowlistPrefixes(rawContent, sourceLabel) {
+  const trimmedContent = rawContent?.trim();
+  if (!trimmedContent) {
+    return [];
+  }
+  if (trimmedContent.startsWith("[") || trimmedContent.startsWith("{")) {
+    const parsedValue = JSON.parse(trimmedContent);
+    if (Array.isArray(parsedValue)) {
+      return normalizeAllowlistPrefixes(parsedValue);
+    }
+    if (Array.isArray(parsedValue?.prefixes)) {
+      return normalizeAllowlistPrefixes(parsedValue.prefixes);
+    }
+    throw new Error(
+      `${sourceLabel} must be a JSON array or an object with a 'prefixes' array.`,
+    );
+  }
+  return normalizeAllowlistPrefixes(
+    trimmedContent
+      .split(/\r?\n/u)
+      .map((line) => line.replace(/\s+#.*$/u, "").trim())
+      .filter(Boolean),
+  );
+}
+
+function loadAllowlistPrefixes(filePath, sourceLabel) {
+  let rawContent;
+  try {
+    rawContent = readFileSync(filePath, "utf8");
+  } catch (error) {
+    const errorCodeSuffix =
+      typeof error?.code === "string" ? ` (${error.code})` : "";
+    throw new Error(
+      `Failed to load ${sourceLabel} from ${filePath}${errorCodeSuffix}.`,
+      {
+        cause: error,
+      },
+    );
+  }
+  try {
+    return parseAllowlistPrefixes(rawContent, sourceLabel);
+  } catch (error) {
+    throw new Error(
+      `Invalid ${sourceLabel} in ${filePath}. Use a JSON array, a JSON object with a 'prefixes' array, or newline-delimited purl prefixes.`,
+      {
+        cause: error,
+      },
+    );
+  }
+}
+
+function getAllowlistPrefixes(options) {
+  const customPrefixes = options?.allowlistFile
+    ? loadAllowlistPrefixes(options.allowlistFile, "predictive audit allowlist")
+    : normalizeAllowlistPrefixes(options?.allowlistPrefixes);
+  return normalizeAllowlistPrefixes([
+    ...BUILTIN_PREDICTIVE_AUDIT_ALLOWLIST,
+    ...customPrefixes,
+  ]);
+}
+
+/**
+ * Find the first allowlisted purl prefix that matches a component purl using
+ * a real purl boundary.
+ *
+ * This avoids over-filtering when one package name is only a lexical prefix of
+ * another package name (for example `pkg:npm/npm` vs `pkg:npm/npm-run-all`).
+ *
+ * @param {string | undefined} componentPurl Candidate component purl
+ * @param {string[] | undefined} allowlistPrefixes Normalized allowlist prefixes
+ * @returns {string | undefined} matched allowlist prefix, if any
+ */
+function findMatchingAllowlistPrefix(componentPurl, allowlistPrefixes) {
+  const normalizedPurl = componentPurl?.toLowerCase();
+  if (!normalizedPurl || !allowlistPrefixes?.length) {
+    return undefined;
+  }
+  return allowlistPrefixes.find((prefix) => {
+    if (!normalizedPurl.startsWith(prefix)) {
+      return false;
+    }
+    const boundaryCharacter = normalizedPurl[prefix.length];
+    return (
+      // Purl boundaries after a matched prefix can be the version separator,
+      // namespace/package separator, qualifier separator, or subpath separator.
+      boundaryCharacter === undefined ||
+      ["/", "@", "?", "#"].includes(boundaryCharacter)
+    );
+  });
+}
 
 /**
  * Normalize predictive audit target selection options.
  *
  * @param {number | object | undefined} options selector options or legacy maxTargets value
  * @returns {{
+ *   allowlistPrefixes: string[],
  *   maxTargets: number | undefined,
+ *   prioritizeDirectRuntime: boolean,
  *   scope: string | undefined,
  *   trusted: "exclude" | "include" | "only",
  * }} normalized options
@@ -23,6 +140,7 @@ const NON_REQUIRED_SCOPES = new Set(["excluded", "optional"]);
 function normalizeTargetSelectionOptions(options) {
   if (typeof options === "number") {
     return {
+      allowlistPrefixes: BUILTIN_PREDICTIVE_AUDIT_ALLOWLIST,
       maxTargets: options,
       prioritizeDirectRuntime: true,
       scope: undefined,
@@ -30,6 +148,7 @@ function normalizeTargetSelectionOptions(options) {
     };
   }
   return {
+    allowlistPrefixes: getAllowlistPrefixes(options),
     maxTargets: options?.maxTargets,
     prioritizeDirectRuntime: options?.prioritizeDirectRuntime ?? true,
     scope: options?.scope === "required" ? "required" : undefined,
@@ -452,6 +571,22 @@ export function extractPurlTargetsFromBom(bomJson, sourceName, options) {
       });
       continue;
     }
+    const matchedAllowlistPrefix = findMatchingAllowlistPrefix(
+      componentPurl,
+      selectorOptions.allowlistPrefixes,
+    );
+    if (matchedAllowlistPrefix) {
+      skipped.push({
+        reason: "allowlisted-purl-prefix",
+        matchedPrefix: matchedAllowlistPrefix,
+        source: sourceName,
+        purl: componentPurl,
+        bomRef: component?.["bom-ref"],
+        name: component?.name,
+        type: purlObj.type,
+      });
+      continue;
+    }
     targets.push({
       bomRef: component?.["bom-ref"],
       buildOnlyWorkspace:
@@ -511,6 +646,7 @@ export function extractPurlTargetsFromBom(bomJson, sourceName, options) {
  */
 export function collectAuditTargets(inputBoms, options) {
   const selectorOptions = normalizeTargetSelectionOptions(options);
+  const allowlistedTargetPurls = new Set();
   const skipped = [];
   const targetMap = new Map();
   for (const inputBom of inputBoms) {
@@ -519,7 +655,15 @@ export function collectAuditTargets(inputBoms, options) {
       inputBom.source,
       selectorOptions,
     );
-    skipped.push(...extracted.skipped);
+    for (const skippedEntry of extracted.skipped) {
+      skipped.push(skippedEntry);
+      if (
+        skippedEntry?.reason === "allowlisted-purl-prefix" &&
+        skippedEntry?.purl
+      ) {
+        allowlistedTargetPurls.add(skippedEntry.purl);
+      }
+    }
     for (const target of extracted.targets) {
       const existing = targetMap.get(target.purl);
       if (existing) {
@@ -630,6 +774,7 @@ export function collectAuditTargets(inputBoms, options) {
     skipped,
     stats: {
       availableTargets,
+      allowlistedTargetsExcluded: allowlistedTargetPurls.size,
       directRuntimeTargets: directRuntimeTargets.length,
       buildOnlyWorkspaceTargets: buildOnlyWorkspaceTargets.length,
       cargoRuntimeFacingTargets: cargoRuntimeFacingTargets.length,

package/lib/audit/targets.poku.js

@@ -1,3 +1,7 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
 import esmock from "esmock";
 import { assert, describe, it } from "poku";
 
@@ -17,6 +21,42 @@ function makeBom(components, extra = {}) {
   };
 }
 
+function makeAllowlistInputBom(source) {
+  return {
+    bomJson: makeBom([
+      {
+        "bom-ref": "pkg:npm/%40acme/core@1.0.0",
+        name: "core",
+        purl: "pkg:npm/%40acme/core@1.0.0",
+      },
+      {
+        "bom-ref": "pkg:pypi/internal-tool@1.0.0",
+        name: "internal-tool",
+        purl: "pkg:pypi/internal-tool@1.0.0",
+      },
+      {
+        "bom-ref": "pkg:npm/left-pad@1.3.0",
+        name: "left-pad",
+        purl: "pkg:npm/left-pad@1.3.0",
+      },
+    ]),
+    source,
+  };
+}
+
+function withTemporaryAllowlistFile(fileName, content, callback) {
+  const tmpDir = mkdtempSync(path.join(os.tmpdir(), "cdx-audit-allowlist-"));
+  const allowlistFile = path.join(tmpDir, fileName);
+  writeFileSync(allowlistFile, content);
+  try {
+    // Let test failures propagate after cleanup so the original assertion error
+    // is preserved for the runner.
+    callback(allowlistFile);
+  } finally {
+    rmSync(tmpDir, { force: true, recursive: true });
+  }
+}
+
 describe("normalizePackageName()", () => {
   it("normalizes Python-style package separators", () => {
     assert.strictEqual(
@@ -312,6 +352,152 @@ describe("collectAuditTargets()", () => {
     assert.strictEqual(collected.stats.nonRequiredTargets, 0);
   });
 
+  it("skips built-in well-known npm allowlist prefixes by default", () => {
+    const inputBoms = [
+      {
+        bomJson: makeBom([
+          {
+            "bom-ref": "pkg:npm/%40babel/parser@7.29.3",
+            name: "parser",
+            purl: "pkg:npm/%40babel/parser@7.29.3",
+          },
+          {
+            "bom-ref": "pkg:npm/npm@10.9.0",
+            name: "npm",
+            purl: "pkg:npm/npm@10.9.0",
+          },
+          {
+            "bom-ref": "pkg:npm/%40types/node@24.0.0",
+            name: "node",
+            purl: "pkg:npm/%40types/node@24.0.0",
+          },
+          {
+            "bom-ref": "pkg:npm/left-pad@1.3.0",
+            name: "left-pad",
+            purl: "pkg:npm/left-pad@1.3.0",
+          },
+        ]),
+        source: "allowlist-default.json",
+      },
+    ];
+
+    const collected = collectAuditTargets(inputBoms, { trusted: "include" });
+
+    assert.deepStrictEqual(
+      collected.targets.map((target) => target.purl),
+      ["pkg:npm/left-pad@1.3.0"],
+    );
+    assert.strictEqual(collected.stats.allowlistedTargetsExcluded, 3);
+    assert.strictEqual(
+      collected.skipped.filter(
+        (entry) => entry.reason === "allowlisted-purl-prefix",
+      ).length,
+      3,
+    );
+  });
+
+  it("supports additive custom predictive audit allowlists", () => {
+    withTemporaryAllowlistFile(
+      "custom-allowlist.json",
+      `${JSON.stringify(["pkg:npm/%40acme", "pkg:pypi/internal-tool"])}\n`,
+      (allowlistFile) => {
+        const inputBoms = [makeAllowlistInputBom("allowlist-custom.json")];
+
+        const collected = collectAuditTargets(inputBoms, {
+          allowlistFile,
+          trusted: "include",
+        });
+
+        assert.deepStrictEqual(
+          collected.targets.map((target) => target.purl),
+          ["pkg:npm/left-pad@1.3.0"],
+        );
+        assert.strictEqual(collected.stats.allowlistedTargetsExcluded, 2);
+      },
+    );
+  });
+
+  it("supports newline-delimited custom allowlists with comments", () => {
+    withTemporaryAllowlistFile(
+      "custom-allowlist.txt",
+      [
+        "pkg:npm/%40acme # internal namespace",
+        "",
+        "pkg:pypi/internal-tool",
+      ].join("\n"),
+      (allowlistFile) => {
+        const inputBoms = [makeAllowlistInputBom("allowlist-custom-text.json")];
+
+        const collected = collectAuditTargets(inputBoms, {
+          allowlistFile,
+          trusted: "include",
+        });
+
+        assert.deepStrictEqual(
+          collected.targets.map((target) => target.purl),
+          ["pkg:npm/left-pad@1.3.0"],
+        );
+        assert.strictEqual(collected.stats.allowlistedTargetsExcluded, 2);
+      },
+    );
+  });
+
+  it("supports custom allowlists provided as a prefixes object", () => {
+    withTemporaryAllowlistFile(
+      "custom-allowlist.json",
+      `${JSON.stringify({ prefixes: ["pkg:npm/%40acme", "pkg:pypi/internal-tool"] })}\n`,
+      (allowlistFile) => {
+        const inputBoms = [
+          makeAllowlistInputBom("allowlist-custom-prefixes.json"),
+        ];
+
+        const collected = collectAuditTargets(inputBoms, {
+          allowlistFile,
+          trusted: "include",
+        });
+
+        assert.deepStrictEqual(
+          collected.targets.map((target) => target.purl),
+          ["pkg:npm/left-pad@1.3.0"],
+        );
+        assert.strictEqual(collected.stats.allowlistedTargetsExcluded, 2);
+      },
+    );
+  });
+
+  it("requires a purl boundary after an allowlisted prefix", () => {
+    const inputBoms = [
+      {
+        bomJson: makeBom([
+          {
+            "bom-ref": "pkg:npm/npm@10.9.0",
+            name: "npm",
+            purl: "pkg:npm/npm@10.9.0",
+          },
+          {
+            "bom-ref": "pkg:npm/npm-run-all@4.1.5",
+            name: "npm-run-all",
+            purl: "pkg:npm/npm-run-all@4.1.5",
+          },
+          {
+            "bom-ref": "pkg:npm/npm-check-updates@17.1.0",
+            name: "npm-check-updates",
+            purl: "pkg:npm/npm-check-updates@17.1.0",
+          },
+        ]),
+        source: "allowlist-boundary.json",
+      },
+    ];
+
+    const collected = collectAuditTargets(inputBoms, { trusted: "include" });
+
+    assert.deepStrictEqual(
+      collected.targets.map((target) => target.purl),
+      ["pkg:npm/npm-check-updates@17.1.0", "pkg:npm/npm-run-all@4.1.5"],
+    );
+    assert.strictEqual(collected.stats.allowlistedTargetsExcluded, 1);
+  });
+
   it("prioritizes required targets before optional ones when maxTargets is set", () => {
     const inputBoms = [
       {