@cdxgen/cdxgen 0.0.1 → 13.0.0

package/lib/inventory/lolbas.js

@@ -0,0 +1,285 @@
+import { readFileSync } from "node:fs";
+import path, { basename } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const LOLBAS_INDEX_FILE = fileURLToPath(
+  new URL("../../data/lolbas-index.json", import.meta.url),
+);
+const LOLBAS_REFERENCE_PREFIX =
+  "https://lolbas-project.github.io/lolbas/Binaries/";
+const DIRECT_ALIASES = new Map([
+  ["bitsadmin", "bitsadmin.exe"],
+  ["certutil", "certutil.exe"],
+  ["cmd", "cmd.exe"],
+  ["cmdkey", "cmdkey.exe"],
+  ["cmstp", "cmstp.exe"],
+  ["cscript", "cscript.exe"],
+  ["ftp", "ftp.exe"],
+  ["installutil", "installutil.exe"],
+  ["msbuild", "msbuild.exe"],
+  ["mshta", "mshta.exe"],
+  ["msiexec", "msiexec.exe"],
+  ["odbcconf", "odbcconf.exe"],
+  ["powershell", "powershell.exe"],
+  ["pwsh", "pwsh.exe"],
+  ["regsvr32", "regsvr32.exe"],
+  ["rundll32", "rundll32.exe"],
+  ["wmic", "wmic.exe"],
+  ["wscript", "wscript.exe"],
+]);
+const MATCH_FIELDS = [
+  "action",
+  "arguments",
+  "cmdline",
+  "command",
+  "command_line",
+  "command_line_template",
+  "description",
+  "display_name",
+  "executable",
+  "name",
+  "path",
+  "program",
+  "source",
+];
+const CATEGORY_MATCH_FIELDS = {
+  appcompat_shims: ["executable", "path", "sdb_path"],
+  listening_ports: ["cmdline", "name", "path"],
+  process_open_handles_snapshot: ["cmdline", "name", "path"],
+  processes: ["cmdline", "name", "path"],
+  scheduled_tasks: ["action"],
+  services_snapshot: ["module_path", "path"],
+  startup_items: ["path"],
+  windows_run_keys: ["description", "name"],
+  wmi_cli_event_consumers: ["command_line_template", "command_line", "name"],
+  wmi_cli_event_consumers_snapshot: [
+    "command_line_template",
+    "command_line",
+    "name",
+  ],
+};
+const STANDALONE_COMMAND_PATTERN =
+  /\b(bitsadmin|certutil|cmd|cmdkey|cmstp|cscript|ftp|installutil|msbuild|mshta|msiexec|odbcconf|powershell|pwsh|regsvr32|rundll32|wmic|wscript)\b/gi;
+const WINDOWS_EXECUTABLE_PATTERN =
+  /(?:[a-z]:\\[^\s"'`,;|]+|\\\\[^\s"'`,;|]+|[a-z0-9._-]+)\.(?:exe|cmd|bat|dll|hta|js|jse|ps1|vbs|vbe|wsf|wsh)\b/gi;
+
+const LOLBAS_INDEX = loadLolbasIndex();
+
+function loadLolbasIndex() {
+  try {
+    return JSON.parse(readFileSync(LOLBAS_INDEX_FILE, "utf8"));
+  } catch {
+    return { entries: {}, source: "", sourceRef: "" };
+  }
+}
+
+function normalizeCandidate(candidate) {
+  if (!candidate || typeof candidate !== "string") {
+    return undefined;
+  }
+  const trimmed = candidate
+    .trim()
+    .replace(/^["']|["']$/g, "")
+    .replace(/\\/g, "/");
+  if (!trimmed) {
+    return undefined;
+  }
+  return basename(trimmed).toLowerCase();
+}
+
+function uniqueSortedStrings(values) {
+  return Array.from(
+    new Set(
+      values.filter(
+        (value) => typeof value === "string" && value.trim().length,
+      ),
+    ),
+  ).sort();
+}
+
+function resolveLolbasCandidate(candidate) {
+  const normalized = normalizeCandidate(candidate);
+  if (!normalized) {
+    return undefined;
+  }
+  if (LOLBAS_INDEX.entries?.[normalized]) {
+    return normalized;
+  }
+  const alias = DIRECT_ALIASES.get(normalized);
+  if (alias && LOLBAS_INDEX.entries?.[alias]) {
+    return alias;
+  }
+  return undefined;
+}
+
+function deriveRiskTags(entry) {
+  const riskTags = new Set(entry?.riskTags || []);
+  const functions = new Set(entry?.functions || []);
+  const contexts = new Set(entry?.contexts || []);
+  if (
+    functions.has("proxy-execution") ||
+    functions.has("library-load") ||
+    functions.has("script-execution")
+  ) {
+    riskTags.add("proxy-execution");
+  }
+  if (
+    functions.has("download") ||
+    functions.has("upload") ||
+    functions.has("credential-access")
+  ) {
+    riskTags.add("high-signal");
+  }
+  if (contexts.has("uac-bypass")) {
+    riskTags.add("uac-bypass");
+  }
+  if (functions.has("download") || functions.has("upload")) {
+    riskTags.add("network-transfer");
+  }
+  return Array.from(riskTags).sort();
+}
+
+function collectValueCandidates(value) {
+  if (!value || typeof value !== "string") {
+    return [];
+  }
+  const candidates = new Set();
+  for (const match of value.matchAll(WINDOWS_EXECUTABLE_PATTERN)) {
+    candidates.add(match[0]);
+  }
+  for (const match of value.matchAll(STANDALONE_COMMAND_PATTERN)) {
+    candidates.add(match[1]);
+  }
+  return Array.from(candidates);
+}
+
+/**
+ * Resolve LOLBAS metadata for a binary or script name.
+ *
+ * @param {string} candidate Binary or script path/name
+ * @returns {object|undefined} Matched LOLBAS metadata
+ */
+export function getLolbasMetadata(candidate) {
+  const canonicalName = resolveLolbasCandidate(candidate);
+  if (!canonicalName) {
+    return undefined;
+  }
+  const entry = LOLBAS_INDEX.entries[canonicalName];
+  return {
+    attackTactics: uniqueSortedStrings(entry.attackTactics || []),
+    attackTechniques: uniqueSortedStrings(entry.attackTechniques || []),
+    canonicalName,
+    contexts: uniqueSortedStrings(entry.contexts || []),
+    functions: uniqueSortedStrings(entry.functions || []),
+    reference:
+      entry.reference ||
+      `${LOLBAS_REFERENCE_PREFIX}${encodeURIComponent(path.parse(canonicalName).name)}/`,
+    riskTags: deriveRiskTags(entry),
+    source: LOLBAS_INDEX.source,
+    sourceRef: LOLBAS_INDEX.sourceRef,
+  };
+}
+
+/**
+ * Resolve LOLBAS properties for an osquery row.
+ *
+ * @param {string} queryCategory Osquery query category
+ * @param {object} row Osquery row
+ * @returns {Array<object>} CycloneDX custom properties
+ */
+export function createLolbasProperties(queryCategory, row) {
+  const matches = new Map();
+  const matchFieldsForCategory =
+    CATEGORY_MATCH_FIELDS[queryCategory] || MATCH_FIELDS;
+  for (const field of matchFieldsForCategory) {
+    const fieldValue = row?.[field];
+    if (!fieldValue) {
+      continue;
+    }
+    for (const candidate of collectValueCandidates(String(fieldValue))) {
+      const metadata = getLolbasMetadata(candidate);
+      if (!metadata) {
+        continue;
+      }
+      const existing = matches.get(metadata.canonicalName) || {
+        fields: new Set(),
+        metadata,
+      };
+      existing.fields.add(field);
+      matches.set(metadata.canonicalName, existing);
+    }
+  }
+  if (!matches.size) {
+    return [];
+  }
+  const attackTactics = uniqueSortedStrings(
+    Array.from(matches.values()).flatMap(
+      (match) => match.metadata.attackTactics,
+    ),
+  );
+  const attackTechniques = uniqueSortedStrings(
+    Array.from(matches.values()).flatMap(
+      (match) => match.metadata.attackTechniques,
+    ),
+  );
+  const contexts = uniqueSortedStrings(
+    Array.from(matches.values()).flatMap((match) => match.metadata.contexts),
+  );
+  const functions = uniqueSortedStrings(
+    Array.from(matches.values()).flatMap((match) => match.metadata.functions),
+  );
+  const references = uniqueSortedStrings(
+    Array.from(matches.values()).map((match) => match.metadata.reference),
+  );
+  const riskTags = uniqueSortedStrings(
+    Array.from(matches.values()).flatMap((match) => match.metadata.riskTags),
+  );
+  const matchFields = uniqueSortedStrings(
+    Array.from(matches.values()).flatMap((match) => Array.from(match.fields)),
+  );
+  const names = uniqueSortedStrings(Array.from(matches.keys()));
+  const properties = [
+    { name: "cdx:lolbas:matched", value: "true" },
+    { name: "cdx:lolbas:names", value: names.join(",") },
+    { name: "cdx:lolbas:matchFields", value: matchFields.join(",") },
+    { name: "cdx:lolbas:queryCategory", value: queryCategory },
+    { name: "cdx:lolbas:sourceRef", value: LOLBAS_INDEX.sourceRef || "" },
+  ];
+  if (functions.length) {
+    properties.push({
+      name: "cdx:lolbas:functions",
+      value: functions.join(","),
+    });
+  }
+  if (contexts.length) {
+    properties.push({
+      name: "cdx:lolbas:contexts",
+      value: contexts.join(","),
+    });
+  }
+  if (riskTags.length) {
+    properties.push({
+      name: "cdx:lolbas:riskTags",
+      value: riskTags.join(","),
+    });
+  }
+  if (attackTactics.length) {
+    properties.push({
+      name: "cdx:lolbas:attackTactics",
+      value: attackTactics.join(","),
+    });
+  }
+  if (attackTechniques.length) {
+    properties.push({
+      name: "cdx:lolbas:attackTechniques",
+      value: attackTechniques.join(","),
+    });
+  }
+  if (references.length) {
+    properties.push({
+      name: "cdx:lolbas:references",
+      value: references.join(","),
+    });
+  }
+  return properties;
+}

package/lib/inventory/mcp.js

@@ -0,0 +1,253 @@
+import { Purl } from "@cdxgen/cdx-purl";
+
+const OFFICIAL_NPM_NAMESPACE = "@modelcontextprotocol";
+const OFFICIAL_PYPI_PACKAGES = new Set(["mcp"]);
+const OFFICIAL_MAVEN_GROUPS = new Set(["io.modelcontextprotocol.sdk"]);
+const OFFICIAL_NUGET_PREFIXES = ["modelcontextprotocol"];
+const OFFICIAL_GOLANG_PREFIX = "github.com/modelcontextprotocol/";
+const OFFICIAL_CARGO_PACKAGES = new Set(["rmcp", "rmcp-macros"]);
+const KNOWN_MCP_INTEGRATION_GROUPS = new Set(["org.springframework.ai"]);
+
+const MCP_ROLE_HINTS = [
+  ["server-sdk", /(?:^|[-/.])server(?:$|[-/.])/i],
+  ["client-sdk", /(?:^|[-/.])client(?:$|[-/.])/i],
+  [
+    "transport-sdk",
+    /(?:^|[-/.])(express|node|webflux|webmvc|aspnetcore)(?:$|[-/.])/i,
+  ],
+];
+
+function lower(value) {
+  return typeof value === "string" ? value.toLowerCase() : "";
+}
+
+function rootImportName(source) {
+  if (typeof source !== "string" || !source.length || source.startsWith(".")) {
+    return "";
+  }
+  if (source.startsWith("@")) {
+    return source.split("/").slice(0, 2).join("/");
+  }
+  return source.split("/")[0];
+}
+
+function normalizeReference(ref) {
+  if (typeof ref === "string") {
+    const importName = rootImportName(ref);
+    const importParts = importName.startsWith("@")
+      ? importName.split("/")
+      : ["", importName];
+    return {
+      ecosystem: "npm",
+      group: lower(importParts[0]),
+      name: lower(importParts[1]),
+      source: ref,
+    };
+  }
+  if (!ref || typeof ref !== "object") {
+    return { ecosystem: "", group: "", name: "", source: "" };
+  }
+  if (typeof ref.purl === "string" && ref.purl.length) {
+    try {
+      const purl = Purl.parse(ref.purl);
+      return {
+        ecosystem: lower(purl.type),
+        group: lower(purl.namespace),
+        name: lower(purl.name),
+        source: ref.purl,
+      };
+    } catch {
+      // continue with object fallback
+    }
+  }
+  return {
+    ecosystem: lower(ref.ecosystem || ref.type),
+    group: lower(ref.group),
+    name: lower(ref.name),
+    source: lower(ref.source),
+  };
+}
+
+function inferRole(name, group) {
+  const combined = `${group}/${name}`;
+  for (const [role, pattern] of MCP_ROLE_HINTS) {
+    if (pattern.test(combined)) {
+      return role;
+    }
+  }
+  if (name.includes("sdk") || group.includes("modelcontextprotocol")) {
+    return "sdk";
+  }
+  if (name.includes("integration") || group.includes("springframework")) {
+    return "integration";
+  }
+  return "sdk";
+}
+
+/**
+ * Classify a package/component/import reference as MCP-related.
+ *
+ * @param {Object|string} ref Package/component reference or import source
+ * @returns {{
+ *   isMcp: boolean,
+ *   isOfficial: boolean,
+ *   isKnownIntegration: boolean,
+ *   role: string | undefined,
+ *   catalogSource: string | undefined,
+ *   packageName: string
+ * }}
+ */
+export function classifyMcpReference(ref) {
+  const normalized = normalizeReference(ref);
+  const ecosystem = normalized.ecosystem;
+  const group = normalized.group;
+  const name = normalized.name;
+  const packageName = [group, name].filter(Boolean).join("/") || name;
+  if (!name && !group) {
+    return {
+      isMcp: false,
+      isOfficial: false,
+      isKnownIntegration: false,
+      role: undefined,
+      catalogSource: undefined,
+      packageName,
+    };
+  }
+
+  let isMcp = false;
+  let isOfficial = false;
+  let isKnownIntegration = false;
+  let catalogSource;
+
+  if (ecosystem === "npm" && group === OFFICIAL_NPM_NAMESPACE) {
+    isMcp = true;
+    isOfficial = true;
+    catalogSource = "official-sdk";
+  } else if (ecosystem === "pypi" && OFFICIAL_PYPI_PACKAGES.has(name)) {
+    isMcp = true;
+    isOfficial = true;
+    catalogSource = "official-sdk";
+  } else if (ecosystem === "maven" && OFFICIAL_MAVEN_GROUPS.has(group)) {
+    isMcp = true;
+    isOfficial = true;
+    catalogSource = "official-sdk";
+  } else if (
+    ecosystem === "nuget" &&
+    OFFICIAL_NUGET_PREFIXES.some((prefix) => name.startsWith(prefix))
+  ) {
+    isMcp = true;
+    isOfficial = true;
+    catalogSource = "official-sdk";
+  } else if (
+    ecosystem === "golang" &&
+    `${group}/${name}`.startsWith(OFFICIAL_GOLANG_PREFIX)
+  ) {
+    isMcp = true;
+    isOfficial = true;
+    catalogSource = "official-sdk";
+  } else if (ecosystem === "cargo" && OFFICIAL_CARGO_PACKAGES.has(name)) {
+    isMcp = true;
+    isOfficial = true;
+    catalogSource = "official-sdk";
+  } else if (
+    ecosystem === "maven" &&
+    KNOWN_MCP_INTEGRATION_GROUPS.has(group) &&
+    name.includes("mcp")
+  ) {
+    isMcp = true;
+    isKnownIntegration = true;
+    catalogSource = "known-integration";
+  } else if (
+    packageName.includes("modelcontextprotocol") ||
+    packageName.includes("mcp")
+  ) {
+    isMcp = true;
+    catalogSource = "heuristic";
+  }
+
+  return {
+    isMcp,
+    isOfficial,
+    isKnownIntegration,
+    role: isMcp ? inferRole(name, group) : undefined,
+    catalogSource,
+    packageName,
+  };
+}
+
+function pushUniqueProperty(properties, name, value) {
+  if (value === undefined || value === null || value === "") {
+    return;
+  }
+  if (properties.some((prop) => prop.name === name && prop.value === value)) {
+    return;
+  }
+  properties.push({ name, value });
+}
+
+/**
+ * Add MCP catalog metadata to a CycloneDX component.
+ *
+ * @param {Object} component CycloneDX component
+ * @returns {Object} Same component reference
+ */
+export function enrichComponentWithMcpMetadata(component) {
+  if (!component || typeof component !== "object") {
+    return component;
+  }
+  const classification = classifyMcpReference(component);
+  if (!classification.isMcp) {
+    return component;
+  }
+  const tags = new Set(component.tags || []);
+  tags.add("mcp");
+  tags.add("mcp-sdk");
+  if (classification.role === "server-sdk") {
+    tags.add("mcp-server");
+  }
+  if (classification.role === "client-sdk") {
+    tags.add("mcp-client");
+  }
+  if (classification.isOfficial) {
+    tags.add("official-mcp-sdk");
+    tags.add("trusted-source");
+  }
+  if (classification.isKnownIntegration) {
+    tags.add("known-mcp-integration");
+  }
+  component.tags = Array.from(tags).sort();
+  component.properties = component.properties || [];
+  // cdx:mcp:package is the retention signal for `--exclude-type mcp`: it is
+  // stamped exclusively on genuine MCP SDK dependency packages (never on MCP
+  // primitives, services, or config files), so matchesAiInventoryExcludeType()
+  // uses it to keep real supply-chain components while dropping the inventory
+  // overlay. Do not remove/rename it without updating that predicate.
+  pushUniqueProperty(component.properties, "cdx:mcp:package", "true");
+  pushUniqueProperty(
+    component.properties,
+    "cdx:mcp:official",
+    classification.isOfficial ? "true" : "false",
+  );
+  if (classification.role) {
+    pushUniqueProperty(
+      component.properties,
+      "cdx:mcp:role",
+      classification.role,
+    );
+  }
+  if (classification.catalogSource) {
+    pushUniqueProperty(
+      component.properties,
+      "cdx:mcp:catalogSource",
+      classification.catalogSource,
+    );
+  }
+  if (classification.packageName) {
+    pushUniqueProperty(
+      component.properties,
+      "cdx:mcp:packageName",
+      classification.packageName,
+    );
+  }
+  return component;
+}