@cdxgen/cdxgen 13.0.0 → 13.1.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,
@@ -31,8 +39,14 @@ import {
   safeExistsSync,
   safeSpawnSync,
 } 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.
@@ -204,12 +218,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,
     },
   );
 }
@@ -291,6 +310,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
  *
@@ -302,7 +375,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 ", ""),
@@ -314,7 +387,10 @@ export function collectJavaInfo(dir) {
         },
       ],
     };
+    recordToolProbeResolved("java", "java", info.version);
+    return info;
   }
+  recordToolProbeFailure("java", "java", getJavaCommand());
   return undefined;
 }
 
@@ -329,13 +405,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;
 }
 
@@ -346,25 +425,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;
 }
 
@@ -385,6 +460,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;
 }
@@ -399,13 +477,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;
 }
 
@@ -419,13 +500,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;
 }
 
@@ -438,12 +522,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;
 }
 
@@ -456,12 +543,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;
 }
 
@@ -474,12 +564,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;
 }
 
@@ -666,6 +759,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 = "";
@@ -919,9 +1023,12 @@ export function bundleInstallWithDocker(rubyVersion, cdxgenGemHome, filePath) {
     "install",
   ];
   console.log(`Performing bundle install with: ${ociCmd}`);
+  // The container's own output is a diagnostic. Inheriting stdout would let it
+  // interleave with the BOM document when the caller asked for `-o -`, so the
+  // child's stdout is pointed at the diagnostic stream instead.
   const result = safeSpawnSync(ociCmd, ociArgs, {
     shell: isWin,
-    stdio: "inherit",
+    stdio: ["inherit", diagnosticStream, "inherit"],
   });
   if (result.error || result.status !== 0) {
     return false;
@@ -964,6 +1071,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 };
@@ -971,6 +1086,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".`,
     );
@@ -979,6 +1102,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.`,
     );
@@ -992,6 +1123,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],
@@ -1000,6 +1137,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);
     }
@@ -1125,6 +1270,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,
@@ -1134,6 +1286,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 (
@@ -1180,6 +1341,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,
@@ -1189,6 +1357,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);
@@ -1736,6 +1914,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/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 {
@@ -545,6 +548,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 +609,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