@cdxgen/cdxgen 13.0.1 → 13.2.0

package/lib/inventory/envcontext.js

@@ -10,6 +10,14 @@ import {
   isSecureMode,
   readEnvironmentVariable,
 } from "../core/activity.js";
+import {
+  commandOutputText,
+  isLedgerEnabled,
+  LEDGER_EVENT_IMPACTS,
+  LEDGER_EVENT_KINDS,
+  recordDegradation,
+  recordLedgerEvent,
+} from "../core/buildLedger.js";
 import {
   CARGO_CMD,
   DOTNET_CMD,
@@ -33,7 +41,12 @@ import {
 } from "../core/fs.js";
 import { diagnosticStream } from "../core/logger.js";
 import { dirNameStr, isMac, isWin } from "../core/paths.js";
+import { isValidSdkmanVersion } from "./jvmToolEnv.js";
 import { applyPurl, tryBuildPurl } from "./purl.js";
+import {
+  classifySpawnRestriction,
+  describeSpawnRestriction,
+} from "./toolRequirements.js";
 
 /**
  * Git executable name used for all git invocations, overridable via GIT_CMD.
@@ -88,15 +101,18 @@ function hardenedGitEnv() {
  * @type {Object<string, string>}
  */
 export const SDKMAN_JAVA_TOOL_ALIASES = {
-  java8: readEnvironmentVariable("JAVA8_TOOL") || "8.0.452-amzn", // Temurin no longer offers java8 :(
-  java11: readEnvironmentVariable("JAVA11_TOOL") || "11.0.31-tem",
-  java17: readEnvironmentVariable("JAVA17_TOOL") || "17.0.19-tem",
-  java21: readEnvironmentVariable("JAVA21_TOOL") || "21.0.11-tem",
+  // Identifiers must be downloadable from the sdkman broker: the `sdk list`
+  // output advertises Temurin respin ids such as 21.0.12+1.1-tem, but the
+  // broker cannot serve ids containing '+', so the plain ids are pinned.
+  java8: readEnvironmentVariable("JAVA8_TOOL") || "8.0.504-zulu", // Temurin no longer offers java8 :(
+  java11: readEnvironmentVariable("JAVA11_TOOL") || "11.0.32-tem",
+  java17: readEnvironmentVariable("JAVA17_TOOL") || "17.0.20-tem",
+  java21: readEnvironmentVariable("JAVA21_TOOL") || "21.0.12-tem",
   java22: readEnvironmentVariable("JAVA22_TOOL") || "22.0.2-tem",
   java23: readEnvironmentVariable("JAVA23_TOOL") || "23.0.2-tem",
   java24: readEnvironmentVariable("JAVA24_TOOL") || "24.0.2-tem",
-  java25: readEnvironmentVariable("JAVA25_TOOL") || "25.0.3-tem",
-  java26: readEnvironmentVariable("JAVA26_TOOL") || "26.0.1-tem",
+  java25: readEnvironmentVariable("JAVA25_TOOL") || "25.0.4-tem",
+  java26: readEnvironmentVariable("JAVA26_TOOL") || "26.0.2-tem",
 };
 
 /**
@@ -205,12 +221,17 @@ export function execGitCommand(dir, args) {
   // Prepend hardening `-c` overrides before the subcommand and run git with a
   // hardened environment so a scanned/untrusted repo cannot execute hooks,
   // fsmonitor commands, or config-driven scripts.
+  // git is a real executable, so Windows can spawn it without a shell. Doing
+  // so keeps the pretty-format arguments intact: `%H`, `%n` and `%x1e` are
+  // cmd.exe variable-expansion syntax, which the shell-execution guard rightly
+  // refuses to pass through a shell.
   return getCommandOutput(
     GIT_COMMAND,
     dir,
     [...GIT_HARDENING_CONFIG_ARGS, ...args],
     {
       env: hardenedGitEnv(),
+      shell: false,
     },
   );
 }
@@ -292,6 +313,60 @@ export function gitLogTrailers(dir, maxCount = 20) {
   return commits;
 }
 
+/**
+ * Record a successful version probe with the version the tool reported.
+ *
+ * @param {string} tool Tool name
+ * @param {string} ecosystem Ecosystem the tool belongs to
+ * @param {string} found Version string reported by the tool
+ */
+function recordToolProbeResolved(tool, ecosystem, found) {
+  recordLedgerEvent(LEDGER_EVENT_KINDS.TOOL_RESOLVED, {
+    ecosystem,
+    tool,
+    found,
+    source: "PATH",
+  });
+}
+
+/**
+ * Record a failed version probe. A probe the environment did not let run is
+ * degraded evidence — the tool may well be present — while only a probe that
+ * ran and found nothing counts as a missing tool.
+ *
+ * @param {string} tool Tool name
+ * @param {string} ecosystem Ecosystem the tool belongs to
+ * @param {string} command Probe command that failed
+ */
+function recordToolProbeFailure(tool, ecosystem, command) {
+  if (!isLedgerEnabled()) {
+    return;
+  }
+  const restriction = describeSpawnRestriction(command);
+  if (restriction) {
+    // A dry-run block is the user's own request, so it costs nothing; any
+    // other policy restriction hides a version the tool may well have.
+    const isDryRunBlock = classifySpawnRestriction(command) === "dry-run";
+    recordLedgerEvent(LEDGER_EVENT_KINDS.EVIDENCE_DEGRADED, {
+      ecosystem,
+      tool,
+      source: "PATH",
+      remediationId: isDryRunBlock ? "policy.dry-run" : "policy.secure-mode",
+      impact: isDryRunBlock
+        ? LEDGER_EVENT_IMPACTS.NONE
+        : LEDGER_EVENT_IMPACTS.VERSIONS,
+      detail: `The ${tool} version probe could not run: ${restriction}.`,
+    });
+  } else {
+    recordLedgerEvent(LEDGER_EVENT_KINDS.TOOL_MISSING, {
+      ecosystem,
+      tool,
+      source: "PATH",
+      detail: `No ${tool} command answered the version probe.`,
+    });
+  }
+}
+
 /**
  * Collect Java version and installed modules
  *
@@ -303,7 +378,7 @@ export function collectJavaInfo(dir) {
   const moduleDesc =
     getCommandOutput(getJavaCommand(), dir, ["--list-modules"]) || "";
   if (versionDesc) {
-    return {
+    const info = {
       type: "platform",
       name: "java",
       version: versionDesc.split("\n")[0].replace("java ", ""),
@@ -315,7 +390,10 @@ export function collectJavaInfo(dir) {
         },
       ],
     };
+    recordToolProbeResolved("java", "java", info.version);
+    return info;
   }
+  recordToolProbeFailure("java", "java", getJavaCommand());
   return undefined;
 }
 
@@ -330,13 +408,16 @@ export function collectDotnetInfo(dir) {
   const moduleDesc =
     getCommandOutput(DOTNET_CMD, dir, ["--list-runtimes"]) || "";
   if (versionDesc) {
-    return {
+    const info = {
       type: "platform",
       name: "dotnet",
       version: versionDesc.trim(),
       description: moduleDesc.replaceAll("\n", "\\n"),
     };
+    recordToolProbeResolved("dotnet", "csharp", info.version);
+    return info;
   }
+  recordToolProbeFailure("dotnet", "csharp", DOTNET_CMD);
   return undefined;
 }
 
@@ -347,25 +428,21 @@ export function collectDotnetInfo(dir) {
  * @returns Object containing python details
  */
 export function collectPythonInfo(dir) {
-  const versionDesc = getCommandOutput(getPythonCommand(), dir, [
-    "-S",
-    "--version",
-  ]);
+  const pythonCmd = getPythonCommand();
+  const versionDesc = getCommandOutput(pythonCmd, dir, ["-S", "--version"]);
   const moduleDesc =
-    getCommandOutput(getPythonCommand(), dir, [
-      "-I",
-      "-m",
-      "pip",
-      "--version",
-    ]) || "";
+    getCommandOutput(pythonCmd, dir, ["-I", "-m", "pip", "--version"]) || "";
   if (versionDesc) {
-    return {
+    const info = {
       type: "platform",
       name: "python",
       version: versionDesc.replace("Python ", ""),
       description: moduleDesc.replaceAll("\n", "\\n"),
     };
+    recordToolProbeResolved("python", "python", info.version);
+    return info;
   }
+  recordToolProbeFailure("python", "python", pythonCmd);
   return undefined;
 }
 
@@ -386,6 +463,9 @@ export function collectNodeInfo(dir) {
   const moduleDesc = getCommandOutput(NPM_CMD, dir, ["--version"]);
   if (moduleDesc) {
     nodeInfo.description = `npm: ${moduleDesc}`;
+    recordToolProbeResolved("npm", "npm", moduleDesc);
+  } else {
+    recordToolProbeFailure("npm", "npm", NPM_CMD);
   }
   return nodeInfo;
 }
@@ -400,13 +480,16 @@ export function collectGccInfo(dir) {
   const versionDesc = getCommandOutput(GCC_CMD, dir, ["--version"]);
   const moduleDesc = getCommandOutput(GCC_CMD, dir, ["-print-search-dirs"]);
   if (versionDesc) {
-    return {
+    const info = {
       type: "platform",
       name: "gcc",
       version: versionDesc.split("\n")[0],
       description: (moduleDesc || "").replaceAll("\n", "\\n"),
     };
+    recordToolProbeResolved("gcc", "c", info.version);
+    return info;
   }
+  recordToolProbeFailure("gcc", "c", GCC_CMD);
   return undefined;
 }
 
@@ -420,13 +503,16 @@ export function collectRustInfo(dir) {
   const versionDesc = getCommandOutput(RUSTC_CMD, dir, ["--version"]);
   const moduleDesc = getCommandOutput(CARGO_CMD, dir, ["--version"]);
   if (versionDesc) {
-    return {
+    const info = {
       type: "platform",
       name: "rustc",
       version: versionDesc.trim(),
       description: (moduleDesc || "").trim(),
     };
+    recordToolProbeResolved("rustc", "rust", info.version);
+    return info;
   }
+  recordToolProbeFailure("rustc", "rust", RUSTC_CMD);
   return undefined;
 }
 
@@ -439,12 +525,15 @@ export function collectRustInfo(dir) {
 export function collectGoInfo(dir) {
   const versionDesc = getCommandOutput(GO_CMD, dir, ["version"]);
   if (versionDesc) {
-    return {
+    const info = {
       type: "platform",
       name: "go",
       version: versionDesc.trim(),
     };
+    recordToolProbeResolved("go", "go", info.version);
+    return info;
   }
+  recordToolProbeFailure("go", "go", GO_CMD);
   return undefined;
 }
 
@@ -457,12 +546,15 @@ export function collectGoInfo(dir) {
 export function collectSwiftInfo(dir) {
   const versionDesc = getCommandOutput(SWIFT_CMD, dir, ["--version"]);
   if (versionDesc) {
-    return {
+    const info = {
       type: "platform",
       name: "swift",
       version: versionDesc.trim(),
     };
+    recordToolProbeResolved("swift", "swift", info.version);
+    return info;
   }
+  recordToolProbeFailure("swift", "swift", SWIFT_CMD);
   return undefined;
 }
 
@@ -475,12 +567,15 @@ export function collectSwiftInfo(dir) {
 export function collectRubyInfo(dir) {
   const versionDesc = getCommandOutput(RUBY_CMD, dir, ["--version"]);
   if (versionDesc) {
-    return {
+    const info = {
       type: "platform",
       name: "ruby",
       version: versionDesc.trim(),
     };
+    recordToolProbeResolved("ruby", "ruby", info.version);
+    return info;
   }
+  recordToolProbeFailure("ruby", "ruby", RUBY_CMD);
   return undefined;
 }
 
@@ -667,6 +762,17 @@ export function installSdkmanTool(toolType, toolName) {
     return false;
   }
   toolName = getSdkmanToolFullname(toolName);
+  // The version is interpolated into an interactive shell command, so reject
+  // any identifier that is not a single safe token before spawning.
+  if (
+    !/^[a-z][a-z0-9-]*$/.test(`${toolType}`) ||
+    !isValidSdkmanVersion(toolName)
+  ) {
+    console.log(
+      `Unable to install ${toolType} with an invalid version identifier '${toolName}'. Use exact sdkman version identifiers such as '3.9.9' or '21.0.7-tem'.`,
+    );
+    return false;
+  }
   let result;
   if (!isSdkmanToolAvailable(toolType, toolName)) {
     let installDir = "";
@@ -968,6 +1074,14 @@ export function installRubyVersion(rubyVersion, filePath) {
       if (result.stderr) {
         console.log(result.stderr);
       }
+      recordLedgerEvent(LEDGER_EVENT_KINDS.COMMAND_FAILED, {
+        ecosystem: "ruby",
+        tool: "rbenv",
+        command: `rbenv local ${rubyVersion}`,
+        exitCode: typeof result.status === "number" ? result.status : undefined,
+        detail: `Selecting Ruby ${rubyVersion} with rbenv local did not succeed.`,
+        outputExcerpt: commandOutputText(result),
+      });
     }
     if (result.status === 0) {
       return { fullToolBinDir, status: true };
@@ -975,6 +1089,14 @@ export function installRubyVersion(rubyVersion, filePath) {
   }
   // Check if we're trying to install Ruby 1.x or 2.x
   if (rubyVersion.startsWith("1.")) {
+    recordDegradation("ruby.version.unsupported-host", {
+      ecosystem: "ruby",
+      tool: "ruby",
+      impact: "transitive-deps",
+      wanted: rubyVersion,
+      detail:
+        "Building Ruby 1.x on this host is unsupported; a matching legacy container image is required to build this project.",
+    });
     console.log(
       `Ruby version ${rubyVersion} requires very old versions of Linux such as debian:8. Consider using the container image "ghcr.io/cdxgen/debian-ruby18:master" to build the application first and then invoke cdxgen with the arguments "--lifecycle pre-build".`,
     );
@@ -983,6 +1105,14 @@ export function installRubyVersion(rubyVersion, filePath) {
     rubyVersion.startsWith("2.") &&
     readEnvironmentVariable("CDXGEN_IN_CONTAINER") !== "true"
   ) {
+    recordDegradation("ruby.build-deps.missing", {
+      ecosystem: "ruby",
+      tool: "ruby",
+      impact: "transitive-deps",
+      wanted: rubyVersion,
+      detail:
+        "Building Ruby 2.x on this host requires development libraries that are not installed.",
+    });
     console.log(
       `Installing Ruby version ${rubyVersion} requires specific development libraries. Consider using the custom container image "ghcr.io/cdxgen/cdxgen-debian-ruby26:v13" instead.`,
     );
@@ -996,6 +1126,12 @@ export function installRubyVersion(rubyVersion, filePath) {
       `To speed up this step, use bind mounts. Example: "--mount type=bind,src=/tmp/rbenv,dst=/root/.rbenv/versions/${rubyVersion}"`,
     );
   }
+  recordLedgerEvent(LEDGER_EVENT_KINDS.COMMAND_ATTEMPTED, {
+    ecosystem: "ruby",
+    tool: "rbenv",
+    command: `rbenv install ${rubyVersion}`,
+    detail: `Installing Ruby ${rubyVersion} with rbenv.`,
+  });
   const result = safeSpawnSync(
     readEnvironmentVariable("RBENV_CMD") || "rbenv",
     ["install", rubyVersion],
@@ -1004,6 +1140,14 @@ export function installRubyVersion(rubyVersion, filePath) {
     },
   );
   if (result.error || result.status !== 0) {
+    recordLedgerEvent(LEDGER_EVENT_KINDS.COMMAND_FAILED, {
+      ecosystem: "ruby",
+      tool: "rbenv",
+      command: `rbenv install ${rubyVersion}`,
+      exitCode: typeof result.status === "number" ? result.status : undefined,
+      detail: `The rbenv install of Ruby ${rubyVersion} did not succeed.`,
+      outputExcerpt: commandOutputText(result),
+    });
     if (result.stdout) {
       console.log(result.stdout);
     }
@@ -1129,6 +1273,13 @@ export function performBundleInstall(
   console.log(
     `Invoking ${bundleCommand} ${installArgs.join(" ")} from ${basePath} with GEM_HOME ${cdxgenGemHome}. Please wait ...`,
   );
+  recordLedgerEvent(LEDGER_EVENT_KINDS.COMMAND_ATTEMPTED, {
+    ecosystem: "ruby",
+    tool: "bundler",
+    command: `${bundleCommand} ${installArgs.join(" ")}`,
+    path: basePath,
+    detail: "Installing the project dependencies with bundler.",
+  });
   let result = safeSpawnSync(bundleCommand, installArgs, {
     shell: isWin,
     cwd: basePath,
@@ -1138,6 +1289,15 @@ export function performBundleInstall(
     },
   });
   if (result.error || result.status !== 0) {
+    recordLedgerEvent(LEDGER_EVENT_KINDS.COMMAND_FAILED, {
+      ecosystem: "ruby",
+      tool: "bundler",
+      command: `${bundleCommand} ${installArgs.join(" ")}`,
+      path: basePath,
+      exitCode: typeof result.status === "number" ? result.status : undefined,
+      detail: "The bundle install did not succeed.",
+      outputExcerpt: commandOutputText(result),
+    });
     let pythonWarningShown = false;
     let rubyVersionWarningShown = false;
     if (
@@ -1184,6 +1344,13 @@ export function performBundleInstall(
         );
       }
       console.log(`${bundleCommand}`);
+      recordLedgerEvent(LEDGER_EVENT_KINDS.COMMAND_ATTEMPTED, {
+        ecosystem: "ruby",
+        tool: "bundler",
+        command: `${bundleCommand} ${updateArgs.join(" ")}`,
+        path: basePath,
+        detail: "Updating the outdated lockfile with bundler.",
+      });
       result = safeSpawnSync(bundleCommand, updateArgs, {
         shell: isWin,
         cwd: basePath,
@@ -1193,6 +1360,16 @@ export function performBundleInstall(
         },
       });
       if (result.error || result.status !== 0) {
+        recordLedgerEvent(LEDGER_EVENT_KINDS.COMMAND_FAILED, {
+          ecosystem: "ruby",
+          tool: "bundler",
+          command: `${bundleCommand} ${updateArgs.join(" ")}`,
+          path: basePath,
+          exitCode:
+            typeof result.status === "number" ? result.status : undefined,
+          detail: "The bundle update did not succeed.",
+          outputExcerpt: commandOutputText(result),
+        });
         console.log("------------");
         if (result.stdout) {
           console.log(result.stdout);
@@ -1740,6 +1917,20 @@ export function getRuntimeInformation() {
     runtimeInfo.version = "N/A";
   }
 
+  // The runtime hosting the cdxgen run is part of the report's
+  // reproducibility context, so it is recorded alongside the scanned tools.
+  const runtimeTools = { Deno: "deno", Bun: "bun", "Node.js": "node" };
+  const runtimeTool = runtimeTools[runtimeInfo.runtime];
+  if (runtimeTool && runtimeInfo.version && runtimeInfo.version !== "N/A") {
+    recordLedgerEvent(LEDGER_EVENT_KINDS.TOOL_RESOLVED, {
+      ecosystem: "generic",
+      tool: runtimeTool,
+      found: runtimeInfo.version,
+      source: "runtime",
+      detail:
+        "The runtime hosting this cdxgen run, recorded for report reproducibility.",
+    });
+  }
   return runtimeInfo;
 }
 

package/lib/inventory/evidenceUtils.js

@@ -6,6 +6,7 @@ import { build } from "@cdxgen/cdx-purl";
 
 import { safeExistsSync } from "../core/fs.js";
 import { thoughtLog } from "../core/logger.js";
+import { addDosaiReachabilityProperties } from "./dosai.js";
 import {
   addDosaiSetValue,
   buildDosaiPurlAliasMap,
@@ -256,6 +257,7 @@ export function addEvidenceForDotnet(pkgList, slicesFile) {
   const purlLocationMap = {};
   const purlModulesMap = {};
   const purlMethodsMap = {};
+  const purlReachabilityMap = {};
   const purlAliasMap = buildDosaiPurlAliasMap(pkgList);
   for (const apkg of pkgList) {
     if (apkg.properties && Array.isArray(apkg.properties)) {
@@ -340,6 +342,9 @@ export function addEvidenceForDotnet(pkgList, slicesFile) {
         if (!modPurl) {
           continue;
         }
+        // Confidence/evidence facts for this purl, applied to the component below so an
+        // unbuilt tree stays distinguishable from an only-imported package.
+        purlReachabilityMap[modPurl] ??= reachability;
         let hasExplicitSourceLocations = false;
         for (const sourceLocation of reachability.SourceLocations || []) {
           const location = dosaiSourceLocation(sourceLocation);
@@ -456,6 +461,14 @@ export function addEvidenceForDotnet(pkgList, slicesFile) {
       "I didn't find any occurrence evidence or detailed imported modules, even though there is good dependency slice data from dosai. This is surprising.",
     );
   }
+  // Reachability confidence facts (kind, confidence, evidence, reasons) as properties.
+  // Applied outside the location guard: a Low-confidence unbuilt tree must stay
+  // distinguishable from an only-imported package even when no locations were found.
+  for (const apkg of pkgList) {
+    if (purlReachabilityMap[apkg.purl]) {
+      addDosaiReachabilityProperties(apkg, purlReachabilityMap[apkg.purl]);
+    }
+  }
   return pkgList;
 }
 

package/lib/inventory/fetchBatch.js

@@ -34,10 +34,13 @@
  */
 
 import {
+  BLOCKED_HOST_ERROR_CODE,
   cdxgenAgent,
   DEBUG_MODE,
+  DRY_RUN_ERROR_CODE,
   readEnvironmentVariable,
 } from "../core/activity.js";
+import { isLedgerEnabled, recordDegradation } from "../core/buildLedger.js";
 import { resolveCacheDir } from "./cacheDir.js";
 import { cdxrsAvailable, runCdxrs } from "./cdxrs.js";
 import {
@@ -245,21 +248,58 @@ export async function prefetchJson(requests, options = {}) {
  * - a non-JSON `responseType`, since the envelope has nowhere to put HTML;
  * - request-specific `headers`, since cdxrs derives its own Authorization from
  *   `GITHUB_TOKEN` and would silently drop any other credential, turning an
- *   authenticated lookup into an anonymous one.
+ *   authenticated lookup into an anonymous one;
+ * - anything addressed to a host whose rate policy only one transport knows.
+ *   crates.io's crawler policy allows one request per second with no
+ *   parallelism, and package.elm-lang.org has a JS-only allowance because
+ *   rate.rs carries no row for it. Both transports keep separate gates, so a
+ *   batch split across the two would issue twice the agreed rate; the JS pool
+ *   owns these hosts so there is one gate to reason about.
  *
  * The pool applies the same global and per-host concurrency and rate policy, so
  * the batching win is unaffected; only the on-disk cache is skipped.
  *
- * @param {{responseType?: string, headers?: Object}} request
+ * @param {{url?: string, responseType?: string, headers?: Object}} request
  * @returns {boolean}
  */
 function cdxrsCanServe(request) {
   if (request.responseType && request.responseType !== "json") {
     return false;
   }
+  if (isSingleGateHost(extractHost(request.url))) {
+    return false;
+  }
   return !request.headers || !Object.keys(request.headers).length;
 }
 
+/**
+ * Whether a hostname belongs to crates.io, including its index and CDN hosts.
+ *
+ * @param {string|null} host Hostname, or null when the URL did not parse.
+ * @returns {boolean}
+ */
+export function isCratesHost(host) {
+  if (!host) {
+    return false;
+  }
+  const lower = host.toLowerCase();
+  return lower === "crates.io" || lower.endsWith(".crates.io");
+}
+
+/**
+ * Whether a host's rate policy lives in the JS table alone and therefore needs
+ * every request to pass through the one gate the JS pool holds.
+ *
+ * @param {string|null} host Hostname, or null when the URL did not parse.
+ * @returns {boolean}
+ */
+export function isSingleGateHost(host) {
+  if (!host) {
+    return false;
+  }
+  return isCratesHost(host) || host.toLowerCase() === "package.elm-lang.org";
+}
+
 /**
  * Run the batch through the `cdxrs fetch` subprocess and translate its
  * envelope into the shared result shape.
@@ -545,6 +585,59 @@ async function issueWithRetries(request, limiter) {
   }
 }
 
+/** Policy and connectivity degradations already recorded this run; these describe the run, not one URL. */
+const recordedPolicyDegradations = new Set();
+
+/**
+ * Record a run-level policy or connectivity degradation once per process. A
+ * batch touches many URLs, but "dry-run blocked the network", "a host was not
+ * permitted" and "the network is unreachable" are properties of the run, so
+ * only the first occurrence is recorded and the report reads one line, not
+ * one per URL.
+ *
+ * @param {string} remediationId Remediation id from data/remediations.json
+ * @param {Object} fields Ledger event fields
+ * @returns {void}
+ */
+function recordPolicyDegradationOnce(remediationId, fields) {
+  if (!isLedgerEnabled() || recordedPolicyDegradations.has(remediationId)) {
+    return;
+  }
+  recordedPolicyDegradations.add(remediationId);
+  recordDegradation(remediationId, fields);
+}
+
+/**
+ * Record the run-level policy or connectivity condition carried by a caught
+ * fetch error, if it names one. Shared by the batch retry loop and by the
+ * serial enrichment paths that catch and swallow the same typed errors.
+ *
+ * @param {Error} err Error caught from a `cdxgenAgent` request.
+ * @returns {void}
+ */
+export function recordPolicyDegradationFromError(err) {
+  if (err?.code === DRY_RUN_ERROR_CODE) {
+    recordPolicyDegradationOnce("policy.dry-run", {
+      ecosystem: "generic",
+      impact: "none",
+      detail: `Dry-run mode blocked a registry request: ${err.message}`,
+    });
+  } else if (err?.code === BLOCKED_HOST_ERROR_CODE) {
+    recordPolicyDegradationOnce("policy.host-blocked", {
+      ecosystem: "generic",
+      impact: "licenses",
+      detail: `A registry request was blocked by policy: ${err.message}`,
+    });
+  } else if (err?.name === "RequestError") {
+    recordPolicyDegradationOnce("policy.offline", {
+      ecosystem: "generic",
+      impact: "licenses",
+      detail:
+        "A registry request failed with a transport error, so registry metadata and license enrichment may be missing.",
+    });
+  }
+}
+
 /**
  * Classify an error thrown by `cdxgenAgent.get` into a retry decision and the
  * batch entry to record when retries are exhausted.
@@ -553,6 +646,7 @@ async function issueWithRetries(request, limiter) {
  * @returns {{retryable: boolean, delay: number|null, entry: BatchEntry}}
  */
 function classifyAgentError(err) {
+  recordPolicyDegradationFromError(err);
   // Secure-mode and dry-run blocks must not be retried, and the caller's own
   // fallback `cdxgenAgent.get` will surface the same error. Recording this as
   // non-definite lets the caller's catch run exactly as it would on the serial
@@ -643,6 +737,41 @@ async function fetchOne(request, gauge) {
   }
 }
 
+/**
+ * Run a caller's own request under the same per-host gate the batch pool uses.
+ *
+ * Not every registry lookup goes through the pool: a caller that misses the
+ * prefetch, or runs with prefetching disabled, issues `cdxgenAgent.get`
+ * directly. Those requests reach the same host and count against the same
+ * published budget, so they have to queue behind the same limiter rather than
+ * a second one — crates.io's one-request-per-second policy is not honoured by
+ * two independent gates that each allow one per second.
+ *
+ * The per-host semaphore and limiter are module state, so this shares one gate
+ * per host for the life of the process.
+ *
+ * @template T
+ * @param {string} url The URL about to be requested.
+ * @param {() => Promise<T>} issue Issues the request and resolves its result.
+ * @returns {Promise<T>} Whatever `issue` resolves to.
+ */
+export async function withHostRateLimit(url, issue) {
+  const host = extractHost(url);
+  if (!host) {
+    return await issue();
+  }
+  const controls = getHostControls(host);
+  const releaseGlobal = await _globalSemaphore.acquire();
+  const releaseHost = await controls.sem.acquire();
+  try {
+    await controls.limiter.wait();
+    return await issue();
+  } finally {
+    releaseHost();
+    releaseGlobal();
+  }
+}
+
 /**
  * Dedupe key for an in-flight request: the URL, plus everything that changes
  * which response the caller gets back. That is the headers which change what