@cdxgen/cdxgen 13.3.0 → 13.5.0

package/lib/inventory/dosai.js

@@ -10,7 +10,7 @@ import {
 import { basename, delimiter, isAbsolute, join, resolve } from "node:path";
 import process from "node:process";
 
-import { DEBUG_MODE } from "../core/activity.js";
+import { DEBUG_MODE, readEnvironmentVariable } from "../core/activity.js";
 import { recordDegradation } from "../core/buildLedger.js";
 import {
   getTmpDir,
@@ -20,10 +20,14 @@ import {
   safeSpawnSync,
   safeWriteChunksSync,
   safeWriteSync,
+  TIMEOUT_MS,
 } from "../core/fs.js";
+import { formatDuration, reapProcessTree } from "../core/processTree.js";
+import { encodeUriReference } from "../core/propertySanitizer.js";
 import {
   indexJsonObject,
   MAX_JSON_TEXT_BYTES,
+  readJsonMember,
   readJsonRange,
 } from "../parsers/largeJson.js";
 import {
@@ -152,11 +156,7 @@ function sanitizeEndpoint(endpoint) {
   // CycloneDX types `services[].endpoints[]` as an iri-reference, where square
   // brackets are reserved for IPv6 literals and braces are excluded outright,
   // so the template is percent-encoded before it reaches the BOM.
-  const encodedPath = routePath.replace(
-    /[[\]{}]/g,
-    (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
-  );
-  return encodedPath;
+  return encodeUriReference(routePath);
 }
 
 function serviceNameFromEndpoint(endpoint) {
@@ -167,15 +167,67 @@ function serviceNameFromEndpoint(endpoint) {
     .replace(/-+/g, "-");
 }
 
-function dosaiSdkMessage(result) {
-  return (
-    result?.stdout?.includes(
-      "You must install or update .NET to run this application",
-    ) ||
-    result?.stderr?.includes(
-      "You must install or update .NET to run this application",
-    )
-  );
+// The .NET host prints "You must install .NET" when it finds no .NET at all,
+// and "You must install or update .NET" when no installed runtime is new
+// enough for the app.
+const DOTNET_HOST_LAUNCH_FAILURE =
+  /You must install (?:or update )?\.NET to run this application/;
+
+/**
+ * The .NET runtime a framework-dependent dosai needs, read from the error the
+ * .NET host prints when it refuses to start dosai.
+ *
+ * When an older runtime is installed, the host names the exact framework
+ * version it looked for. When it finds no .NET at all, it names only its own
+ * version. The app host comes from the pack of the runtime the app targets, so
+ * its major version is still the .NET release to install.
+ *
+ * @param {Object|string} resultOrOutput spawnSync result, or the text it printed
+ * @returns {{version: (string|undefined), major: (string|undefined)}|undefined}
+ *   The framework version, when the host named it, and the .NET major version;
+ *   undefined when the output is not a .NET host launch failure
+ */
+export function dosaiDotnetRequirement(resultOrOutput) {
+  const output =
+    typeof resultOrOutput === "string"
+      ? resultOrOutput
+      : `${resultOrOutput?.stdout || ""}\n${resultOrOutput?.stderr || ""}`;
+  if (!DOTNET_HOST_LAUNCH_FAILURE.test(output)) {
+    return undefined;
+  }
+  const version = output.match(
+    /Framework: 'Microsoft\.NETCore\.App', version '([^']+)'/,
+  )?.[1];
+  const major =
+    version?.match(/^(\d+)\./)?.[1] ||
+    output.match(/App host version: (\d+)\./)?.[1];
+  return { version, major };
+}
+
+/**
+ * What stopped dosai from starting, for warnings and ledger details.
+ *
+ * @param {{version: (string|undefined), major: (string|undefined)}} [requirement] Result of dosaiDotnetRequirement
+ * @returns {string} A clause naming the missing .NET runtime when it is known
+ */
+export function dosaiDotnetRequirementDetail(requirement) {
+  if (requirement?.version) {
+    return `dosai needs the .NET runtime ${requirement.version} or newer, which is not installed`;
+  }
+  if (requirement?.major) {
+    return `dosai needs the .NET ${requirement.major} runtime, and no .NET installation was found`;
+  }
+  return "dosai could not start because the .NET runtime it needs is not installed";
+}
+
+/**
+ * How to get dosai running when the .NET host refused to start it.
+ *
+ * @param {{version: (string|undefined), major: (string|undefined)}} [requirement] Result of dosaiDotnetRequirement
+ * @returns {string} Install instructions, naming the .NET major version when it is known
+ */
+export function dosaiDotnetRequirementAdvice(requirement) {
+  return `Install the .NET${requirement?.major ? ` ${requirement.major}` : ""} runtime or SDK from https://dotnet.microsoft.com/download, or download the self-contained dosai (-full suffix) from https://github.com/owasp-dep-scan/dosai/releases and set DOSAI_CMD to its path.`;
 }
 
 function safeDosaiPath(value) {
@@ -196,6 +248,16 @@ function safeDosaiPatternPacks(value) {
     .join(delimiter);
 }
 
+// A --sections value names top-level report sections, which are plain
+// identifiers in dosai's report contract. Anything else is not passed.
+function safeDosaiSections(value) {
+  if (!value || typeof value !== "string") {
+    return undefined;
+  }
+  const names = value.split(",");
+  return names.every((name) => /^[A-Za-z]+$/.test(name)) ? value : undefined;
+}
+
 const MAX_DOSAI_EXCLUDES = 256;
 const MAX_BRACE_RANGE = 64;
 const GLOB_ESCAPABLE = "*?[]{}()!+@,";
@@ -207,7 +269,10 @@ const SAFE_DOSAI_GLOB = /^[\p{L}\p{N} _.+@#%~=/*?-]+$/u;
 // letters and "Program Files (x86)". Shell metacharacters are not allowed.
 const SAFE_DOSAI_EXECUTABLE = /^[\p{L}\p{N} _.,+@#%~=/\\:()-]+$/u;
 const warnedDosaiMessages = new Set();
-const dosaiWithoutExclude = new Set();
+// Optional dosai flags this executable has rejected, so later runs drop them
+// without the doomed first attempt. dosai reports every unknown token in one
+// run, so one rejection teaches the memo about every flag of that run.
+const dosaiRejectedFlagMemo = new Map();
 
 function warnDosaiOnce(message) {
   if (!warnedDosaiMessages.has(message)) {
@@ -494,9 +559,25 @@ function dosaiExcludeArgs(excludes, srcPath) {
   return patterns.flatMap((pattern) => ["--exclude", pattern]);
 }
 
-function dosaiRejectedExclude(result) {
+/**
+ * Every flag dosai reported as unknown in a run.
+ *
+ * System.CommandLine prints one `Unrecognized command or argument '--x'` line
+ * per unknown token (and a second line for the value that follows it, which
+ * carries no leading dashes and so never matches), so one failed run names
+ * every rejected flag.
+ *
+ * @param {Object} result spawnSync result
+ * @returns {Set<string>} The rejected flag literals, e.g. `{"--exclude"}`
+ */
+function dosaiRejectedFlags(result) {
   const output = `${result?.stdout || ""}${result?.stderr || ""}`;
-  return output.includes("Unrecognized command or argument '--exclude'");
+  const rejected = new Set();
+  const pattern = /Unrecognized command or argument '(--[^\s']+)'/g;
+  for (const match of output.matchAll(pattern)) {
+    rejected.add(match[1]);
+  }
+  return rejected;
 }
 
 function safeDosaiExecutable(value) {
@@ -537,9 +618,10 @@ export function readDosaiJsonFile(jsonFile) {
   }
 }
 
-// The sections of a dosai methods report that cdxgen reads. The rest (Methods,
-// Properties, Fields, Reachability, DeadCode, ...) only reaches downstream
-// tools through the persisted native report.
+// The sections of a dosai methods report that cdxgen reads. A run that will
+// not run evinse asks dosai to write only these (--sections;
+// Metadata.OmittedSections names the rest), so the complete report reaches
+// downstream tools through the semantics slices file of an evidence run.
 const DOSAI_METHODS_SECTIONS = [
   "Metadata",
   "Dependencies",
@@ -552,6 +634,84 @@ const DOSAI_METHODS_SECTIONS = [
   "AiComponents",
 ];
 
+/**
+ * The `--sections` value that writes exactly the sections cdxgen reads.
+ *
+ * Passed as `dosaiMethodsSections` by callers that know their run will not
+ * need the whole report (see {@link runsEvidenceAnalysis}); an older dosai
+ * that rejects `--sections` falls back to the full report on its own.
+ *
+ * @returns {string} Comma-separated section list for dosai `--sections`
+ */
+export function dosaiMethodsSectionsArgument() {
+  return DOSAI_METHODS_SECTIONS.join(",");
+}
+
+/**
+ * Whether this scan will run the evidence (evinse) analysis.
+ *
+ * One place answers for both the trim decision in `createCsharpBom` and the
+ * evinse gate in `bin/cdxgen.js`: `--evidence` alone runs it, and so does
+ * `--include-crypto` alone, after profiles are applied (`--profile research`
+ * turns on both). Testing `options.evidence` alone would trim a report that
+ * `--include-crypto` then needs full.
+ *
+ * @param {Object} options Scan options after profile expansion
+ * @returns {boolean} True when the scan will run evinse
+ */
+export function runsEvidenceAnalysis(options) {
+  return Boolean(options?.evidence || options?.includeCrypto);
+}
+
+/**
+ * The top-level sections a dosai methods report left out, empty for a full
+ * report. dosai v4 reports have no `OmittedSections`, so they count as full.
+ *
+ * @param {Object} [report] A dosai methods report as read by readDosaiMethodsReport
+ * @returns {string[]} The omitted section names
+ */
+export function dosaiOmittedSections(report) {
+  const omitted = report?.Metadata?.OmittedSections;
+  return Array.isArray(omitted)
+    ? omitted.filter((name) => typeof name === "string" && name)
+    : [];
+}
+
+/**
+ * The top-level sections a dosai methods report file left out, read from its
+ * Metadata alone. dosai writes Metadata first, so this reads only the head of
+ * the file, however large the report is. A missing or unreadable file counts
+ * as full: the read that follows reports it.
+ *
+ * @param {string} reportFile Path to the dosai methods JSON
+ * @returns {string[]} The omitted section names
+ */
+export function dosaiReportFileOmittedSections(reportFile) {
+  if (!reportFile || !safeExistsSync(reportFile)) {
+    return [];
+  }
+  try {
+    return dosaiOmittedSections({
+      Metadata: readJsonMember(reportFile, "Metadata"),
+    });
+  } catch (_err) {
+    return [];
+  }
+}
+
+/**
+ * The omitted sections of a dosai methods report that cdxgen reads, so the
+ * evidence built from the report lacks their input.
+ *
+ * @param {string[]} omittedSections Sections the report left out
+ * @returns {string[]} The ones cdxgen reads
+ */
+export function dosaiSectionsCdxgenReads(omittedSections) {
+  return omittedSections.filter((name) =>
+    DOSAI_METHODS_SECTIONS.includes(name),
+  );
+}
+
 // The file each report returned by readDosaiReport came from, and whether it
 // was trimmed to what cdxgen reads. persistDosaiSemanticsReport copies the
 // file rather than re-serialising a trimmed or oversized report.
@@ -675,14 +835,123 @@ export function readDosaiDataFlowReport(reportFile, options = {}) {
   });
 }
 
+/**
+ * Whether a dosai run ended because it ran out of time.
+ *
+ * dosai has no limit of its own: cdxgen's spawn timeout
+ * (CDXGEN_TIMEOUT_MS) stops the process, which reaches the caller only as an
+ * ETIMEDOUT error looking like any other failure (issue 4438).
+ *
+ * @param {Object} result spawnSync result
+ * @returns {boolean} true when the run was stopped by the spawn timeout
+ */
+export function dosaiRunTimedOut(result) {
+  return result?.error?.code === "ETIMEDOUT";
+}
+
+/**
+ * How a dosai run was stopped before it could finish, if it was.
+ *
+ * Besides the spawn timeout, a run is stopped when its console output outgrows
+ * CDXGEN_MAX_BUFFER (ENOBUFS) or a signal ends it, such as the kernel's
+ * out-of-memory killer. A stopped run can leave its slice half written.
+ *
+ * @param {Object} result spawnSync result
+ * @returns {"timeout"|"buffer"|"signal"|undefined} Why the run was stopped, or undefined when it ended by itself
+ */
+export function dosaiRunStopReason(result) {
+  if (dosaiRunTimedOut(result)) {
+    return "timeout";
+  }
+  if (result?.error?.code === "ENOBUFS") {
+    return "buffer";
+  }
+  if (result?.signal) {
+    return "signal";
+  }
+  return undefined;
+}
+
+// The output files of the dosai runs of this process that were stopped, so a
+// caller does not follow the stop warning with advice for another failure.
+const stoppedDosaiOutputs = new Set();
+// The output files of the dosai runs the .NET host refused to start; the
+// warning naming the missing runtime already says why they are absent.
+const unstartedDosaiOutputs = new Set();
+// The executable that wrote each output file of this process, and whether it
+// was the cdxgen-plugins-bin build rather than an override.
+const dosaiOutputProducers = new Map();
+// Executables the .NET host refused to start, once that has been reported to
+// the user, by the pregen check or by a dosai run.
+const dosaiLaunchFailuresReported = new Set();
+
+/**
+ * Note that the .NET host's refusal to start a dosai executable has been
+ * reported, so dosai runs of the same executable do not repeat the warning.
+ *
+ * @param {string} executable dosai executable
+ */
+export function markDosaiLaunchFailureReported(executable) {
+  const safeExecutable = safeDosaiExecutable(executable);
+  if (safeExecutable) {
+    dosaiLaunchFailuresReported.add(safeExecutable);
+  }
+}
+
+/**
+ * Whether the dosai run that should have written a file was stopped (by the
+ * time limit, the output buffer limit, or a signal) and already reported so.
+ *
+ * @param {string} outputFile Output file passed to the dosai run
+ * @returns {boolean} true when the run was stopped
+ */
+export function dosaiRunWasStopped(outputFile) {
+  const outputPath = safeDosaiPath(outputFile);
+  return Boolean(outputPath && stoppedDosaiOutputs.has(outputPath));
+}
+
+/**
+ * Whether the dosai run that should have written a file failed in a way it has
+ * already reported: it was stopped (see dosaiRunWasStopped), or the .NET host
+ * refused to start dosai and the warning named the missing runtime.
+ *
+ * @param {string} outputFile Output file passed to the dosai run
+ * @returns {boolean} true when the failure has been reported
+ */
+export function dosaiFailureReported(outputFile) {
+  const outputPath = safeDosaiPath(outputFile);
+  return Boolean(
+    outputPath &&
+      (stoppedDosaiOutputs.has(outputPath) ||
+        unstartedDosaiOutputs.has(outputPath)),
+  );
+}
+
+function dosaiStopMessage(reason, signal) {
+  if (reason === "timeout") {
+    return `WARN: dosai did not finish within ${formatDuration(TIMEOUT_MS)} and was stopped, so its slices are missing or incomplete. Allow more time with CDXGEN_TIMEOUT_MS (milliseconds, every external command).`;
+  }
+  if (reason === "buffer") {
+    return "WARN: dosai wrote more console output than CDXGEN_MAX_BUFFER allows and was stopped, so its slices are missing or incomplete. Raise CDXGEN_MAX_BUFFER (bytes).";
+  }
+  return `WARN: dosai was stopped by ${signal || "a signal"} before it finished, so its slices are missing or incomplete. A SIGKILL usually means the system ran out of memory.`;
+}
+
 /**
  * Run a dosai subcommand ("methods", "dataflows", or "crypto") against a source
  * tree and write its JSON output to the given file.
  *
+ * Flags cdxgen adds for its own benefit that an older dosai may not know
+ * (--exclude, --sections, --crypto-dataflows) are optional: when dosai reports
+ * them as unknown, every rejected one is dropped in a single retry, later runs
+ * of the same executable skip them up front, and dropping is reported once
+ * (a warning for --exclude, whose loss changes results; a debug line for the
+ * size-only flags). A run that rejects anything else has simply failed.
+ *
  * @param {string} command Dosai subcommand to execute
  * @param {string} src Source directory to analyze
  * @param {string} outputFile Path where the dosai JSON output is written
- * @param {Object} [options] Options carrying dosaiCommand, dataFlowPatterns, patternPacks, or exclude globs
+ * @param {Object} [options] Options carrying dosaiCommand, dataFlowPatterns, patternPacks, exclude globs, or dosaiMethodsSections
  * @returns {boolean} True when the command succeeded and produced the output file, false otherwise
  */
 export function runDosaiCommand(command, src, outputFile, options = {}) {
@@ -714,47 +983,138 @@ export function runDosaiCommand(command, src, outputFile, options = {}) {
   } else if (command === "crypto") {
     args.push("--format", "dosai");
   }
-  const excludeArgs = dosaiWithoutExclude.has(executable)
-    ? []
-    : dosaiExcludeArgs(options.exclude, srcPath);
+  // Optional flag groups: the flag literal, the tokens to append while it is
+  // active, and whether dropping it changes what dosai analyses (true, only
+  // --exclude) or only the size of the output (false).
+  const flagGroups = [];
+  if (command === "crypto") {
+    // cdxgen reads only Assets, Operations, and Materials from the crypto
+    // report, so the data-flow graph it never reads is omitted.
+    flagGroups.push({
+      flag: "--crypto-dataflows",
+      tokens: ["--crypto-dataflows", "none"],
+      changesResults: false,
+    });
+  }
+  const sections =
+    command === "methods"
+      ? safeDosaiSections(options.dosaiMethodsSections)
+      : undefined;
+  if (sections) {
+    flagGroups.push({
+      flag: "--sections",
+      tokens: ["--sections", sections],
+      changesResults: false,
+    });
+  }
+  const rejectedBefore = dosaiRejectedFlagMemo.get(executable);
+  // An executable that rejected --exclude gets no exclude translation at all:
+  // computing it would print warnings about patterns that are never passed.
+  const excludeTokens =
+    rejectedBefore?.has("--exclude") || !options.exclude
+      ? []
+      : dosaiExcludeArgs(options.exclude, srcPath);
+  if (excludeTokens.length) {
+    flagGroups.push({
+      flag: "--exclude",
+      tokens: excludeTokens,
+      changesResults: true,
+    });
+  }
+  const activeGroups = flagGroups.filter(
+    (group) => !rejectedBefore?.has(group.flag),
+  );
+  const commandArgs = [
+    ...args,
+    ...activeGroups.flatMap((group) => group.tokens),
+  ];
   if (DEBUG_MODE) {
-    console.log("Executing", executable, [...args, ...excludeArgs].join(" "));
+    console.log("Executing", executable, commandArgs.join(" "));
   }
-  let result = safeSpawnSync(executable, [...args, ...excludeArgs], {
+  stoppedDosaiOutputs.delete(outputPath);
+  unstartedDosaiOutputs.delete(outputPath);
+  dosaiOutputProducers.delete(outputPath);
+  let startedAt = Date.now();
+  let result = safeSpawnSync(executable, commandArgs, {
     cwd: srcPath,
     shell: false,
   });
-  // Dosai releases that predate --exclude reject it. Rerun without it so a
-  // user supplied exclude never turns into a missing slice.
-  if (
-    excludeArgs.length &&
-    result?.status !== 0 &&
-    dosaiRejectedExclude(result)
-  ) {
-    dosaiWithoutExclude.add(executable);
-    warnDosaiOnce(
-      "This dosai build does not support --exclude, so it runs without the exclude patterns. Upgrade dosai or set DOSAI_CMD to a newer build to honour them.",
-    );
-    result = safeSpawnSync(executable, args, {
-      cwd: srcPath,
-      shell: false,
-    });
+  // Dosai releases that predate an optional flag reject it. Rerun once without
+  // every flag this run rejected, so a newer cdxgen flag never turns into a
+  // missing slice on an older dosai.
+  if (result?.status !== 0) {
+    const rejected = dosaiRejectedFlags(result);
+    if (
+      rejected.size &&
+      [...rejected].every((flag) =>
+        activeGroups.some((group) => group.flag === flag),
+      )
+    ) {
+      const dropped = flagGroups.filter((group) => rejected.has(group.flag));
+      const memo = dosaiRejectedFlagMemo.get(executable) ?? new Set();
+      for (const group of dropped) {
+        memo.add(group.flag);
+      }
+      dosaiRejectedFlagMemo.set(executable, memo);
+      const droppedExclude = dropped.some((group) => group.changesResults);
+      if (droppedExclude) {
+        warnDosaiOnce(
+          "This dosai build does not support --exclude, so it runs without the exclude patterns. Upgrade dosai or set DOSAI_CMD to a newer build to honour them.",
+        );
+      }
+      if (DEBUG_MODE) {
+        console.log(
+          `Retrying without the optional dosai flag(s) it rejected: ${dropped.map((group) => group.flag).join(", ")}.`,
+        );
+      }
+      const retryArgs = [
+        ...args,
+        ...activeGroups
+          .filter((group) => !rejected.has(group.flag))
+          .flatMap((group) => group.tokens),
+      ];
+      startedAt = Date.now();
+      result = safeSpawnSync(executable, retryArgs, {
+        cwd: srcPath,
+        shell: false,
+      });
+    }
   }
-  if (dosaiSdkMessage(result)) {
+  const dotnetRequirement = dosaiDotnetRequirement(result);
+  if (dotnetRequirement) {
+    const detail = dosaiDotnetRequirementDetail(dotnetRequirement);
     recordDegradation("dotnet.sdk.missing", {
       ecosystem: "csharp",
       tool: "dotnet",
       impact: "none",
       command: `${basename(executable)} ${args.join(" ")}`,
-      detail:
-        "dosai reported that no .NET SDK is installed, so the requested dosai analysis could not run.",
+      detail: `${detail}, so the requested dosai analysis could not run.`,
     });
-    console.log(
-      "Dotnet SDK is not installed. Please use the cdxgen dotnet container images to analyze this project with dosai.",
-    );
-    console.log(
-      "Alternatively, download the dosai self-contained binary (-full suffix) from https://github.com/owasp-dep-scan/dosai/releases and set DOSAI_CMD to its location.",
-    );
+    // Visible without debug output, and once per scan: every later run of
+    // this executable fails the same way.
+    if (!dosaiLaunchFailuresReported.has(executable)) {
+      dosaiLaunchFailuresReported.add(executable);
+      console.warn(
+        `WARNING: ${detail}, so dosai could not run and the .NET evidence it provides (call graph, reachability, services, crypto) is missing. ${dosaiDotnetRequirementAdvice(dotnetRequirement)}`,
+      );
+    }
+    unstartedDosaiOutputs.add(outputPath);
+  }
+  const stopReason = dosaiRunStopReason(result);
+  if (stopReason) {
+    // Visible without debug output: otherwise a stopped dosai reads like any
+    // other failure while the scan silently loses its .NET evidence.
+    console.warn(dosaiStopMessage(stopReason, result.signal));
+    // Windows kills only the dosai process itself, and the build hosts it
+    // started would keep running.
+    reapProcessTree(result.pid, startedAt, Date.now(), "dosai");
+    // A stopped dosai can leave its output half written, and the caller would
+    // read the truncated file back as a slice.
+    if (safeExistsSync(outputPath)) {
+      safeRmSync(outputPath, { force: true });
+    }
+    stoppedDosaiOutputs.add(outputPath);
+    return false;
   }
   if (result?.status !== 0 || result?.error || !safeExistsSync(outputPath)) {
     if (DEBUG_MODE) {
@@ -766,6 +1126,10 @@ export function runDosaiCommand(command, src, outputFile, options = {}) {
     }
     return false;
   }
+  dosaiOutputProducers.set(outputPath, {
+    executable,
+    bundled: !options.dosaiCommand && !readEnvironmentVariable("DOSAI_CMD"),
+  });
   return true;
 }
 
@@ -774,7 +1138,7 @@ export function runDosaiCommand(command, src, outputFile, options = {}) {
  *
  * @param {string} src Source directory to analyze
  * @param {string} outputFile Path where the methods slice JSON is written
- * @param {Object} [options] Options forwarded to runDosaiCommand
+ * @param {Object} [options] Options forwarded to runDosaiCommand; `dosaiMethodsSections` names the top-level sections to write (see dosaiMethodsSectionsArgument), omitted for the full report
  * @returns {boolean} True when the slice was produced successfully
  */
 export function createDosaiMethodsSlice(src, outputFile, options = {}) {
@@ -827,6 +1191,141 @@ export function analyzeDosaiCrypto(src, options = {}) {
   }
 }
 
+const DOSAI_PURL = "pkg:github/owasp-dep-scan/dosai";
+const DOSAI_VERSION_PATTERN = /^\d+(?:\.\d+){1,3}(?:-[0-9A-Za-z.-]+)?$/;
+// The version each dosai executable reported for itself, by executable.
+const dosaiExecutableVersions = new Map();
+
+/**
+ * The version a dosai executable reports with `--version`, without its build
+ * metadata: `5.0.0-rc.2+e42b205` reads as `5.0.0-rc.2`. Each executable is
+ * asked once per process.
+ *
+ * @param {string} executable dosai executable
+ * @returns {string|undefined} The version, or undefined when dosai reported none
+ */
+function dosaiExecutableVersion(executable) {
+  const safeExecutable = safeDosaiExecutable(executable);
+  if (!safeExecutable) {
+    return undefined;
+  }
+  if (!dosaiExecutableVersions.has(safeExecutable)) {
+    const result = safeSpawnSync(safeExecutable, ["--version"], {
+      shell: false,
+    });
+    const reported =
+      result?.status === 0 && !result.error
+        ? `${result.stdout || ""}`.trim().split(/\s+/)[0].split("+")[0]
+        : "";
+    dosaiExecutableVersions.set(
+      safeExecutable,
+      DOSAI_VERSION_PATTERN.test(reported) ? reported : undefined,
+    );
+  }
+  return dosaiExecutableVersions.get(safeExecutable);
+}
+
+/**
+ * The dosai version a report records about its producer. AnalyzerVersion is
+ * the four-part assembly version, so `4.1.0.0` reads as `4.1.0`, and a
+ * prerelease build reads as the release it precedes.
+ *
+ * @param {Object} [report] A dosai report
+ * @returns {string|undefined} The version, or undefined when the report names no dosai version
+ */
+function dosaiReportVersion(report) {
+  const metadata = report?.Metadata;
+  if (`${metadata?.Tool || ""}`.toLowerCase() !== "dosai") {
+    return undefined;
+  }
+  const match = `${metadata.AnalyzerVersion || ""}`.match(
+    /^(\d+\.\d+\.\d+)(?:\.(\d+))?$/,
+  );
+  if (!match) {
+    return undefined;
+  }
+  return match[2] && match[2] !== "0" ? match[0] : match[1];
+}
+
+function dosaiToolComponent(version, manifestComponent, bundled) {
+  // The manifest component describes the bundled binary, hashes included
+  if (bundled && version && manifestComponent?.version === version) {
+    return structuredClone(manifestComponent);
+  }
+  const purl = version ? `${DOSAI_PURL}@${version}` : DOSAI_PURL;
+  const component = { type: "application", name: "dosai" };
+  if (version) {
+    component.version = version;
+  }
+  if (manifestComponent?.description) {
+    component.description = manifestComponent.description;
+  }
+  component.purl = purl;
+  component["bom-ref"] = purl;
+  for (const field of ["licenses", "externalReferences"]) {
+    if (manifestComponent?.[field]) {
+      component[field] = structuredClone(manifestComponent[field]);
+    }
+  }
+  return component;
+}
+
+/**
+ * The tool component naming the dosai behind a methods report.
+ *
+ * A report that a dosai run of this process wrote names the executable that
+ * wrote it, with the version that executable reports. A report reused from an
+ * earlier run names the version recorded in its Metadata, or the configured
+ * dosai's own version when that is a build of the same release. No component
+ * is returned for a report that is missing or that no dosai wrote, such as
+ * when the .NET host refused to start dosai.
+ *
+ * The cdxgen-plugins-bin manifest component is returned as-is only for its
+ * own binary at its own version. Any other dosai gets a component built from
+ * the manifest's project fields (description, licenses, references), without
+ * the bundled binary's hashes or path.
+ *
+ * @param {string} reportFile Path of the dosai methods report
+ * @param {Object} [report] The report as read, for its Metadata
+ * @param {Object} [manifestComponent] dosai component of the cdxgen-plugins-bin manifest
+ * @returns {Object[]} The dosai tool component, or an empty array
+ */
+export function dosaiToolComponents(reportFile, report, manifestComponent) {
+  const reportPath = safeDosaiPath(reportFile);
+  if (!reportPath) {
+    return [];
+  }
+  const producer = dosaiOutputProducers.get(reportPath);
+  if (producer) {
+    return [
+      dosaiToolComponent(
+        dosaiExecutableVersion(producer.executable) ||
+          dosaiReportVersion(report),
+        manifestComponent,
+        producer.bundled,
+      ),
+    ];
+  }
+  const recorded = dosaiReportVersion(report);
+  if (!recorded) {
+    return [];
+  }
+  const executable = dosaiBin();
+  const configured = executable
+    ? dosaiExecutableVersion(executable)
+    : undefined;
+  if (configured?.split("-")[0] === recorded) {
+    return [
+      dosaiToolComponent(
+        configured,
+        manifestComponent,
+        !readEnvironmentVariable("DOSAI_CMD"),
+      ),
+    ];
+  }
+  return [dosaiToolComponent(recorded, manifestComponent, false)];
+}
+
 /**
  * Build the combined native dosai report object persisted for downstream tools.
  *
@@ -887,10 +1386,12 @@ function* combinedDosaiReportChunks(combined, parts) {
  * analyzeGolemProject on branch feat/rusi-persist-report): when a semantics-
  * slices path is provided, the FULL native report is written there and kept so
  * downstream tools (depscan) can consume the complete methods + data-flow
- * facts that cdxgen only projects a subset of into the SBOM evidence. dotnet
- * does not otherwise use the semantics slice (atom is never run for dotnet),
- * so the path is free to carry the combined dosai report. Returns the resolved
- * durable path when something was persisted, otherwise undefined.
+ * facts that cdxgen only projects a subset of into the SBOM evidence. A
+ * methods report the user supplied with --usages-slices-file is written as
+ * given, with a recorded degradation when it was trimmed with --sections.
+ * dotnet does not otherwise use the semantics slice (atom is never run for
+ * dotnet), so the path is free to carry the combined dosai report. Returns the
+ * resolved durable path when something was persisted, otherwise undefined.
  */
 export function persistDosaiSemanticsReport(
   options,
@@ -912,6 +1413,19 @@ export function persistDosaiSemanticsReport(
   const combined = buildCombinedDosaiReport(methodsSlice, dataFlowSlice);
   const methodsSource = dosaiReportSources.get(methodsSlice);
   const dataFlowSource = dosaiReportSources.get(dataFlowSlice);
+  // A methods report written with --sections is partial. Persist it as given
+  // (a user-supplied usages slice is their choice), but say so, because the
+  // semantics file is the source of truth for downstream tools.
+  const omittedSections = dosaiOmittedSections(methodsSlice);
+  if (omittedSections.length) {
+    recordDegradation("dosai.semantics.trimmed-report", {
+      ecosystem: "csharp",
+      tool: "dosai",
+      impact: "none",
+      command: `persistDosaiSemanticsReport ${durablePath}`,
+      detail: `The dosai methods report was written with --sections, so the persisted report omits: ${omittedSections.join(", ")}. Run dosai methods without --sections for the complete report.`,
+    });
+  }
   try {
     let text;
     if (!methodsSource?.trimmed && !dataFlowSource?.trimmed) {
@@ -958,21 +1472,63 @@ export function persistDosaiSemanticsReport(
  * Build a purl alias map for a list of components.
  *
  * @param {Object[]} [components] Component objects with purl fields
- * @returns {Map<string, string>} Map of exact purls and normalized type/namespace/name keys to canonical purls
+ * @param {Object} [options] Options passed to {@link buildDosaiPurlAliasMap} (`srcPath`)
+ * @returns {Map<string, string>} Map of component purls, carrying the version-free identity index
  */
-export function buildPurlAliasMap(components = []) {
-  return buildDosaiPurlAliasMap(components);
+export function buildPurlAliasMap(components = [], options = {}) {
+  return buildDosaiPurlAliasMap(components, options);
 }
 
 /**
- * Resolve a possibly-aliased purl to the canonical component purl.
+ * Resolve a dosai purl to the canonical component purl, by version, and for a
+ * package the BOM holds in several versions by the record's location.
  *
  * @param {string} purl Purl from a dosai report
  * @param {Map<string, string>} purlAliasMap Alias map built by buildPurlAliasMap
- * @returns {string|undefined} Canonical component purl, the input purl when unaliased, or undefined when empty
+ * @param {string} [location] Source location of the dosai record
+ * @returns {string|undefined} Canonical component purl, the input purl when the BOM has no such package,
+ *          or undefined when empty or ambiguous
  */
-export function resolveComponentPurl(purl, purlAliasMap) {
-  return resolveDosaiComponentPurl(purl, purlAliasMap);
+export function resolveComponentPurl(purl, purlAliasMap, location) {
+  return resolveDosaiComponentPurl(purl, purlAliasMap, location);
+}
+
+/**
+ * The component purls one PackageReachability fact belongs to: each of its
+ * locations resolved in its own project (a versionless purl from unrestored
+ * projects spans several), else the purl alone.
+ *
+ * @param {Object} reachability dosai PackageReachability entry
+ * @param {Map<string, string>} purlAliasMap Alias map built by buildPurlAliasMap
+ * @param {Object} [graph] Call graph lookups `{ edgesById, nodesById }`
+ * @returns {string[]} Component purls
+ */
+function reachabilityComponentPurls(reachability, purlAliasMap, graph = {}) {
+  const locations = [
+    ...(reachability.SourceLocations || []).map((location) =>
+      dosaiSourceLocation(location),
+    ),
+    ...(reachability.EdgeIds || []).map((edgeId) =>
+      dosaiSourceLocation(graph.edgesById?.get(edgeId)),
+    ),
+    ...(reachability.NodeIds || []).map((nodeId) =>
+      dosaiSourceLocationFromNode(graph.nodesById?.get(nodeId)),
+    ),
+  ].filter(Boolean);
+  const purls = new Set(
+    locations
+      .map((location) =>
+        resolveComponentPurl(reachability.Purl, purlAliasMap, location),
+      )
+      .filter(Boolean),
+  );
+  if (!purls.size) {
+    const purl = resolveComponentPurl(reachability.Purl, purlAliasMap);
+    if (purl) {
+      purls.add(purl);
+    }
+  }
+  return [...purls];
 }
 
 /**
@@ -1021,24 +1577,51 @@ export function addDosaiReachabilityProperties(component, reachability) {
  *
  * @param {Object} methodsSlice Parsed dosai methods slice JSON
  * @param {Object[]} [components] BOM components used to resolve purl aliases and mutate
+ * @param {Object} [options] Options
+ * @param {string} [options.srcPath] Directory dosai analyzed; a package the BOM holds in several
+ *        versions is matched by the project of the record's file
  * @returns {number} Number of distinct components enriched
  */
-export function applyDosaiReachabilityEvidence(methodsSlice, components = []) {
-  const purlAliasMap = buildPurlAliasMap(components);
+export function applyDosaiReachabilityEvidence(
+  methodsSlice,
+  components = [],
+  options = {},
+) {
+  const purlAliasMap = buildPurlAliasMap(components, options);
   const componentsByPurl = new Map(
     components
       .filter((component) => component?.purl)
       .map((component) => [component.purl, component]),
   );
+  const graph = {
+    edgesById: new Map(
+      (methodsSlice?.CallGraph?.Edges || []).map((edge) => [edge.Id, edge]),
+    ),
+    nodesById: new Map(
+      (methodsSlice?.CallGraph?.Nodes || []).map((node) => [node.Id, node]),
+    ),
+  };
   const enriched = new Set();
-  for (const reachability of methodsSlice?.PackageReachability || []) {
-    const purl = resolveComponentPurl(reachability.Purl, purlAliasMap);
-    const component = purl && componentsByPurl.get(purl);
-    if (!component) {
-      continue;
+  // The first fact applied to a component wins, so a fact that names the
+  // component's exact purl goes before one that reached it by name.
+  const facts = [...(methodsSlice?.PackageReachability || [])].sort(
+    (a, b) =>
+      Number(!componentsByPurl.has(a.Purl)) -
+      Number(!componentsByPurl.has(b.Purl)),
+  );
+  for (const reachability of facts) {
+    for (const purl of reachabilityComponentPurls(
+      reachability,
+      purlAliasMap,
+      graph,
+    )) {
+      const component = componentsByPurl.get(purl);
+      if (!component) {
+        continue;
+      }
+      addDosaiReachabilityProperties(component, reachability);
+      enriched.add(component);
     }
-    addDosaiReachabilityProperties(component, reachability);
-    enriched.add(component);
   }
   return enriched.size;
 }
@@ -1051,10 +1634,17 @@ export function applyDosaiReachabilityEvidence(methodsSlice, components = []) {
  *
  * @param {Object} methodsSlice Parsed dosai methods slice JSON
  * @param {Object[]} [components] BOM components used to resolve purl aliases
+ * @param {Object} [options] Options
+ * @param {string} [options.srcPath] Directory dosai analyzed; a package the BOM holds in several
+ *        versions is matched by the project of the record's file
  * @returns {Object} Object with purlLocationMap, purlModulesMap, and purlMethodsMap keyed by purl
  */
-export function collectDosaiPurlEvidence(methodsSlice, components = []) {
-  const purlAliasMap = buildPurlAliasMap(components);
+export function collectDosaiPurlEvidence(
+  methodsSlice,
+  components = [],
+  options = {},
+) {
+  const purlAliasMap = buildPurlAliasMap(components, options);
   const purlLocationMap = {};
   const purlModulesMap = {};
   const purlMethodsMap = {};
@@ -1066,7 +1656,11 @@ export function collectDosaiPurlEvidence(methodsSlice, components = []) {
   );
 
   for (const dependency of methodsSlice?.Dependencies || []) {
-    const purl = resolveComponentPurl(dependency.Purl, purlAliasMap);
+    const purl = resolveComponentPurl(
+      dependency.Purl,
+      purlAliasMap,
+      dependency.Path,
+    );
     if (!purl) {
       continue;
     }
@@ -1079,42 +1673,61 @@ export function collectDosaiPurlEvidence(methodsSlice, components = []) {
   }
 
   for (const reachability of methodsSlice?.PackageReachability || []) {
-    const purl = resolveComponentPurl(reachability.Purl, purlAliasMap);
-    if (!purl) {
-      continue;
-    }
+    // Every location resolves in its own project: a versionless purl from
+    // unrestored projects spans projects restored at different versions.
+    const resolveAt = (location) =>
+      resolveComponentPurl(reachability.Purl, purlAliasMap, location);
+    const factPurls = new Set();
+    // Modules and methods of call-graph items that name no source file
+    // (frames inside the package), held for the fact's own version.
+    const unplaced = [];
     let hasExplicitSourceLocations = false;
     for (const sourceLocation of reachability.SourceLocations || []) {
       const location = dosaiSourceLocation(sourceLocation);
+      const purl = resolveAt(location);
       addDosaiSetValue(purlLocationMap, purl, location);
+      if (purl) {
+        factPurls.add(purl);
+      }
       hasExplicitSourceLocations ||= Boolean(location);
     }
     for (const edgeId of reachability.EdgeIds || []) {
       const edge = edgesById.get(edgeId);
+      const location = dosaiSourceLocation(edge);
+      const purl = resolveAt(location ?? edge?.Path);
+      const method = edge?.CalledMethodName || edge?.TargetName;
+      if (!purl) {
+        unplaced.push([purlMethodsMap, method]);
+        continue;
+      }
+      factPurls.add(purl);
       if (!hasExplicitSourceLocations) {
-        addDosaiSetValue(purlLocationMap, purl, dosaiSourceLocation(edge));
+        addDosaiSetValue(purlLocationMap, purl, location);
       }
-      addDosaiSetValue(
-        purlMethodsMap,
-        purl,
-        edge?.CalledMethodName || edge?.TargetName,
-      );
+      addDosaiSetValue(purlMethodsMap, purl, method);
     }
     for (const nodeId of reachability.NodeIds || []) {
       const node = nodesById.get(nodeId);
+      const location = dosaiSourceLocationFromNode(node);
+      const purl = resolveAt(location);
+      const module = node?.ClassName || node?.Module;
+      const method = node?.Name || node?.Identity?.MethodName;
+      if (!purl) {
+        unplaced.push([purlModulesMap, module], [purlMethodsMap, method]);
+        continue;
+      }
+      factPurls.add(purl);
       if (!hasExplicitSourceLocations) {
-        addDosaiSetValue(
-          purlLocationMap,
-          purl,
-          dosaiSourceLocationFromNode(node),
-        );
+        addDosaiSetValue(purlLocationMap, purl, location);
+      }
+      addDosaiSetValue(purlModulesMap, purl, module);
+      addDosaiSetValue(purlMethodsMap, purl, method);
+    }
+    if (factPurls.size === 1) {
+      const [purl] = factPurls;
+      for (const [map, value] of unplaced) {
+        addDosaiSetValue(map, purl, value);
       }
-      addDosaiSetValue(purlModulesMap, purl, node?.ClassName || node?.Module);
-      addDosaiSetValue(
-        purlMethodsMap,
-        purl,
-        node?.Name || node?.Identity?.MethodName,
-      );
     }
   }
   return { purlLocationMap, purlModulesMap, purlMethodsMap };
@@ -1128,17 +1741,38 @@ export function collectDosaiPurlEvidence(methodsSlice, components = []) {
  *
  * @param {Object} dataFlowResult Parsed dosai data-flow slice JSON
  * @param {Object[]} [components] BOM components used to resolve purl aliases
+ * @param {Object} [options] Options
+ * @param {string} [options.srcPath] Directory dosai analyzed; a package the BOM holds in several
+ *        versions is matched by the project of the record's file
  * @returns {Object} Map of canonical purl to arrays of call-stack frame objects
  */
-export function collectDosaiDataFlowFrames(dataFlowResult, components = []) {
-  const purlAliasMap = buildPurlAliasMap(components);
+export function collectDosaiDataFlowFrames(
+  dataFlowResult,
+  components = [],
+  options = {},
+) {
+  const purlAliasMap = buildPurlAliasMap(components, options);
   const nodesById = new Map(
     (dataFlowResult?.Nodes || []).map((node) => [node.Id, node]),
   );
   const dataFlowFrames = {};
   const addFramesForPurl = (purl, frames) => {
-    const componentPurl = resolveComponentPurl(purl, purlAliasMap);
-    if (!componentPurl || !frames.length) {
+    if (!frames.length) {
+      return;
+    }
+    // The flow runs in the project of its first frame that settles one.
+    let componentPurl;
+    for (const frame of frames) {
+      componentPurl = resolveComponentPurl(
+        purl,
+        purlAliasMap,
+        frame.fullFilename,
+      );
+      if (componentPurl) {
+        break;
+      }
+    }
+    if (!componentPurl) {
       return;
     }
     dataFlowFrames[componentPurl] ??= [];
@@ -1575,6 +2209,12 @@ export function collectDosaiServicesFromMethods(
 /**
  * Normalize a services map into a sorted array of CycloneDX service objects.
  *
+ * This is where evinse's service maps — dosai, golem, kosi, scalasem, an
+ * OpenAPI document, and the atom usage and type detectors — become
+ * `services[]`, so it is also where every endpoint is percent-encoded into the
+ * iri-reference CycloneDX requires. The collectors keep the readable template
+ * (`/users/{id}`); the BOM gets `/users/%7Bid%7D`.
+ *
  * @param {Object} [servicesMap] Map of service name to service definition with Set-backed endpoints
  * @returns {Object[]} Array of service objects with sorted endpoint arrays and properties
  */
@@ -1582,12 +2222,18 @@ export function normalizeDosaiServiceMap(servicesMap = {}) {
   return Object.keys(servicesMap)
     .map((serviceName) => {
       const definition = servicesMap[serviceName];
+      const endpoints = new Set();
+      for (const endpoint of definition.endpoints || []) {
+        if (typeof endpoint === "string" && endpoint) {
+          endpoints.add(encodeUriReference(endpoint));
+        }
+      }
       const service = {
         name:
           definition.name ||
           serviceName ||
           `dosai-${basename(serviceName)}-service`,
-        endpoints: Array.from(definition.endpoints || []).sort(),
+        endpoints: Array.from(endpoints).sort(),
         authenticated: definition.authenticated,
         // Accept both spellings. Every pre-4.0.0 producer — collectDosaiServicesFromMethods here, and
         // the OpenAPI/Java/Python paths in evinser.js — sets the camelCase `xTrustBoundary`; only the