@cdxgen/cdxgen 13.3.0 → 13.5.0

package/lib/inventory/dosaiParsers.js

@@ -1,5 +1,18 @@
+import { readFileSync } from "node:fs";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  relative,
+  resolve,
+  sep,
+  win32,
+} from "node:path";
+
 import { Purl } from "@cdxgen/cdx-purl";
 
+import { safeExistsSync } from "../core/fs.js";
+
 /**
  * Build a lowercase type/namespace/name lookup key for a purl.
  *
@@ -73,6 +86,62 @@ function dosaiSourceLineNumber(item) {
   return location?.LineNumber || item?.LineNumber;
 }
 
+/**
+ * Format the `file#line` location of a dosai MethodCalls row, relative to the
+ * scanned directory like dosai's source rows.
+ *
+ * A call site found in assembly IL names its file through the PDB. dosai 5
+ * writes it relative to the scan root and leaves Path out when the file has
+ * no place in the tree; dosai 4 writes the PDB path as it is: absolute for a
+ * local build, `/_/` for a deterministic one (owasp-dep-scan/dosai#79). An
+ * absolute path under the scanned directory is made relative to it, and any
+ * other build path, or a missing one, gives way to the file name, as for call
+ * graph edges, so both versions list a call site found in source and in IL
+ * once. Where no sequence point covers a call, the row names the assembly and
+ * its line is an IL offset, which is no source location.
+ *
+ * @param {Object} methodCall Dosai MethodCalls row
+ * @param {string} [srcPath] Directory dosai analyzed
+ * @returns {string|undefined} Location string, or undefined when the row names no source file
+ */
+export function dosaiCallSiteLocation(methodCall, srcPath) {
+  const file = dosaiCallSiteFile(methodCall, srcPath);
+  const lowerFile = file?.toLowerCase();
+  if (!file || lowerFile.endsWith(".dll") || lowerFile.endsWith(".exe")) {
+    return undefined;
+  }
+  const lineNumber = methodCall?.LineNumber;
+  return lineNumber > 0 ? `${file}#${lineNumber}` : file;
+}
+
+function dosaiCallSiteFile(methodCall, srcPath) {
+  const filePath = methodCall?.Path;
+  if (filePath && filePath !== "<unknown>") {
+    if (!isAbsolute(filePath) && !win32.isAbsolute(filePath)) {
+      return filePath;
+    }
+    if (srcPath && isAbsolute(filePath)) {
+      const relativePath = relative(resolve(srcPath), filePath);
+      if (
+        relativePath &&
+        relativePath !== ".." &&
+        !relativePath.startsWith(`..${sep}`) &&
+        !isAbsolute(relativePath)
+      ) {
+        return relativePath;
+      }
+    }
+  }
+  const fileName = methodCall?.FileName || filePath;
+  if (!fileName || fileName === "<unknown>") {
+    return undefined;
+  }
+  // dosai 4 kept a Windows build's whole path as the file name on Linux.
+  return fileName.slice(
+    Math.max(fileName.lastIndexOf("/"), fileName.lastIndexOf("\\")) + 1,
+  );
+}
+
 /**
  * Return a validated source location for .NET source extensions, from a call graph node.
  *
@@ -111,44 +180,270 @@ export function dosaiSourceLocation(location) {
   return sourceLocation;
 }
 
+/**
+ * Split a purl into its version-free identity key and its version.
+ *
+ * @param {string} purl Package URL string
+ * @returns {{key: string, version: (string|undefined)}|undefined} Parts, or undefined for an empty input
+ */
+function dosaiPurlParts(purl) {
+  const key = normalizeDosaiPurlKey(purl);
+  if (!key) {
+    return undefined;
+  }
+  let version;
+  try {
+    version = Purl.parse(purl).version || undefined;
+  } catch (_err) {
+    const at = purl.split("?")[0].split("#")[0].lastIndexOf("@");
+    version = at > 0 ? purl.slice(at + 1).split("?")[0] : undefined;
+  }
+  return { key, version };
+}
+
+/**
+ * The manifests a component was identified from, as recorded in its
+ * `internal:SrcFile` values.
+ *
+ * @param {Object} component BOM component
+ * @returns {string[]} Manifest paths as recorded
+ */
+function componentSrcFiles(component) {
+  const files = new Set();
+  for (const property of component?.properties || []) {
+    if (property?.name === "internal:SrcFile" && property.value) {
+      files.add(`${property.value}`);
+    }
+  }
+  return [...files];
+}
+
+/**
+ * Resolve a recorded manifest path. A BOM records it relative to the scanned
+ * directory, a scan in progress as found; a relative path that does not exist
+ * under the scanned directory is tried against the working directory.
+ *
+ * @param {string} file Manifest path as recorded
+ * @param {string} [srcPath] Scanned directory
+ * @returns {string} Absolute manifest path
+ */
+function resolveManifestPath(file, srcPath) {
+  if (isAbsolute(file)) {
+    return file;
+  }
+  const fromSrcPath = resolve(srcPath || ".", file);
+  if (!srcPath || safeExistsSync(fromSrcPath)) {
+    return fromSrcPath;
+  }
+  const fromCwd = resolve(file);
+  return safeExistsSync(fromCwd) ? fromCwd : fromSrcPath;
+}
+
+/**
+ * The project directory a .NET manifest belongs to. A project.assets.json
+ * names its project, which an artifacts layout keeps outside the `obj/`
+ * holding the file; otherwise it sits in the project's `obj/`, and the other
+ * manifests in the project directory.
+ *
+ * @param {string} file Absolute manifest path
+ * @returns {string} Absolute project directory
+ */
+function manifestProjectDir(file) {
+  const dir = dirname(file);
+  if (basename(file).toLowerCase() === "project.assets.json") {
+    try {
+      const projectPath = JSON.parse(readFileSync(file, "utf-8"))?.project
+        ?.restore?.projectPath;
+      const projectDir = projectPath && dirname(resolve(projectPath));
+      if (projectDir && safeExistsSync(projectDir)) {
+        return projectDir;
+      }
+    } catch (_err) {
+      // An unreadable file falls back to its location
+    }
+  }
+  return basename(dir) === "obj" ? dirname(dir) : dir;
+}
+
+/**
+ * The project directories a candidate's manifests belong to, worked out on
+ * first use: only a record that names a version the BOM lacks, of a package
+ * the BOM holds in several versions, needs them.
+ *
+ * @param {Object} candidate Candidate built by buildDosaiPurlAliasMap
+ * @param {Map<string, string>} purlAliasMap Alias map carrying srcPath and the directory cache
+ * @returns {string[]} Absolute project directories
+ */
+function candidateProjectDirs(candidate, purlAliasMap) {
+  if (!candidate.projectDirs) {
+    const dirs = new Set();
+    for (const file of candidate.srcFiles) {
+      const path = resolveManifestPath(file, purlAliasMap?.srcPath);
+      let dir = purlAliasMap?.projectDirCache?.get(path);
+      if (!dir) {
+        dir = manifestProjectDir(path);
+        purlAliasMap?.projectDirCache?.set(path, dir);
+      }
+      dirs.add(dir);
+    }
+    candidate.projectDirs = [...dirs];
+  }
+  return candidate.projectDirs;
+}
+
 /**
  * Build a purl alias map from BOM components.
  *
- * Maps both exact component purls and normalized type/namespace/name keys to
- * the canonical component purl so dosai-reported purls can be reconciled.
+ * Maps each component purl to itself, and indexes the components by their
+ * version-free identity, so a dosai-reported purl can be reconciled by version
+ * (see {@link resolveDosaiComponentPurl}). Two versions of one package are two
+ * components, and nothing here picks one of them on a name alone.
  *
  * @param {Object[]} [components] Component objects with purl fields
- * @returns {Map<string, string>} Map of purl or normalized key to canonical component purl
+ * @param {Object} [options] Options
+ * @param {string} [options.srcPath] Directory dosai analyzed, which its relative locations
+ *        and the BOM's relative manifest paths are relative to
+ * @returns {Map<string, string>} Map of purl to canonical component purl, carrying the identity index
  */
-export function buildDosaiPurlAliasMap(components = []) {
+export function buildDosaiPurlAliasMap(components = [], options = {}) {
   const purlAliasMap = new Map();
+  const candidatesByKey = new Map();
   for (const component of components) {
     if (!component?.purl) {
       continue;
     }
     purlAliasMap.set(component.purl, component.purl);
-    const key = normalizeDosaiPurlKey(component.purl);
-    if (key && !purlAliasMap.has(key)) {
-      purlAliasMap.set(key, component.purl);
+    const parts = dosaiPurlParts(component.purl);
+    if (!parts) {
+      continue;
+    }
+    const candidates = candidatesByKey.get(parts.key) || [];
+    const existing = candidates.find(
+      (candidate) => candidate.purl === component.purl,
+    );
+    if (existing) {
+      for (const file of componentSrcFiles(component)) {
+        if (!existing.srcFiles.includes(file)) {
+          existing.srcFiles.push(file);
+        }
+      }
+    } else {
+      candidates.push({
+        purl: component.purl,
+        version: parts.version,
+        srcFiles: componentSrcFiles(component),
+      });
     }
+    candidatesByKey.set(parts.key, candidates);
   }
+  purlAliasMap.candidatesByKey = candidatesByKey;
+  purlAliasMap.srcPath = options.srcPath;
+  purlAliasMap.projectDirCache = new Map();
   return purlAliasMap;
 }
 
 /**
- * Resolve a purl to the canonical component purl via the alias map.
+ * The candidate whose project directory is the nearest one holding a file.
+ *
+ * @param {Object[]} candidates Candidates of one package identity
+ * @param {string} location Location string (`path` or `path#line`), relative to srcPath or absolute
+ * @param {Map<string, string>} purlAliasMap Alias map built by buildDosaiPurlAliasMap
+ * @returns {string|undefined} Candidate purl, or undefined when no single candidate is nearest
+ */
+function candidateForLocation(candidates, location, purlAliasMap) {
+  if (!location) {
+    return undefined;
+  }
+  const file = resolve(
+    purlAliasMap?.srcPath || ".",
+    `${location}`.split("#")[0],
+  );
+  let best;
+  let bestLength = -1;
+  let tied = false;
+  for (const candidate of candidates) {
+    for (const dir of candidateProjectDirs(candidate, purlAliasMap)) {
+      if (file !== dir && !file.startsWith(`${dir}${sep}`)) {
+        continue;
+      }
+      if (dir.length > bestLength) {
+        best = candidate.purl;
+        bestLength = dir.length;
+        tied = false;
+      } else if (dir.length === bestLength && best !== candidate.purl) {
+        tied = true;
+      }
+    }
+  }
+  return tied ? undefined : best;
+}
+
+/**
+ * Choose among the components that share a file name (two versions of a
+ * package ship the same DLLs): the only one, else the one whose project
+ * directory is nearest the record's location.
+ *
+ * @param {Iterable<string>} purls Candidate component purls
+ * @param {Map<string, string>} purlAliasMap Alias map built by buildDosaiPurlAliasMap
+ * @param {string} [location] Source location of the dosai record (`path` or `path#line`)
+ * @returns {string|undefined} The component purl, or undefined when it cannot be told
+ */
+export function pickDosaiComponentByLocation(purls, purlAliasMap, location) {
+  const wanted = new Set(purls);
+  if (wanted.size <= 1) {
+    return [...wanted][0];
+  }
+  const candidates = [];
+  for (const list of purlAliasMap?.candidatesByKey?.values() || []) {
+    for (const candidate of list) {
+      if (wanted.has(candidate.purl)) {
+        candidates.push(candidate);
+      }
+    }
+  }
+  return candidateForLocation(candidates, location, purlAliasMap);
+}
+
+/**
+ * Resolve a dosai-reported purl to a BOM component purl.
+ *
+ * The exact purl wins, then the same package at the same version (ids compare
+ * case-insensitively). A versionless purl, or a version the BOM does not hold,
+ * maps to the package's only component when it has one. When the BOM holds
+ * several versions, the record's location picks the version of the project
+ * that file belongs to; without a location that settles it the purl maps to
+ * nothing rather than to an arbitrary version (issue dosai#72).
  *
  * @param {string} purl Purl reported by dosai
  * @param {Map<string, string>} purlAliasMap Alias map built by buildDosaiPurlAliasMap
- * @returns {string|undefined} Canonical component purl, the input purl when unaliased, or undefined when empty
+ * @param {string} [location] Source location of the dosai record (`path` or `path#line`)
+ * @returns {string|undefined} Canonical component purl, the input purl when the BOM has no
+ *          component of that package, or undefined when empty or ambiguous
  */
-export function resolveDosaiComponentPurl(purl, purlAliasMap) {
+export function resolveDosaiComponentPurl(purl, purlAliasMap, location) {
   if (!purl) {
     return undefined;
   }
-  return (
-    purlAliasMap.get(purl) ||
-    purlAliasMap.get(normalizeDosaiPurlKey(purl)) ||
-    purl
-  );
+  const exact = purlAliasMap?.get(purl);
+  if (exact) {
+    return exact;
+  }
+  const parts = dosaiPurlParts(purl);
+  const candidates = parts && purlAliasMap?.candidatesByKey?.get(parts.key);
+  if (!candidates?.length) {
+    return purl;
+  }
+  if (parts.version) {
+    const sameVersion = candidates.filter(
+      (candidate) =>
+        candidate.version?.toLowerCase() === parts.version.toLowerCase(),
+    );
+    if (sameVersion.length === 1) {
+      return sameVersion[0].purl;
+    }
+  }
+  if (candidates.length === 1) {
+    return candidates[0].purl;
+  }
+  return candidateForLocation(candidates, location, purlAliasMap);
 }

package/lib/inventory/dynamic.js

@@ -4,8 +4,37 @@ import { checksumFile } from "../core/fs.js";
 import { mapWithConcurrency } from "../core/parallel.js";
 import { resolvePackageForFile } from "./osPackageResolver.js";
 import { applyPurl, tryBuildPurl } from "./purl.js";
+import {
+  cryptoLibrariesByPath,
+  normalizeTracedCryptoComponents,
+  observedChainComponents,
+} from "./tracedCrypto.js";
 import { executeAndTrace, groupHttpEntriesToServices } from "./traceRunner.js";
 
+/**
+ * Converts a traced library path into a purl subpath. Windows paths
+ * ("C:\Windows\System32\bcrypt.dll", "\\server\share\x.dll") use forward
+ * slashes and drop the drive or UNC prefix, which a purl subpath cannot carry;
+ * the full path stays in the cdx:dynamic:filePath property.
+ *
+ * @param {string} libPath - Absolute path of the loaded library
+ * @returns {string|null} Subpath without leading separators, or null
+ */
+export function librarySubpath(libPath) {
+  if (!libPath) {
+    return null;
+  }
+  let subpath = libPath;
+  const isDrivePath = /^[A-Za-z]:[\\/]/.test(subpath);
+  if (isDrivePath || subpath.startsWith("\\\\")) {
+    subpath = subpath.replaceAll("\\", "/");
+    if (isDrivePath) {
+      subpath = subpath.substring(3);
+    }
+  }
+  return subpath.replace(/^\/+/, "") || null;
+}
+
 /**
  * Builds a flat list of CycloneDX component objects and services by executing
  * the given command and inspecting which shared libraries it loads at runtime
@@ -21,10 +50,14 @@ import { executeAndTrace, groupHttpEntriesToServices } from "./traceRunner.js";
  * Services are detected from HTTP request URLs collected during tracing and
  * follow the CycloneDX service schema with endpoints.
  *
+ * The certificate chains servers presented in TLS ≤ 1.2 handshakes become the
+ * shared certificate model, with `provides` edges from the TLS protocol
+ * components.
+ *
  * @param {string} commandStr - Shell command to execute and trace (e.g. "node --version")
  * @param {string} workingDir - Working directory for the traced process
  * @param {Object} [traceOptions] - Additional sandbox options forwarded to executeAndTrace
- * @returns {Promise<{components: Array<Object>, services: Array<Object>}>} Components and services
+ * @returns {Promise<{components: Array<Object>, services: Array<Object>, dependencies: Array<Object>}>} Components, services and dependencies
  */
 export async function buildDynamicComponents(
   commandStr,
@@ -32,7 +65,12 @@ export async function buildDynamicComponents(
   traceOptions = {},
 ) {
   const result = await executeAndTrace(commandStr, workingDir, traceOptions);
-  const libPaths = result.libPaths || [];
+  // A crypto library is a loaded library too, even when library tracing
+  // missed it.
+  const cryptoLibraries = cryptoLibrariesByPath(result.cryptoEntries);
+  const libPaths = Array.from(
+    new Set([...(result.libPaths || []), ...cryptoLibraries.keys()]),
+  );
   const httpAccessEntries = result.httpAccessEntries || [];
   const egressEntries = result.egressEntries || [];
   const cryptoComponents = result.cryptoComponents || [];
@@ -50,7 +88,10 @@ export async function buildDynamicComponents(
     }
 
     const pkgInfo = resolvePackageForFile(libPath);
-    let name = basename(libPath);
+    const cryptoLibrary = cryptoLibraries.get(libPath);
+    // The subpath uses forward slashes, so this also names a Windows DLL
+    // correctly when the BOM is built on another host.
+    let name = basename(librarySubpath(libPath) || libPath);
     let version = "";
     let purlStr = "";
     let confidence = 0.5;
@@ -71,12 +112,16 @@ export async function buildDynamicComponents(
           qualifiers: pkgInfo.arch ? { arch: pkgInfo.arch } : null,
         });
     } else {
+      // A crypto library's version is its file version (Windows reports one
+      // for each DLL it classifies).
+      version = cryptoLibrary?.version || "";
       // Fall back to a generic purl carrying the file path as a subpath. It was
       // previously a `path` qualifier, which generic does not permit.
       purlStr = tryBuildPurl({
         type: "generic",
         name: name,
-        subpath: libPath ? libPath.replace(/^\/+/, "") : null,
+        version: version || null,
+        subpath: librarySubpath(libPath),
       });
     }
 
@@ -117,6 +162,12 @@ export async function buildDynamicComponents(
     if (version) {
       component.version = version;
     }
+    if (cryptoLibrary) {
+      component.properties.push({
+        name: "cdx:dynamic:cryptoLibrary",
+        value: cryptoLibrary.name,
+      });
+    }
     // applyPurl sets a unique fallback bom-ref when no valid purl exists, so a
     // library that cannot be expressed as a purl still participates correctly in
     // the dependency graph.
@@ -126,9 +177,41 @@ export async function buildDynamicComponents(
   }
 
   // Append cryptographic assets
-  for (const comp of cryptoComponents) {
+  const normalizedCryptoComponents =
+    normalizeTracedCryptoComponents(cryptoComponents);
+  // The chains servers presented in TLS ≤ 1.2 handshakes become the shared
+  // certificate model, linked from the TLS protocol components.
+  const protocolRefs = new Set(
+    normalizedCryptoComponents
+      .filter((comp) => comp.cryptoProperties?.assetType === "protocol")
+      .map((comp) => comp["bom-ref"]),
+  );
+  const observedModel = observedChainComponents(
+    result.cryptoResult,
+    protocolRefs,
+  );
+  // The traced CBOM names post-quantum algorithms after crypto-oid.json
+  // (ml-dsa-44) while the certificate model follows PLAN section 2.5
+  // (ML-DSA-44); one OID must still be one component, and the certificates
+  // reference the model's name, so a traced duplicate yields to it.
+  const observedAlgorithmOids = new Set(
+    observedModel.components
+      .filter((comp) => comp.cryptoProperties?.assetType === "algorithm")
+      .map((comp) => comp.cryptoProperties.oid),
+  );
+  for (const comp of normalizedCryptoComponents) {
+    if (
+      comp.cryptoProperties?.assetType === "algorithm" &&
+      observedAlgorithmOids.has(comp.cryptoProperties.oid)
+    ) {
+      continue;
+    }
+    components.push(comp);
+  }
+  for (const comp of observedModel.components) {
     components.push(comp);
   }
+  const dependencies = observedModel.dependencies;
 
   // Build services from collected HTTP URLs
   const servicesMap = groupHttpEntriesToServices(httpAccessEntries);
@@ -136,7 +219,7 @@ export async function buildDynamicComponents(
     const entry = servicesMap[serviceName];
     return {
       name: serviceName,
-      bomRef: `urn:service:dynamic:${serviceName}`,
+      "bom-ref": `urn:service:dynamic:${serviceName}`,
       endpoints: Array.from(entry.endpoints).sort(),
       properties: entry.properties,
     };
@@ -154,7 +237,7 @@ export async function buildDynamicComponents(
     if (!svc) {
       svc = {
         name,
-        bomRef: `urn:service:dynamic:${name}`,
+        "bom-ref": `urn:service:dynamic:${name}`,
         endpoints: [],
         properties: [],
       };
@@ -179,5 +262,10 @@ export async function buildDynamicComponents(
     }
   }
 
-  return { components, services, dryRunSummary: result.dryRunSummary };
+  return {
+    components,
+    services,
+    dependencies,
+    dryRunSummary: result.dryRunSummary,
+  };
 }