@mcp-shark/mcp-shark 1.5.13 → 1.7.2

package/core/services/security/TrafficToxicFlowService.js

@@ -0,0 +1,154 @@
+/**
+ * Cross-server toxic-flow analysis from observed MCP traffic (tools/list responses).
+ * Complements CLI static scan: same analyzeToxicFlows heuristics, fed by proxy captures.
+ */
+import { analyzeToxicFlows } from '#core/cli/ToxicFlowAnalyzer.js';
+import {
+  toolsFromJsonrpcResultString,
+  toolsFromTrafficResponseBody,
+} from './toolsListFromTrafficParser.js';
+
+const TRAFFIC_IDE = 'Traffic';
+const DEBOUNCE_MS = 400;
+
+function serverKey(mcpServerName, sessionId) {
+  if (mcpServerName && String(mcpServerName).trim()) {
+    return String(mcpServerName).trim();
+  }
+  if (sessionId && String(sessionId).trim()) {
+    return `session:${String(sessionId).trim()}`;
+  }
+  return null;
+}
+
+export class TrafficToxicFlowService {
+  constructor(packetRepository, logger) {
+    this.packetRepository = packetRepository;
+    this.logger = logger;
+    /** @type {Map<string, { tools: object[], updatedAt: number }>} */
+    this._byServer = new Map();
+    this._debounceTimer = null;
+    this._lastFlows = [];
+    this._lastComputedAt = null;
+    this._lastReplayPacketCount = 0;
+  }
+
+  /**
+   * Ingest a proxied JSON-RPC response (live path).
+   * @param {{ mcpServerName?: string|null, sessionId?: string|null, body?: unknown }} packetData
+   */
+  ingestFromTrafficResponse(packetData) {
+    const tools = toolsFromTrafficResponseBody(packetData?.body);
+    if (!tools?.length) {
+      return;
+    }
+    const key = serverKey(packetData?.mcpServerName, packetData?.sessionId);
+    if (!key) {
+      this.logger?.debug?.('Traffic toxic flow: skip tools/list — no server name or session');
+      return;
+    }
+    this._byServer.set(key, { tools, updatedAt: Date.now() });
+    this._scheduleRecompute();
+  }
+
+  _scheduleRecompute() {
+    if (this._debounceTimer) {
+      clearTimeout(this._debounceTimer);
+    }
+    this._debounceTimer = setTimeout(() => {
+      this._debounceTimer = null;
+      this._recomputeNow();
+    }, DEBOUNCE_MS);
+  }
+
+  _serversForAnalyzer() {
+    const servers = [];
+    for (const [name, entry] of this._byServer.entries()) {
+      servers.push({
+        name,
+        ide: TRAFFIC_IDE,
+        config: {},
+        tools: entry.tools,
+      });
+    }
+    return servers;
+  }
+
+  _recomputeNow() {
+    const servers = this._serversForAnalyzer();
+    this._lastFlows = servers.length >= 2 ? analyzeToxicFlows(servers) : [];
+    this._lastComputedAt = Date.now();
+    this.logger?.debug?.(
+      { serverCount: servers.length, flowCount: this._lastFlows.length },
+      'Traffic toxic flows recomputed'
+    );
+  }
+
+  /**
+   * Batch replay: rebuild registry from sqlite packets, then recompute.
+   * @returns {{ packetRows: number, serverCount: number, flowCount: number }}
+   */
+  rebuildFromDatabase() {
+    if (!this.packetRepository?.listResponsesWithToolsList) {
+      this.logger?.warn?.('Traffic toxic flow replay: packet repository unavailable');
+      return { packetRows: 0, serverCount: 0, flowCount: 0 };
+    }
+    const rows = this.packetRepository.listResponsesWithToolsList();
+    this._byServer.clear();
+    this._lastReplayPacketCount = rows.length;
+
+    for (const row of rows) {
+      let tools = toolsFromJsonrpcResultString(row.jsonrpc_result);
+      if (!tools?.length) {
+        tools = toolsFromTrafficResponseBody(row.body_json || row.body_raw);
+      }
+      if (!tools?.length) {
+        continue;
+      }
+      const key = serverKey(row.remote_address, row.session_id);
+      if (!key) {
+        continue;
+      }
+      this._byServer.set(key, { tools, updatedAt: Date.now() });
+    }
+
+    this._recomputeNow();
+    return {
+      packetRows: rows.length,
+      serverCount: this._byServer.size,
+      flowCount: this._lastFlows.length,
+    };
+  }
+
+  getSnapshot() {
+    const servers = [];
+    for (const [name, entry] of this._byServer.entries()) {
+      servers.push({
+        name,
+        toolCount: entry.tools.length,
+        updatedAt: entry.updatedAt,
+      });
+    }
+    return {
+      success: true,
+      toxicFlows: this._lastFlows,
+      servers,
+      computedAt: this._lastComputedAt,
+      lastReplayPacketCount: this._lastReplayPacketCount,
+      note:
+        'Heuristic cross-server pairs from tools seen in tools/list traffic (HTTP proxy). ' +
+        'Not runtime taint tracking. Requires at least two distinct server keys and overlapping capability rules.',
+    };
+  }
+
+  clear() {
+    this._byServer.clear();
+    this._lastFlows = [];
+    this._lastComputedAt = null;
+    this._lastReplayPacketCount = 0;
+    if (this._debounceTimer) {
+      clearTimeout(this._debounceTimer);
+      this._debounceTimer = null;
+    }
+  }
+}

package/core/services/security/aauthGraph.js

@@ -0,0 +1,199 @@
+/**
+ * AAuth knowledge-graph builder.
+ *
+ * Walks the captured packets, extracts AAuth signals via aauthParser, and
+ * shapes a node/edge graph that mirrors the categories on
+ * https://mcp-shark.github.io/aauth-explorer/ — but every node here is
+ * grounded in observed traffic, not a static spec illustration.
+ *
+ * Categories (kept stable so the UI can color-code them):
+ *   - agent     — observed AAuth-Agent values
+ *   - mission   — observed AAuth-Mission values
+ *   - resource  — destination host/server names
+ *   - signing   — algorithms parsed from Signature-Input (`alg=...`)
+ *   - access    — access modes parsed from AAuth-Requirement (`mode=...`)
+ *
+ * Edges are weighted by observed packet count so the force layout settles
+ * naturally around the busiest nodes.
+ */
+
+import { parseAauthForPacket } from './aauthParser.js';
+
+const ACCESS_MODE_REGEX = /mode\s*=\s*"?([A-Za-z0-9_-]+)"?/i;
+
+function nodeKey(category, id) {
+  return `${category}::${id}`;
+}
+
+function ensureNode(map, category, id, extra = {}) {
+  const key = nodeKey(category, id);
+  if (!map.has(key)) {
+    map.set(key, {
+      id: key,
+      name: id,
+      category,
+      packet_count: 0,
+      sample_frame_numbers: [],
+      ...extra,
+    });
+  }
+  return map.get(key);
+}
+
+function bumpNode(node, frameNumber) {
+  node.packet_count += 1;
+  if (frameNumber != null && node.sample_frame_numbers.length < 5) {
+    node.sample_frame_numbers.push(frameNumber);
+  }
+}
+
+function ensureEdge(map, sourceKey, targetKey, kind) {
+  const key = `${sourceKey}->${targetKey}::${kind}`;
+  if (!map.has(key)) {
+    map.set(key, { id: key, source: sourceKey, target: targetKey, kind, weight: 0 });
+  }
+  return map.get(key);
+}
+
+function bumpEdge(edge) {
+  edge.weight += 1;
+}
+
+function extractAccessMode(requirement) {
+  if (!requirement || typeof requirement !== 'string') {
+    return null;
+  }
+  const m = requirement.match(ACCESS_MODE_REGEX);
+  return m ? m[1] : null;
+}
+
+function extractResource(packet) {
+  const host = packet?.host || packet?.remote_address || null;
+  if (host) {
+    return host;
+  }
+  const url = packet?.url;
+  if (typeof url === 'string') {
+    try {
+      return new URL(url).host;
+    } catch {
+      return null;
+    }
+  }
+  return null;
+}
+
+/**
+ * Build an AAuth knowledge graph from a list of packets.
+ *
+ * @param {Array} packets - packets as returned by RequestService.getRequests
+ * @returns {{
+ *   categories: Array<{id:string,label:string}>,
+ *   nodes: Array,
+ *   edges: Array,
+ *   stats: object,
+ * }}
+ */
+export function buildAauthGraph(packets) {
+  const nodes = new Map();
+  const edges = new Map();
+
+  let observedSignals = 0;
+
+  for (const packet of packets || []) {
+    const aauth = parseAauthForPacket(packet);
+    const hasAnySignal =
+      aauth.posture !== 'none' ||
+      aauth.agent ||
+      aauth.mission ||
+      aauth.requirement ||
+      aauth.sig_alg;
+    if (!hasAnySignal) {
+      continue;
+    }
+    observedSignals += 1;
+
+    const resourceId = extractResource(packet);
+    const frame = packet?.frame_number ?? null;
+
+    const resourceNode = resourceId
+      ? ensureNode(nodes, 'resource', resourceId, { url: packet?.url || null })
+      : null;
+    if (resourceNode) {
+      bumpNode(resourceNode, frame);
+    }
+
+    let agentNode = null;
+    if (aauth.agent) {
+      agentNode = ensureNode(nodes, 'agent', aauth.agent, {
+        last_keyid: aauth.sig_keyid,
+        posture: aauth.posture,
+      });
+      bumpNode(agentNode, frame);
+    }
+
+    let missionNode = null;
+    if (aauth.mission) {
+      missionNode = ensureNode(nodes, 'mission', aauth.mission);
+      bumpNode(missionNode, frame);
+    }
+
+    let signingNode = null;
+    if (aauth.sig_alg) {
+      signingNode = ensureNode(nodes, 'signing', aauth.sig_alg, {
+        keyid: aauth.sig_keyid,
+      });
+      bumpNode(signingNode, frame);
+    }
+
+    const accessMode = extractAccessMode(aauth.requirement);
+    let accessNode = null;
+    if (accessMode) {
+      accessNode = ensureNode(nodes, 'access', accessMode);
+      bumpNode(accessNode, frame);
+    }
+
+    if (agentNode && resourceNode) {
+      bumpEdge(ensureEdge(edges, agentNode.id, resourceNode.id, 'calls'));
+    }
+    if (agentNode && missionNode) {
+      bumpEdge(ensureEdge(edges, agentNode.id, missionNode.id, 'pursues'));
+    }
+    if (missionNode && resourceNode) {
+      bumpEdge(ensureEdge(edges, missionNode.id, resourceNode.id, 'targets'));
+    }
+    if (agentNode && signingNode) {
+      bumpEdge(ensureEdge(edges, agentNode.id, signingNode.id, 'signs-with'));
+    }
+    if (resourceNode && accessNode) {
+      bumpEdge(ensureEdge(edges, resourceNode.id, accessNode.id, 'requires'));
+    }
+  }
+
+  const categories = [
+    { id: 'agent', label: 'Agent' },
+    { id: 'mission', label: 'Mission' },
+    { id: 'resource', label: 'Resource' },
+    { id: 'signing', label: 'Signing' },
+    { id: 'access', label: 'Access' },
+  ];
+
+  return {
+    categories,
+    nodes: [...nodes.values()],
+    edges: [...edges.values()],
+    stats: {
+      observed_packets: observedSignals,
+      node_counts: countByCategory([...nodes.values()]),
+      edge_count: edges.size,
+    },
+  };
+}
+
+function countByCategory(nodes) {
+  const out = {};
+  for (const n of nodes) {
+    out[n.category] = (out[n.category] || 0) + 1;
+  }
+  return out;
+}

package/core/services/security/aauthParser.js

@@ -0,0 +1,274 @@
+/**
+ * AAuth Visibility Parser
+ *
+ * Pure, observer-only parser for AAuth artifacts as they appear in HTTP
+ * headers and (incidentally) MCP server config. Does NOT perform any
+ * cryptographic verification — every signal it returns is described as
+ * "observed" or "present", never "valid".
+ *
+ * Specs informally referenced:
+ *   - HTTP Message Signatures (RFC 9421)        — Signature, Signature-Input
+ *   - draft-hardt-http-signature-keys (AAuth)   — Signature-Key, Signature-Error
+ *   - draft-hardt-aauth-protocol                — AAuth-Agent, AAuth-Mission,
+ *                                                  AAuth-Requirement
+ *
+ * The parser is intentionally liberal in what it accepts: AAuth drafts evolve,
+ * and visibility-only is the right place to record what is on the wire.
+ */
+
+const AAUTH_AGENT_ID_REGEX = /aauth:[a-zA-Z0-9._-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}/g;
+
+const SIGNATURE_HEADER_NAMES = ['signature', 'signature-input'];
+const AAUTH_HEADER_PREFIX = 'aauth-';
+
+/**
+ * Lower-case all header keys, returning a new object.
+ * Tolerates non-object input by returning {}.
+ */
+function normalizeHeaders(headers) {
+  if (!headers || typeof headers !== 'object') {
+    return {};
+  }
+  const out = {};
+  for (const key of Object.keys(headers)) {
+    out[key.toLowerCase()] = headers[key];
+  }
+  return out;
+}
+
+/**
+ * Parse a Signature-Input value into its first label's covered components and
+ * algorithm parameter. Format example:
+ *   sig1=("@method" "@target-uri" "host");keyid="abc";alg="ed25519";created=1700000000
+ *
+ * Returns { label, covered, alg, keyid, created } or null on failure.
+ */
+function parseSignatureInput(value) {
+  if (!value || typeof value !== 'string') {
+    return null;
+  }
+  const labelMatch = value.match(/^\s*([A-Za-z0-9_-]+)\s*=\s*\(([^)]*)\)(.*)$/);
+  if (!labelMatch) {
+    return null;
+  }
+  const [, label, componentsRaw, paramsRaw] = labelMatch;
+  const covered = [];
+  const componentRegex = /"([^"]+)"/g;
+  let m = componentRegex.exec(componentsRaw);
+  while (m) {
+    covered.push(m[1]);
+    m = componentRegex.exec(componentsRaw);
+  }
+
+  const params = {};
+  const paramRegex = /;\s*([A-Za-z0-9_-]+)=("([^"]*)"|([0-9]+))/g;
+  let pm = paramRegex.exec(paramsRaw);
+  while (pm) {
+    const [, key, , quoted, raw] = pm;
+    params[key] = quoted !== undefined ? quoted : raw;
+    pm = paramRegex.exec(paramsRaw);
+  }
+
+  return {
+    label,
+    covered,
+    alg: params.alg || null,
+    keyid: params.keyid || null,
+    created: params.created ? Number(params.created) : null,
+  };
+}
+
+/**
+ * Truncate a key/thumbprint string to a UI-friendly preview while keeping
+ * enough characters to be visually distinguishable.
+ */
+function shortFingerprint(value) {
+  if (!value || typeof value !== 'string') {
+    return null;
+  }
+  const trimmed = value.replace(/^"|"$/g, '').trim();
+  if (trimmed.length <= 16) {
+    return trimmed;
+  }
+  return `${trimmed.slice(0, 8)}…${trimmed.slice(-4)}`;
+}
+
+/**
+ * Extract any AAuth agent identifier(s) from a string. Returns the first match
+ * or null. Matches the form `aauth:<local>@<domain>` from the AAuth draft.
+ */
+export function extractAgentId(text) {
+  if (!text || typeof text !== 'string') {
+    return null;
+  }
+  AAUTH_AGENT_ID_REGEX.lastIndex = 0;
+  const m = text.match(AAUTH_AGENT_ID_REGEX);
+  return m ? m[0] : null;
+}
+
+/**
+ * Parse AAuth signals from a single packet's headers.
+ *
+ * Returns a normalized envelope. Every field is purely observational; the
+ * caller MUST NOT treat any of these values as cryptographically validated.
+ *
+ * @param {object|string|null|undefined} headers
+ * @returns {{
+ *   posture: 'signed' | 'aauth-aware' | 'bearer' | 'none',
+ *   sig_present: boolean,
+ *   sig_alg: string | null,
+ *   sig_keyid: string | null,
+ *   sig_keyid_short: string | null,
+ *   sig_covered: string[],
+ *   key_thumbprint: string | null,
+ *   key_thumbprint_short: string | null,
+ *   agent: string | null,
+ *   mission: string | null,
+ *   requirement: string | null,
+ *   error: string | null,
+ *   raw: Record<string, string>
+ * }}
+ */
+export function parseAauthHeaders(headers) {
+  const h = normalizeHeaders(headers);
+
+  const sigInputRaw = h['signature-input'] || null;
+  const sigRaw = h.signature || null;
+  const sigKeyRaw = h['signature-key'] || null;
+  const sigErrorRaw = h['signature-error'] || null;
+  const agentRaw = h['aauth-agent'] || null;
+  const missionRaw = h['aauth-mission'] || null;
+  const requirementRaw = h['aauth-requirement'] || h['www-authenticate-aauth'] || null;
+  const authzRaw = h.authorization || null;
+
+  const parsedInput = parseSignatureInput(sigInputRaw);
+
+  const sigPresent = Boolean(sigRaw && sigInputRaw);
+  const sigAlg = parsedInput?.alg || null;
+  const sigKeyid = parsedInput?.keyid || null;
+  const sigCovered = parsedInput?.covered || [];
+
+  const agent = agentRaw || extractAgentId(authzRaw) || extractAgentId(sigKeyRaw) || null;
+
+  const aauthHeaderNames = Object.keys(h).filter((k) => k.startsWith(AAUTH_HEADER_PREFIX));
+  const aauthAware = aauthHeaderNames.length > 0 || Boolean(sigKeyRaw);
+
+  let posture;
+  if (sigPresent) {
+    posture = 'signed';
+  } else if (aauthAware) {
+    posture = 'aauth-aware';
+  } else if (authzRaw && /^bearer\s/i.test(authzRaw)) {
+    posture = 'bearer';
+  } else {
+    posture = 'none';
+  }
+
+  const raw = {};
+  for (const name of [
+    ...SIGNATURE_HEADER_NAMES,
+    'signature-key',
+    'signature-error',
+    'aauth-agent',
+    'aauth-mission',
+    'aauth-requirement',
+  ]) {
+    if (h[name]) {
+      raw[name] = h[name];
+    }
+  }
+
+  return {
+    posture,
+    sig_present: sigPresent,
+    sig_alg: sigAlg,
+    sig_keyid: sigKeyid,
+    sig_keyid_short: shortFingerprint(sigKeyid),
+    sig_covered: sigCovered,
+    key_thumbprint: sigKeyRaw,
+    key_thumbprint_short: shortFingerprint(sigKeyRaw),
+    agent,
+    mission: missionRaw,
+    requirement: requirementRaw,
+    error: sigErrorRaw,
+    raw,
+  };
+}
+
+/**
+ * Parse AAuth signals from a packet record (shape returned by PacketRepository).
+ * Reads `headers_json` (string or object).
+ */
+export function parseAauthForPacket(packet) {
+  if (!packet) {
+    return parseAauthHeaders(null);
+  }
+  let headers = packet.headers_json || packet.headers;
+  if (typeof headers === 'string') {
+    try {
+      headers = JSON.parse(headers);
+    } catch {
+      headers = {};
+    }
+  }
+  return parseAauthHeaders(headers);
+}
+
+/**
+ * Summarize AAuth posture across a list of packets. Useful for the inventory
+ * panel and CLI summary line.
+ *
+ * Returns counts by posture and the set of unique agents/missions observed.
+ */
+export function summarizeAauth(packets) {
+  const counts = { signed: 0, 'aauth-aware': 0, bearer: 0, none: 0 };
+  const agents = new Set();
+  const missions = new Set();
+  let total = 0;
+
+  for (const packet of packets || []) {
+    const aauth = parseAauthForPacket(packet);
+    counts[aauth.posture] = (counts[aauth.posture] || 0) + 1;
+    total += 1;
+    if (aauth.agent) {
+      agents.add(aauth.agent);
+    }
+    if (aauth.mission) {
+      missions.add(aauth.mission);
+    }
+  }
+
+  return {
+    total,
+    counts,
+    unique_agents: [...agents],
+    unique_missions: [...missions],
+  };
+}
+
+/**
+ * Decide whether a config-level server entry advertises AAuth in any way we
+ * can recognize without a network call. This is intentionally narrow: presence
+ * of an `aauth_id`, a JWKS URL, or a `.well-known/aauth` URL.
+ *
+ * Returns null if no signal, otherwise an object describing what we saw.
+ */
+export function inspectServerConfigForAauth(serverConfig) {
+  if (!serverConfig || typeof serverConfig !== 'object') {
+    return null;
+  }
+  const blob = JSON.stringify(serverConfig);
+  const aauthId = extractAgentId(blob);
+  const wellKnown = blob.match(/https?:\/\/[^"'\s]+\/\.well-known\/aauth[^"'\s]*/);
+  const jwksUrl = blob.match(/https?:\/\/[^"'\s]+\/jwks(?:\.json)?[^"'\s]*/i);
+
+  if (!aauthId && !wellKnown && !jwksUrl) {
+    return null;
+  }
+
+  return {
+    agent: aauthId || null,
+    well_known_url: wellKnown ? wellKnown[0] : null,
+    jwks_url: jwksUrl ? jwksUrl[0] : null,
+  };
+}