@cdxgen/cdxgen 13.5.0 → 13.6.0

package/lib/core/brotliProbe.js

@@ -0,0 +1,182 @@
+// Bounded probe for a Brotli decoder compiled into a native file, and for
+// whether that copy carries the CVE-2026-111497 fix.
+//
+// Node.js, the Python Brotli and brotlicffi wheels, the PHP and Ruby
+// extensions, the .NET runtime and many static binaries carry a private copy of
+// Google's C decoder. No package manager names that copy, and its version is
+// not stored as a string anywhere in the file, so a BOM has to read the file
+// to say whether a vulnerable decoder ships in it.
+//
+// Three kinds of evidence are read, each classified by the bytes around it:
+//
+// - The names of the decoder's error codes, which BrotliDecoderErrorString()
+//   returns (EXUBERANT_NIBBLE is one). Upstream 1.1+ stores them prefixed,
+//   `_ERROR_FORMAT_EXUBERANT_NIBBLE`; 1.0.x and Debian's backport store the
+//   bare name between NULs. The fix, google/brotli 0ed4268, added the name
+//   BLOCK_SWITCH, so a decoder whose table has it is patched.
+//   https://github.com/google/brotli/blob/v1.2.0/c/include/brotli/decode.h#L72
+//   https://github.com/google/brotli/commit/0ed4268a4401abcb4472096340477cf4af7d1a2b
+// - Two decoder tables, kCodeLengthCodeOrder and kCodeLengthPrefixValue
+//   (c/dec/decode.c). They stay when a linker drops the error-name table
+//   because nothing calls BrotliDecoderErrorString (--gc-sections, LTO,
+//   -dead_strip). The encoder keeps the first table but not the second. With
+//   the tables alone the decoder is present but its fix state is unknown.
+// - Node.js's zlib.constants table, BROTLI_DECODER_ERROR_FORMAT_*. It mirrors
+//   the brotli headers Node.js was built with, and a linker that merges string
+//   tails (lld -O2, lld-link /OPT:ICF) can leave only it in place of the
+//   decoder's own names. Next to the decoder tables it stands for them; alone,
+//   as in a Node.js linked to a shared libbrotlidec, it is no decoder.
+//
+// The ports are told apart. The Go port (andybalholm/brotli, fixed in v1.2.7)
+// keeps the same names in Go's undelimited string table, so a Go binary can
+// hold both a cgo-linked C decoder and the Go port, and each gets its own
+// fix state. The Rust port (brotli-decompressor) keeps `ERROR_FORMAT_...`
+// strings and the same tables but is not affected; its crate name in symbols
+// or panic paths marks it, and its evidence is ignored.
+//
+// Nothing is executed. A file over the read cap is reported as skipped, never
+// as free of a decoder.
+//
+// The component helpers that put the answer into a BOM are in
+// lib/inventory/brotliDecoder.js; this half lives in the core layer so the HTTP
+// client can ask it about its own runtime.
+
+import { scanFileMarkers } from "./boundedFile.js";
+
+const NAME = Buffer.from("EXUBERANT_NIBBLE");
+const FIX_NAME = Buffer.from("BLOCK_SWITCH");
+// The Go linker writes this magic at the start of the buildinfo section.
+// https://github.com/golang/go/blob/go1.25.0/src/debug/buildinfo/buildinfo.go#L58
+const GO_BUILDINFO_MAGIC = Buffer.from("\xff Go buildinf:", "latin1");
+// static const uint8_t kCodeLengthCodeOrder[18] and
+// kCodeLengthPrefixValue[16], c/dec/decode.c.
+const CODE_LENGTH_CODE_ORDER = Buffer.from([
+  1, 2, 3, 4, 0, 5, 17, 6, 16, 7, 8, 9, 10, 11, 12, 13, 14, 15,
+]);
+const CODE_LENGTH_PREFIX_VALUE = Buffer.from([
+  0, 4, 3, 2, 0, 4, 3, 1, 0, 4, 3, 2, 0, 4, 3, 5,
+]);
+// Legacy and v0 Rust mangling length-prefix the crate name; panic messages
+// name the crate's source path.
+const RUST_CRATE_SYMBOL = Buffer.from("19brotli_decompressor");
+const RUST_CRATE_PATH = Buffer.from("brotli-decompressor-");
+
+const CONSTANT_PREFIX = Buffer.from("BROTLI_DECODER_ERROR_FORMAT_");
+const C_PREFIX = Buffer.from("_ERROR_FORMAT_");
+const RUST_PREFIX = Buffer.from("ERROR_FORMAT_");
+
+/**
+ * The most files of one kind (executables and libraries, or extension
+ * modules) one scan opens in search of a Brotli decoder.
+ *
+ * @type {number}
+ */
+export const MAX_BROTLI_PROBES = 4096;
+
+/**
+ * The most bytes one scan reads in search of Brotli decoders.
+ *
+ * @type {number}
+ */
+export const MAX_BROTLI_PROBE_BYTES = 16 * 1024 * 1024 * 1024;
+
+function endsWith(buffer, suffix) {
+  return (
+    buffer.length >= suffix.length &&
+    buffer.subarray(buffer.length - suffix.length).equals(suffix)
+  );
+}
+
+/**
+ * Classify one hit of an error name by what it is part of.
+ *
+ * @param {{before: Buffer, after: Buffer}} hit marker hit
+ * @returns {string} `constant`, `c`, `rust` or `other`
+ */
+function classify(hit) {
+  if (endsWith(hit.before, CONSTANT_PREFIX)) {
+    return "constant";
+  }
+  if (endsWith(hit.before, C_PREFIX)) {
+    return "c";
+  }
+  if (endsWith(hit.before, RUST_PREFIX)) {
+    return "rust";
+  }
+  const previous = hit.before.length ? hit.before[hit.before.length - 1] : 0;
+  if (previous === 0 && hit.after.length && hit.after[0] === 0) {
+    return "c";
+  }
+  return "other";
+}
+
+/**
+ * Read which Brotli decoders a native file embeds and whether each carries
+ * the CVE-2026-111497 fix.
+ *
+ * @param {string} absPath absolute path of the file
+ * @param {string|undefined} rootDir extracted root the file must stay under
+ * @returns {{c?: {blockSwitchFix: string, evidence: string}, go?: {blockSwitchFix: string}, skipped?: string, size: number}|undefined}
+ *   undefined when the file cannot be read or holds no decoder. `c` is
+ *   Google's C decoder, with blockSwitchFix `true`, `false` or `unknown` and
+ *   the evidence it rests on (`error-names`, `constant-names` or `tables`);
+ *   `go` is the Go port. `skipped` is `too-large` for a file over the read cap.
+ */
+export function readBrotliDecoder(absPath, rootDir) {
+  const scan = scanFileMarkers(
+    absPath,
+    rootDir,
+    [
+      NAME,
+      FIX_NAME,
+      GO_BUILDINFO_MAGIC,
+      CODE_LENGTH_CODE_ORDER,
+      CODE_LENGTH_PREFIX_VALUE,
+      RUST_CRATE_SYMBOL,
+      RUST_CRATE_PATH,
+    ],
+    { contextBytes: 1, beforeBytes: CONSTANT_PREFIX.length, maxHits: 256 },
+  );
+  if (!scan) {
+    return undefined;
+  }
+  if (scan.skipped) {
+    return { skipped: scan.skipped, size: scan.size };
+  }
+  const [
+    names,
+    fixNames,
+    goMagic,
+    codeOrder,
+    prefixValue,
+    rustSymbol,
+    rustPath,
+  ] = scan.hits;
+  const kinds = (hits) => new Set(hits.map(classify));
+  const nameKinds = kinds(names);
+  const fixKinds = kinds(fixNames);
+  const isGo = goMagic.length > 0;
+  const isRust = rustSymbol.length > 0 || rustPath.length > 0;
+  const hasTables = codeOrder.length > 0 && prefixValue.length > 0;
+  const result = { size: scan.size };
+  // Go strings are not delimited, so a name that is neither C-shaped nor a
+  // constant is the Go port's, in a Go binary.
+  const hasGoPort = isGo && nameKinds.has("other");
+  if (hasGoPort) {
+    result.go = { blockSwitchFix: fixKinds.has("other") ? "true" : "false" };
+  }
+  if (nameKinds.has("c")) {
+    result.c = {
+      blockSwitchFix: fixKinds.has("c") ? "true" : "false",
+      evidence: "error-names",
+    };
+  } else if (hasTables && !hasGoPort && !isRust) {
+    result.c = nameKinds.has("constant")
+      ? {
+          blockSwitchFix: fixKinds.has("constant") ? "true" : "false",
+          evidence: "constant-names",
+        }
+      : { blockSwitchFix: "unknown", evidence: "tables" };
+  }
+  return result.c || result.go ? result : undefined;
+}

package/lib/core/env.js

@@ -301,6 +301,13 @@ export const SWIFT_CMD = readEnvironmentVariable("SWIFT_CMD") || "swift";
 /** Resolved Ruby executable command (RUBY_CMD env var, or "ruby"). */
 export const RUBY_CMD = readEnvironmentVariable("RUBY_CMD") || "ruby";
 
+/** Resolved RubyGems executable command (CDXGEN_GEM_CMD env var, or "gem"). */
+export const GEM_CMD = readEnvironmentVariable("CDXGEN_GEM_CMD") || "gem";
+
+/** Resolved Bundler executable command (CDXGEN_BUNDLE_CMD env var, or "bundle"). */
+export const BUNDLE_CMD =
+  readEnvironmentVariable("CDXGEN_BUNDLE_CMD") || "bundle";
+
 /** Resolved PHP executable command (PHP_CMD env var, or "php"). */
 export const PHP_CMD = readEnvironmentVariable("PHP_CMD") || "php";
 
@@ -520,6 +527,7 @@ export const PROJECT_TYPE_ALIASES = {
     "vscode",
     "openvsx",
     "vscode-extensions",
+    "ide",
     "ide-extension",
     "ide-extensions",
   ],

package/lib/core/fs.js

@@ -43,6 +43,7 @@ import {
 } from "./activity.js";
 import { thoughtLog, traceLog } from "./logger.js";
 import { isWin } from "./paths.js";
+import { recordExecutedTool } from "./toolRegistry.js";
 
 function getArchiveSourceByteSize(sourcePath) {
   if (!sourcePath || !safeExistsSync(sourcePath)) {
@@ -991,6 +992,8 @@ export function safeSpawnSync(command, args, options) {
   }
   traceLog("spawn", { command, args, ...options });
   commandsExecuted.add(command);
+  // The tool as invoked, before a shell invocation folds the arguments in.
+  const executedCommand = command;
   // Fix for DEP0190 warning
   if (options?.shell === true) {
     const joined = joinShellCommand(command, args, rawShellArgs);
@@ -1000,6 +1003,15 @@ export function safeSpawnSync(command, args, options) {
     }
   }
   const result = spawnSync(command, args, options);
+  // The run-scoped tool registry feeds metadata.tools (issue #598); every
+  // external execution funnels through this wrapper. A spawn that failed to
+  // start, such as a missing binary, ran nothing and is not recorded; through
+  // a shell, a missing command shows as exit code 127, or 9009 on cmd.exe.
+  const shellCommandNotFound =
+    options?.shell === true && [127, 9009].includes(result.status);
+  if (!result.error && !shellCommandNotFound) {
+    recordExecutedTool(executedCommand);
+  }
   recordActivity({
     kind: activityDescriptor.kind,
     ...activityDescriptor.metadata,

package/lib/core/httpClient.js

@@ -5,6 +5,7 @@ import { brotliDecompressSync, gunzipSync, inflateSync } from "node:zlib";
 
 import { Agent, EnvHttpProxyAgent, request as undiciRequest } from "undici";
 
+import { readBrotliDecoder } from "./brotliProbe.js";
 import { registerRunReset } from "./runState.js";
 
 // Environment variables here are read with raw `process.env` rather than
@@ -208,6 +209,75 @@ export function resolveTimeout(timeout) {
   return undefined;
 }
 
+let runtimeBrotliVerdict;
+
+/**
+ * Set or clear the cached runtime Brotli verdict. Exported for unit tests only.
+ *
+ * @param {boolean|undefined} verdict verdict to use, or undefined to re-check
+ */
+export function _setRuntimeBrotliVerdict(verdict) {
+  runtimeBrotliVerdict = verdict;
+}
+
+/**
+ * Whether the Brotli decoder of the runtime cdxgen runs on carries the
+ * CVE-2026-111497 fix, read once from the decoder itself: the node binary, or
+ * the shared libbrotlidec a `--shared-brotli` build (Homebrew, distro
+ * packages) loads; under Bun, the bun binary, which carries its own copy.
+ * process.versions.brotli cannot answer this, since Node.js backports the fix
+ * without changing it. Deno decodes Brotli in Rust, which was never affected.
+ *
+ * On Node.js cdxgen never asks for `br`, so a Brotli response comes only from
+ * a server that sends it unasked. When the decoder cannot be shown to be
+ * patched, such a body is left undecoded rather than handed to a decoder an
+ * attacker can write past. Bun decodes in its transport, so there the client
+ * stops asking for `br` instead.
+ *
+ * @param {Object} [runtime] the runtime to judge, for tests
+ * @returns {boolean} true when Brotli bodies may be decoded
+ */
+export function runtimeBrotliDecoderIsPatched(runtime = undefined) {
+  if (!runtime && runtimeBrotliVerdict !== undefined) {
+    return runtimeBrotliVerdict;
+  }
+  const subject = runtime || {
+    isDeno: globalThis.Deno?.version?.deno !== undefined,
+    execPath: process.execPath,
+    sharedBrotli: [true, "true"].includes(
+      process.config?.variables?.node_shared_brotli,
+    ),
+    sharedObjects: () => process.report?.getReport?.()?.sharedObjects || [],
+  };
+  let verdict = false;
+  if (subject.isDeno) {
+    verdict = true;
+  } else {
+    const decoderFile = subject.sharedBrotli
+      ? subject
+          .sharedObjects()
+          .find((path) =>
+            `${path}`.split(/[\\/]/).pop().startsWith("libbrotlidec"),
+          )
+      : subject.execPath;
+    verdict = Boolean(
+      decoderFile &&
+        readBrotliDecoder(decoderFile)?.c?.blockSwitchFix === "true",
+    );
+  }
+  if (!runtime) {
+    runtimeBrotliVerdict = verdict;
+    if (!verdict) {
+      console.warn(
+        isBun
+          ? "The Brotli decoder in this Bun is not patched for CVE-2026-111497, or could not be checked, so cdxgen no longer asks servers for Brotli-encoded responses. Bun still decodes one a server sends unasked; upgrade Bun to a release with a patched Brotli."
+          : "The Brotli decoder of this runtime is not patched for CVE-2026-111497, or could not be checked, so Brotli-encoded responses are left undecoded. Upgrade Node.js to 22.23.4, 24.22.1 or 26.12.1 or later (and the shared brotli library on Homebrew or distro builds).",
+      );
+    }
+  }
+  return verdict;
+}
+
 /**
  * Decompress a response body buffer according to its `Content-Encoding`. undici
  * performs no automatic decompression, so we replicate the behaviour `got` gave
@@ -235,6 +305,9 @@ function decompressBody(rawBody, contentEncoding) {
       } else if (encoding === "deflate") {
         buffer = inflateSync(buffer);
       } else if (encoding === "br") {
+        if (!runtimeBrotliDecoderIsPatched()) {
+          return buffer;
+        }
         buffer = brotliDecompressSync(buffer);
       } else if (encoding === "identity") {
         // no-op
@@ -296,6 +369,30 @@ async function readBody(undiciResponse, responseType) {
   return { body, rawBody };
 }
 
+/**
+ * The headers to put on the wire. Bun's bundled undici asks for br by default
+ * and decodes it with Bun's own decoder before this client sees the body, so
+ * the check in decompressBody never runs there. Where that decoder is not
+ * patched, ask only for the encodings this client decodes itself. A server
+ * that sends br unasked is still decoded by Bun; only upgrading Bun closes
+ * that. The cache key is built from the caller's headers, not these.
+ *
+ * @param {Object} headers Request headers.
+ * @returns {Object} Headers to send.
+ */
+function transportHeaders(headers) {
+  if (
+    !isBun ||
+    Object.keys(headers).some(
+      (key) => key.toLowerCase() === "accept-encoding",
+    ) ||
+    runtimeBrotliDecoderIsPatched()
+  ) {
+    return headers;
+  }
+  return { ...headers, "accept-encoding": "gzip, deflate" };
+}
+
 /**
  * Convert a body into the `[body, headers]` pair to hand to undici. When the
  * `json` option is present it is serialized and a JSON `content-type` is added
@@ -752,7 +849,7 @@ async function doRequest(mergedOptions) {
   const insecure = options.https?.rejectUnauthorized === false;
   const requestOptions = {
     method,
-    headers,
+    headers: transportHeaders(headers),
     body: method === "GET" || method === "HEAD" ? undefined : body,
     dispatcher: selectDispatcher(insecure),
     signal,

package/lib/core/lockPaths.js

@@ -0,0 +1,38 @@
+import { isAbsolute, relative, resolve, win32 } from "node:path";
+
+/**
+ * Containment check for a path taken from a lockfile (issue #3816). A crafted
+ * npm lockfile can name `file:`/`link:` specifiers or link targets built from
+ * `..` chains or absolute paths, so a parser that is about to list such an
+ * entry checks the resolved path against the project root first.
+ *
+ * The candidate is resolved against `projectRoot`, so both relative values
+ * and the absolute paths arborist already normalised are accepted. The root
+ * itself counts as inside: a lockfile may legitimately link the project to
+ * its own directory.
+ *
+ * @param {string} candidate Path to check, absolute or relative to projectRoot
+ * @param {string} projectRoot Project root the path must stay inside; a falsy
+ *   root means the current working directory, mirroring `node:path`
+ *
+ * @returns {Boolean} True when the path is inside projectRoot
+ */
+export function isPathInsideProject(candidate, projectRoot) {
+  if (typeof candidate !== "string" || !candidate) {
+    return false;
+  }
+  if (candidate.includes("\0")) {
+    return false;
+  }
+  const rootAbs = resolve(projectRoot || process.cwd());
+  const rel = relative(rootAbs, resolve(rootAbs, candidate));
+  if (!rel) {
+    return true;
+  }
+  // relative() returns an absolute path when the two sit on different
+  // Windows drives.
+  if (isAbsolute(rel) || win32.isAbsolute(rel)) {
+    return false;
+  }
+  return rel !== ".." && !rel.startsWith("../") && !rel.startsWith("..\\");
+}

package/lib/core/paths.js

@@ -14,7 +14,7 @@
  * `https://` URL, and `fileURLToPath` throws `ERR_INVALID_URL_SCHEME` on those.
  */
 
-import { platform } from "node:os";
+import { homedir, platform } from "node:os";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -68,3 +68,26 @@ export function isValidDriveRoot(root) {
 export function toCamel(str) {
   return str.replace(/-([a-z])/g, (_, g) => g.toUpperCase());
 }
+
+/**
+ * Rewrite an absolute path under the user's home directory to a `~`-relative
+ * form so the emitted BOM does not carry the local username.
+ *
+ * @param {string} filePath Absolute path
+ * @param {string} [home] Home directory, defaulting to the current user's
+ * @returns {string} Home-relative path when applicable, else the input
+ */
+export function redactHomePath(filePath, home = homedir()) {
+  const value = String(filePath || "");
+  if (!home || !value.startsWith(home)) {
+    return value;
+  }
+  // Require a path boundary so a sibling home such as /Users/alice-backup is
+  // not rewritten as if it sat under /Users/alice.
+  const remainder = value.slice(home.length);
+  if (remainder && !/^[/\\]/u.test(remainder)) {
+    return value;
+  }
+  const rest = remainder.replace(/^[/\\]/u, "");
+  return rest ? `~/${rest.replaceAll("\\", "/")}` : "~";
+}

package/lib/core/processTree.js

@@ -37,6 +37,8 @@ export function formatDuration(ms) {
  * its end: once the root is gone its pid can be handed to an unrelated
  * process, whose children would otherwise look like the run's. Elsewhere this
  * does nothing: an orphan is re-parented and can no longer be told apart.
+ * It returns once the stopped processes have exited, or after ten seconds,
+ * so the caller can remove files the run left half-written.
  *
  * @param {number|undefined} rootPid pid of the process cdxgen spawned
  * @param {number} startedAt Epoch milliseconds at which the run started
@@ -77,6 +79,9 @@ export function reapProcessTree(
     "  }",
     "}",
     "foreach ($child in $found) { Stop-Process -Id $child -Force -ErrorAction SilentlyContinue }",
+    // Stop-Process returns before the process exits, and a process that is
+    // still exiting keeps its files open, so wait for the exits.
+    "if ($found.Count) { Wait-Process -Id $found.ToArray() -Timeout 10 -ErrorAction SilentlyContinue }",
     "$found -join ','",
   ].join("\n");
   const result = safeSpawnSync(

package/lib/core/toolRegistry.js

@@ -0,0 +1,170 @@
+import { basename } from "node:path";
+
+import { registerRunReset } from "./runState.js";
+
+/**
+ * Run-scoped registry of the external tools cdxgen actually executed, feeding
+ * the `metadata.tools` section (issue #598). `safeSpawnSync` records a command
+ * once the process has started, so a binary that is missing or a spawn that
+ * was blocked never appears, and the stages that already know a tool's
+ * version - such as the JVM tool resolution in pregen - enrich the entry; no
+ * process is ever spawned just to learn a version.
+ *
+ * The registry is filled in as the run progresses and read once per BOM when
+ * the metadata section is assembled. A run that spawns nothing external keeps
+ * it empty, which is what keeps such BOMs byte-identical to the previous
+ * behaviour. It is per-run state: a long-lived process such as the server
+ * empties it between scans through {@link resetRunState}.
+ *
+ * @type {Map<string, {name: string, version: (string|undefined)}>}
+ */
+const EXECUTED_TOOLS = new Map();
+
+/**
+ * Versions stages already resolved for a tool, keyed like EXECUTED_TOOLS. They
+ * are applied only to tools that actually started, so provisioning a tool the
+ * run then never invokes adds nothing to `metadata.tools`.
+ *
+ * @type {Map<string, string>}
+ */
+const KNOWN_VERSIONS = new Map();
+
+/**
+ * Interpreter and shell binaries that wrap the real work. They appear on
+ * nearly every spawn, so recording them would drown the tools that actually
+ * generated the BOM.
+ *
+ * @type {Set<string>}
+ */
+const WRAPPER_BASENAMES = new Set([
+  "bash",
+  "cmd",
+  "cmd.exe",
+  "node",
+  "powershell",
+  "powershell.exe",
+  "pwsh",
+  "sh",
+  "zsh",
+]);
+
+/**
+ * Strip a trailing Windows executable suffix from a binary name.
+ *
+ * @param {string} name Binary name
+ * @returns {string} Name without a trailing `.exe`, `.bat`, or `.cmd`
+ */
+function trimWindowsSuffix(name) {
+  for (const suffix of [".exe", ".bat", ".cmd"]) {
+    if (name.endsWith(suffix)) {
+      return name.slice(0, -suffix.length);
+    }
+  }
+  return name;
+}
+
+/**
+ * Name a tool the way the registry keys it: the basename without a Windows
+ * executable suffix, and without the `-cdxgen-<os>-<arch>` suffix of a
+ * bundled cdxgen-plugins-bin helper, so `trivy-cdxgen-linux-amd64` is `trivy`
+ * on every platform and matches its plugin manifest entry.
+ *
+ * @param {string} name Tool name as invoked (a bare name or a path)
+ * @returns {string} Tool name
+ */
+function toolNameOf(name) {
+  const toolName = trimWindowsSuffix(basename(`${name}`.split("\\").join("/")));
+  const pluginSuffixAt = toolName.lastIndexOf("-cdxgen-");
+  if (
+    pluginSuffixAt > 0 &&
+    toolName.slice(pluginSuffixAt + "-cdxgen-".length).split("-").length === 2
+  ) {
+    return toolName.slice(0, pluginSuffixAt);
+  }
+  return toolName;
+}
+
+/**
+ * Record an external tool cdxgen executed. The first version seen wins unless
+ * it was unknown, so an enriched probe never overwrites a concrete version
+ * with `undefined` and a later concrete version fills an earlier gap.
+ *
+ * @param {string} name Tool name as invoked (a bare name or a path)
+ * @param {string|undefined} version Version when cheaply known
+ */
+export function recordExecutedTool(name, version) {
+  if (typeof name !== "string" || !name) {
+    return;
+  }
+  const toolName = toolNameOf(name);
+  if (!toolName || WRAPPER_BASENAMES.has(toolName)) {
+    return;
+  }
+  const key = toolName.toLowerCase();
+  const existing = EXECUTED_TOOLS.get(key);
+  if (!existing) {
+    EXECUTED_TOOLS.set(key, {
+      name: toolName,
+      version: typeof version === "string" && version ? version : undefined,
+    });
+    return;
+  }
+  if (typeof version === "string" && version && !existing.version) {
+    existing.version = version;
+  }
+}
+
+/**
+ * Remember the version a stage already resolved for a tool, such as the JVM
+ * build tool pregen provisioned. The version shows in `metadata.tools` only if
+ * the tool is executed; the first version recorded wins.
+ *
+ * @param {string} name Tool name as it will be invoked (a bare name or a path)
+ * @param {string} version Resolved version
+ */
+export function recordToolVersion(name, version) {
+  if (typeof name !== "string" || !name) {
+    return;
+  }
+  if (typeof version !== "string" || !version) {
+    return;
+  }
+  const key = toolNameOf(name).toLowerCase();
+  if (key && !KNOWN_VERSIONS.has(key)) {
+    KNOWN_VERSIONS.set(key, version);
+  }
+}
+
+/**
+ * Snapshot of the tools recorded so far, sorted by name so the assembled
+ * `metadata.tools` diff stays stable between runs.
+ *
+ * @returns {Array<{name: string, version: (string|undefined)}>} Sorted tool records
+ */
+export function getExecutedTools() {
+  return [...EXECUTED_TOOLS.entries()]
+    .map(([key, tool]) => ({
+      name: tool.name,
+      version: tool.version || KNOWN_VERSIONS.get(key),
+    }))
+    .sort((a, b) =>
+      a.name === b.name
+        ? 0
+        : a.name.toLowerCase() < b.name.toLowerCase()
+          ? -1
+          : 1,
+    );
+}
+
+/**
+ * Clear the registry. The server calls it between scans through the run-state
+ * reset; tests call it directly.
+ *
+ * @returns {void}
+ */
+export function resetExecutedTools() {
+  EXECUTED_TOOLS.clear();
+  KNOWN_VERSIONS.clear();
+}
+
+registerRunReset("toolRegistry.executedTools", resetExecutedTools);