@cdxgen/cdxgen 0.0.1 → 13.0.0

package/lib/inventory/dosaiParsers.js

@@ -0,0 +1,154 @@
+import { Purl } from "@cdxgen/cdx-purl";
+
+/**
+ * Build a lowercase type/namespace/name lookup key for a purl.
+ *
+ * Falls back to a stripped, lowercased form of the raw string when the purl
+ * cannot be parsed.
+ *
+ * @param {string} purl Package URL string
+ * @returns {string|undefined} Normalized key, or undefined when the input is empty or not a string
+ */
+export function normalizeDosaiPurlKey(purl) {
+  if (!purl || typeof purl !== "string") {
+    return undefined;
+  }
+  try {
+    const purlObj = Purl.parse(purl);
+    return [
+      purlObj.type?.toLowerCase(),
+      purlObj.namespace?.toLowerCase() || "",
+      purlObj.name?.toLowerCase(),
+    ].join("/");
+  } catch (_err) {
+    return purl.split("?")[0].split("#")[0].split("@")[0].toLowerCase();
+  }
+}
+
+/**
+ * Append a value to the Set stored under a key in a map, creating the Set when absent.
+ *
+ * @param {Object} map Map of key to Set of values, mutated in place
+ * @param {string} key Map key (usually a purl)
+ * @param {string} value Value to add; no-op when key or value is falsy
+ * @returns {void}
+ */
+export function addDosaiSetValue(map, key, value) {
+  if (!key || !value) {
+    return;
+  }
+  map[key] ??= new Set();
+  map[key].add(value);
+}
+
+/**
+ * Format a `file#line` location string from a dosai node or location item.
+ *
+ * @param {Object} item Dosai node, edge, or location object carrying Path/FileName and LineNumber fields
+ * @returns {string|undefined} Location string with a `#line` suffix when available, or undefined when no file is known
+ */
+export function dosaiLocation(item) {
+  const location = item?.Location || item?.CallLocation || item;
+  const fileName =
+    location?.Path || location?.FileName || item?.Path || item?.FileName;
+  if (!fileName || fileName === "<unknown>") {
+    return undefined;
+  }
+  const lineNumber = location?.LineNumber || item?.LineNumber;
+  if (lineNumber && lineNumber > 0) {
+    return `${fileName}#${lineNumber}`;
+  }
+  return fileName;
+}
+
+function dosaiSourceFileName(item) {
+  const location = item?.Location || item?.CallLocation || item;
+  return String(
+    location?.Path || location?.FileName || item?.Path || item?.FileName || "",
+  );
+}
+
+function dosaiSourceLineNumber(item) {
+  const location = item?.Location || item?.CallLocation || item;
+  return location?.LineNumber || item?.LineNumber;
+}
+
+/**
+ * Return a validated source location for .NET source extensions, from a call graph node.
+ *
+ * @param {Object} node Dosai call graph node object
+ * @returns {string|undefined} Location string, or undefined unless the file is .cs/.vb/.fs/.fsx/.r with a positive line number
+ */
+export function dosaiSourceLocationFromNode(node) {
+  const location = dosaiLocation(node);
+  const fileName = dosaiSourceFileName(node).toLowerCase();
+  const lineNumber = dosaiSourceLineNumber(node);
+  if (!location || !/\.(cs|vb|fs|fsx|r)$/i.test(fileName)) {
+    return undefined;
+  }
+  if (!lineNumber || lineNumber <= 0) {
+    return undefined;
+  }
+  return location;
+}
+
+/**
+ * Return a validated source location for .NET source extensions, from a location object.
+ *
+ * @param {Object} location Dosai location object carrying Path/FileName and LineNumber fields
+ * @returns {string|undefined} Location string, or undefined unless the file is .cs/.vb/.fs/.fsx/.r with a positive line number
+ */
+export function dosaiSourceLocation(location) {
+  const sourceLocation = dosaiLocation(location);
+  const fileName = dosaiSourceFileName(location);
+  const lineNumber = dosaiSourceLineNumber(location);
+  if (!sourceLocation || !/\.(cs|vb|fs|fsx|r)$/i.test(fileName)) {
+    return undefined;
+  }
+  if (!lineNumber || lineNumber <= 0) {
+    return undefined;
+  }
+  return sourceLocation;
+}
+
+/**
+ * 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.
+ *
+ * @param {Object[]} [components] Component objects with purl fields
+ * @returns {Map<string, string>} Map of purl or normalized key to canonical component purl
+ */
+export function buildDosaiPurlAliasMap(components = []) {
+  const purlAliasMap = 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);
+    }
+  }
+  return purlAliasMap;
+}
+
+/**
+ * Resolve a purl to the canonical component purl via the alias map.
+ *
+ * @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
+ */
+export function resolveDosaiComponentPurl(purl, purlAliasMap) {
+  if (!purl) {
+    return undefined;
+  }
+  return (
+    purlAliasMap.get(purl) ||
+    purlAliasMap.get(normalizeDosaiPurlKey(purl)) ||
+    purl
+  );
+}

package/lib/inventory/dynamic.js

@@ -0,0 +1,145 @@
+import { basename } from "node:path";
+
+import { checksumFile } from "../core/fs.js";
+import { mapWithConcurrency } from "../core/parallel.js";
+import { resolvePackageForFile } from "./osPackageResolver.js";
+import { applyPurl, tryBuildPurl } from "./purl.js";
+import { executeAndTrace, groupHttpEntriesToServices } from "./traceRunner.js";
+
+/**
+ * Builds a flat list of CycloneDX component objects and services by executing
+ * the given command and inspecting which shared libraries it loads at runtime
+ * and which HTTP URLs it accesses.
+ *
+ * Each component receives:
+ *  - type: "library"
+ *  - scope: "required"  (loaded at runtime — definitely required)
+ *  - hashes: SHA-256 of the on-disk file
+ *  - evidence.identity[].methods[].technique: "instrumentation"
+ *  - confidence: 0.8 when the OS package manager reports a version, 0.5 otherwise
+ *
+ * Services are detected from HTTP request URLs collected during tracing and
+ * follow the CycloneDX service schema with endpoints.
+ *
+ * @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
+ */
+export async function buildDynamicComponents(
+  commandStr,
+  workingDir,
+  traceOptions = {},
+) {
+  const result = await executeAndTrace(commandStr, workingDir, traceOptions);
+  const libPaths = result.libPaths || [];
+  const httpAccessEntries = result.httpAccessEntries || [];
+  const cryptoComponents = result.cryptoComponents || [];
+  const components = [];
+
+  const libHashes = await mapWithConcurrency(libPaths, (libPath) =>
+    checksumFile("sha256", libPath).catch(() => null),
+  );
+
+  for (let li = 0; li < libPaths.length; li++) {
+    const libPath = libPaths[li];
+    const fileHash = libHashes[li];
+    if (!fileHash) {
+      continue;
+    }
+
+    const pkgInfo = resolvePackageForFile(libPath);
+    let name = basename(libPath);
+    let version = "";
+    let purlStr = "";
+    let confidence = 0.5;
+
+    if (pkgInfo) {
+      name = pkgInfo.name;
+      version = pkgInfo.version || "";
+      confidence = version ? 0.8 : 0.5;
+
+      // pkgInfo.purl is already computed by resolvePackageForFile using the
+      // correct distro-aware namespace derived from /etc/os-release.
+      purlStr =
+        pkgInfo.purl ||
+        tryBuildPurl({
+          type: pkgInfo.type,
+          name: name,
+          version: version || null,
+          qualifiers: pkgInfo.arch ? { arch: pkgInfo.arch } : null,
+        });
+    } else {
+      // 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,
+      });
+    }
+
+    /** @type {Object} */
+    const component = {
+      name,
+      type: "library",
+      scope: "required",
+      hashes: [
+        {
+          alg: "SHA-256",
+          content: fileHash,
+        },
+      ],
+      properties: [
+        {
+          name: "cdx:dynamic:filePath",
+          value: libPath,
+        },
+      ],
+      evidence: {
+        identity: [
+          {
+            field: "purl",
+            confidence,
+            methods: [
+              {
+                technique: "instrumentation",
+                confidence,
+                value: purlStr,
+              },
+            ],
+          },
+        ],
+      },
+    };
+
+    if (version) {
+      component.version = version;
+    }
+    // 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.
+    applyPurl(component, purlStr);
+
+    components.push(component);
+  }
+
+  // Append cryptographic assets
+  for (const comp of cryptoComponents) {
+    components.push(comp);
+  }
+
+  // Build services from collected HTTP URLs
+  const servicesMap = groupHttpEntriesToServices(httpAccessEntries);
+  const services = Object.keys(servicesMap).map((serviceName) => {
+    const entry = servicesMap[serviceName];
+    return {
+      name: serviceName,
+      bomRef: `urn:service:dynamic:${serviceName}`,
+      endpoints: Array.from(entry.endpoints).sort(),
+      properties: entry.properties,
+    };
+  });
+
+  return { components, services };
+}