@cdxgen/cdxgen 0.0.1 → 13.0.0

package/lib/inventory/mcpDiscovery.js

@@ -0,0 +1,112 @@
+const PROVIDER_TEXT_PATTERNS = [
+  ["anthropic", /\banthropic\b|claude/i],
+  ["openai", /\bopenai\b|\bgpt-[a-z0-9-]+\b|\bo[13]\b/i],
+  ["google", /\bgemini\b|google(?:\s+ai)?/i],
+  ["mistral", /\bmistral\b/i],
+  ["deepseek", /\bdeepseek\b/i],
+  ["ollama", /\bollama\b/i],
+  ["groq", /\bgroq\b/i],
+];
+
+const INLINE_CREDENTIAL_PATTERNS = [
+  ["aws-access-key", /\bAKIA[0-9A-Z]{16}\b/u],
+  ["bearer-token", /\bbearer\s+[a-z0-9._-]{16,}\b/iu],
+  ["generic-secret", /\b(?:sk|rk|pk)_[a-z0-9_-]{8,}\b/iu],
+  ["github-token", /\bgh[pousr]_[a-z0-9]{20,}\b/iu],
+  ["google-api-key", /\bAIza[0-9A-Za-z_-]{20,}\b/u],
+];
+
+/**
+ * Normalize a string into a safe MCP reference token.
+ *
+ * NFKC-normalizes, lowercases, collapses separator runs, strips leading and
+ * trailing punctuation, and truncates to 128 characters, falling back to
+ * `unknown` for empty or dot-only results.
+ *
+ * @param {string} value Raw token value
+ * @returns {string} Sanitized reference token
+ */
+export function sanitizeMcpRefToken(value) {
+  const input = String(value || "")
+    .normalize("NFKC")
+    .trim()
+    .toLowerCase();
+  const normalized = input
+    .replaceAll(/[/\\:]/gu, "-")
+    .replaceAll(/[^a-z0-9._-]+/gu, "-")
+    .replaceAll(/[._-]{2,}/gu, "-")
+    .replaceAll(/^\.+|\.+$/gu, "")
+    .replaceAll(/^[._-]+|[._-]+$/gu, "");
+  if (!normalized || normalized === "." || normalized === "..") {
+    return "unknown";
+  }
+  return normalized.slice(0, 128);
+}
+
+/**
+ * Determine whether a hostname is local: `localhost`, loopback, link-local, or a private address range.
+ *
+ * @param {string} hostname Hostname or IP address
+ * @returns {boolean} `true` when the host resolves to a local or private address
+ */
+export function isLocalHost(hostname) {
+  const normalized = String(hostname || "").toLowerCase();
+  if (
+    !normalized ||
+    normalized === "localhost" ||
+    normalized === "127.0.0.1" ||
+    normalized === "::1"
+  ) {
+    return true;
+  }
+  if (
+    normalized.startsWith("10.") ||
+    normalized.startsWith("127.") ||
+    normalized.startsWith("169.254.") ||
+    normalized.startsWith("192.168.")
+  ) {
+    return true;
+  }
+  const octets = normalized.split(".");
+  if (
+    octets.length === 4 &&
+    octets[0] === "172" &&
+    Number(octets[1]) >= 16 &&
+    Number(octets[1]) <= 31
+  ) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Return the AI provider names whose detection patterns match the given text.
+ *
+ * @param {string} text Text to scan
+ * @returns {string[]} Matching provider names (e.g. `anthropic`, `openai`)
+ */
+export function providerNamesForText(text) {
+  return [
+    ...new Set(
+      PROVIDER_TEXT_PATTERNS.flatMap(([name, pattern]) =>
+        pattern.test(text) ? [name] : [],
+      ),
+    ),
+  ];
+}
+
+/**
+ * Return the credential-indicator names whose patterns match the given text.
+ *
+ * @param {string} text Text to scan
+ * @returns {string[]} Matching indicator names (e.g. `github-token`, `bearer-token`)
+ */
+export function credentialIndicatorsForText(text) {
+  return [
+    ...new Set(
+      INLINE_CREDENTIAL_PATTERNS.flatMap(([name, pattern]) =>
+        pattern.test(text) ? [name] : [],
+      ),
+    ),
+  ];
+}

package/lib/inventory/mcpPinning.js

@@ -0,0 +1,209 @@
+// Experimental, off-by-default MCP server pinning and composition enrichment.
+//
+// The CycloneDX working group's agent-BOM proposal is not yet a ratified
+// standard, so everything emitted here is gated behind an explicit opt-in and
+// namespaced under `cdx:mcp:` so the property names can be renamed or removed
+// mechanically when the standard lands. See docs/MCP.md (Gap analysis).
+//
+// The governing rule: an unpinned or unhashable MCP server must never serialise
+// as though it were pinned. Absence of a hash is represented explicitly, never
+// implied by the absence of a property.
+
+import { readEnvironmentVariable } from "../core/activity.js";
+import { createCitation, findCdxgenToolBomRef } from "./citations.js";
+
+const PINNING_PROPERTY = "cdx:mcp:pinning";
+const COMPOSITION_PROPERTY = "cdx:mcp:composition";
+const MCP_PACKAGE_FLAG = "cdx:mcp:package";
+const MCP_TRANSPORT_PROPERTY = "cdx:mcp:transport";
+
+/**
+ * @param {Object} component A CycloneDX component
+ * @returns {boolean} true when the component carries an MCP-package flag property
+ */
+function isMcpPackageComponent(component) {
+  return Boolean(
+    Array.isArray(component?.properties) &&
+      component.properties.some(
+        (property) =>
+          property?.name === MCP_PACKAGE_FLAG &&
+          String(property?.value).toLowerCase() === "true",
+      ),
+  );
+}
+
+function findProperty(component, name) {
+  return component?.properties?.find((property) => property?.name === name);
+}
+
+function setProperty(component, name, value) {
+  component.properties = component.properties || [];
+  const existing = component.properties.find(
+    (property) => property?.name === name,
+  );
+  if (existing) {
+    existing.value = value;
+    return;
+  }
+  component.properties.push({ name, value });
+}
+
+/**
+ * A package component is considered pinned when it carries at least one
+ * CycloneDX hash, or an ssri `_integrity` that downstream processing converts
+ * into a `hashes[]` entry.
+ *
+ * @param {Object} component A CycloneDX component
+ * @returns {boolean} true when the component is integrity-pinned
+ */
+function isPinnedComponent(component) {
+  if (Array.isArray(component?.hashes) && component.hashes.length > 0) {
+    return true;
+  }
+  return Boolean(component?._integrity);
+}
+
+/**
+ * Decide whether a discovered MCP service is a remote endpoint with no local
+ * package backing. Such servers are composition-unknown: a consumer must not
+ * mistake them for a fully-resolved local package.
+ *
+ * @param {Object} service A CycloneDX service
+ * @returns {boolean} true when the service is a remote, package-less MCP server
+ */
+function isRemotePackagelessService(service) {
+  if (!service || typeof service !== "object") {
+    return false;
+  }
+  const isMcpService =
+    Array.isArray(service.properties) &&
+    service.properties.some((property) =>
+      property?.name?.startsWith("cdx:mcp:"),
+    );
+  if (!isMcpService) {
+    return false;
+  }
+  // Config/source servers record their package references as a string property.
+  // An empty or absent list means no resolvable local package.
+  const packageRefs = findProperty(service, "cdx:mcp:packageRefs");
+  const hasPackageRefs =
+    packageRefs && String(packageRefs.value || "").trim().length > 0;
+  return !hasPackageRefs;
+}
+
+/**
+ * Index MCP service transports by the package names they reference, so package
+ * components can inherit the transport of the service they back.
+ *
+ * @param {Object[]} services CycloneDX services
+ * @returns {Map<string, string>} lower-cased package reference -> transport
+ */
+function indexServiceTransportsByPackage(services) {
+  const index = new Map();
+  for (const service of services || []) {
+    const transport = findProperty(service, MCP_TRANSPORT_PROPERTY)?.value;
+    const packageRefs = findProperty(service, "cdx:mcp:packageRefs");
+    if (!transport || !packageRefs) {
+      continue;
+    }
+    for (const token of String(packageRefs.value || "")
+      .split(/[\s,]+/)
+      .map((part) => part.trim().toLowerCase())
+      .filter(Boolean)) {
+      index.set(token, transport);
+    }
+  }
+  return index;
+}
+
+function packageNameTokens(component) {
+  const tokens = new Set();
+  if (component.name) {
+    tokens.add(String(component.name).toLowerCase());
+  }
+  if (component.purl) {
+    const match = /\/([^@/]+)@/.exec(String(component.purl));
+    if (match) {
+      tokens.add(match[1].toLowerCase());
+    }
+  }
+  return tokens;
+}
+
+/**
+ * Apply experimental MCP pinning/composition properties. Mutates `bomJson` in
+ * place and returns citation hints for the registry-attributed integrity. The
+ * caller is responsible for emitting citations only at spec version 1.7+.
+ *
+ * @param {Object} bomJson CycloneDX BOM
+ * @param {Object} [options] CLI options
+ * @returns {Object[]} Citation hints produced by the enrichment
+ */
+export function applyMcpPinningState(bomJson, options = {}) {
+  const enabled =
+    options?.experimentalMcpPinning === true ||
+    readEnvironmentVariable("CDXGEN_EXPERIMENTAL_MCP_PINNING") === "true";
+  if (!enabled || !bomJson) {
+    return [];
+  }
+  const pinnedNames = [];
+  const components = Array.isArray(bomJson.components)
+    ? bomJson.components
+    : [];
+  const services = Array.isArray(bomJson.services) ? bomJson.services : [];
+  const transportsByPackage = indexServiceTransportsByPackage(services);
+
+  for (const component of components) {
+    if (!isMcpPackageComponent(component)) {
+      continue;
+    }
+    const pinned = isPinnedComponent(component);
+    setProperty(component, PINNING_PROPERTY, pinned ? "pinned" : "unpinned");
+    if (pinned) {
+      pinnedNames.push(component.name);
+    }
+    // Inherit transport from any service that references this package.
+    if (!findProperty(component, MCP_TRANSPORT_PROPERTY)) {
+      for (const token of packageNameTokens(component)) {
+        if (transportsByPackage.has(token)) {
+          setProperty(
+            component,
+            MCP_TRANSPORT_PROPERTY,
+            transportsByPackage.get(token),
+          );
+          break;
+        }
+      }
+    }
+  }
+
+  // Remote, package-less MCP services are composition-unknown.
+  for (const service of services) {
+    if (isRemotePackagelessService(service)) {
+      setProperty(service, COMPOSITION_PROPERTY, "unknown");
+      setProperty(service, PINNING_PROPERTY, "unhashable");
+    }
+  }
+
+  if (!pinnedNames.length) {
+    return [];
+  }
+  // One citation covers every pinned package: the integrity values all come
+  // from the same place — the package registry, resolved by cdxgen's dependency
+  // pipeline — so a per-component citation would repeat one fact N times.
+  // Attribution names the cdxgen tool component, the only ref that exists in
+  // the BOM for this claim; without it there is nothing honest to point at and
+  // the citation is dropped rather than aimed at an invented ref.
+  const attributedTo = findCdxgenToolBomRef(bomJson);
+  if (!attributedTo) {
+    return [];
+  }
+  const citation = createCitation({
+    expressions: [
+      "$.components[?(@.properties[?(@.name == 'cdx:mcp:pinning' && @.value == 'pinned')])].hashes",
+    ],
+    attributedTo,
+    note: `Integrity for ${pinnedNames.length} pinned MCP package(s) resolved from the package registry.`,
+  });
+  return citation ? [citation] : [];
+}