@cdxgen/cdxgen 13.4.0 → 13.6.0

package/lib/ecosystems/golem.js

@@ -15,7 +15,13 @@ import {
   reportPluginRunFailure,
   resolvePluginSourceDir,
 } from "../core/pluginRun.js";
+import {
+  encodeUriReference,
+  hasInlineCredential,
+  sanitizeBomUrl,
+} from "../core/propertySanitizer.js";
 import { resolvePluginBinary } from "../inventory/plugins.js";
+import { canonicalPurlFromLooseString } from "../inventory/purl.js";
 
 const GO_LANGUAGES = new Set(["go", "golang"]);
 const GOLEM_CALLGRAPH_MODES = new Set(["none", "static", "cha", "rta", "vta"]);
@@ -108,7 +114,38 @@ function purlWithoutVersion(purl) {
 }
 
 function modulePurl(module) {
-  return module?.purl || module?.PURL;
+  // cdxgen reports a module that a replace directive swapped out under the
+  // replacement's coordinates, which golem names as replace.purl. A directory
+  // replacement has none, and its versionless component matches module.purl.
+  return module?.replace?.purl || module?.purl || module?.PURL;
+}
+
+// The canonical form of every purl an alias map was asked about, so a report
+// naming one module in many usages parses its purl once.
+const purlMatchKeyCache = new WeakMap();
+
+/**
+ * The form two purls of one module share. Golem prints a module path as Go
+ * does, keeping its upper-case letters (github.com/BurntSushi/toml), while
+ * cdxgen components carry the canonical golang purl, which lower-cases them.
+ * Canonicalising both sides also reads an unescaped `+incompatible` like the
+ * escaped one.
+ *
+ * @param {string} purl A purl from the report or a component
+ * @param {Map} purlAliasMap The alias map the key belongs to
+ * @returns {string} The canonical purl, or the purl itself when it cannot be
+ *   parsed
+ */
+function purlMatchKey(purl, purlAliasMap) {
+  let cache = purlMatchKeyCache.get(purlAliasMap);
+  if (!cache) {
+    cache = new Map();
+    purlMatchKeyCache.set(purlAliasMap, cache);
+  }
+  if (!cache.has(purl)) {
+    cache.set(purl, canonicalPurlFromLooseString(purl) || purl);
+  }
+  return cache.get(purl);
 }
 
 function createPurlAliasMap(components = []) {
@@ -117,8 +154,9 @@ function createPurlAliasMap(components = []) {
     if (!component?.purl) {
       continue;
     }
-    purlAliasMap.set(component.purl, component.purl);
-    const noVersionPurl = purlWithoutVersion(component.purl);
+    const key = purlMatchKey(component.purl, purlAliasMap);
+    purlAliasMap.set(key, component.purl);
+    const noVersionPurl = purlWithoutVersion(key);
     if (noVersionPurl && !purlAliasMap.has(noVersionPurl)) {
       purlAliasMap.set(noVersionPurl, component.purl);
     }
@@ -130,7 +168,13 @@ function resolveComponentPurl(purl, purlAliasMap) {
   if (!purl) {
     return undefined;
   }
-  return purlAliasMap.get(purl) || purlAliasMap.get(purlWithoutVersion(purl));
+  const key = purlMatchKey(purl, purlAliasMap);
+  return (
+    purlAliasMap.get(key) ||
+    // A package subpath (`#internal`) names a part of the module.
+    purlAliasMap.get(key.split("#")[0]) ||
+    purlAliasMap.get(purlWithoutVersion(key))
+  );
 }
 
 function addResolvedPurl(purls, purl, purlAliasMap) {
@@ -1613,14 +1657,18 @@ export function isGolemGoLanguage(language) {
  *
  * @param {string} jsonFile Path to the golem JSON report.
  * @returns {object|undefined} Parsed report object, or undefined when the file
- *   is missing or cannot be parsed.
+ *   is missing, cannot be parsed, or holds something other than a JSON object
+ *   such as `null`.
  */
 export function readGolemJsonFile(jsonFile) {
   if (!jsonFile || !safeExistsSync(jsonFile)) {
     return undefined;
   }
   try {
-    return JSON.parse(readFileSync(jsonFile, "utf-8"));
+    const report = JSON.parse(readFileSync(jsonFile, "utf-8"));
+    return report && typeof report === "object" && !Array.isArray(report)
+      ? report
+      : undefined;
   } catch (_err) {
     return undefined;
   }
@@ -1831,3 +1879,499 @@ export function collectGolemEvidence(golemReport = {}, components = []) {
     purlLocationMap,
   };
 }
+
+// The methods a route can be registered for: the RFC 9110 methods, PATCH,
+// and the catch-all that gin's and echo's Any register.
+const GOLEM_HTTP_METHODS = new Set([
+  "get",
+  "head",
+  "post",
+  "put",
+  "delete",
+  "connect",
+  "options",
+  "trace",
+  "patch",
+  "any",
+]);
+
+// An RFC 9110 token, which is what net/http accepts as a pattern's method.
+const HTTP_METHOD_TOKEN = /^[!#$%&'*+.^_`|~0-9A-Za-z-]+$/;
+
+// The host of a net/http pattern: a name or address with an optional port.
+const GO_PATTERN_HOST = /^[A-Za-z0-9.:[\]-]+$/;
+
+// Hosts whose URL path carries the credential itself — webhook and bot URLs
+// that authenticate by the path alone — with the route each keeps. Everything
+// below that route, the team, channel and hook ids and the secret, is dropped.
+const GOLEM_SECRET_PATH_ROUTES = [
+  ["hooks.slack.com", ["/services/", "/workflows/", "/triggers/"]],
+  ["discord.com", ["/api/webhooks/"]],
+  ["discordapp.com", ["/api/webhooks/"]],
+  ["hooks.zapier.com", ["/hooks/catch/", "/hooks/standard/"]],
+  ["maker.ifttt.com", ["/trigger/"]],
+  ["api.telegram.org", ["/bot", "/file/bot"]],
+  ["outlook.office.com", ["/webhook/", "/webhookb2/"]],
+  ["webhook.office.com", ["/webhookb2/"]],
+];
+
+/**
+ * Append a property to a service definition unless the same name and value are
+ * already there, so repeated endpoints of one service do not repeat their
+ * framework or method.
+ *
+ * @param {Object[]} properties Property array, appended to in place
+ * @param {string} name Property name
+ * @param {string} value Property value, skipped unless a non-empty string
+ */
+function appendGolemServiceProperty(properties, name, value) {
+  if (typeof value !== "string" || !value) {
+    return;
+  }
+  if (
+    !properties.some((known) => known.name === name && known.value === value)
+  ) {
+    properties.push({ name, value });
+  }
+}
+
+/**
+ * The method a golem endpoint names, lower-cased the way the OpenAPI flow
+ * spells `cdx:service:httpMethod`, or undefined when it is not an HTTP
+ * method. golem takes the selector of a chained gorilla/mux call for the
+ * method, so `.Methods("GET", "POST")` arrives as `METHODS` and
+ * `.PathPrefix("/products")` as `PATHPREFIX`; neither names one.
+ *
+ * @param {unknown} method Method a golem endpoint reports
+ * @returns {string|undefined} The lower-cased method
+ */
+function golemHttpMethod(method) {
+  if (typeof method !== "string") {
+    return undefined;
+  }
+  const lowered = method.trim().toLowerCase();
+  return GOLEM_HTTP_METHODS.has(lowered) ? lowered : undefined;
+}
+
+/**
+ * The host a golem service names, without the `/` golem puts in front of a
+ * listener address that has a host (`/127.0.0.1:9095`) and without userinfo.
+ *
+ * @param {unknown} host Host a golem service reports
+ * @returns {string|undefined} The host
+ */
+function golemServiceHost(host) {
+  if (typeof host !== "string") {
+    return undefined;
+  }
+  return host.slice(host.lastIndexOf("@") + 1).replace(/^\/+/, "") || undefined;
+}
+
+/**
+ * Index of the brace that closes the one at `open`, counting nesting the way
+ * gorilla/mux's braceIndices does, so the `{3}` of `{code:[0-9]{3}}` stays
+ * inside the variable. -1 when the braces are unbalanced.
+ *
+ * @param {string} text Route path
+ * @param {number} open Index of an opening brace
+ * @returns {number} Index of the closing brace, or -1
+ */
+function closingBraceIndex(text, open) {
+  let depth = 0;
+  for (let index = open; index < text.length; index++) {
+    if (text[index] === "{") {
+      depth++;
+    } else if (text[index] === "}" && --depth === 0) {
+      return index;
+    }
+  }
+  return -1;
+}
+
+/**
+ * The OpenAPI spelling of a braced variable. gorilla/mux, chi and iris write
+ * `{name:pattern}`; Go 1.22 net/http writes `{name...}` for a trailing
+ * wildcard and `{$}` for an exact match of a trailing slash, which names no
+ * parameter and is dropped.
+ *
+ * @param {string} raw Text between the braces
+ * @returns {string} The placeholder
+ */
+function bracedPlaceholder(raw) {
+  let name = raw.split(":", 1)[0].trim();
+  if (name.endsWith("...")) {
+    name = name.slice(0, -3);
+  }
+  if (name === "$") {
+    return "";
+  }
+  return name ? `{${name}}` : `{${raw}}`;
+}
+
+/**
+ * The name of a `:name` parameter starting at `start` and the index after it.
+ * gin and echo end the name at the next `/`, so `:user-id` names `user-id`.
+ * fiber also ends it at `-` and `.`, which lets one segment hold two
+ * parameters (`:from-:to`), and allows a constraint and an optional marker
+ * after it (`:id<int>?`); both are dropped.
+ *
+ * @param {string} routePath Route path
+ * @param {number} start Index after the colon
+ * @param {boolean} fiber Whether the route is a fiber route
+ * @returns {{name: string, end: number}|undefined} The parameter
+ */
+function colonParameter(routePath, start, fiber) {
+  const stops = fiber ? "/-.<?" : "/<?";
+  let end = start;
+  while (end < routePath.length && !stops.includes(routePath[end])) {
+    end++;
+  }
+  const name = routePath.slice(start, end);
+  if (!name) {
+    return undefined;
+  }
+  if (routePath[end] === "<") {
+    const close = routePath.indexOf(">", end);
+    if (close >= 0) {
+      end = close + 1;
+    }
+  }
+  if (routePath[end] === "?") {
+    end++;
+  }
+  return { name, end };
+}
+
+/**
+ * Normalise a Go route path to the placeholder spelling OpenAPI — and
+ * therefore the rest of the services a BOM carries — uses. gin, echo and
+ * fiber write `:id`, gin writes `*filepath`, chi and gorilla/mux write `{id}`
+ * or `{id:[0-9]+}`, and Go 1.22's net/http patterns write `{id...}`; all
+ * become `{id}`. Braces are matched by depth, so a regular expression with
+ * its own braces or slashes (`{code:[0-9]{3}}`, `{rest:[a-z/]+}`) stays one
+ * variable. A fiber constraint or optional marker (`:id<int>`, `:name?`) is
+ * dropped, and net/http's `{$}` is removed. A `:` or `*` placeholder is only
+ * recognised at the start of a segment — or, for fiber, after a `-` or `.` —
+ * so a literal colon such as `/time/09:30` is left alone. Values that do not
+ * start with `/` are returned as they are, and so is echo's catch-all, whose
+ * bare `*` names no placeholder.
+ *
+ * @param {string} routePath Path a golem endpoint reports
+ * @param {string} [framework] Framework the route was registered with
+ * @returns {string} The normalised path
+ */
+export function normalizeGolemRoutePath(routePath, framework) {
+  if (typeof routePath !== "string" || !routePath.startsWith("/")) {
+    return routePath;
+  }
+  const fiber = framework === "fiber";
+  let normalized = "";
+  let index = 0;
+  while (index < routePath.length) {
+    const character = routePath[index];
+    const previous = routePath[index - 1];
+    if (character === "{") {
+      const close = closingBraceIndex(routePath, index);
+      if (close < 0) {
+        // gorilla/mux rejects unbalanced braces; keep the rest as written.
+        normalized += routePath.slice(index);
+        break;
+      }
+      normalized += bracedPlaceholder(routePath.slice(index + 1, close));
+      index = close + 1;
+      continue;
+    }
+    if (
+      character === ":" &&
+      (previous === "/" || (fiber && (previous === "-" || previous === ".")))
+    ) {
+      const parameter = colonParameter(routePath, index + 1, fiber);
+      if (parameter) {
+        normalized += `{${parameter.name}}`;
+        index = parameter.end;
+        continue;
+      }
+    }
+    if (character === "*" && previous === "/") {
+      let end = routePath.indexOf("/", index);
+      if (end < 0) {
+        end = routePath.length;
+      }
+      const name = routePath.slice(index + 1, end);
+      if (/^[A-Za-z0-9_]+$/.test(name)) {
+        normalized += `{${name}}`;
+        index = end;
+        continue;
+      }
+    }
+    normalized += character;
+    index++;
+  }
+  return normalized;
+}
+
+/**
+ * Split a route golem reports into the `[METHOD ][HOST]/PATH` parts of a Go
+ * 1.22 net/http ServeMux pattern. golem puts a `/` in front of the pattern it
+ * read, so `GET /items/{id}` arrives as `/GET /items/{id}` and
+ * `GET example.com/items` as `/GET example.com/items`. A method followed by a
+ * space or tab is split off, and so is a host between the method and the
+ * path. Without a method, only a value that starts with `/` is a route: the
+ * `:8080` a listener reports and the `GET` that a gorilla/mux
+ * `.Methods("GET")` call leaves behind are not, and give undefined. A host
+ * pattern without a method reaches golem's report as a plain path
+ * (`/example.com/items`) and stays one.
+ *
+ * @param {string} routePath Path a golem endpoint reports
+ * @returns {{method: (string|undefined), host: (string|undefined), path: string}|undefined}
+ *   The parts, or undefined when the value is not a route
+ */
+export function parseGolemRoutePattern(routePath) {
+  if (typeof routePath !== "string") {
+    return undefined;
+  }
+  const body = routePath.startsWith("/") ? routePath.slice(1) : routePath;
+  const gap = body.search(/[ \t]/);
+  if (gap > 0) {
+    const method = body.slice(0, gap);
+    const rest = body.slice(gap + 1).replace(/^[ \t]+/, "");
+    const slash = rest.indexOf("/");
+    if (HTTP_METHOD_TOKEN.test(method) && slash >= 0) {
+      const host = rest.slice(0, slash);
+      if (host && !GO_PATTERN_HOST.test(host)) {
+        return undefined;
+      }
+      return { method, host: host || undefined, path: rest.slice(slash) };
+    }
+  }
+  if (!routePath.startsWith("/")) {
+    return undefined;
+  }
+  return { method: undefined, host: undefined, path: routePath };
+}
+
+/**
+ * The route a golem endpoint of a server names: its CycloneDX endpoint, HTTP
+ * method and, for a host-specific net/http pattern, host. Undefined when the
+ * entry is not a route — the listener entry that repeats the address a server
+ * binds, the leftovers of a chained gorilla/mux call, or the `/PATCH` golem
+ * reports for gin's `Handle("PATCH", "/path")`, whose method it read as the
+ * path.
+ *
+ * @param {object} endpoint Endpoint a golem server service reports
+ * @param {object} service The service
+ * @returns {{endpoint: string, method: (string|undefined), host: (string|undefined)}|undefined}
+ *   The route
+ */
+function golemServerRoute(endpoint, service) {
+  const routePath = endpoint.path;
+  if (typeof routePath !== "string" || !routePath) {
+    return undefined;
+  }
+  const listener = golemServiceHost(service.host);
+  if (listener && routePath.replace(/^\//, "") === listener) {
+    return undefined;
+  }
+  const pattern = parseGolemRoutePattern(routePath);
+  if (!pattern) {
+    return undefined;
+  }
+  const method =
+    golemHttpMethod(endpoint.method) || golemHttpMethod(pattern.method);
+  if (
+    !method &&
+    /^\/[A-Z]+$/.test(pattern.path) &&
+    GOLEM_HTTP_METHODS.has(pattern.path.slice(1).toLowerCase())
+  ) {
+    return undefined;
+  }
+  const path = normalizeGolemRoutePath(
+    pattern.path,
+    endpoint.properties?.framework,
+  ).split(/[?#]/, 1)[0];
+  return {
+    endpoint: encodeUriReference(path),
+    method,
+    host: pattern.host,
+  };
+}
+
+/**
+ * Reduce an outbound URL golem reports to what is safe to keep in a BOM:
+ * scheme, host and path, without userinfo, query, fragment or `;name=value`
+ * path parameters such as `;jsessionid=` and `;token=`. Webhook and bot URLs
+ * that authenticate by their path — Slack, Discord, Teams, Zapier, IFTTT,
+ * Telegram — keep only their route (`https://hooks.slack.com/services`), and a
+ * path segment holding a token shape the BOM sanitizer recognises ends the
+ * path there. Undefined when the value is not a URL with a host.
+ *
+ * @param {string} value URL golem reports
+ * @returns {string|undefined} The sanitised URL
+ */
+export function sanitizeGolemEndpointUrl(value) {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  let parsed;
+  try {
+    // sanitizeBomUrl returns what it cannot parse as it is, which this parse
+    // then rejects.
+    parsed = new URL(sanitizeBomUrl(value));
+  } catch (_err) {
+    return undefined;
+  }
+  if (!parsed.host) {
+    return undefined;
+  }
+  const segments = [];
+  for (const segment of parsed.pathname.split("/").slice(1)) {
+    const bare = segment.split(";", 1)[0];
+    let decoded = bare;
+    try {
+      decoded = decodeURIComponent(bare);
+    } catch (_err) {
+      // A malformed escape is checked as written.
+    }
+    if (hasInlineCredential(decoded)) {
+      break;
+    }
+    segments.push(bare);
+  }
+  let path = `/${segments.join("/")}`;
+  for (const [host, routes] of GOLEM_SECRET_PATH_ROUTES) {
+    if (parsed.hostname !== host && !parsed.hostname.endsWith(`.${host}`)) {
+      continue;
+    }
+    const route = routes.find((prefix) => path.startsWith(prefix));
+    if (route) {
+      path = route.endsWith("/") ? route.slice(0, -1) : route;
+      break;
+    }
+  }
+  return encodeUriReference(`${parsed.protocol}//${parsed.host}${path}`);
+}
+
+/**
+ * The URL a golem endpoint of an external service names, sanitised, with its
+ * HTTP method. golem reports the full URL; a report without one has the
+ * service's scheme and host put in front of the path.
+ *
+ * @param {object} endpoint Endpoint a golem external service reports
+ * @param {object} service The service
+ * @returns {{endpoint: string, method: (string|undefined)}|undefined} The URL
+ */
+function golemExternalEndpoint(endpoint, service) {
+  let url = endpoint.url;
+  if (typeof url !== "string" || !url) {
+    const host = golemServiceHost(service.host);
+    if (
+      !host ||
+      typeof service.scheme !== "string" ||
+      typeof endpoint.path !== "string" ||
+      !endpoint.path.startsWith("/")
+    ) {
+      return undefined;
+    }
+    url = `${service.scheme}://${host}${endpoint.path}`;
+  }
+  const sanitized = sanitizeGolemEndpointUrl(url);
+  return sanitized
+    ? { endpoint: sanitized, method: golemHttpMethod(endpoint.method) }
+    : undefined;
+}
+
+/**
+ * Project the services and API endpoints of a golem report into evinse's
+ * service map, so a Go `evinse`/`saasbom` run lists its services the way the
+ * kosi (Kotlin) and dosai (.NET) collectors already do (#4498).
+ *
+ * golem rolls one service up per server it saw — a `gin` engine, a net/http
+ * listener on `:8080` — and lists the routes registered on it, each with its
+ * HTTP method and framework. Route paths are normalised to OpenAPI
+ * placeholders and Go 1.22 ServeMux patterns are split into method, host and
+ * path; entries that are not routes are skipped. It also rolls the outbound
+ * hosts the source calls into services of `kind: "external"`; those carry
+ * `x-trust-boundary: true`, since a host the application calls sits outside
+ * its own trust boundary, and their URLs are sanitised before they become
+ * endpoints. Every endpoint is percent-encoded to an RFC 3986 reference. The
+ * map is keyed by the golem service id, which is unique per server, while
+ * `name` carries the display name.
+ *
+ * HTTP methods are lower-cased to match the property values the OpenAPI flow
+ * emits, so a consumer grouping by `cdx:service:httpMethod` sees one value
+ * per method.
+ *
+ * @param {object|null} [golemReport={}] Parsed golem analysis report.
+ * @param {Object} [servicesMap={}] Service map to populate.
+ * @returns {Object} The service map
+ */
+export function collectGolemServices(golemReport = {}, servicesMap = {}) {
+  const services = Array.isArray(golemReport?.services)
+    ? golemReport.services
+    : [];
+  for (const service of services) {
+    const id = typeof service?.id === "string" ? service.id : undefined;
+    const name = typeof service?.name === "string" ? service.name : undefined;
+    if (!id && !name) {
+      continue;
+    }
+    const definition = (servicesMap[id || name] ??= {
+      name: name || id,
+      bomRef: id || name,
+      endpoints: new Set(),
+      properties: [],
+    });
+    const external = service.kind === "external";
+    if (external) {
+      definition["x-trust-boundary"] = true;
+    }
+    const endpoints = Array.isArray(service.endpoints) ? service.endpoints : [];
+    for (const endpoint of endpoints) {
+      if (!endpoint || typeof endpoint !== "object") {
+        continue;
+      }
+      const route = external
+        ? golemExternalEndpoint(endpoint, service)
+        : golemServerRoute(endpoint, service);
+      if (route) {
+        definition.endpoints.add(route.endpoint);
+        appendGolemServiceProperty(
+          definition.properties,
+          "cdx:service:httpMethod",
+          route.method,
+        );
+      }
+      appendGolemServiceProperty(
+        definition.properties,
+        "cdx:golem:service:framework",
+        endpoint.properties?.framework,
+      );
+      appendGolemServiceProperty(
+        definition.properties,
+        "cdx:golem:service:host",
+        route?.host,
+      );
+    }
+    appendGolemServiceProperty(
+      definition.properties,
+      "cdx:golem:service:kind",
+      service.kind,
+    );
+    appendGolemServiceProperty(
+      definition.properties,
+      "cdx:golem:service:scheme",
+      service.scheme,
+    );
+    appendGolemServiceProperty(
+      definition.properties,
+      "cdx:golem:service:host",
+      golemServiceHost(service.host),
+    );
+    appendGolemServiceProperty(
+      definition.properties,
+      "cdx:golem:service:package",
+      service.packagePath,
+    );
+  }
+  return servicesMap;
+}