@cdxgen/cdxgen 13.0.0 → 13.1.0

package/lib/inventory/dosai.js

@@ -2,6 +2,7 @@ import { readFileSync } from "node:fs";
 import { basename, delimiter, join, resolve } from "node:path";
 
 import { DEBUG_MODE } from "../core/activity.js";
+import { recordDegradation } from "../core/buildLedger.js";
 import {
   getTmpDir,
   safeExistsSync,
@@ -59,6 +60,39 @@ function frameFromDosaiNode(node) {
   };
 }
 
+/**
+ * Whether this slice's ApiEndpoints carry a resolved route in `Path`.
+ *
+ * Schema 4.0.0 introduced `Path` as the resolved route ([controller] substituted, constraints
+ * stripped) alongside the verbatim `Route`. In every earlier schema `Path` is the **source file
+ * path**, so preferring it unconditionally emits file paths as service endpoints. cdxgen ships a
+ * pinned dosai via @cdxgen/cdxgen-plugins-bin and users can point DOSAI_CMD at any build, so both
+ * shapes are live and the version has to be checked.
+ *
+ * @param {Object} methodsSlice Parsed dosai methods slice JSON
+ * @returns {boolean} True when `Path` holds a resolved route
+ */
+function hasResolvedEndpointPaths(methodsSlice) {
+  const version = methodsSlice?.Metadata?.SchemaVersion;
+  if (typeof version !== "string") {
+    return false;
+  }
+  const major = Number.parseInt(version.split(".")[0], 10);
+  return Number.isFinite(major) && major >= 4;
+}
+
+/**
+ * Coerce a dosai string list into the array-of-strings shape serviceData.source/destination require.
+ * Returns undefined rather than an empty or malformed array so the key is omitted entirely.
+ */
+function toStringArray(value) {
+  if (!Array.isArray(value)) {
+    return undefined;
+  }
+  const strings = value.filter((entry) => typeof entry === "string" && entry);
+  return strings.length ? strings : undefined;
+}
+
 function appendUniqueProperty(properties, name, value) {
   if (value === undefined || value === null || value === "") {
     return;
@@ -219,6 +253,14 @@ export function runDosaiCommand(command, src, outputFile, options = {}) {
     shell: false,
   });
   if (dosaiSdkMessage(result)) {
+    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.",
+    });
     console.log(
       "Dotnet SDK is not installed. Please use the cdxgen dotnet container images to analyze this project with dosai.",
     );
@@ -348,7 +390,21 @@ export function persistDosaiSemanticsReport(
     return undefined;
   }
   const combined = buildCombinedDosaiReport(methodsSlice, dataFlowSlice);
-  safeWriteSync(durablePath, JSON.stringify(combined));
+  try {
+    safeWriteSync(durablePath, JSON.stringify(combined));
+  } catch (err) {
+    // Combined methods + data-flow reports for large solutions can exceed the
+    // JS maximum string length. The SBOM evidence is already collected by this
+    // point, so skip the durable copy instead of losing the whole analysis.
+    recordDegradation("dosai.semantics.persistFailed", {
+      ecosystem: "csharp",
+      tool: "dosai",
+      impact: "minor",
+      command: `persistDosaiSemanticsReport ${durablePath}`,
+      detail: `The combined dosai report could not be persisted: ${err.message}. The SBOM evidence is unaffected.`,
+    });
+    return undefined;
+  }
   return durablePath;
 }
 
@@ -498,6 +554,288 @@ export function collectDosaiDataFlowFrames(dataFlowResult, components = []) {
   return dataFlowFrames;
 }
 
+/**
+ * Consume dosai's AiComponents[] inventory (schema 4.0.0): model identifiers,
+ * on-disk model artifacts with hashes, MCP tools, prompts (redacted), and agents
+ * become CycloneDX machine-learning-model / data components with modelCard data.
+ *
+ * @param {Object} methodsSlice Parsed dosai methods slice JSON
+ * @param {Array} [components] Component list to mutate in place
+ * @returns {Array} The updated component list
+ */
+export function collectDosaiAiComponents(methodsSlice, components = []) {
+  for (const ai of methodsSlice?.AiComponents || []) {
+    if (!ai?.Id || !ai?.Name) {
+      continue;
+    }
+    if (components.some((c) => c["bom-ref"] === ai.Id)) {
+      continue;
+    }
+    if (ai.Kind === "model") {
+      const modelCard = {
+        modelParameters: {},
+      };
+      if (ai.Task) {
+        modelCard.modelParameters.task = ai.Task;
+      }
+      if (ai.ArchitectureFamily) {
+        modelCard.modelParameters.architectureFamily = ai.ArchitectureFamily;
+      }
+      if (ai.ModelArchitecture) {
+        // modelArchitecture lives under modelParameters; modelCard itself is
+        // additionalProperties:false, so placing it at the top level fails validation.
+        modelCard.modelParameters.modelArchitecture = ai.ModelArchitecture;
+      }
+      if (Array.isArray(ai.InputFormats) && ai.InputFormats.length) {
+        modelCard.modelParameters.inputs = ai.InputFormats.map((format) => ({
+          format,
+        }));
+      }
+      if (Array.isArray(ai.OutputFormats) && ai.OutputFormats.length) {
+        modelCard.modelParameters.outputs = ai.OutputFormats.map((format) => ({
+          format,
+        }));
+      }
+      const component = {
+        "bom-ref": ai.Id,
+        type: "machine-learning-model",
+        name: ai.Name,
+        version: ai.Version,
+        purl: ai.Purl,
+        modelCard,
+        properties: [
+          { name: "cdx:ai:provider", value: ai.Provider || "unknown" },
+          { name: "cdx:ai:deployment", value: ai.Deployment || "unknown" },
+        ],
+      };
+      if (ai.Sha256) {
+        component.hashes = [{ alg: "SHA-256", content: ai.Sha256 }];
+      }
+      if (ai.FilePath) {
+        component.properties.push({
+          name: "cdx:ai:modelFile",
+          value: ai.FilePath,
+        });
+      }
+      components.push(component);
+    } else if (ai.Kind === "prompt" || ai.Kind === "dataset") {
+      components.push({
+        "bom-ref": ai.Id,
+        type: "data",
+        name: ai.Name,
+        properties: [
+          { name: "cdx:ai:kind", value: ai.Kind },
+          ...(ai.PromptText
+            ? [{ name: "cdx:ai:promptText", value: ai.PromptText }]
+            : []),
+          ...Object.entries(ai.Properties || {}).map(([name, value]) => ({
+            name: `cdx:ai:${name}`,
+            value: String(value),
+          })),
+        ],
+      });
+    } else if (
+      ai.Kind === "tool" ||
+      ai.Kind === "agent" ||
+      ai.Kind === "guardrail" ||
+      ai.Kind === "embedding"
+    ) {
+      const properties = [
+        { name: "cdx:ai:kind", value: ai.Kind },
+        { name: "cdx:ai:provider", value: ai.Provider || "unknown" },
+      ];
+      if (ai.ToolSchema) {
+        properties.push({ name: "cdx:ai:toolSchema", value: ai.ToolSchema });
+      }
+      components.push({
+        "bom-ref": ai.Id,
+        type: "data",
+        name: ai.Name,
+        properties,
+      });
+    }
+  }
+  return components;
+}
+
+/**
+ * Consume dosai's first-class Services[] inventory (schema 4.0.0) directly: richer
+ * than deriving services from ApiEndpoints alone — stable bom-refs, trust zones,
+ * data classifications, providers, and per-service evidence occurrences.
+ *
+ * @param {Object} methodsSlice Parsed dosai methods slice JSON
+ * @param {Object} [servicesMap] Map of service key to service definition, mutated in place
+ * @returns {Object} The updated services map
+ */
+export function collectDosaiServiceComponents(methodsSlice, servicesMap = {}) {
+  for (const service of methodsSlice?.Services || []) {
+    if (!service?.Id || !service?.Name) {
+      continue;
+    }
+    const key = service.Id;
+    const definition = (servicesMap[key] ??= {
+      name: service.Name,
+      bomRef: service.Id,
+      endpoints: new Set(),
+      properties: [],
+    });
+    definition.group = definition.group || service.Group;
+    definition.version = definition.version || service.Version;
+    // The same service Id can appear in several Services[] entries (one per
+    // implementing type or call site). Scalar facts left unset by earlier
+    // entries must still be filled from later ones, in particular the
+    // outbound provider: an entry that is only inbound must not lock the
+    // definition into an anonymous egress.
+    if (
+      !definition.provider &&
+      service.Provider &&
+      service.Direction === "outbound"
+    ) {
+      definition.provider = { name: service.Provider };
+    }
+    if (typeof definition.authenticated === "undefined") {
+      definition.authenticated = service.Authenticated ?? undefined;
+    }
+    if (!definition.trustZone) {
+      definition.trustZone = service.TrustZone;
+    }
+    if (!definition["x-trust-boundary"]) {
+      definition["x-trust-boundary"] =
+        service.CrossesTrustBoundary === true ? true : undefined;
+    }
+    for (const endpoint of service.Endpoints || []) {
+      const sanitized = sanitizeEndpoint(endpoint);
+      if (sanitized) {
+        definition.endpoints.add(sanitized);
+      }
+    }
+    if (Array.isArray(service.Operations) && service.Operations.length) {
+      appendUniqueProperty(
+        definition.properties,
+        "cdx:dosai:operationCount",
+        service.Operations.length,
+      );
+      for (const operation of service.Operations) {
+        // Endpoints[] can miss routes that only Operations carry (e.g. gRPC and
+        // messaging operations resolved per method), so both are collected.
+        const sanitized = sanitizeEndpoint(operation.Path);
+        if (sanitized) {
+          definition.endpoints.add(sanitized);
+        }
+        // Verbs are small enum values; they keep the HTTP surface auditable
+        // per endpoint without copying request payloads.
+        appendUniqueProperty(
+          definition.properties,
+          "cdx:service:httpMethod",
+          operation.HttpMethod,
+        );
+        if (operation.RouteTemplate && operation.Path) {
+          appendUniqueProperty(
+            definition.properties,
+            "cdx:service:pathTemplate",
+            operation.RouteTemplate,
+          );
+        }
+      }
+    }
+    if (Array.isArray(service.Data) && service.Data.length) {
+      // First population of services[].data[] for .NET: flow + classification
+      // with auditable descriptions from dosai.
+      definition.data = (definition.data || []).concat(
+        service.Data
+          // `flow` and `classification` are both required by serviceData in the 1.7 schema; an entry
+          // missing either fails validation and would fail the whole BOM, so drop it instead.
+          .filter((entry) => entry?.Classification && entry?.Flow)
+          .map((entry) => ({
+            classification: entry.Classification,
+            // "unknown" is a legitimate dataFlowDirection member. Coercing it to "bi-directional"
+            // turned an absence of knowledge into a positive claim that data flows both ways.
+            flow: ["inbound", "outbound", "bi-directional", "unknown"].includes(
+              entry.Flow,
+            )
+              ? entry.Flow
+              : "unknown",
+            name: entry.Name,
+            description: entry.Description,
+            // source/destination are arrays of strings (iri-reference or BOM-link) in the schema.
+            source: toStringArray(entry.Source),
+            destination: toStringArray(entry.Destination),
+          })),
+      );
+    }
+    const properties = definition.properties;
+    appendUniqueProperty(properties, "cdx:service:kind", service.ServiceKind);
+    appendUniqueProperty(
+      properties,
+      "cdx:service:direction",
+      service.Direction,
+    );
+    appendUniqueProperty(
+      properties,
+      "cdx:service:framework",
+      service.Framework,
+    );
+    appendUniqueProperty(
+      properties,
+      "cdx:dosai:confidence",
+      service.Confidence,
+    );
+    for (const tag of service.Tags || []) {
+      appendUniqueProperty(properties, "cdx:dosai:tag", tag);
+    }
+    // Auth surface as counts and scheme categories only; policies, roles, and
+    // claim values never cross into the BOM verbatim.
+    appendUniqueProperty(
+      properties,
+      "cdx:dosai:allowAnonymous",
+      service.AllowAnonymous,
+    );
+    for (const scheme of service.AuthenticationSchemes || []) {
+      appendUniqueProperty(properties, "cdx:dosai:authScheme", scheme);
+    }
+    appendUniqueProperty(
+      properties,
+      "cdx:dosai:authorizationPolicyCount",
+      service.AuthorizationPolicies?.length,
+    );
+    appendUniqueProperty(
+      properties,
+      "cdx:dosai:roleCount",
+      service.Roles?.length,
+    );
+    if (service.Location?.Path) {
+      // Accumulate call sites: a service implemented across files must keep
+      // every occurrence, not just the last one processed.
+      definition.evidence ??= { occurrences: [] };
+      const location = {
+        path: service.Location.Path,
+        line: service.Location.LineNumber || undefined,
+        column: service.Location.ColumnNumber || undefined,
+      };
+      const occurrenceKey = `${location.path}#${location.line}#${location.column}`;
+      const knownOccurrences = definition.evidence.occurrences;
+      if (
+        !knownOccurrences.some(
+          (known) =>
+            `${known?.location?.path}#${known?.location?.line}#${known?.location?.column}` ===
+            occurrenceKey,
+        )
+      ) {
+        knownOccurrences.push({ location });
+      }
+      // services[].evidence is a CycloneDX 2.0 field that spec-version
+      // compatibility strips below 2.0, so the location also lands in a
+      // property where it survives at 1.6 and 1.7.
+      appendUniqueProperty(
+        definition.properties,
+        "cdx:dosai:location",
+        `${location.path}:${location.line || 0}:${location.column || 0}`,
+      );
+    }
+  }
+  return servicesMap;
+}
+
 /**
  * Infer service and endpoint definitions from a dosai methods slice.
  *
@@ -513,21 +851,40 @@ export function collectDosaiServicesFromMethods(
   methodsSlice,
   servicesMap = {},
 ) {
+  const resolvedPaths = hasResolvedEndpointPaths(methodsSlice);
   for (const endpoint of methodsSlice?.ApiEndpoints || []) {
-    const route = sanitizeEndpoint(endpoint.Route || endpoint.Path);
-    if (!route) {
+    // Endpoints owned by a provider service (ServiceId set and already
+    // collected) enrich the owner instead of being re-derived into a duplicate
+    // service. Their method and auth metadata still lands on the owner via the
+    // shared property recording below.
+    const ownedDefinition =
+      endpoint.ServiceId && servicesMap[endpoint.ServiceId]
+        ? servicesMap[endpoint.ServiceId]
+        : undefined;
+    // Schema 4.0.0: Path is the resolved route (tokens substituted, constraints
+    // stripped); Route keeps the verbatim template. Preferring Path is the fix for
+    // cdxgen discussion #4333, where [controller] shipped as %5Bcontroller%5D.
+    const route = sanitizeEndpoint(
+      resolvedPaths ? endpoint.Path || endpoint.Route : endpoint.Route,
+    );
+    if (!ownedDefinition && !route) {
       continue;
     }
-    const serviceName = serviceNameFromEndpoint(endpoint);
-    servicesMap[serviceName] ??= {
-      endpoints: new Set(),
-      authenticated: endpoint.AuthorizationRequired,
-      xTrustBoundary:
-        endpoint.AuthorizationRequired === true ? true : undefined,
-      properties: [],
-    };
-    servicesMap[serviceName].endpoints.add(route);
-    const properties = servicesMap[serviceName].properties;
+    let definition = ownedDefinition;
+    if (!definition) {
+      const serviceName = serviceNameFromEndpoint(endpoint);
+      definition = servicesMap[serviceName] ??= {
+        endpoints: new Set(),
+        authenticated: endpoint.AuthorizationRequired,
+        xTrustBoundary:
+          endpoint.AuthorizationRequired === true ? true : undefined,
+        properties: [],
+      };
+    }
+    if (route) {
+      definition.endpoints.add(route);
+    }
+    const properties = definition.properties;
     appendUniqueProperty(
       properties,
       "cdx:service:httpMethod",
@@ -571,13 +928,30 @@ export function collectDosaiServicesFromMethods(
     appendUniqueProperty(
       properties,
       "internal:SrcFile",
-      endpoint.Path || endpoint.FileName,
+      endpoint.FilePath || endpoint.FileName,
     );
     if (endpoint.LineNumber) {
       appendUniqueProperty(
         properties,
         "cdx:dosai:location",
-        `${endpoint.Path || endpoint.FileName}:${endpoint.LineNumber}:${endpoint.ColumnNumber || 0}`,
+        // Schema 4.0.0 renamed the ApiEndpoint source file field to FilePath;
+        // Path carries the resolved route there, not a location.
+        `${endpoint.FilePath || endpoint.FileName}:${endpoint.LineNumber}:${endpoint.ColumnNumber || 0}`,
+      );
+    }
+    if (endpoint.Route && endpoint.Path && endpoint.Route !== endpoint.Path) {
+      // The verbatim template (e.g. api/[controller]/{id:int}) alongside the resolved path.
+      appendUniqueProperty(
+        properties,
+        "cdx:service:pathTemplate",
+        endpoint.Route,
+      );
+    }
+    if (endpoint.Confidence) {
+      appendUniqueProperty(
+        properties,
+        "cdx:dosai:confidence",
+        endpoint.Confidence,
       );
     }
   }
@@ -591,11 +965,46 @@ export function collectDosaiServicesFromMethods(
  * @returns {Object[]} Array of service objects with sorted endpoint arrays and properties
  */
 export function normalizeDosaiServiceMap(servicesMap = {}) {
-  return Object.keys(servicesMap).map((serviceName) => ({
-    name: serviceName || `dosai-${basename(serviceName)}-service`,
-    endpoints: Array.from(servicesMap[serviceName].endpoints || []).sort(),
-    authenticated: servicesMap[serviceName].authenticated,
-    "x-trust-boundary": servicesMap[serviceName].xTrustBoundary,
-    properties: servicesMap[serviceName].properties,
-  }));
+  return Object.keys(servicesMap)
+    .map((serviceName) => {
+      const definition = servicesMap[serviceName];
+      const service = {
+        name:
+          definition.name ||
+          serviceName ||
+          `dosai-${basename(serviceName)}-service`,
+        endpoints: Array.from(definition.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
+        // new Services[] path sets the hyphenated CycloneDX key. Reading just the latter silently
+        // dropped the flag for all of them, including languages dosai has nothing to do with.
+        "x-trust-boundary":
+          definition["x-trust-boundary"] ?? definition.xTrustBoundary,
+        properties: definition.properties,
+      };
+      if (definition.bomRef) {
+        service["bom-ref"] = definition.bomRef;
+      }
+      if (definition.group) {
+        service.group = definition.group;
+      }
+      if (definition.version) {
+        service.version = definition.version;
+      }
+      if (definition.trustZone) {
+        service.trustZone = definition.trustZone;
+      }
+      if (definition.provider) {
+        service.provider = definition.provider;
+      }
+      if (definition.data) {
+        service.data = definition.data;
+      }
+      if (definition.evidence) {
+        service.evidence = definition.evidence;
+      }
+      return service;
+    })
+    .filter((service) => service.name);
 }