@cdxgen/cdxgen 13.2.0 → 13.4.0

package/lib/core/pluginRun.js

@@ -0,0 +1,184 @@
+/**
+ * Shared plumbing for plugin (rusi/golem/kosi) invocations: resolving the
+ * directory to analyze, and reporting a failed run.
+ */
+
+import { isAbsolute, join, normalize, resolve, sep } from "node:path";
+import process from "node:process";
+
+import { DEBUG_MODE } from "./activity.js";
+import { deferFailOnError } from "./deferredExit.js";
+import { safeExistsSync } from "./fs.js";
+
+/**
+ * The working directory, when a relative source argument names it.
+ *
+ * cdxgen is frequently launched with its working directory already set to the
+ * project (depscan does exactly that) while the path argument stays relative
+ * to some repository root, e.g. cwd `/work/repo/test/data/app` with argument
+ * `test/data/app`. A plain `path.resolve` then produces the doubled
+ * `/work/repo/test/data/app/test/data/app`. This recognises that shape and
+ * nothing looser: the argument's path segments must be the trailing segments
+ * of the working directory, so a mistyped argument run from some other
+ * project is never silently redirected to that project.
+ *
+ * @param {string} src The source path as the caller typed it.
+ * @param {string} [cwd] Working directory; defaults to `process.cwd()`.
+ * @returns {string|undefined} The absolute working directory when the
+ *   argument names it, otherwise undefined.
+ */
+export function cwdNamedByRelativeSource(src, cwd = process.cwd()) {
+  if (typeof src !== "string" || !src || isAbsolute(src)) {
+    return undefined;
+  }
+  // normalize() converts separators to the platform's, so one split on sep
+  // handles both "a/b" and "a\\b" on Windows; on POSIX a backslash is an
+  // ordinary file-name character and must not split.
+  const relParts = normalize(src)
+    .split(sep)
+    .filter((part) => part && part !== ".");
+  if (!relParts.length || relParts.includes("..")) {
+    return undefined;
+  }
+  const absCwd = resolve(cwd);
+  const cwdParts = absCwd.split(sep).filter(Boolean);
+  if (relParts.length > cwdParts.length) {
+    return undefined;
+  }
+  const tail = cwdParts.slice(cwdParts.length - relParts.length);
+  const caseInsensitive = process.platform === "win32";
+  const same = (a, b) =>
+    caseInsensitive ? a.toLowerCase() === b.toLowerCase() : a === b;
+  return relParts.every((part, i) => same(part, tail[i])) ? absCwd : undefined;
+}
+
+/**
+ * Resolve the source path argument once, at cdxgen's entry point.
+ *
+ * Everything downstream — the BOM generators, evinse, and the rusi/golem/kosi
+ * launchers — resolves the argument against the working directory, so the
+ * doubled-directory shape has to be corrected before any of them run;
+ * correcting it only in the plugin launchers leaves the main BOM built from a
+ * directory that does not exist.
+ *
+ * @param {string} src The source path as the caller typed it.
+ * @param {string} [cwd] Working directory; defaults to `process.cwd()`.
+ * @returns {{path: string, rewritten: boolean, missing: boolean}} `path` is
+ *   the argument to use: unchanged when it resolves to an existing path, the
+ *   working directory when the argument names it (`rewritten`), and otherwise
+ *   unchanged with `missing` set.
+ */
+export function resolveSourcePathArgument(src, cwd = process.cwd()) {
+  if (typeof src !== "string" || !src) {
+    return { path: src, rewritten: false, missing: false };
+  }
+  if (safeExistsSync(resolve(cwd, src))) {
+    return { path: src, rewritten: false, missing: false };
+  }
+  const named = cwdNamedByRelativeSource(src, cwd);
+  if (named) {
+    return { path: named, rewritten: true, missing: false };
+  }
+  return { path: src, rewritten: false, missing: true };
+}
+
+/**
+ * Resolve the directory a plugin should analyze.
+ *
+ * The entry point already corrects the doubled-directory shape (see
+ * resolveSourcePathArgument); this is the same rule for callers that reach a
+ * plugin launcher directly (evinse, the library API). An existing directory
+ * wins and an absolute path is never rewritten. Otherwise the working
+ * directory is used only when the argument names it AND it carries the
+ * project marker the plugin needs (a `Cargo.toml` for rusi, a `go.mod` for
+ * golem). Anything else keeps the resolved path so the plugin's own error
+ * names the directory that was actually attempted.
+ *
+ * @param {string} src The source path as the caller typed it.
+ * @param {string[]} markerFiles File names that, present in the working
+ *   directory, identify it as the project the plugin should analyze.
+ * @returns {string} The directory to pass to the plugin.
+ */
+export function resolvePluginSourceDir(src, markerFiles = []) {
+  const resolved = resolve(src);
+  if (safeExistsSync(resolved) || isAbsolute(src)) {
+    return resolved;
+  }
+  const cwd = cwdNamedByRelativeSource(src);
+  if (!cwd) {
+    return resolved;
+  }
+  for (const marker of markerFiles) {
+    if (marker && safeExistsSync(join(cwd, marker))) {
+      console.error(
+        `Resolved source directory ${resolved} does not exist; the working directory ${cwd} is the project the argument names (found ${marker}), using it instead.`,
+      );
+      return cwd;
+    }
+  }
+  return resolved;
+}
+
+/**
+ * Report a failed plugin run, keeping the two failure classes apart.
+ *
+ * A spawn error means the plugin binary itself could not run — not installed,
+ * not executable, blocked by the command policy — which is an installation
+ * problem. A non-zero exit status or a missing report means the plugin ran
+ * and the analysis failed, which must not be dressed up as an installation
+ * problem: the message names the directory and says the reachability
+ * evidence will be missing, because a silent degradation is what let a
+ * doubled `--dir` go unnoticed in the first place.
+ *
+ * Under `--fail-on-error` the failure additionally claims the process exit
+ * status through the deferred-exit contract.
+ *
+ * @param {Object} run What ran and how it failed.
+ * @param {string} run.tool Plugin name, e.g. "rusi".
+ * @param {string} run.ecosystem Ecosystem the plugin serves, e.g. "rust".
+ * @param {string} run.executable The binary that was invoked.
+ * @param {string[]} run.args The arguments it was invoked with.
+ * @param {string} run.dir The directory that was analyzed.
+ * @param {Object} run.result The spawn result.
+ * @param {string} run.outputFile The report file the plugin should have written.
+ * @param {Object} [run.options] CLI options, for the `--fail-on-error` contract.
+ * @returns {void}
+ */
+export function reportPluginRunFailure({
+  tool,
+  ecosystem,
+  executable,
+  args,
+  dir,
+  result,
+  outputFile,
+  options,
+}) {
+  const command = `${executable} ${(args || []).join(" ")}`.trim();
+  if (result?.error) {
+    console.error(
+      `${tool} plugin could not be executed for ${dir}: ${result.error.message}. Check if the ${tool} plugin was installed successfully.`,
+    );
+  } else {
+    const status =
+      typeof result?.status === "number" ? result.status : "unknown";
+    const reason = safeExistsSync(outputFile)
+      ? "exited unsuccessfully"
+      : "wrote no report";
+    console.error(
+      `${tool} analysis ${reason} for directory ${dir} (exit status ${status}); ${ecosystem} reachability evidence will be missing from the BOM.`,
+    );
+  }
+  if (DEBUG_MODE && (result?.stdout || result?.stderr)) {
+    console.error(result.stdout, result.stderr);
+  }
+  deferFailOnError(options, {
+    ecosystem,
+    tool,
+    detail: result?.error
+      ? `${tool} plugin could not be executed: ${result.error.message}`
+      : `${tool} analysis failed for directory ${dir}`,
+    exitCode: typeof result?.status === "number" ? result.status : undefined,
+    command,
+  });
+}

package/lib/core/processTree.js

@@ -0,0 +1,100 @@
+/**
+ * Helpers for external commands stopped by cdxgen's spawn timeout.
+ *
+ * Layer 0: this module imports nothing outside `lib/core`, so both the atom
+ * and the dosai runners (layer 2) can share it.
+ */
+
+import { DEBUG_MODE } from "./activity.js";
+import { safeSpawnSync } from "./fs.js";
+import { isWin } from "./paths.js";
+
+/**
+ * A duration for a message: seconds to one decimal below a minute, minutes to
+ * one decimal from there.
+ *
+ * @param {number} ms Duration in milliseconds
+ * @returns {string} Human-readable duration
+ */
+export function formatDuration(ms) {
+  if (ms >= 60_000) {
+    const minutes = Math.round(ms / 6_000) / 10;
+    return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+  }
+  return `${Math.round(ms / 100) / 10} seconds`;
+}
+
+/**
+ * Stop the descendants a timed-out run left behind on Windows.
+ *
+ * The spawn timeout terminates only the process cdxgen spawned, and Windows
+ * neither kills nor re-parents its children: a shell's command, a runtime's
+ * workers, or the build hosts a .NET analyzer starts keep running while still
+ * pointing at the dead process's pid. `taskkill /T` on that pid finds nothing,
+ * because the root is already gone. The live descendants are therefore found
+ * by parent pid in a process snapshot and stopped, limited to processes
+ * created after the run started. The root's own children must also predate
+ * 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.
+ *
+ * @param {number|undefined} rootPid pid of the process cdxgen spawned
+ * @param {number} startedAt Epoch milliseconds at which the run started
+ * @param {number} [endedAt] Epoch milliseconds at which the spawned process ended
+ * @param {string} [toolName] Name of the tool, for the debug message
+ * @returns {number[]} The pids that were stopped
+ */
+export function reapProcessTree(
+  rootPid,
+  startedAt,
+  endedAt = Date.now(),
+  toolName = "external",
+) {
+  if (!isWin || !Number.isInteger(rootPid) || rootPid <= 0) {
+    return [];
+  }
+  // All three values are integers, so interpolating them cannot inject anything.
+  const since = Math.max(0, Math.floor(startedAt) - 1000);
+  const until = Math.max(since, Math.floor(endedAt) + 1000);
+  const script = [
+    `$root = ${rootPid}`,
+    `$since = [DateTimeOffset]::FromUnixTimeMilliseconds(${since}).UtcDateTime`,
+    `$until = [DateTimeOffset]::FromUnixTimeMilliseconds(${until}).UtcDateTime`,
+    "$children = @{}",
+    "foreach ($p in Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,CreationDate) {",
+    "  if (-not $p.CreationDate) { continue }",
+    "  $created = $p.CreationDate.ToUniversalTime()",
+    "  if ($created -lt $since) { continue }",
+    "  if ([int]$p.ParentProcessId -eq $root -and $created -gt $until) { continue }",
+    "  $children[[int]$p.ParentProcessId] += @([int]$p.ProcessId)",
+    "}",
+    "$found = [System.Collections.Generic.List[int]]::new()",
+    "$queue = [System.Collections.Generic.Queue[int]]::new()",
+    "$queue.Enqueue($root)",
+    "while ($queue.Count) {",
+    "  foreach ($child in @($children[$queue.Dequeue()])) {",
+    "    if ($child -and -not $found.Contains($child)) { $found.Add($child); $queue.Enqueue($child) }",
+    "  }",
+    "}",
+    "foreach ($child in $found) { Stop-Process -Id $child -Force -ErrorAction SilentlyContinue }",
+    "$found -join ','",
+  ].join("\n");
+  const result = safeSpawnSync(
+    "powershell",
+    ["-NoProfile", "-NonInteractive", "-Command", script],
+    { timeout: 60000 },
+  );
+  const reaped = `${result?.stdout || ""}`
+    .trim()
+    .split(",")
+    .map((pid) => Number.parseInt(pid, 10))
+    .filter((pid) => pid > 0);
+  if (DEBUG_MODE) {
+    console.log(
+      reaped.length
+        ? `Stopped ${reaped.length} process(es) the timed-out ${toolName} run left behind: ${reaped.join(", ")}.`
+        : `The timed-out ${toolName} run left no processes behind.`,
+    );
+  }
+  return reaped;
+}

package/lib/core/projectConfig.js

@@ -1,5 +1,10 @@
 import path from "node:path";
 
+import {
+  isReservedMetadataPropertyName,
+  METADATA_PROPERTY_CONFIG_KEYS,
+  parseMetadataProperties,
+} from "./metadataProperties.js";
 import { toCamel } from "./paths.js";
 
 /**
@@ -87,19 +92,41 @@ function isContainedPath(configDir, value) {
  * whenever that tree is. Path options are therefore confined to the config's
  * own directory - a scanned project may choose where in itself the BOM lands,
  * but not write outside it - and options that redirect data off the host or
- * widen what cdxgen executes are announced on the console.
+ * widen what cdxgen executes are announced on the console. A project may
+ * describe itself with custom metadata properties, but not in the namespaces
+ * cdxgen reserves for the facts it establishes, so a scanned tree cannot pass
+ * its own claims off as cdxgen's.
  *
  * @param {Object} config parsed config file contents
  * @param {string} configDir directory the config file was read from
- * @returns {{config: Object, rejected: string[], announced: string[]}} sanitized config and what it did
+ * @returns {{config: Object, rejected: string[], announced: string[], reservedProperties: string[]}} sanitized config and what it did
  */
 export function sanitizeProjectConfig(config, configDir) {
   if (!config || typeof config !== "object") {
-    return { announced: [], config: {}, rejected: [] };
+    return { announced: [], config: {}, rejected: [], reservedProperties: [] };
   }
   const sanitized = { ...config };
   const rejected = [];
   const announced = [];
+  const reservedProperties = [];
+  for (const key of METADATA_PROPERTY_CONFIG_KEYS) {
+    if (sanitized[key] === undefined) {
+      continue;
+    }
+    const properties = [];
+    for (const aprop of parseMetadataProperties(sanitized[key])) {
+      if (isReservedMetadataPropertyName(aprop.name)) {
+        reservedProperties.push(aprop.name);
+      } else {
+        properties.push(aprop);
+      }
+    }
+    if (properties.length) {
+      sanitized[key] = properties;
+    } else {
+      delete sanitized[key];
+    }
+  }
   for (const option of PATH_OPTIONS) {
     for (const key of optionSpellings(option)) {
       if (sanitized[key] === undefined) {
@@ -118,5 +145,5 @@ export function sanitizeProjectConfig(config, configDir) {
       }
     }
   }
-  return { announced, config: sanitized, rejected };
+  return { announced, config: sanitized, rejected, reservedProperties };
 }

package/lib/core/runState.js

@@ -0,0 +1,39 @@
+/**
+ * State that lasts for one run.
+ *
+ * Registry answers, prefetched documents, recorded misses and local cache
+ * lookups are kept in module state, so that a package several lockfiles name
+ * costs one lookup. A run is one BOM generation. The CLI exits when it ends, but
+ * a long-lived process such as the server performs many, and nothing a run
+ * remembered should outlive it: the registries publish new releases, builds
+ * download new artifacts, and the memory belongs to the next scan.
+ *
+ * Every module that keeps such state registers a reset when it loads. The
+ * server calls {@link resetRunState} between scans. A module that has not
+ * loaded yet holds nothing to reset.
+ */
+
+/** @type {Map<string, () => void>} */
+const runResets = new Map();
+
+/**
+ * Register the function that empties a module's per-run state.
+ *
+ * @param {string} name Unique name, normally the module and what it holds
+ * @param {() => void} reset Empties that state
+ * @returns {void}
+ */
+export function registerRunReset(name, reset) {
+  runResets.set(name, reset);
+}
+
+/**
+ * Empty the per-run state of every module that registered one.
+ *
+ * @returns {void}
+ */
+export function resetRunState() {
+  for (const reset of runResets.values()) {
+    reset();
+  }
+}

package/lib/core/toml.js

@@ -0,0 +1,72 @@
+/**
+ * TOML parsing with stable, ordinary objects.
+ *
+ * smol-toml 1.9 began returning tables and inline tables with a `null`
+ * prototype so that a hostile `__proto__` key in a manifest cannot pollute
+ * `Object.prototype`. The SBOM data itself is unaffected, but cdxgen hands
+ * parsed manifests straight to callers (and `assert.deepStrictEqual` in the
+ * test suite), which compare by prototype and would see every table as a
+ * different kind of value. Re-wrapping the parse result with the standard
+ * prototype keeps the pre-1.9 contract: plain objects all the way down,
+ * `__proto__` keys included as ordinary own properties.
+ */
+
+import { parse as smolParse } from "smol-toml";
+
+/**
+ * Recursively rebuild a parsed value with `Object.prototype` roots.
+ *
+ * Class instances other than plain tables (smol-toml dates, strings, numbers)
+ * are passed through untouched, and arrays are copied only when an element
+ * actually changes, so unmodified branches keep their original identity.
+ *
+ * @param {unknown} value value produced by smol-toml's parse
+ * @returns {unknown} the same data with plain-prototype objects
+ */
+function toPlainPrototype(value) {
+  if (!value || typeof value !== "object") {
+    return value;
+  }
+  if (Array.isArray(value)) {
+    let changed = false;
+    const out = new Array(value.length);
+    for (let i = 0; i < value.length; i++) {
+      out[i] = toPlainPrototype(value[i]);
+      if (out[i] !== value[i]) {
+        changed = true;
+      }
+    }
+    return changed ? out : value;
+  }
+  const proto = Object.getPrototypeOf(value);
+  if (proto !== null && proto !== Object.prototype) {
+    return value;
+  }
+  const out = {};
+  for (const [key, entry] of Object.entries(value)) {
+    if (key === "__proto__") {
+      // Plain assignment would re-point the new object's prototype instead
+      // of recording the key, reintroducing the pollution smol-toml guards
+      // against.
+      Object.defineProperty(out, key, {
+        value: toPlainPrototype(entry),
+        enumerable: true,
+        writable: true,
+        configurable: true,
+      });
+    } else {
+      out[key] = toPlainPrototype(entry);
+    }
+  }
+  return out;
+}
+
+/**
+ * Parse a TOML document into plain objects.
+ *
+ * @param {string} text TOML source
+ * @returns {Object} parsed document whose tables use `Object.prototype`
+ */
+export function parseToml(text) {
+  return toPlainPrototype(smolParse(text));
+}

package/lib/ecosystems/asarutils.js

@@ -30,6 +30,7 @@ import {
 } from "../inventory/analyzer.js";
 import { tryBuildPurl } from "../inventory/purl.js";
 import { xml2js } from "../parsers/xml.js";
+import { resolveNpmLicense } from "./npmutils.js";
 
 const ASAR_JS_ANALYSIS_EXTENSIONS = new Set([
   ".cjs",
@@ -1040,8 +1041,9 @@ function createArchiveParentComponent(
         ? primaryPackageJson.author
         : primaryPackageJson.author?.name || "";
   }
-  if (primaryPackageJson?.license) {
-    component.license = primaryPackageJson.license;
+  const license = resolveNpmLicense(primaryPackageJson);
+  if (license) {
+    component.license = license;
   }
   if (primaryPackageJson?.repository) {
     const repositoryUrl =