@cdxgen/cdxgen 13.4.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,
@@ -23,9 +23,11 @@ import {
   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 {
@@ -154,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) {
@@ -169,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) {
@@ -198,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 = "*?[]{}()!+@,";
@@ -209,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)) {
@@ -496,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) {
@@ -539,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",
@@ -554,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.
@@ -717,6 +875,28 @@ export function dosaiRunStopReason(result) {
 // 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
@@ -730,6 +910,23 @@ export function dosaiRunWasStopped(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).`;
@@ -744,10 +941,17 @@ function dosaiStopMessage(reason, signal) {
  * 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 = {}) {
@@ -779,50 +983,122 @@ 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(" "));
   }
   stoppedDosaiOutputs.delete(outputPath);
+  unstartedDosaiOutputs.delete(outputPath);
+  dosaiOutputProducers.delete(outputPath);
   let startedAt = Date.now();
-  let result = safeSpawnSync(executable, [...args, ...excludeArgs], {
+  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.",
-    );
-    startedAt = Date.now();
-    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) {
@@ -850,6 +1126,10 @@ export function runDosaiCommand(command, src, outputFile, options = {}) {
     }
     return false;
   }
+  dosaiOutputProducers.set(outputPath, {
+    executable,
+    bundled: !options.dosaiCommand && !readEnvironmentVariable("DOSAI_CMD"),
+  });
   return true;
 }
 
@@ -858,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 = {}) {
@@ -911,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.
  *
@@ -971,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,
@@ -996,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) {
@@ -1779,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
  */
@@ -1786,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