@cdxgen/cdxgen 0.0.1 → 13.0.1

package/lib/audit/index.js

@@ -0,0 +1,2800 @@
+import { createHash } from "node:crypto";
+import { readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import process from "node:process";
+
+import { createBom } from "../cli/index.js";
+import {
+  isDryRun,
+  readEnvironmentVariable,
+  recordActivity,
+} from "../core/activity.js";
+import {
+  getTmpDir,
+  safeExistsSync,
+  safeMkdirSync,
+  safeMkdtempSync,
+  safeRmSync,
+  safeWriteSync,
+} from "../core/fs.js";
+import { thoughtLog } from "../core/logger.js";
+import { dirNameStr } from "../core/paths.js";
+import { PROJECT_CONFIG_FILENAMES } from "../core/projectConfig.js";
+import { fetchPomXmlAsJson } from "../ecosystems/ecosystems.js";
+import { DEFAULT_HBOM_AUDIT_CATEGORIES } from "../inventory/auditCategories.js";
+import {
+  DEFAULT_CDX_SPEC_VERSION,
+  getCycloneDxFormat,
+  getNonCycloneDxErrorMessage,
+  isCycloneDxBom,
+} from "../inventory/bomUtils.js";
+import {
+  collectPolicyViolations,
+  loadPolicy,
+} from "../inventory/licenseEnhancer.js";
+import {
+  hasRegistryProvenanceEvidenceProperties,
+  hasTrustedPublishingProperties,
+} from "../inventory/provenanceUtils.js";
+import {
+  cleanupSourceDir,
+  findGitRefForPurlVersion,
+  hardenedGitCommand,
+  isSafeGitRefName,
+  prefetchGitUrlSources,
+  resolveGitUrlFromPurl,
+  resolvePurlSourceDirectory,
+  sanitizeRemoteUrlForLogs,
+} from "../inventory/source.js";
+import { executeOsQuery } from "../managers/binary.js";
+import { getBomWithOras } from "../managers/oci.js";
+import {
+  auditBom,
+  isHbomLikeBom,
+  isObomLikeBom,
+} from "../stages/postgen/auditBom.js";
+import { postProcess } from "../stages/postgen/postgen.js";
+import { formatTargetLabel } from "./progress.js";
+import { renderAuditReport } from "./reporters.js";
+import {
+  SEVERITY_ORDER,
+  scoreTargetRisk,
+  severityMeetsThreshold,
+} from "./scoring.js";
+import {
+  collectAuditTargets,
+  enrichInputBomsWithRegistryMetadata,
+  normalizePackageName,
+} from "./targets.js";
+
+/** Default predictive audit category list applied when none are explicitly requested. */
+export const DEFAULT_AUDIT_CATEGORIES = [
+  "ai-agent",
+  "ci-permission",
+  "dependency-source",
+  "package-integrity",
+];
+
+const DIRECT_AUDIT_TOOL_NAME = "cdx-audit";
+
+const AUDIT_CACHE_DIRNAME = ".cdx-audit";
+const AUDIT_CACHE_BOM_FILE = "source-bom.json";
+const AUDIT_CACHE_META_FILE = "source-bom.meta.json";
+const CLONE_RETRY_DELAYS_MS = [750, 1500];
+const LARGE_PREDICTIVE_AUDIT_THRESHOLD = 50;
+const VERY_LARGE_PREDICTIVE_AUDIT_THRESHOLD = 100;
+
+const PYTHON_METADATA_FILES = ["pyproject.toml", "setup.cfg", "setup.py"];
+const PYTHON_HEURISTIC_FILENAMES = new Set(["setup.py", "__init__.py"]);
+const PYTHON_HEURISTIC_FILE_LIMIT = 32;
+const PYTHON_HEURISTIC_MAX_FILE_BYTES = 256 * 1024;
+const PYTHON_SKIP_DIRS = new Set([
+  ".git",
+  ".hg",
+  ".tox",
+  ".venv",
+  "__pycache__",
+  "build",
+  "dist",
+  "node_modules",
+  "site-packages",
+  "venv",
+]);
+
+const PYTHON_EXECUTION_PATTERN =
+  /\b(?:exec|eval|compile)\s*\(|\b(?:subprocess\.(?:Popen|run|call|check_output)|os\.(?:system|popen))\b/i;
+
+const PYTHON_NETWORK_PATTERN =
+  /\b(?:requests\.(?:get|post|put|patch)|urllib(?:\.request)?\.urlopen|http\.client|socket\.socket)\b/i;
+
+const PYTHON_OBFUSCATION_PATTERN =
+  /\b(?:base64\.(?:b64decode|urlsafe_b64decode)|binascii\.a2b_base64|marshal\.loads|zlib\.decompress|codecs\.decode\s*\([^)]*base64|bytes\.fromhex)\b/i;
+
+const PYTHON_SETUP_CMDCLASS_PATTERN = /\bcmdclass\s*=/i;
+
+/**
+ * Read and validate a CycloneDX BOM file.
+ *
+ * @param {string} bomPath BOM file path
+ * @returns {object} parsed CycloneDX BOM
+ */
+export function loadBomFile(bomPath) {
+  const resolvedPath = resolve(bomPath);
+  let bomJson;
+  try {
+    bomJson = JSON.parse(readFileSync(resolvedPath, "utf8"));
+  } catch (error) {
+    throw new Error(`Failed to parse ${resolvedPath}: ${error.message}`);
+  }
+  if (!isCycloneDxBom(bomJson)) {
+    throw new Error(getNonCycloneDxErrorMessage(bomJson, "cdx-audit"));
+  }
+  return bomJson;
+}
+
+/**
+ * Recursively list JSON files under a BOM directory.
+ *
+ * @param {string} bomDir directory path
+ * @returns {string[]} discovered file paths
+ */
+export function listBomFiles(bomDir) {
+  const foundFiles = [];
+  const queue = [resolve(bomDir)];
+  while (queue.length) {
+    const currentDir = queue.shift();
+    const entries = readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const entryPath = join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        queue.push(entryPath);
+        continue;
+      }
+      if (entry.isFile() && entry.name.endsWith(".json")) {
+        foundFiles.push(entryPath);
+      }
+    }
+  }
+  return foundFiles.sort();
+}
+
+/**
+ * Load input BOM files from either a single file or a directory.
+ *
+ * @param {object} options CLI options
+ * @returns {{ source: string, bomJson: object }[]} loaded input BOMs
+ */
+export function loadInputBoms(options) {
+  const inputBoms = [];
+  if (options.bom) {
+    inputBoms.push({
+      bomJson: loadBomFile(options.bom),
+      source: resolve(options.bom),
+    });
+  }
+  if (options.bomDir) {
+    const bomFiles = listBomFiles(options.bomDir);
+    for (const bomFile of bomFiles) {
+      try {
+        inputBoms.push({
+          bomJson: loadBomFile(bomFile),
+          source: bomFile,
+        });
+      } catch (error) {
+        console.warn(
+          `Skipping non-CycloneDX JSON file '${bomFile}': ${error.message}`,
+        );
+      }
+    }
+  }
+  return inputBoms;
+}
+
+function summarizeDirectAuditFindings(findings = []) {
+  const findingsBySeverity = {
+    critical: 0,
+    high: 0,
+    low: 0,
+    medium: 0,
+  };
+  let maxSeverity = "none";
+  for (const finding of findings) {
+    const severity = finding?.severity || "low";
+    if (findingsBySeverity[severity] !== undefined) {
+      findingsBySeverity[severity] += 1;
+    }
+    if (
+      (SEVERITY_ORDER[severity] ?? -1) > (SEVERITY_ORDER[maxSeverity] ?? -1)
+    ) {
+      maxSeverity = severity;
+    }
+  }
+  return {
+    findingsBySeverity,
+    findingsCount: findings.length,
+    maxSeverity,
+  };
+}
+
+function buildDirectAuditOptions(bomJson, options = {}) {
+  const explicitCategories = options.categories?.length
+    ? options.categories.join(",")
+    : undefined;
+  return {
+    aiProvenance: options.aiProvenance,
+    bomAuditCategories:
+      explicitCategories ||
+      (isHbomLikeBom(bomJson)
+        ? DEFAULT_HBOM_AUDIT_CATEGORIES
+        : isObomLikeBom(bomJson)
+          ? "obom-runtime"
+          : undefined),
+    bomAuditMinSeverity: options.minSeverity || "low",
+    bomAuditRulesDir: options.rulesDir,
+    workspaceDir: options.workspaceDir,
+  };
+}
+
+/**
+ * Run the direct (post-generation) BOM policy audit over loaded input BOMs.
+ *
+ * Audits each supplied BOM with {@link auditBom}, collects per-BOM findings and
+ * summaries, and aggregates them into a single report keyed by `auditMode: "direct"`.
+ *
+ * @param {{ source: string, bomJson: object }[]} inputBoms Loaded CycloneDX BOM objects to audit
+ * @param {object} [options={}] CLI options including optional category, severity, and rules configuration
+ * @returns {Promise<object>} Aggregate direct audit report with per-BOM results and a rollup summary
+ */
+export async function runDirectBomAuditFromBoms(inputBoms, options = {}) {
+  if (!inputBoms.length) {
+    throw new Error("No CycloneDX BOM inputs were found.");
+  }
+  const results = [];
+  for (const inputBom of inputBoms) {
+    const directAuditOptions = buildDirectAuditOptions(
+      inputBom.bomJson,
+      options,
+    );
+    const findings = await auditBom(inputBom.bomJson, {
+      ...directAuditOptions,
+      getBomWithOras,
+    });
+    results.push({
+      auditOptions: directAuditOptions,
+      bomFormat: getCycloneDxFormat(inputBom.bomJson),
+      findings,
+      serialNumber: inputBom.bomJson?.serialNumber,
+      source: inputBom.source,
+      specVersion: inputBom.bomJson?.specVersion,
+      status: "audited",
+      summary: summarizeDirectAuditFindings(findings),
+    });
+  }
+  const summary = {
+    findingsBySeverity: {
+      critical: 0,
+      high: 0,
+      low: 0,
+      medium: 0,
+    },
+    inputBomCount: inputBoms.length,
+    maxSeverity: "none",
+    totalFindings: 0,
+    bomsWithFindings: 0,
+  };
+  for (const result of results) {
+    summary.totalFindings += result.summary.findingsCount;
+    if (result.summary.findingsCount > 0) {
+      summary.bomsWithFindings += 1;
+    }
+    for (const [severity, count] of Object.entries(
+      result.summary.findingsBySeverity,
+    )) {
+      summary.findingsBySeverity[severity] += count;
+    }
+    if (
+      (SEVERITY_ORDER[result.summary.maxSeverity] ?? -1) >
+      (SEVERITY_ORDER[summary.maxSeverity] ?? -1)
+    ) {
+      summary.maxSeverity = result.summary.maxSeverity;
+    }
+  }
+  return {
+    auditMode: "direct",
+    generatedAt: new Date().toISOString(),
+    inputs: inputBoms.map((inputBom) => inputBom.source),
+    results,
+    summary,
+    tool: {
+      name: DIRECT_AUDIT_TOOL_NAME,
+      version: readPackageVersion(),
+    },
+  };
+}
+
+/**
+ * Read the package version from the local package.json file.
+ *
+ * @returns {string} package version
+ */
+function readPackageVersion() {
+  const packageJson = JSON.parse(
+    readFileSync(join(dirNameStr, "package.json"), "utf8"),
+  );
+  return packageJson.version;
+}
+
+/**
+ * Build a deterministic directory-safe slug for report and workspace paths.
+ *
+ * @param {object} target audit target
+ * @returns {string} slug string
+ */
+function targetSlug(target) {
+  const packageName = target.namespace
+    ? `${target.namespace}-${target.name}`
+    : target.name;
+  const normalized = normalizePackageName(packageName)
+    .replace(/[^a-z0-9-]/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+  const version = normalizePackageName(target.version || "latest") || "latest";
+  const digest = createHash("sha256")
+    .update(target.purl)
+    .digest("hex")
+    .slice(0, 12);
+  return `${target.type}-${normalized || "package"}-${version}-${digest}`;
+}
+
+/**
+ * Ensure a parent directory exists before writing a file.
+ *
+ * @param {string} filePath file path to create
+ * @param {string} content file content
+ * @returns {void}
+ */
+function writeTextFile(filePath, content) {
+  const parentDir = dirname(filePath);
+  if (!safeExistsSync(parentDir)) {
+    safeMkdirSync(parentDir, { recursive: true });
+  }
+  safeWriteSync(filePath, content);
+}
+
+/**
+ * Ensure a parent directory exists before writing JSON.
+ *
+ * @param {string} filePath file path to create
+ * @param {object} payload JSON payload
+ * @returns {void}
+ */
+function writeJsonFile(filePath, payload) {
+  writeTextFile(filePath, `${JSON.stringify(payload, null, 2)}\n`);
+}
+
+function sleep(ms) {
+  return new Promise((resolvePromise) => {
+    setTimeout(resolvePromise, ms);
+  });
+}
+
+function isPathWithin(parentDir, childPath) {
+  const normalizePath = (candidatePath) => {
+    try {
+      return realpathSync.native
+        ? realpathSync.native(candidatePath)
+        : realpathSync(candidatePath);
+    } catch {
+      return resolve(candidatePath);
+    }
+  };
+  const normalizedChild = normalizePath(childPath);
+  const candidateParents = [parentDir];
+  if (process.platform !== "win32") {
+    candidateParents.push("/tmp");
+    candidateParents.push("/private/tmp");
+  }
+  return candidateParents.some((candidateParent) => {
+    const normalizedParent = normalizePath(candidateParent);
+    return (
+      normalizedChild === normalizedParent ||
+      normalizedChild.startsWith(`${normalizedParent}/`)
+    );
+  });
+}
+
+function isTemporaryWorkspaceDir(workspaceDir) {
+  return workspaceDir ? isPathWithin(getTmpDir(), workspaceDir) : false;
+}
+
+function prepareWorkspaceContext(options = {}) {
+  if (!options.workspaceDir) {
+    return {
+      cleanupOnFinish: false,
+      workspaceDir: undefined,
+    };
+  }
+  const workspaceDir = resolve(options.workspaceDir);
+  const existed = safeExistsSync(workspaceDir);
+  if (!existed) {
+    safeMkdirSync(workspaceDir, { recursive: true });
+  }
+  return {
+    cleanupOnFinish: !existed && isTemporaryWorkspaceDir(workspaceDir),
+    workspaceDir,
+  };
+}
+
+function getWorkspaceTargetDir(workspaceDir, target) {
+  return join(resolve(workspaceDir), targetSlug(target));
+}
+
+function getWorkspaceCachePaths(workspaceDir, target) {
+  const targetDir = getWorkspaceTargetDir(workspaceDir, target);
+  const cacheDir = join(targetDir, AUDIT_CACHE_DIRNAME);
+  return {
+    cacheDir,
+    metadataFile: join(cacheDir, AUDIT_CACHE_META_FILE),
+    sourceBomFile: join(cacheDir, AUDIT_CACHE_BOM_FILE),
+    targetDir,
+  };
+}
+
+function loadCachedChildBom(workspaceDir, target) {
+  if (!workspaceDir) {
+    return undefined;
+  }
+  const cachePaths = getWorkspaceCachePaths(workspaceDir, target);
+  if (!safeExistsSync(cachePaths.sourceBomFile)) {
+    return undefined;
+  }
+  try {
+    const bomJson = loadBomFile(cachePaths.sourceBomFile);
+    let metadata = {};
+    if (safeExistsSync(cachePaths.metadataFile)) {
+      metadata = JSON.parse(readFileSync(cachePaths.metadataFile, "utf8"));
+    }
+    const scanDir = metadata.scanDirRelative
+      ? resolve(cachePaths.targetDir, metadata.scanDirRelative)
+      : cachePaths.targetDir;
+    return {
+      bomJson,
+      cacheDir: cachePaths.cacheDir,
+      repoUrl: metadata.repoUrl,
+      resolution: metadata.resolution,
+      scanDir,
+      sourceDirectoryConfidence: metadata.sourceDirectoryConfidence || "medium",
+      versionMatched: metadata.versionMatched !== false,
+    };
+  } catch {
+    return undefined;
+  }
+}
+
+function writeCachedChildBom(workspaceDir, target, payload) {
+  if (!workspaceDir || !payload?.bomJson) {
+    return;
+  }
+  const cachePaths = getWorkspaceCachePaths(workspaceDir, target);
+  safeMkdirSync(cachePaths.cacheDir, { recursive: true });
+  writeJsonFile(cachePaths.sourceBomFile, payload.bomJson);
+  writeJsonFile(cachePaths.metadataFile, {
+    generatedAt: new Date().toISOString(),
+    repoUrl: payload.repoUrl,
+    resolution: payload.resolution,
+    scanDirRelative: payload.scanDir
+      ? relative(cachePaths.targetDir, resolve(payload.scanDir)) || "."
+      : ".",
+    sourceDirectoryConfidence: payload.sourceDirectoryConfidence,
+    versionMatched: payload.versionMatched,
+  });
+}
+
+function persistAuditArtifacts(result, options, sourceBomJson) {
+  if (!options.reportsDir) {
+    return result;
+  }
+  const resultDir = join(
+    resolve(options.reportsDir),
+    targetSlug(result.target),
+  );
+  safeMkdirSync(resultDir, { recursive: true });
+  result.reportDir = resultDir;
+  result.findingsFile = join(resultDir, "findings.json");
+  result.summaryFile = join(resultDir, "summary.json");
+  if (sourceBomJson) {
+    result.sourceBomFile = join(resultDir, "source-bom.json");
+    writeJsonFile(result.sourceBomFile, sourceBomJson);
+  }
+  writeJsonFile(result.findingsFile, result.findings || []);
+  writeJsonFile(result.summaryFile, {
+    assessment: result.assessment,
+    cacheHit: result.cacheHit || false,
+    error: result.error,
+    errorType: result.errorType,
+    findingsCount: result.findings?.length || 0,
+    repoUrl: result.repoUrl,
+    sourceDirectoryConfidence: result.sourceDirectoryConfidence,
+    status: result.status,
+    target: result.target,
+  });
+  return result;
+}
+
+/**
+ * Emit a progress event when a callback is configured.
+ *
+ * @param {object} options CLI options
+ * @param {object} event progress event payload
+ * @returns {void}
+ */
+function emitProgress(options, event) {
+  if (typeof options?.onProgress === "function") {
+    options.onProgress(event);
+  }
+}
+
+function buildPredictiveAuditEstimate(selectedTargets) {
+  if (selectedTargets >= VERY_LARGE_PREDICTIVE_AUDIT_THRESHOLD) {
+    return "This may take 10+ minutes depending on repository lookups and child SBOM generation.";
+  }
+  if (selectedTargets >= LARGE_PREDICTIVE_AUDIT_THRESHOLD) {
+    return "This may take several minutes depending on repository lookups and child SBOM generation.";
+  }
+  return undefined;
+}
+
+function buildPredictiveAuditPreflightMessage(extractedTargets, options) {
+  const selectedTargets = extractedTargets?.targets?.length || 0;
+  const allowlistedTargetsExcluded =
+    extractedTargets?.stats?.allowlistedTargetsExcluded || 0;
+  const availableTargets = extractedTargets?.stats?.availableTargets || 0;
+  const requiredTargets = extractedTargets?.stats?.requiredTargets || 0;
+  const trustedTargetsExcluded =
+    extractedTargets?.stats?.trustedTargetsExcluded || 0;
+  const truncatedTargets = extractedTargets?.stats?.truncatedTargets || 0;
+  const estimate = buildPredictiveAuditEstimate(selectedTargets);
+  const trustedHint = options?.trustedSelectionHelp
+    ? ` ${options.trustedSelectionHelp}`
+    : "";
+  const trustedExclusionMessage = trustedTargetsExcluded
+    ? ` Skipping ${trustedTargetsExcluded} trusted-publishing-backed package(s) by default.${trustedHint}`
+    : "";
+  const customAllowlistSuffix = options?.allowlistFile
+    ? " and your custom allowlist"
+    : "";
+  const allowlistExclusionMessage = allowlistedTargetsExcluded
+    ? ` Skipping ${allowlistedTargetsExcluded} allowlisted package(s) using the built-in well-known purl prefix filter${customAllowlistSuffix}.`
+    : "";
+  if (!estimate && availableTargets < LARGE_PREDICTIVE_AUDIT_THRESHOLD) {
+    const passiveMessage =
+      `${trustedExclusionMessage}${allowlistExclusionMessage}`.trim();
+    return passiveMessage || undefined;
+  }
+  if (options?.scope === "required") {
+    return `Predictive audit will scan ${selectedTargets} required package(s). ${estimate || "Large required-only scans may still take a while depending on repository lookups and child SBOM generation."}${trustedExclusionMessage}${allowlistExclusionMessage}`;
+  }
+  if (truncatedTargets > 0) {
+    const additionalTargets = Math.max(0, selectedTargets - requiredTargets);
+    return `Predictive audit selected ${selectedTargets} of ${availableTargets} package(s) (${requiredTargets} required${additionalTargets ? ` + ${additionalTargets} additional` : ""}) using required-first prioritization. ${estimate || "This run was trimmed to keep audit time reasonable."}${trustedExclusionMessage}${allowlistExclusionMessage}`;
+  }
+  return `Predictive audit will scan ${selectedTargets} package(s). ${estimate || "Large predictive audits may still take a while depending on repository lookups and child SBOM generation."}${trustedExclusionMessage}${allowlistExclusionMessage}`;
+}
+
+/**
+ * Read a custom property 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;
+}
+
+function getTargetNumberProperty(target, propertyName) {
+  const value = getTargetProperty(target, propertyName);
+  if (!value) {
+    return undefined;
+  }
+  const numericValue = Number(value);
+  return Number.isFinite(numericValue) ? numericValue : undefined;
+}
+
+function getTargetTimestampProperty(target, propertyName) {
+  const value = getTargetProperty(target, propertyName);
+  if (!value) {
+    return undefined;
+  }
+  const timestamp = Date.parse(value);
+  return Number.isNaN(timestamp) ? undefined : timestamp;
+}
+
+function getTargetListProperty(target, propertyName) {
+  const value = getTargetProperty(target, propertyName);
+  if (!value) {
+    return [];
+  }
+  return [
+    ...new Set(
+      value
+        .split(",")
+        .map((entry) => entry.trim())
+        .filter(Boolean),
+    ),
+  ];
+}
+
+function isEstablishedPackage(target, propertyPrefix) {
+  const packageCreatedTime = getTargetTimestampProperty(
+    target,
+    `${propertyPrefix}:packageCreatedTime`,
+  );
+  const versionCount = getTargetNumberProperty(
+    target,
+    `${propertyPrefix}:versionCount`,
+  );
+  if (!packageCreatedTime || !versionCount) {
+    return false;
+  }
+  const packageAgeMs = Date.now() - packageCreatedTime;
+  return packageAgeMs >= 1000 * 60 * 60 * 24 * 30 && versionCount >= 3;
+}
+
+function isRecentRelease(target, propertyPrefix) {
+  const publishTime = getTargetTimestampProperty(
+    target,
+    `${propertyPrefix}:publishTime`,
+  );
+  if (!publishTime) {
+    return false;
+  }
+  const releaseAgeMs = Date.now() - publishTime;
+  return releaseAgeMs >= 0 && releaseAgeMs <= 1000 * 60 * 60 * 72;
+}
+
+function hasPublisherDrift(target, propertyPrefix) {
+  return (
+    getTargetProperty(target, `${propertyPrefix}:publisherDrift`) === "true"
+  );
+}
+
+function hasMaintainerSetDrift(target, propertyPrefix) {
+  return (
+    getTargetProperty(target, `${propertyPrefix}:maintainerSetDrift`) ===
+      "true" ||
+    getTargetProperty(target, `${propertyPrefix}:uploaderSetDrift`) === "true"
+  );
+}
+
+function hasPartialIdentitySetDrift(target, propertyPrefix) {
+  const explicitPropertyName =
+    propertyPrefix === "cdx:npm"
+      ? `${propertyPrefix}:maintainerSetPartialDrift`
+      : `${propertyPrefix}:uploaderSetPartialDrift`;
+  if (getTargetProperty(target, explicitPropertyName) === "true") {
+    return true;
+  }
+  const currentPropertyName =
+    propertyPrefix === "cdx:npm"
+      ? `${propertyPrefix}:maintainerSet`
+      : `${propertyPrefix}:uploaderSet`;
+  const priorPropertyName =
+    propertyPrefix === "cdx:npm"
+      ? `${propertyPrefix}:priorMaintainerSet`
+      : `${propertyPrefix}:priorUploaderSet`;
+  const currentSet = getTargetListProperty(target, currentPropertyName);
+  const priorSet = getTargetListProperty(target, priorPropertyName);
+  if (!currentSet.length || !priorSet.length) {
+    return false;
+  }
+  const priorValues = new Set(priorSet);
+  const overlapCount = currentSet.filter((value) =>
+    priorValues.has(value),
+  ).length;
+  if (overlapCount === 0) {
+    return false;
+  }
+  const unionCount = new Set([...currentSet, ...priorSet]).size;
+  return (
+    overlapCount < unionCount &&
+    (overlapCount < currentSet.length || overlapCount < priorSet.length)
+  );
+}
+
+function hasDormantReleaseGapAnomaly(target, propertyPrefix) {
+  const currentGapDays = getTargetNumberProperty(
+    target,
+    `${propertyPrefix}:releaseGapDays`,
+  );
+  const baselineGapDays = getTargetNumberProperty(
+    target,
+    `${propertyPrefix}:releaseGapBaselineDays`,
+  );
+  const sampleSize = getTargetNumberProperty(
+    target,
+    `${propertyPrefix}:releaseGapSampleSize`,
+  );
+  if (!currentGapDays || !baselineGapDays || !sampleSize || sampleSize < 3) {
+    return false;
+  }
+  return currentGapDays >= Math.max(90, baselineGapDays * 8);
+}
+
+function hasCompressedCadence(target, propertyPrefix) {
+  if (
+    getTargetProperty(target, `${propertyPrefix}:compressedCadence`) === "true"
+  ) {
+    return true;
+  }
+  const currentGapDays = getTargetNumberProperty(
+    target,
+    `${propertyPrefix}:releaseGapDays`,
+  );
+  const baselineGapDays = getTargetNumberProperty(
+    target,
+    `${propertyPrefix}:releaseGapBaselineDays`,
+  );
+  const sampleSize = getTargetNumberProperty(
+    target,
+    `${propertyPrefix}:releaseGapSampleSize`,
+  );
+  if (
+    currentGapDays === undefined ||
+    baselineGapDays === undefined ||
+    sampleSize === undefined ||
+    sampleSize < 3 ||
+    currentGapDays <= 0 ||
+    baselineGapDays <= 0 ||
+    baselineGapDays < 21
+  ) {
+    return false;
+  }
+  return currentGapDays <= 14 && currentGapDays / baselineGapDays <= 0.33;
+}
+
+/**
+ * Build low-noise provenance-aware contextual findings from the root BOM target.
+ *
+ * These are intentionally conservative and only fire when there is explicit risk
+ * posture already present in the target metadata.
+ *
+ * @param {object} target audit target
+ * @returns {object[]} contextual findings
+ */
+export function buildTargetContextFindings(target) {
+  const findings = [];
+  const hasTrustedPublishing = hasTrustedPublishingProperties(
+    target?.properties,
+  );
+  const hasProvenanceEvidence = hasRegistryProvenanceEvidenceProperties(
+    target?.properties,
+  );
+  if (target.type === "npm") {
+    const hasInstallScript =
+      getTargetProperty(target, "cdx:npm:hasInstallScript") === "true";
+    const establishedPackage = isEstablishedPackage(target, "cdx:npm");
+    const recentRelease = isRecentRelease(target, "cdx:npm");
+    const publisherDrift = hasPublisherDrift(target, "cdx:npm");
+    const maintainerSetDrift = hasMaintainerSetDrift(target, "cdx:npm");
+    const partialMaintainerSetDrift = hasPartialIdentitySetDrift(
+      target,
+      "cdx:npm",
+    );
+    const dormantReleaseGapAnomaly = hasDormantReleaseGapAnomaly(
+      target,
+      "cdx:npm",
+    );
+    const compressedCadence = hasCompressedCadence(target, "cdx:npm");
+    if (
+      target.version &&
+      hasInstallScript &&
+      !hasTrustedPublishing &&
+      !hasProvenanceEvidence
+    ) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "Install-time execution combined with missing registry-visible provenance raises future tampering risk.",
+        location: {
+          bomRef: target.bomRefs?.[0],
+          purl: target.purl,
+        },
+        message: `npm package '${target.name}@${target.version}' has install-time execution hooks but no registry-visible trusted publishing or provenance evidence.`,
+        mitigation:
+          "Prefer versions with registry-visible provenance evidence, review install scripts carefully, and pin/allowlist publishers for high-risk packages.",
+        ruleId: "PROV-001",
+        severity: "medium",
+      });
+    }
+    if (
+      target.version &&
+      establishedPackage &&
+      recentRelease &&
+      hasInstallScript &&
+      !hasTrustedPublishing &&
+      !hasProvenanceEvidence
+    ) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "A very recent release on a mature package, combined with install-time execution and missing provenance, deserves extra scrutiny before adoption.",
+        location: {
+          bomRef: target.bomRefs?.[0],
+          purl: target.purl,
+        },
+        message: `npm package '${target.name}@${target.version}' is a very recent release on an established package and still lacks registry-visible provenance.`,
+        mitigation:
+          "Delay adoption briefly, verify publisher identity, and prefer registry-visible provenance for high-risk packages with install hooks.",
+        ruleId: "PROV-003",
+        severity: "low",
+      });
+    }
+    if (
+      target.version &&
+      establishedPackage &&
+      publisherDrift &&
+      hasInstallScript &&
+      !hasTrustedPublishing &&
+      !hasProvenanceEvidence
+    ) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "Publisher drift on mature packages can be legitimate, but becomes more concerning when install-time execution is present and provenance is weak.",
+        location: {
+          bomRef: target.bomRefs?.[0],
+          purl: target.purl,
+        },
+        message: `npm package '${target.name}@${target.version}' was published by a different identity than the prior release and lacks registry-visible provenance.`,
+        mitigation:
+          "Review maintainer changes, compare the prior release publisher, and validate provenance before upgrading execution-capable packages.",
+        ruleId: "PROV-004",
+        severity: "medium",
+      });
+    }
+    if (
+      target.version &&
+      establishedPackage &&
+      maintainerSetDrift &&
+      hasInstallScript &&
+      !hasTrustedPublishing &&
+      !hasProvenanceEvidence
+    ) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "Maintainer-set drift on execution-capable packages is a triage signal when the resolved release also lacks registry-visible provenance.",
+        location: {
+          bomRef: target.bomRefs?.[0],
+          purl: target.purl,
+        },
+        message: `npm package '${target.name}@${target.version}' has a fully different maintainer identity set than the prior release and lacks registry-visible provenance.`,
+        mitigation:
+          "Compare the prior and current maintainer sets, verify maintainer transitions, and prefer releases with provenance before upgrading packages with install hooks.",
+        ruleId: "PROV-007",
+        severity: "medium",
+      });
+    }
+    if (
+      target.version &&
+      establishedPackage &&
+      partialMaintainerSetDrift &&
+      !maintainerSetDrift &&
+      hasInstallScript &&
+      !hasTrustedPublishing &&
+      !hasProvenanceEvidence
+    ) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "Partial maintainer-set drift is a low-severity triage signal when execution-capable releases retain some identities but also introduce maintainer churn without registry-visible provenance.",
+        location: {
+          bomRef: target.bomRefs?.[0],
+          purl: target.purl,
+        },
+        message: `npm package '${target.name}@${target.version}' retains only part of the prior maintainer identity set and lacks registry-visible provenance.`,
+        mitigation:
+          "Review which maintainer identities changed, compare against the prior release, and validate the transition before upgrading packages with install hooks.",
+        ruleId: "PROV-011",
+        severity: "low",
+      });
+    }
+    if (
+      target.version &&
+      establishedPackage &&
+      dormantReleaseGapAnomaly &&
+      hasInstallScript &&
+      !hasTrustedPublishing &&
+      !hasProvenanceEvidence
+    ) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "A long dormant gap followed by a new execution-capable release can warrant a short review window when provenance is missing.",
+        location: {
+          bomRef: target.bomRefs?.[0],
+          purl: target.purl,
+        },
+        message: `npm package '${target.name}@${target.version}' arrived after an unusually long release gap and lacks registry-visible provenance.`,
+        mitigation:
+          "Review the release diff, compare against the prior version, and validate maintainer continuity before adopting after long dormancy.",
+        ruleId: "PROV-008",
+        severity: "low",
+      });
+    }
+    if (
+      target.version &&
+      establishedPackage &&
+      compressedCadence &&
+      hasInstallScript &&
+      !hasTrustedPublishing &&
+      !hasProvenanceEvidence
+    ) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "A materially faster-than-usual release on a mature execution-capable package is a low-severity review signal when registry-visible provenance is absent.",
+        location: {
+          bomRef: target.bomRefs?.[0],
+          purl: target.purl,
+        },
+        message: `npm package '${target.name}@${target.version}' arrived materially faster than its prior release cadence and lacks registry-visible provenance.`,
+        mitigation:
+          "Review the release diff, compare the release timing against prior cadence, and validate the publisher transition before rapid upgrades of execution-capable packages.",
+        ruleId: "PROV-012",
+        severity: "low",
+      });
+    }
+  }
+  if (target.type === "pypi") {
+    const registry = getTargetProperty(target, "cdx:pypi:registry");
+    const isDefaultRegistry =
+      !registry ||
+      ["https://pypi.org", "https://pypi.org/simple"].includes(registry);
+    const uploaderVerified =
+      getTargetProperty(target, "cdx:pypi:uploaderVerified") === "true";
+    const establishedPackage = isEstablishedPackage(target, "cdx:pypi");
+    const recentRelease = isRecentRelease(target, "cdx:pypi");
+    const publisherDrift = hasPublisherDrift(target, "cdx:pypi");
+    const maintainerSetDrift = hasMaintainerSetDrift(target, "cdx:pypi");
+    const partialMaintainerSetDrift = hasPartialIdentitySetDrift(
+      target,
+      "cdx:pypi",
+    );
+    const dormantReleaseGapAnomaly = hasDormantReleaseGapAnomaly(
+      target,
+      "cdx:pypi",
+    );
+    const compressedCadence = hasCompressedCadence(target, "cdx:pypi");
+    if (
+      target.version &&
+      isDefaultRegistry &&
+      !hasTrustedPublishing &&
+      !hasProvenanceEvidence &&
+      !uploaderVerified
+    ) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "Default-registry PyPI packages without provenance or verified uploader context are weaker candidates for publisher-trust decisions.",
+        location: {
+          bomRef: target.bomRefs?.[0],
+          purl: target.purl,
+        },
+        message: `PyPI package '${target.name}@${target.version}' lacks registry-visible provenance and uploader verification signals.`,
+        mitigation:
+          "Prefer releases with provenance evidence or verified uploader metadata, especially for sensitive or newly introduced dependencies.",
+        ruleId: "PROV-002",
+        severity: "low",
+      });
+    }
+    if (
+      target.version &&
+      isDefaultRegistry &&
+      establishedPackage &&
+      recentRelease &&
+      !hasTrustedPublishing &&
+      !hasProvenanceEvidence &&
+      !uploaderVerified
+    ) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "Very recent releases on mature packages can benefit from a short review window when provenance and uploader-verification signals are absent.",
+        location: {
+          bomRef: target.bomRefs?.[0],
+          purl: target.purl,
+        },
+        message: `PyPI package '${target.name}@${target.version}' is a very recent release on an established package without provenance or uploader verification signals.`,
+        mitigation:
+          "Delay adoption briefly, compare the release to the previous known-good version, and prefer verified/provenance-backed uploads for sensitive dependencies.",
+        ruleId: "PROV-005",
+        severity: "low",
+      });
+    }
+    if (
+      target.version &&
+      isDefaultRegistry &&
+      establishedPackage &&
+      publisherDrift &&
+      !hasTrustedPublishing &&
+      !hasProvenanceEvidence &&
+      !uploaderVerified
+    ) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "Uploader drift on established PyPI packages is usually a triage signal, but becomes more meaningful when provenance and verification are missing.",
+        location: {
+          bomRef: target.bomRefs?.[0],
+          purl: target.purl,
+        },
+        message: `PyPI package '${target.name}@${target.version}' was uploaded by a different identity than the prior release and lacks provenance or uploader verification signals.`,
+        mitigation:
+          "Review the uploader change, compare the prior release uploader, and validate project ownership before upgrading critical dependencies.",
+        ruleId: "PROV-006",
+        severity: "low",
+      });
+    }
+    if (
+      target.version &&
+      isDefaultRegistry &&
+      establishedPackage &&
+      maintainerSetDrift &&
+      !hasTrustedPublishing &&
+      !hasProvenanceEvidence &&
+      !uploaderVerified
+    ) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "Uploader-set drift on established PyPI packages is a triage signal when provenance and uploader verification are absent.",
+        location: {
+          bomRef: target.bomRefs?.[0],
+          purl: target.purl,
+        },
+        message: `PyPI package '${target.name}@${target.version}' has a fully different uploader identity set than the prior release and lacks provenance or uploader verification signals.`,
+        mitigation:
+          "Review uploader transitions, compare the prior release uploader set, and validate project ownership before upgrading sensitive dependencies.",
+        ruleId: "PROV-009",
+        severity: "low",
+      });
+    }
+    if (
+      target.version &&
+      isDefaultRegistry &&
+      establishedPackage &&
+      partialMaintainerSetDrift &&
+      !maintainerSetDrift &&
+      !hasTrustedPublishing &&
+      !hasProvenanceEvidence &&
+      !uploaderVerified
+    ) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "Partial uploader-set drift is a low-severity review signal on established PyPI packages when provenance and uploader verification are absent.",
+        location: {
+          bomRef: target.bomRefs?.[0],
+          purl: target.purl,
+        },
+        message: `PyPI package '${target.name}@${target.version}' retains only part of the prior uploader identity set and lacks provenance or uploader verification signals.`,
+        mitigation:
+          "Review which uploader identities changed, compare the release against the prior version, and validate project ownership before upgrading sensitive dependencies.",
+        ruleId: "PROV-013",
+        severity: "low",
+      });
+    }
+    if (
+      target.version &&
+      isDefaultRegistry &&
+      establishedPackage &&
+      dormantReleaseGapAnomaly &&
+      !hasTrustedPublishing &&
+      !hasProvenanceEvidence &&
+      !uploaderVerified
+    ) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "Established packages resurfacing after a long dormant gap benefit from extra review when provenance is weak.",
+        location: {
+          bomRef: target.bomRefs?.[0],
+          purl: target.purl,
+        },
+        message: `PyPI package '${target.name}@${target.version}' followed an unusually long release gap and lacks provenance or uploader verification signals.`,
+        mitigation:
+          "Compare the release to the prior known-good version and review maintainership continuity before adopting after long dormancy.",
+        ruleId: "PROV-010",
+        severity: "low",
+      });
+    }
+    if (
+      target.version &&
+      isDefaultRegistry &&
+      establishedPackage &&
+      compressedCadence &&
+      !hasTrustedPublishing &&
+      !hasProvenanceEvidence &&
+      !uploaderVerified
+    ) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "Materially faster-than-usual release timing is a low-severity triage signal on mature PyPI packages when provenance and uploader verification remain weak.",
+        location: {
+          bomRef: target.bomRefs?.[0],
+          purl: target.purl,
+        },
+        message: `PyPI package '${target.name}@${target.version}' arrived materially faster than its prior release cadence and lacks provenance or uploader verification signals.`,
+        mitigation:
+          "Compare the release timing and contents against prior versions, then validate uploader continuity before rapid upgrades of sensitive dependencies.",
+        ruleId: "PROV-014",
+        severity: "low",
+      });
+    }
+  }
+  if (target.type === "cargo") {
+    const yanked = getTargetProperty(target, "cdx:cargo:yanked") === "true";
+    const establishedPackage = isEstablishedPackage(target, "cdx:cargo");
+    const recentRelease = isRecentRelease(target, "cdx:cargo");
+    const publisherDrift = hasPublisherDrift(target, "cdx:cargo");
+    const dormantReleaseGapAnomaly = hasDormantReleaseGapAnomaly(
+      target,
+      "cdx:cargo",
+    );
+    const compressedCadence = hasCompressedCadence(target, "cdx:cargo");
+    if (target.version && yanked) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "Yanked crates are removed from normal Cargo resolution and usually indicate a correctness, security, or publisher-action issue that deserves review before further adoption.",
+        location: {
+          bomRef: target.bomRefs?.[0],
+          purl: target.purl,
+        },
+        message: `Cargo crate '${target.name}@${target.version}' has been yanked from crates.io.`,
+        mitigation:
+          "Prefer a non-yanked release and review the crate's publisher history and changelog before upgrading.",
+        ruleId: "PROV-015",
+        severity: "high",
+      });
+    }
+    if (
+      target.version &&
+      establishedPackage &&
+      recentRelease &&
+      !hasTrustedPublishing &&
+      !hasProvenanceEvidence
+    ) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "Very recent releases on established crates benefit from a short review window when trusted publishing and provenance remain weak.",
+        location: {
+          bomRef: target.bomRefs?.[0],
+          purl: target.purl,
+        },
+        message: `Cargo crate '${target.name}@${target.version}' is a very recent release on an established package without registry-visible provenance signals.`,
+        mitigation:
+          "Delay adoption briefly, compare the release to the prior version, and prefer trusted-publishing-backed releases for sensitive crates.",
+        ruleId: "PROV-016",
+        severity: "low",
+      });
+    }
+    if (
+      target.version &&
+      establishedPackage &&
+      publisherDrift &&
+      !hasTrustedPublishing &&
+      !hasProvenanceEvidence
+    ) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "Publisher drift on established crates is often benign, but becomes more meaningful when provenance and trusted publishing are absent.",
+        location: {
+          bomRef: target.bomRefs?.[0],
+          purl: target.purl,
+        },
+        message: `Cargo crate '${target.name}@${target.version}' was published by a different identity than the prior release and lacks registry-visible provenance signals.`,
+        mitigation:
+          "Review the publisher transition, compare the prior release metadata, and validate ownership before upgrading sensitive crates.",
+        ruleId: "PROV-017",
+        severity: "medium",
+      });
+    }
+    if (
+      target.version &&
+      establishedPackage &&
+      (dormantReleaseGapAnomaly || compressedCadence) &&
+      !hasTrustedPublishing &&
+      !hasProvenanceEvidence
+    ) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "Release timing anomalies on established crates are low-noise triage signals when provenance remains weak.",
+        location: {
+          bomRef: target.bomRefs?.[0],
+          purl: target.purl,
+        },
+        message: `Cargo crate '${target.name}@${target.version}' shows unusual release timing and lacks registry-visible provenance signals.`,
+        mitigation:
+          "Review the release diff and timing versus prior versions before rapidly adopting the new crate release.",
+        ruleId: "PROV-018",
+        severity: "low",
+      });
+    }
+  }
+  return findings;
+}
+
+/**
+ * Clone a repository into a deterministic workspace directory.
+ *
+ * @param {string} repoUrl repository URL
+ * @param {string} cloneDir target clone directory
+ * @param {string | undefined} gitRef git ref to checkout
+ * @throws {Error} when gitRef is not a safe ref name
+ * @returns {void}
+ */
+function cloneRepositoryToDir(repoUrl, cloneDir, gitRef) {
+  const gitArgs = [
+    "-c",
+    "alias.clone=",
+    "-c",
+    "core.fsmonitor=false",
+    "-c",
+    "safe.bareRepository=explicit",
+    "-c",
+    "core.hooksPath=/dev/null",
+    "clone",
+    "--template=",
+    "--depth",
+    "1",
+    "--",
+    repoUrl,
+    cloneDir,
+  ];
+  if (gitRef) {
+    if (!isSafeGitRefName(gitRef)) {
+      const error = new Error("git ref contains unsupported characters");
+      error.errorType = "clone";
+      error.retryable = false;
+      throw error;
+    }
+    const cloneIndex = gitArgs.indexOf("clone");
+    gitArgs.splice(cloneIndex + 1, 0, "--branch", gitRef);
+  }
+  const result = hardenedGitCommand(gitArgs);
+  if (result.status !== 0) {
+    const stderr = result.stderr
+      ? result.stderr.toString()
+      : "unknown git clone error";
+    const error = new Error(stderr.trim());
+    error.retryable =
+      /(timed out|unable to connect|could not resolve host|network is unreachable|connection reset|connection refused|temporary failure|remote end hung up unexpectedly|http 5\d\d|tls|econnreset|econnrefused|etimedout)/i.test(
+        stderr,
+      );
+    error.errorType = error.retryable ? "network" : "clone";
+    throw error;
+  }
+}
+
+async function cloneRepositoryToDirWithRetry(repoUrl, cloneDir, gitRef) {
+  let lastError;
+  for (let attempt = 0; attempt <= CLONE_RETRY_DELAYS_MS.length; attempt += 1) {
+    try {
+      cloneRepositoryToDir(repoUrl, cloneDir, gitRef);
+      return;
+    } catch (error) {
+      lastError = error;
+      safeRmSync(cloneDir, { force: true, recursive: true });
+      if (!error?.retryable || attempt >= CLONE_RETRY_DELAYS_MS.length) {
+        break;
+      }
+      await sleep(CLONE_RETRY_DELAYS_MS[attempt]);
+    }
+  }
+  const sanitizedRepoUrl = sanitizeRemoteUrlForLogs(repoUrl);
+  const message = lastError?.message || "unknown git clone error";
+  const error = new Error(
+    `Unable to clone '${sanitizedRepoUrl}' after ${CLONE_RETRY_DELAYS_MS.length + 1} attempt(s): ${message}`,
+  );
+  error.errorType = lastError?.errorType || "clone";
+  error.retryable = Boolean(lastError?.retryable);
+  throw error;
+}
+
+/**
+ * Reuse or create a checkout for a target repository.
+ *
+ * @param {object} target audit target
+ * @param {object} resolution resolved repository metadata
+ * @param {string | undefined} workspaceDir workspace directory
+ * @param {string | undefined} gitRef git ref to checkout
+ * @returns {{ cleanup: boolean, cloneDir: string, reused: boolean }} checkout info
+ */
+async function ensureCheckout(target, resolution, workspaceDir, gitRef) {
+  if (!workspaceDir) {
+    const cloneDir = safeMkdtempSync(
+      join(getTmpDir(), `${targetSlug(target)}-`),
+    );
+    await cloneRepositoryToDirWithRetry(resolution.repoUrl, cloneDir, gitRef);
+    return {
+      cleanup: true,
+      cloneDir,
+      reused: false,
+    };
+  }
+  const resolvedWorkspaceDir = resolve(workspaceDir);
+  if (!safeExistsSync(resolvedWorkspaceDir)) {
+    safeMkdirSync(resolvedWorkspaceDir, { recursive: true });
+  }
+  const cloneDir = join(resolvedWorkspaceDir, targetSlug(target));
+  if (safeExistsSync(join(cloneDir, ".git"))) {
+    return {
+      cleanup: false,
+      cloneDir,
+      reused: true,
+    };
+  }
+  if (safeExistsSync(cloneDir)) {
+    safeRmSync(cloneDir, { force: true, recursive: true });
+  }
+  await cloneRepositoryToDirWithRetry(resolution.repoUrl, cloneDir, gitRef);
+  return {
+    cleanup: false,
+    cloneDir,
+    reused: false,
+  };
+}
+
+/**
+ * Extract an expected package name from Python packaging metadata.
+ *
+ * @param {string} filePath metadata file path
+ * @returns {string | undefined} discovered package name
+ */
+function readPythonPackageName(filePath) {
+  let fileContent;
+  try {
+    fileContent = readFileSync(filePath, "utf8");
+  } catch {
+    return undefined;
+  }
+  const patterns = [
+    /(^|\n)\s*name\s*=\s*["']([^"'\n]+)["']/m,
+    /(^|\n)\s*name\s*=\s*([^\n#]+)/m,
+    /setup\s*\([^)]*name\s*=\s*["']([^"']+)["']/ms,
+  ];
+  for (const pattern of patterns) {
+    const match = fileContent.match(pattern);
+    if (!match) {
+      continue;
+    }
+    const packageName = (match[2] || match[1] || "").trim();
+    if (packageName) {
+      return packageName;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Resolve the most specific Python package directory inside a cloned repo.
+ *
+ * @param {string} cloneDir cloned repository root
+ * @param {object} target audit target
+ * @returns {{ confidence: string, scanDir: string }} selected directory and confidence
+ */
+export function resolvePythonSourceDirectory(cloneDir, target) {
+  const normalizedTargetName = normalizePackageName(target.name);
+  const queue = [cloneDir];
+  const matches = [];
+  while (queue.length) {
+    const currentDir = queue.shift();
+    let entries = [];
+    try {
+      entries = readdirSync(currentDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const entryPath = join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (!PYTHON_SKIP_DIRS.has(entry.name)) {
+          queue.push(entryPath);
+        }
+        continue;
+      }
+      if (!entry.isFile() || !PYTHON_METADATA_FILES.includes(entry.name)) {
+        continue;
+      }
+      const packageName = readPythonPackageName(entryPath);
+      if (normalizePackageName(packageName) === normalizedTargetName) {
+        matches.push(currentDir);
+      }
+    }
+  }
+  if (!matches.length) {
+    return {
+      confidence: "low",
+      scanDir: cloneDir,
+    };
+  }
+  matches.sort((left, right) => left.length - right.length);
+  return {
+    confidence: matches[0] === cloneDir ? "medium" : "high",
+    scanDir: matches[0],
+  };
+}
+
+/**
+ * Remove cdxgen config files from a directory the audit is about to scan.
+ *
+ * Audit mode clones repositories cdxgen picked itself, from registry metadata,
+ * so nobody approved the contents. A config file in such a checkout would let
+ * the audited repository choose its own scan options, which is the audited
+ * repository deciding how it gets audited.
+ *
+ * @param {string} dir directory to clear
+ * @returns {void}
+ */
+function rejectProjectConfigFiles(dir) {
+  if (!dir) {
+    return;
+  }
+  for (const configFileName of PROJECT_CONFIG_FILENAMES) {
+    const configPath = join(dir, configFileName);
+    if (!safeExistsSync(configPath)) {
+      continue;
+    }
+    safeRmSync(configPath, { force: true });
+    console.warn(
+      `Ignoring the config file '${configFileName}' found in the cloned repository ${dir}.`,
+    );
+    recordActivity({
+      kind: "inspect",
+      reason:
+        "Removed a cdxgen config file from an audit checkout. Cloned repositories do not configure their own audit.",
+      status: "completed",
+      target: configPath,
+    });
+  }
+}
+
+/**
+ * Resolve the most appropriate scan directory for a cloned target repository.
+ *
+ * @param {string} cloneDir cloned repository root
+ * @param {object} target audit target
+ * @param {object} resolution repository resolution metadata
+ * @returns {{ confidence: string, scanDir: string }} selected directory and confidence
+ */
+export function resolveTargetSourceDirectory(cloneDir, target, resolution) {
+  const selection = selectTargetSourceDirectory(cloneDir, target, resolution);
+  rejectProjectConfigFiles(cloneDir);
+  if (selection.scanDir !== cloneDir) {
+    rejectProjectConfigFiles(selection.scanDir);
+  }
+  return selection;
+}
+
+/**
+ * Pick the scan directory for a cloned target repository.
+ *
+ * @param {string} cloneDir cloned repository root
+ * @param {object} target audit target
+ * @param {object} resolution repository resolution metadata
+ * @returns {{ confidence: string, scanDir: string }} selected directory and confidence
+ */
+function selectTargetSourceDirectory(cloneDir, target, resolution) {
+  if (target.type === "npm") {
+    const scanDir = resolvePurlSourceDirectory(cloneDir, resolution);
+    if (!scanDir) {
+      return {
+        confidence: "medium",
+        scanDir: cloneDir,
+      };
+    }
+    return {
+      confidence: scanDir === cloneDir ? "medium" : "high",
+      scanDir,
+    };
+  }
+  if (target.type === "pypi") {
+    return resolvePythonSourceDirectory(cloneDir, target);
+  }
+  return {
+    confidence: "low",
+    scanDir: cloneDir,
+  };
+}
+
+function collectPythonHeuristicFiles(scanDir) {
+  const candidates = [];
+  const queue = [scanDir];
+  while (queue.length && candidates.length < PYTHON_HEURISTIC_FILE_LIMIT) {
+    const currentDir = queue.shift();
+    let entries = [];
+    try {
+      entries = readdirSync(currentDir, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      const entryPath = join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        if (!PYTHON_SKIP_DIRS.has(entry.name)) {
+          queue.push(entryPath);
+        }
+        continue;
+      }
+      if (
+        entry.isFile() &&
+        PYTHON_HEURISTIC_FILENAMES.has(entry.name) &&
+        candidates.length < PYTHON_HEURISTIC_FILE_LIMIT
+      ) {
+        candidates.push(entryPath);
+      }
+    }
+  }
+  return candidates;
+}
+
+function inspectPythonHeuristicFile(filePath) {
+  let fileSize;
+  try {
+    fileSize = statSync(filePath).size;
+  } catch {
+    return undefined;
+  }
+  if (fileSize > PYTHON_HEURISTIC_MAX_FILE_BYTES) {
+    return undefined;
+  }
+  let fileContent;
+  try {
+    fileContent = readFileSync(filePath, "utf8");
+  } catch {
+    return undefined;
+  }
+  const indicators = [];
+  if (PYTHON_EXECUTION_PATTERN.test(fileContent)) {
+    indicators.push("process-or-dynamic-execution");
+  }
+  if (PYTHON_NETWORK_PATTERN.test(fileContent)) {
+    indicators.push("network-access");
+  }
+  if (PYTHON_OBFUSCATION_PATTERN.test(fileContent)) {
+    indicators.push("encoded-loader");
+  }
+  if (
+    filePath.endsWith("setup.py") &&
+    PYTHON_SETUP_CMDCLASS_PATTERN.test(fileContent)
+  ) {
+    indicators.push("setup-cmdclass");
+  }
+  return indicators.length ? indicators : undefined;
+}
+
+/**
+ * Build shallow predictive findings for suspicious Python packaging files.
+ *
+ * Phase 1 intentionally focuses on high-signal packaging surfaces (`setup.py`
+ * and package `__init__.py`) until deeper Python static analysis is added.
+ *
+ * @param {string} scanDir cloned repository scan directory
+ * @param {object} target audit target
+ * @returns {object[]} predictive findings
+ */
+export function buildPythonSourceHeuristicFindings(scanDir, target) {
+  if (!scanDir || target?.type !== "pypi") {
+    return [];
+  }
+  const findings = [];
+  collectPythonHeuristicFiles(scanDir).forEach((filePath) => {
+    const indicators = inspectPythonHeuristicFile(filePath);
+    if (!indicators?.length) {
+      return;
+    }
+    const relativeFile = relative(scanDir, filePath) || filePath;
+    if (
+      relativeFile.endsWith("setup.py") &&
+      indicators.includes("encoded-loader") &&
+      (indicators.includes("process-or-dynamic-execution") ||
+        indicators.includes("network-access") ||
+        indicators.includes("setup-cmdclass"))
+    ) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "setup.py contains encoded or dynamically executed packaging logic, which is a strong signal of install-time code injection risk.",
+        evidence: {
+          indicators: indicators.join(","),
+        },
+        location: {
+          bomRef: target.bomRefs?.[0],
+          file: relativeFile,
+          purl: target.purl,
+        },
+        message: `PyPI package '${target.name}@${target.version}' contains suspicious setup.py execution patterns in '${relativeFile}'.`,
+        mitigation:
+          "Inspect setup.py before installation, compare against prior releases, and avoid executing packaging hooks until the encoded or dynamic logic is explained and validated.",
+        ruleId: "PYSRC-001",
+        severity: "high",
+      });
+      return;
+    }
+    if (
+      relativeFile.endsWith("__init__.py") &&
+      (indicators.includes("process-or-dynamic-execution") ||
+        indicators.includes("network-access"))
+    ) {
+      findings.push({
+        category: "package-integrity",
+        description:
+          "__init__.py appears to perform process spawning, dynamic execution, or network access during import, which is unusual for a package initializer.",
+        evidence: {
+          indicators: indicators.join(","),
+        },
+        location: {
+          bomRef: target.bomRefs?.[0],
+          file: relativeFile,
+          purl: target.purl,
+        },
+        message: `PyPI package '${target.name}@${target.version}' contains suspicious import-time logic in '${relativeFile}'.`,
+        mitigation:
+          "Review the initializer for import-time side effects, compare it to prior versions, and quarantine the release until maintainers confirm the added behavior.",
+        ruleId: "PYSRC-002",
+        severity: indicators.includes("encoded-loader") ? "high" : "medium",
+      });
+    }
+  });
+  return findings;
+}
+
+/**
+ * Build cdxgen options for a child source scan.
+ *
+ * @param {object} options CLI options
+ * @param {object} target audit target
+ * @returns {object} createBom options
+ */
+function buildChildOptions(options, target) {
+  const projectType =
+    target.type === "npm"
+      ? ["js"]
+      : target.type === "pypi"
+        ? ["py"]
+        : target.type === "cargo"
+          ? ["cargo", "github"]
+          : [target.type];
+  return {
+    deep: true,
+    failOnError: false,
+    filePath: options.workspaceDir || process.cwd(),
+    includeFormulation: true,
+    installDeps: false,
+    multiProject: true,
+    profile: "threat-modeling",
+    projectType,
+    specVersion: DEFAULT_CDX_SPEC_VERSION,
+  };
+}
+
+function normalizeFindingFile(filePath) {
+  return String(filePath)
+    .replace(/\\/g, "/")
+    .replace(/\/+/g, "/")
+    .replace(/^\.\//, "");
+}
+
+function sourceFindingKey(finding) {
+  if (!finding?.ruleId || !finding?.location?.file) {
+    return undefined;
+  }
+  return `${finding.ruleId}|${normalizeFindingFile(finding.location.file)}`;
+}
+
+/**
+ * Recheck high/critical findings against the default branch to identify issues
+ * that have already been fixed upstream. This reduces false positives caused by
+ * scanning a version-specific tag where an issue existed but has since been
+ * resolved in the project's main development line.
+ *
+ * @param {object[]} findings findings from version-specific scan
+ * @param {object} target audit target
+ * @param {object} resolution repository resolution metadata
+ * @param {string[]} categories active audit categories
+ * @param {object} options CLI options
+ * @returns {Promise<{findings: object[], fixedInDefaultBranch: number}|undefined>}
+ */
+async function recheckFindingsAgainstDefaultBranch(
+  findings,
+  target,
+  resolution,
+  categories,
+  options,
+) {
+  let defaultBranchDir;
+  try {
+    defaultBranchDir = safeMkdtempSync(
+      join(getTmpDir(), `${targetSlug(target)}-default-`),
+    );
+    await cloneRepositoryToDirWithRetry(
+      resolution.repoUrl,
+      defaultBranchDir,
+      undefined,
+    );
+    const defaultSourceSelection = resolveTargetSourceDirectory(
+      defaultBranchDir,
+      target,
+      resolution,
+    );
+    const childOptions = {
+      ...buildChildOptions(options, target),
+      executeOsQuery,
+    };
+    const bomNSData =
+      (await createBom(defaultSourceSelection.scanDir, childOptions)) || {};
+    if (!bomNSData?.bomJson) {
+      return undefined;
+    }
+    const processedBomNSData = postProcess(
+      bomNSData,
+      childOptions,
+      defaultSourceSelection.scanDir,
+    );
+    const defaultBranchFindings = await auditBom(processedBomNSData.bomJson, {
+      bomAuditCategories: categories.join(","),
+      bomAuditMinSeverity: options.minSeverity || "low",
+      bomAuditRulesDir: options.rulesDir,
+      getBomWithOras,
+    });
+    const defaultBranchSourceFindings = defaultBranchFindings.concat(
+      buildPythonSourceHeuristicFindings(
+        defaultSourceSelection.scanDir,
+        target,
+      ),
+    );
+    // Build a set of finding signatures present in the default branch
+    const defaultBranchFindingKeys = new Set();
+    for (const finding of defaultBranchSourceFindings) {
+      const key = sourceFindingKey(finding);
+      if (key) {
+        defaultBranchFindingKeys.add(key);
+      }
+    }
+    // Retain findings that are still present in the default branch or are
+    // contextual/heuristic findings (not from rule evaluation against source).
+    // Source-derived findings have a location.file pointing to a repo file,
+    // while contextual findings reference purls or bomRefs only.
+    const retainedFindings = [];
+    let fixedCount = 0;
+    for (const finding of findings) {
+      const isSourceDerivedFinding = Boolean(finding?.location?.file);
+      if (!isSourceDerivedFinding) {
+        // Contextual/heuristic findings are not source-dependent
+        retainedFindings.push(finding);
+        continue;
+      }
+      if (defaultBranchFindingKeys.has(sourceFindingKey(finding))) {
+        retainedFindings.push(finding);
+      } else {
+        fixedCount += 1;
+        thoughtLog("Finding fixed in default branch, removing.", {
+          ruleId: finding.ruleId,
+          file: finding?.location?.file,
+          purl: target.purl,
+        });
+      }
+    }
+    if (fixedCount === 0) {
+      return undefined;
+    }
+    return {
+      findings: retainedFindings,
+      fixedInDefaultBranch: fixedCount,
+    };
+  } catch (error) {
+    const errorMessage = error?.message ?? String(error);
+    thoughtLog("Default branch recheck failed, keeping original findings.", {
+      error: errorMessage,
+      errorType: error?.errorType,
+      purl: target.purl,
+    });
+    return undefined;
+  } finally {
+    if (defaultBranchDir) {
+      cleanupSourceDir(defaultBranchDir);
+    }
+  }
+}
+
+/**
+ * Analyze a single purl target by generating a child SBOM and auditing it.
+ *
+ * @param {object} target audit target
+ * @param {object} options CLI options
+ * @returns {Promise<object>} analyzed target result
+ */
+export async function auditTarget(target, options) {
+  const categories = options.categories?.length
+    ? options.categories
+    : DEFAULT_AUDIT_CATEGORIES;
+  const targetIndex = options._targetIndex || 0;
+  const targetTotal = options._targetTotal || 0;
+  const targetLabel = formatTargetLabel(target);
+  const originalFetchPackageMetadata = readEnvironmentVariable(
+    "CDXGEN_FETCH_PKG_METADATA",
+  );
+  let checkout;
+  let processedBomJson;
+  let resolution;
+  let sourceSelection;
+  let cacheHit = false;
+  let sanitizedRepoUrl;
+  let versionMatched = false;
+  try {
+    const cachedChildBom = loadCachedChildBom(options.workspaceDir, target);
+    if (cachedChildBom) {
+      cacheHit = true;
+      processedBomJson = cachedChildBom.bomJson;
+      resolution = cachedChildBom.resolution;
+      sanitizedRepoUrl = cachedChildBom.repoUrl;
+      sourceSelection = {
+        confidence: cachedChildBom.sourceDirectoryConfidence,
+        scanDir: cachedChildBom.scanDir,
+      };
+      versionMatched = cachedChildBom.versionMatched;
+      emitProgress(options, {
+        index: targetIndex,
+        label: targetLabel,
+        target,
+        total: targetTotal,
+        type: "target:stage",
+        stage: "reusing cached child SBOM",
+      });
+    } else {
+      emitProgress(options, {
+        index: targetIndex,
+        label: targetLabel,
+        target,
+        total: targetTotal,
+        type: "target:stage",
+        stage: "resolving repository metadata",
+      });
+      resolution = await resolveGitUrlFromPurl(target.purl, {
+        fetchPomXmlAsJson,
+      });
+      if (!resolution?.repoUrl) {
+        return persistAuditArtifacts(
+          {
+            assessment: scoreTargetRisk([], target, {
+              skipReason:
+                "Unable to resolve repository URL from purl metadata.",
+            }),
+            error: "Unable to resolve repository URL from purl metadata.",
+            findings: [],
+            resolution,
+            status: "skipped",
+            target,
+          },
+          options,
+        );
+      }
+      sanitizedRepoUrl = sanitizeRemoteUrlForLogs(resolution.repoUrl);
+      thoughtLog("Preparing predictive audit target.", {
+        purl: target.purl,
+        repoUrl: sanitizedRepoUrl,
+      });
+      const gitRef = findGitRefForPurlVersion(resolution.repoUrl, resolution);
+      versionMatched = Boolean(gitRef);
+      emitProgress(options, {
+        index: targetIndex,
+        label: targetLabel,
+        target,
+        total: targetTotal,
+        type: "target:stage",
+        stage: gitRef ? `cloning source at ref ${gitRef}` : "cloning source",
+      });
+      checkout = await ensureCheckout(
+        target,
+        resolution,
+        options.workspaceDir,
+        gitRef,
+      );
+      sourceSelection = resolveTargetSourceDirectory(
+        checkout.cloneDir,
+        target,
+        resolution,
+      );
+      const childOptions = {
+        ...buildChildOptions(options, target),
+        executeOsQuery,
+      };
+      process.env.CDXGEN_FETCH_PKG_METADATA = "true";
+      emitProgress(options, {
+        index: targetIndex,
+        label: targetLabel,
+        target,
+        total: targetTotal,
+        type: "target:stage",
+        stage: "generating child SBOM",
+      });
+      const bomNSData =
+        (await createBom(sourceSelection.scanDir, childOptions)) || {};
+      if (!bomNSData?.bomJson) {
+        return persistAuditArtifacts(
+          {
+            assessment: scoreTargetRisk([], target, {
+              errorMessage:
+                "Unable to generate a child SBOM for the resolved source repository.",
+              scanError: true,
+            }),
+            error:
+              "Unable to generate a child SBOM for the resolved source repository.",
+            errorType: "sbom-generation",
+            findings: [],
+            repoUrl: sanitizedRepoUrl,
+            resolution,
+            status: "error",
+            target,
+          },
+          options,
+        );
+      }
+      const processedBomNSData = postProcess(
+        bomNSData,
+        childOptions,
+        sourceSelection.scanDir,
+      );
+      processedBomJson = processedBomNSData.bomJson;
+      writeCachedChildBom(options.workspaceDir, target, {
+        bomJson: processedBomJson,
+        repoUrl: sanitizedRepoUrl,
+        resolution,
+        scanDir: sourceSelection.scanDir,
+        sourceDirectoryConfidence: sourceSelection.confidence,
+        versionMatched,
+      });
+    }
+    emitProgress(options, {
+      index: targetIndex,
+      label: targetLabel,
+      target,
+      total: targetTotal,
+      type: "target:stage",
+      stage: "evaluating audit rules",
+    });
+    const findings = await auditBom(processedBomJson, {
+      bomAuditCategories: categories.join(","),
+      bomAuditMinSeverity: options.minSeverity || "low",
+      bomAuditRulesDir: options.rulesDir,
+      getBomWithOras,
+    });
+    // Evaluate the license policy against this dependency's child SBOM so
+    // source-derived (and deeper transitive) licenses are covered, not just the
+    // licenses declared in the parent BOM.
+    const licenseViolations = options._licensePolicy
+      ? collectPolicyViolations(processedBomJson, options._licensePolicy, {
+          includeWarnings: true,
+        })
+      : [];
+    const contextualFindings = buildTargetContextFindings(target);
+    const pythonSourceFindings = buildPythonSourceHeuristicFindings(
+      sourceSelection.scanDir,
+      target,
+    );
+    let predictiveFindings = findings.concat(
+      contextualFindings,
+      pythonSourceFindings,
+    );
+    let assessment = scoreTargetRisk(predictiveFindings, target, {
+      bomJson: processedBomJson,
+      repoReused: Boolean(checkout?.reused || cacheHit),
+      resolution,
+      sourceDirectoryConfidence: sourceSelection.confidence,
+      versionMatched,
+    });
+    // When we scanned a version-specific ref and the severity is high or
+    // critical, recheck against the default branch to reduce false positives
+    // from issues already fixed upstream.
+    if (
+      versionMatched &&
+      !options.skipDefaultBranchRecheck &&
+      severityMeetsThreshold(assessment.severity, "high") &&
+      resolution?.repoUrl
+    ) {
+      emitProgress(options, {
+        index: targetIndex,
+        label: targetLabel,
+        target,
+        total: targetTotal,
+        type: "target:stage",
+        stage: "rechecking findings against default branch",
+      });
+      const recheckResult = await recheckFindingsAgainstDefaultBranch(
+        predictiveFindings,
+        target,
+        resolution,
+        categories,
+        options,
+      );
+      if (recheckResult) {
+        predictiveFindings = recheckResult.findings;
+        assessment = scoreTargetRisk(predictiveFindings, target, {
+          bomJson: processedBomJson,
+          repoReused: Boolean(checkout?.reused || cacheHit),
+          resolution,
+          sourceDirectoryConfidence: sourceSelection.confidence,
+          versionMatched,
+        });
+        assessment.defaultBranchRechecked = true;
+        assessment.findingsFixedInDefaultBranch =
+          recheckResult.fixedInDefaultBranch;
+      }
+    }
+    return persistAuditArtifacts(
+      {
+        assessment,
+        cacheHit,
+        findings: predictiveFindings,
+        licenseViolations,
+        repoUrl: sanitizedRepoUrl,
+        resolution,
+        scanDir: sourceSelection.scanDir,
+        sourceDirectoryConfidence: sourceSelection.confidence,
+        status: "audited",
+        target,
+      },
+      options,
+      processedBomJson,
+    );
+  } catch (error) {
+    return persistAuditArtifacts(
+      {
+        assessment: scoreTargetRisk([], target, {
+          errorMessage: error.message,
+          scanError: true,
+        }),
+        error: error.message,
+        errorType: error?.errorType || "runtime",
+        findings: [],
+        repoUrl: sanitizedRepoUrl,
+        resolution,
+        sourceDirectoryConfidence: sourceSelection?.confidence,
+        status: "error",
+        target,
+      },
+      options,
+      processedBomJson,
+    );
+  } finally {
+    if (originalFetchPackageMetadata === undefined) {
+      delete process.env.CDXGEN_FETCH_PKG_METADATA;
+    } else {
+      process.env.CDXGEN_FETCH_PKG_METADATA = originalFetchPackageMetadata;
+    }
+    if (checkout?.cleanup) {
+      cleanupSourceDir(checkout.cloneDir);
+    }
+  }
+}
+
+/**
+ * Build an aggregate summary for all analyzed targets.
+ *
+ * @param {object[]} inputBoms loaded BOMs
+ * @param {object[]} results target results
+ * @param {object[]} skipped skipped component entries
+ * @returns {object} summary object
+ */
+function summarizeAudit(inputBoms, results, skipped) {
+  const analysisErrorCounts = {};
+  const severityCounts = {
+    critical: 0,
+    high: 0,
+    low: 0,
+    medium: 0,
+    none: 0,
+  };
+  let scannedTargets = 0;
+  let erroredTargets = 0;
+  for (const result of results) {
+    const severity = result?.assessment?.severity || "none";
+    severityCounts[severity] = (severityCounts[severity] || 0) + 1;
+    if (result.status === "audited") {
+      scannedTargets += 1;
+    }
+    if (result.status === "error") {
+      erroredTargets += 1;
+      const errorType = result?.errorType || "runtime";
+      analysisErrorCounts[errorType] =
+        (analysisErrorCounts[errorType] || 0) + 1;
+    }
+  }
+  return {
+    analysisErrorCounts,
+    erroredTargets,
+    inputBomCount: inputBoms.length,
+    scannedTargets,
+    severityCounts,
+    skippedTargets:
+      skipped.length +
+      results.filter((result) => result.status === "skipped").length,
+    totalTargets: results.length,
+  };
+}
+
+function normalizeRepoGroupingValue(repoUrl) {
+  if (!repoUrl || typeof repoUrl !== "string") {
+    return undefined;
+  }
+  return repoUrl
+    .trim()
+    .replace(/\.git$/i, "")
+    .toLowerCase();
+}
+
+function preferredResult(left, right) {
+  const leftSeverity = SEVERITY_ORDER[left?.assessment?.severity] ?? -1;
+  const rightSeverity = SEVERITY_ORDER[right?.assessment?.severity] ?? -1;
+  if (leftSeverity !== rightSeverity) {
+    return leftSeverity > rightSeverity ? left : right;
+  }
+  const leftScore = left?.assessment?.score || 0;
+  const rightScore = right?.assessment?.score || 0;
+  return leftScore >= rightScore ? left : right;
+}
+
+function dedupeFindings(findings) {
+  const seen = new Set();
+  const deduped = [];
+  for (const finding of findings || []) {
+    const key = [
+      finding?.ruleId,
+      finding?.message,
+      finding?.location?.file,
+      finding?.location?.purl,
+      finding?.location?.bomRef,
+    ].join("|");
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    deduped.push(finding);
+  }
+  return deduped;
+}
+
+function getNamespaceGroupingKey(result) {
+  if (
+    result?.status !== "audited" ||
+    result?.target?.type !== "npm" ||
+    !result?.target?.namespace ||
+    (result?.assessment?.severity || "none") === "none"
+  ) {
+    return undefined;
+  }
+  const categories = Object.keys(
+    result.assessment?.categoryCounts || {},
+  ).sort();
+  const ruleIds = [
+    ...new Set((result.findings || []).map((f) => f.ruleId).filter(Boolean)),
+  ].sort();
+  if (!categories.length || !ruleIds.length) {
+    return undefined;
+  }
+  return `${result.target.namespace}|${categories.join(",")}|${ruleIds.join(",")}`;
+}
+
+function getCargoRepositoryGroupingKey(result) {
+  const normalizedRepoUrl = normalizeRepoGroupingValue(result?.repoUrl);
+  if (
+    result?.status !== "audited" ||
+    result?.target?.type !== "cargo" ||
+    !normalizedRepoUrl ||
+    (result?.assessment?.severity || "none") === "none" ||
+    !Array.isArray(result?.findings) ||
+    !result.findings.length
+  ) {
+    return undefined;
+  }
+  const categories = new Set();
+  const ruleIds = new Set();
+  for (const finding of result.findings) {
+    if (!finding?.category || !finding?.ruleId) {
+      return undefined;
+    }
+    if (finding.category === "ci-permission") {
+      return undefined;
+    }
+    categories.add(finding.category);
+    ruleIds.add(finding.ruleId);
+  }
+  if (!categories.size || !ruleIds.size) {
+    return undefined;
+  }
+  return `${normalizedRepoUrl}|cargo|${[...categories].sort().join(",")}|${[...ruleIds].sort().join(",")}`;
+}
+
+function getSharedRepoCiGroupingKey(result) {
+  const normalizedRepoUrl = normalizeRepoGroupingValue(result?.repoUrl);
+  if (
+    result?.status !== "audited" ||
+    !normalizedRepoUrl ||
+    !Array.isArray(result?.findings) ||
+    !result.findings.length
+  ) {
+    return undefined;
+  }
+  const categories = new Set();
+  const ruleIds = new Set();
+  for (const finding of result.findings) {
+    const category = finding?.category;
+    const ruleId = finding?.ruleId;
+    const findingFile = finding?.location?.file || "";
+    if (
+      category !== "ci-permission" ||
+      !ruleId?.startsWith("CI-") ||
+      (findingFile && !findingFile.includes(".github/workflows"))
+    ) {
+      return undefined;
+    }
+    categories.add(category);
+    ruleIds.add(ruleId);
+  }
+  return `${normalizedRepoUrl}|${[...categories].sort().join(",")}|${[...ruleIds].sort().join(",")}`;
+}
+
+function getGroupingDescriptor(result, sharedRepoCiGroupCounts) {
+  const sharedRepoCiKey = getSharedRepoCiGroupingKey(result);
+  if (sharedRepoCiKey) {
+    const groupSize = sharedRepoCiGroupCounts?.get(sharedRepoCiKey) || 0;
+    if (groupSize > 1) {
+      return {
+        key: sharedRepoCiKey,
+        kind: "shared-repo-ci",
+      };
+    }
+  }
+  const cargoRepositoryKey = getCargoRepositoryGroupingKey(result);
+  if (cargoRepositoryKey) {
+    return {
+      key: cargoRepositoryKey,
+      kind: "cargo-repository",
+    };
+  }
+  const namespaceKey = getNamespaceGroupingKey(result);
+  if (!namespaceKey) {
+    return undefined;
+  }
+  return {
+    key: namespaceKey,
+    kind: "npm-namespace",
+  };
+}
+
+function consolidateCargoRepositoryResult(group) {
+  const representative = group.reduce((best, result) =>
+    preferredResult(best, result),
+  );
+  const allBomRefs = [
+    ...new Set(group.flatMap((result) => result.target?.bomRefs || [])),
+  ];
+  const groupedPurls = [
+    ...new Set(group.map((result) => result.target?.purl).filter(Boolean)),
+  ];
+  const mergedFindings = dedupeFindings(
+    group.flatMap((result) => result.findings || []),
+  );
+  const categoryCounts = {};
+  for (const result of group) {
+    for (const [category, count] of Object.entries(
+      result.assessment?.categoryCounts || {},
+    )) {
+      categoryCounts[category] = (categoryCounts[category] || 0) + count;
+    }
+  }
+  const reasons = [
+    `${group.length} Cargo packages resolved to the same repository and shared the same predictive pattern, so cdx-audit consolidated them into one alert.`,
+    ...(representative.assessment?.reasons || []),
+  ];
+  return {
+    ...representative,
+    assessment: {
+      ...representative.assessment,
+      categoryCounts,
+      findingsCount: mergedFindings.length,
+      reasons: [...new Set(reasons)],
+    },
+    findings: mergedFindings,
+    grouping: {
+      kind: "cargo-repository",
+      label: `cargo:${representative.repoUrl}`,
+      memberCount: group.length,
+      repoUrl: representative.repoUrl,
+      groupedPurls,
+    },
+    target: {
+      ...representative.target,
+      bomRefs: allBomRefs,
+      name: "*",
+      version: undefined,
+    },
+  };
+}
+
+function consolidateSharedRepoCiResult(group) {
+  const representative = group.reduce((best, result) =>
+    preferredResult(best, result),
+  );
+  const allBomRefs = [
+    ...new Set(group.flatMap((result) => result.target?.bomRefs || [])),
+  ];
+  const groupedPurls = [
+    ...new Set(group.map((result) => result.target?.purl).filter(Boolean)),
+  ];
+  const mergedFindings = dedupeFindings(
+    group.flatMap((result) => result.findings || []),
+  );
+  const reasons = [
+    `${group.length} packages resolved to the same repository and shared the same CI findings, so cdx-audit consolidated them into one alert.`,
+    ...(representative.assessment?.reasons || []),
+  ];
+  return {
+    ...representative,
+    assessment: {
+      ...representative.assessment,
+      categoryCounts: {
+        "ci-permission": mergedFindings.length,
+      },
+      findingsCount: mergedFindings.length,
+      reasons: [...new Set(reasons)],
+    },
+    findings: mergedFindings,
+    grouping: {
+      kind: "shared-repo-ci",
+      label: representative.repoUrl,
+      memberCount: group.length,
+      repoUrl: representative.repoUrl,
+      groupedPurls,
+    },
+    target: {
+      ...representative.target,
+      bomRefs: allBomRefs,
+      name: "*",
+      version: undefined,
+    },
+  };
+}
+
+function consolidateNamespaceResult(group) {
+  const representative = group.reduce((best, result) =>
+    preferredResult(best, result),
+  );
+  const allBomRefs = [
+    ...new Set(group.flatMap((result) => result.target?.bomRefs || [])),
+  ];
+  const groupedPurls = [
+    ...new Set(group.map((result) => result.target?.purl).filter(Boolean)),
+  ];
+  const mergedFindings = dedupeFindings(
+    group.flatMap((result) => result.findings || []),
+  );
+  const categoryCounts = {};
+  for (const result of group) {
+    for (const [category, count] of Object.entries(
+      result.assessment?.categoryCounts || {},
+    )) {
+      categoryCounts[category] = (categoryCounts[category] || 0) + count;
+    }
+  }
+  const reasons = [
+    `${group.length} npm packages under namespace '${representative.target.namespace}' shared the same predictive pattern and were consolidated into one alert.`,
+    ...(representative.assessment?.reasons || []),
+  ];
+  return {
+    ...representative,
+    assessment: {
+      ...representative.assessment,
+      categoryCounts,
+      findingsCount: mergedFindings.length,
+      reasons: [...new Set(reasons)],
+    },
+    findings: mergedFindings,
+    grouping: {
+      kind: "npm-namespace",
+      label: `npm:${representative.target.namespace}/*`,
+      memberCount: group.length,
+      namespace: representative.target.namespace,
+      groupedPurls,
+    },
+    target: {
+      ...representative.target,
+      bomRefs: allBomRefs,
+      name: "*",
+      version: undefined,
+    },
+  };
+}
+
+/**
+ * Consolidate per-target audit results into shared repo/CI alert groups.
+ *
+ * Groups results that share a common repository/CI provenance (or cargo
+ * repository/namespace) into consolidated alert entries while preserving
+ * single-target results unchanged.
+ *
+ * @param {object[]} results Per-target audit result objects
+ * @returns {object[]} Grouped result objects with consolidated entries where applicable
+ */
+export function groupAuditResults(results) {
+  const groupedResults = [];
+  const orderedEntries = [];
+  const resultGroups = new Map();
+  const sharedRepoCiGroupCounts = new Map();
+  for (const result of results) {
+    const sharedRepoCiKey = getSharedRepoCiGroupingKey(result);
+    if (!sharedRepoCiKey) {
+      continue;
+    }
+    sharedRepoCiGroupCounts.set(
+      sharedRepoCiKey,
+      (sharedRepoCiGroupCounts.get(sharedRepoCiKey) || 0) + 1,
+    );
+  }
+  for (const result of results) {
+    const descriptor = getGroupingDescriptor(result, sharedRepoCiGroupCounts);
+    if (!descriptor) {
+      orderedEntries.push({ result, type: "single" });
+      continue;
+    }
+    if (!resultGroups.has(descriptor.key)) {
+      resultGroups.set(descriptor.key, []);
+      orderedEntries.push({ descriptor, type: "group" });
+    }
+    resultGroups.get(descriptor.key).push(result);
+  }
+  for (const entry of orderedEntries) {
+    if (entry.type === "single") {
+      groupedResults.push(entry.result);
+      continue;
+    }
+    const group = resultGroups.get(entry.descriptor.key) || [];
+    if (group.length <= 1) {
+      groupedResults.push(group[0]);
+      continue;
+    }
+    groupedResults.push(
+      entry.descriptor.kind === "shared-repo-ci"
+        ? consolidateSharedRepoCiResult(group)
+        : entry.descriptor.kind === "cargo-repository"
+          ? consolidateCargoRepositoryResult(group)
+          : consolidateNamespaceResult(group),
+    );
+  }
+  return groupedResults;
+}
+
+function summarizeGroupedResults(results) {
+  const severityCounts = {
+    critical: 0,
+    high: 0,
+    low: 0,
+    medium: 0,
+    none: 0,
+  };
+  for (const result of results) {
+    const severity = result?.assessment?.severity || "none";
+    severityCounts[severity] = (severityCounts[severity] || 0) + 1;
+  }
+  return {
+    groupedResultCount: results.length,
+    groupedSeverityCounts: severityCounts,
+  };
+}
+
+/**
+ * Run the predictive audit flow from one or more already-loaded CycloneDX BOM inputs.
+ *
+ * @param {{ source: string, bomJson: object }[]} inputBoms loaded CycloneDX BOM objects
+ * @param {object} options CLI options
+ * @returns {Promise<object>} aggregate audit report
+ */
+export async function runAuditFromBoms(inputBoms, options) {
+  if (!inputBoms.length) {
+    throw new Error("No CycloneDX BOM inputs were found.");
+  }
+  const shouldEnrichRegistryMetadata =
+    !isDryRun && options.trusted !== "include";
+  if (shouldEnrichRegistryMetadata) {
+    await enrichInputBomsWithRegistryMetadata(inputBoms);
+  }
+  const targetSelectionOptions = {
+    allowlistFile: options.allowlistFile,
+    maxTargets: options.maxTargets,
+    prioritizeDirectRuntime: options.prioritizeDirectRuntime,
+    scope: options.scope,
+    trusted: options.trusted,
+  };
+  const extractedTargets = collectAuditTargets(
+    inputBoms,
+    targetSelectionOptions,
+  );
+  if (isDryRun) {
+    // Dry-run mode intentionally stops after target planning. Registry metadata
+    // enrichment, repository cloning, and child SBOM generation are all
+    // side-effecting or outbound behaviors that the predictive audit must avoid.
+    const report = {
+      dryRun: true,
+      generatedAt: new Date().toISOString(),
+      groupedResults: [],
+      inputs: inputBoms.map((inputBom) => inputBom.source),
+      results: extractedTargets.targets.map((target) => ({
+        assessment: {
+          categoryCounts: {},
+          confidenceLabel: "none",
+          findingsCount: 0,
+          reasons: [
+            "Dry run mode planned this predictive audit target from the input BOM but skipped registry metadata fetches, upstream repository cloning, and child SBOM generation.",
+          ],
+          score: 0,
+          severity: "none",
+        },
+        findings: [],
+        status: "skipped",
+        target,
+      })),
+      skipped: extractedTargets.skipped,
+      summary: {
+        predictiveDryRun: true,
+      },
+      tool: {
+        name: "cdx-audit",
+        version: readPackageVersion(),
+      },
+    };
+    Object.assign(
+      report.summary,
+      summarizeAudit(inputBoms, report.results, extractedTargets.skipped),
+      summarizeGroupedResults(report.groupedResults),
+    );
+    recordActivity({
+      kind: "audit",
+      reason:
+        "Dry run mode planned predictive BOM audit targets from the input BOM but skipped registry metadata fetches, repository cloning, and child SBOM generation.",
+      status: extractedTargets.targets.length ? "blocked" : "completed",
+      target: "predictive-dependency-audit",
+    });
+    return report;
+  }
+  const results = [];
+  const preflightMessage = buildPredictiveAuditPreflightMessage(
+    extractedTargets,
+    options,
+  );
+  if (preflightMessage) {
+    emitProgress(options, {
+      message: preflightMessage,
+      total: extractedTargets.targets.length,
+      type: "run:info",
+    });
+  }
+  if (extractedTargets.targets.length) {
+    emitProgress(options, {
+      total: extractedTargets.targets.length,
+      type: "run:start",
+    });
+    // Every target's repository lookup is known here, before the first clone,
+    // so they are resolved in one round rather than one per iteration below.
+    await prefetchGitUrlSources(
+      extractedTargets.targets.map((target) => target.purl),
+    );
+  }
+  for (const [index, target] of extractedTargets.targets.entries()) {
+    const targetIndex = index + 1;
+    emitProgress(options, {
+      index: targetIndex,
+      label: formatTargetLabel(target),
+      target,
+      total: extractedTargets.targets.length,
+      type: "target:start",
+    });
+    const result = await auditTarget(target, {
+      ...options,
+      _targetIndex: targetIndex,
+      _targetTotal: extractedTargets.targets.length,
+    });
+    results.push(result);
+    emitProgress(options, {
+      index: targetIndex,
+      label: formatTargetLabel(target),
+      result,
+      target,
+      total: extractedTargets.targets.length,
+      type: "target:finish",
+    });
+  }
+  const groupedResults = groupAuditResults(results);
+  const report = {
+    generatedAt: new Date().toISOString(),
+    inputs: inputBoms.map((inputBom) => inputBom.source),
+    groupedResults,
+    results,
+    skipped: extractedTargets.skipped,
+    summary: summarizeAudit(inputBoms, results, extractedTargets.skipped),
+    tool: {
+      name: "cdx-audit",
+      version: readPackageVersion(),
+    },
+  };
+  Object.assign(report.summary, summarizeGroupedResults(groupedResults));
+  if (options.reportsDir) {
+    const aggregateFile = join(
+      resolve(options.reportsDir),
+      "aggregate-report.json",
+    );
+    writeJsonFile(aggregateFile, report);
+    report.aggregateReportFile = aggregateFile;
+  }
+  if (extractedTargets.targets.length) {
+    emitProgress(options, {
+      summary: report.summary,
+      type: "run:finish",
+    });
+  }
+  return report;
+}
+
+/**
+ * Run the predictive audit flow from one or more CycloneDX BOM inputs.
+ *
+ * @param {object} options CLI options
+ * @returns {Promise<object>} aggregate audit report
+ */
+export async function runAudit(options) {
+  const inputBoms = loadInputBoms(options);
+  const workspaceContext = prepareWorkspaceContext(options);
+  const licensePolicy = options.licensePolicy
+    ? loadPolicy(options.licensePolicy)
+    : null;
+  try {
+    const auditOptions = {
+      ...options,
+      workspaceDir: workspaceContext.workspaceDir,
+      // Preloaded so each target's child SBOM can be evaluated in auditTarget
+      // without re-reading the policy file per dependency.
+      _licensePolicy: licensePolicy,
+    };
+    const report = options.directBomAudit
+      ? await runDirectBomAuditFromBoms(inputBoms, auditOptions)
+      : await runAuditFromBoms(inputBoms, auditOptions);
+    attachLicenseViolations(report, inputBoms, licensePolicy);
+    return report;
+  } finally {
+    if (workspaceContext.cleanupOnFinish) {
+      cleanupSourceDir(workspaceContext.workspaceDir);
+    }
+  }
+}
+
+/**
+ * Aggregates license compliance violations onto the report. Violations come
+ * from two sources: the input BOM(s) directly, and — in predictive mode — the
+ * per-dependency child SBOMs generated from cloned upstream sources (carried on
+ * each target result). Duplicates across both are collapsed so the same
+ * component/license/alert is reported once. No-op without a policy.
+ *
+ * @param {object} report aggregate audit report (mutated)
+ * @param {object[]} inputBoms loaded input BOMs
+ * @param {object|null} policy preloaded compliance policy
+ * @returns {void}
+ */
+export function attachLicenseViolations(report, inputBoms, policy) {
+  if (!report || !policy) {
+    return;
+  }
+  const seen = new Set();
+  const violations = [];
+  const add = (violation, source) => {
+    const key = `${violation.ref}|${violation.license}|${violation.alert}`;
+    if (seen.has(key)) {
+      return;
+    }
+    seen.add(key);
+    violations.push({ ...violation, source });
+  };
+  // Direct violations from the input BOM(s).
+  for (const inputBom of inputBoms) {
+    for (const violation of collectPolicyViolations(inputBom.bomJson, policy, {
+      includeWarnings: true,
+    })) {
+      add(violation, inputBom.source);
+    }
+  }
+  // Violations surfaced from each dependency's child SBOM (predictive mode).
+  for (const result of report.results || []) {
+    for (const violation of result.licenseViolations || []) {
+      add(violation, formatTargetLabel(result.target) || result.repoUrl);
+    }
+  }
+  report.licenseViolations = violations;
+  report.summary = report.summary || {};
+  report.summary.licenseViolations = violations.length;
+  report.summary.licenseViolationsByAlert = violations.reduce(
+    (counts, violation) => {
+      counts[violation.alert] = (counts[violation.alert] || 0) + 1;
+      return counts;
+    },
+    {},
+  );
+}
+
+/**
+ * Render a report and compute the proper process exit code.
+ *
+ * @param {object} report aggregate report
+ * @param {object} options CLI options
+ * @returns {{ exitCode: number, output: string }} rendered output and exit code
+ */
+export function finalizeAuditReport(report, options) {
+  const output = renderAuditReport(options.report, report, {
+    minSeverity: options.minSeverity,
+  });
+  // Prohibited (error-level) license violations are a hard fail regardless of
+  // the supply-chain severity threshold.
+  const licensePolicyFail = (report?.licenseViolations || []).some(
+    (violation) => violation.alert === "error",
+  );
+  if (report?.auditMode === "direct") {
+    const shouldFail = (report.results || []).some((result) =>
+      (result.findings || []).some((finding) =>
+        severityMeetsThreshold(
+          finding?.severity || "none",
+          options.failSeverity || "high",
+        ),
+      ),
+    );
+    return {
+      exitCode: shouldFail || licensePolicyFail ? 3 : 0,
+      output,
+    };
+  }
+  const effectiveResults = report.groupedResults?.length
+    ? report.groupedResults
+    : report.results;
+  const shouldFail = effectiveResults.some(
+    (result) =>
+      !result?.error &&
+      severityMeetsThreshold(
+        result?.assessment?.severity || "none",
+        options.failSeverity || "high",
+      ),
+  );
+  return {
+    exitCode: shouldFail || licensePolicyFail ? 3 : 0,
+    output,
+  };
+}
+
+/**
+ * Build a result file name for user-provided report output paths.
+ *
+ * @param {object} options CLI options
+ * @returns {string | undefined} output file path
+ */
+export function defaultOutputFile(options) {
+  if (!options.reportsDir) {
+    return undefined;
+  }
+  return join(
+    resolve(options.reportsDir),
+    `cdx-audit-report.${options.report || "console"}.txt`,
+  );
+}