@cdxgen/cdxgen 13.4.0 → 13.6.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.
@@ -569,6 +727,105 @@ function referencedIds(entries, field) {
   return ids;
 }
 
+// The fields of a MethodCalls row cdxgen reads: the component it names (Purl
+// or Module), where the call site is (Path, FileName, LineNumber) and what it
+// calls (ClassName, CalledMethod). Everything else a report row carries -
+// arguments, evidence kinds, caller identities - no cdxgen consumer reads,
+// and a report with millions of calls cannot afford to hold them.
+const DOSAI_METHOD_CALL_FIELDS = [
+  "Purl",
+  "Module",
+  "Path",
+  "FileName",
+  "LineNumber",
+  "ClassName",
+  "CalledMethod",
+];
+
+/**
+ * The largest number of distinct method calls cdxgen keeps from one report.
+ *
+ * Reports in the millions of calls repeat the same call sites heavily, so the
+ * aggregated rows stay far below this; the cap exists so a report whose calls
+ * are all distinct degrades the occurrence evidence instead of the process.
+ *
+ * @returns {number} Cap on distinct kept rows
+ */
+export function maxDosaiMethodCalls() {
+  const configured = Number.parseInt(
+    readEnvironmentVariable("CDXGEN_DOSAI_MAX_METHOD_CALLS") || "",
+    10,
+  );
+  if (Number.isInteger(configured) && configured > 0) {
+    return configured;
+  }
+  return 1_000_000;
+}
+
+/**
+ * Build the `map` that turns report MethodCalls rows into what cdxgen keeps:
+ * rows the caller rejects are dropped, the rest are reduced to
+ * {@link DOSAI_METHOD_CALL_FIELDS} and aggregated by those fields, so a call
+ * site reached a million times is held once with a `CallCount`. Past
+ * {@link maxDosaiMethodCalls} distinct rows, further rows are dropped and one
+ * warning names the cap.
+ *
+ * @param {string} reportFile Report the rows come from, named in the warning
+ * @param {Object} [options] Options
+ * @param {Function} [options.keepMethodCall] Predicate choosing the rows to keep
+ * @param {number} [options.maxMethodCalls] Cap override, for tests
+ * @returns {{map: Function, finish: Function}} The row mapper, and the
+ *   `finish` that reports a cap reached
+ */
+function dosaiMethodCallCollector(reportFile, options = {}) {
+  const keep = options.keepMethodCall;
+  const max = options.maxMethodCalls ?? maxDosaiMethodCalls();
+  const keptByKey = new Map();
+  let dropped = 0;
+  return {
+    map(methodCall) {
+      if (keep && !keep(methodCall)) {
+        return undefined;
+      }
+      const compact = {};
+      for (const field of DOSAI_METHOD_CALL_FIELDS) {
+        if (methodCall?.[field] !== undefined) {
+          compact[field] = methodCall[field];
+        }
+      }
+      const key = DOSAI_METHOD_CALL_FIELDS.map((field) => compact[field]).join(
+        "\u0000",
+      );
+      const kept = keptByKey.get(key);
+      if (kept) {
+        kept.CallCount = (kept.CallCount ?? 1) + 1;
+        return undefined;
+      }
+      if (keptByKey.size >= max) {
+        dropped++;
+        return undefined;
+      }
+      keptByKey.set(key, compact);
+      return compact;
+    },
+    finish() {
+      if (!dropped) {
+        return;
+      }
+      console.warn(
+        `The dosai report "${reportFile}" holds more distinct method calls than cdxgen keeps (${max}); ${dropped} call sites were dropped, so occurrence evidence may be incomplete. Raise the cap with CDXGEN_DOSAI_MAX_METHOD_CALLS.`,
+      );
+      recordDegradation("dosai.method-calls-capped", {
+        ecosystem: "csharp",
+        tool: "dosai",
+        impact: "components",
+        command: reportFile,
+        detail: `The dosai report holds more distinct method calls than the cap of ${max}, so ${dropped} call sites were dropped from the occurrence evidence.`,
+      });
+    },
+  };
+}
+
 function readDosaiReport(reportFile, options, readTrimmed) {
   if (!reportFile || !safeExistsSync(reportFile)) {
     return undefined;
@@ -603,7 +860,13 @@ function readDosaiReport(reportFile, options, readTrimmed) {
     }
     return report;
   } catch (err) {
-    if (DEBUG_MODE) {
+    if (err instanceof RangeError) {
+      // A heap or string limit is a report-size problem the user can act on,
+      // unlike a malformed report, so it is named even without debug output.
+      console.warn(
+        `The dosai report "${reportFile}" is too large to read: ${err.message}. Raise the Node.js heap, for example NODE_OPTIONS="--max-old-space-size=8192", or write the report with dosai's --sections so it holds less.`,
+      );
+    } else if (DEBUG_MODE) {
       console.log(
         `Unable to read the dosai report "${reportFile}": ${err.message}`,
       );
@@ -618,25 +881,34 @@ function readDosaiReport(reportFile, options, readTrimmed) {
  * A report that fits in one JavaScript string is parsed whole. A larger one is
  * read in bounded runs, keeping the requested sections, the CallGraph nodes and
  * edges that PackageReachability references, and the MethodCalls accepted by
- * `keepMethodCall` (none when it is omitted). Nothing cdxgen reads is lost.
+ * `keepMethodCall` (none when it is omitted). A kept MethodCalls row is
+ * reduced to the fields cdxgen reads and aggregated by them, so a call site
+ * reached many times is held once with a `CallCount`; distinct rows past
+ * {@link maxDosaiMethodCalls} are dropped with one warning. Nothing cdxgen
+ * reads is lost.
  *
  * @param {string} reportFile Path to the dosai methods JSON
  * @param {Object} [options] Options
  * @param {string[]} [options.sections] Sections to keep from a large report (default: every section cdxgen reads)
  * @param {Function} [options.keepMethodCall] Predicate choosing the MethodCalls to keep from a large report
+ * @param {number} [options.maxMethodCalls] Cap on distinct kept MethodCalls, for tests
  * @param {number} [options.maxTextBytes] Largest report parsed whole, for tests
  * @returns {Object|undefined} Parsed report, or undefined when missing or invalid
  */
 export function readDosaiMethodsReport(reportFile, options = {}) {
   const sections = options.sections || DOSAI_METHODS_SECTIONS;
-  return readDosaiReport(reportFile, options, (report, read) => {
+  const collector =
+    sections.includes("MethodCalls") && options.keepMethodCall
+      ? dosaiMethodCallCollector(reportFile, options)
+      : undefined;
+  const report = readDosaiReport(reportFile, options, (report, read) => {
     for (const section of sections) {
       if (section !== "CallGraph" && section !== "MethodCalls") {
         read(section);
       }
     }
-    if (sections.includes("MethodCalls") && options.keepMethodCall) {
-      read("MethodCalls", { filter: options.keepMethodCall });
+    if (collector) {
+      read("MethodCalls", { map: collector.map });
     }
     if (sections.includes("CallGraph")) {
       // CallGraph precedes PackageReachability in the file, which is why the
@@ -651,6 +923,26 @@ export function readDosaiMethodsReport(reportFile, options = {}) {
       });
     }
   });
+  // A report parsed whole kept every row, as it always has: reduce them to
+  // the fields cdxgen reads and aggregate repeats, without the caller's
+  // predicate, which the whole parse has never applied. A report that took
+  // the trimmed path already went through the collector above.
+  if (report && !dosaiReportSources.get(report)?.trimmed) {
+    const wholeCollector = dosaiMethodCallCollector(reportFile, {
+      maxMethodCalls: options.maxMethodCalls,
+    });
+    const reduced = [];
+    for (const methodCall of report.MethodCalls || []) {
+      const kept = wholeCollector.map(methodCall);
+      if (kept !== undefined) {
+        reduced.push(kept);
+      }
+    }
+    report.MethodCalls = reduced;
+    wholeCollector.finish();
+  }
+  collector?.finish();
+  return report;
 }
 
 /**
@@ -717,6 +1009,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 +1044,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 +1075,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 +1117,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 +1260,10 @@ export function runDosaiCommand(command, src, outputFile, options = {}) {
     }
     return false;
   }
+  dosaiOutputProducers.set(outputPath, {
+    executable,
+    bundled: !options.dosaiCommand && !readEnvironmentVariable("DOSAI_CMD"),
+  });
   return true;
 }
 
@@ -858,7 +1272,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 +1325,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 +1520,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 +1547,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 +2343,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 +2356,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