@mcp-shark/mcp-shark 1.5.13 → 1.7.2

package/core/mcp-server/server/external/config.js

@@ -4,6 +4,36 @@ import { ConfigParserFactory } from '#core/services/parsers/ConfigParserFactory.
 
 const DEFAULT_TYPE = 'stdio';
 
+// An upstream entry is considered a self-reference (and pruned) when:
+//   - its name is in this reserved set, OR
+//   - it is an HTTP entry whose host:port resolves to mcp-shark's own
+//     listening port. Including such an entry would loop the proxy back
+//     onto itself at startup and crash with RunAllExternalServersError.
+const RESERVED_UPSTREAM_NAMES = new Set(['mcp-shark']);
+
+function isSelfReferencingEntry(name, cfg, selfPort) {
+  if (RESERVED_UPSTREAM_NAMES.has(name)) {
+    return { selfRef: true, reason: `reserved name '${name}'` };
+  }
+  if (!selfPort || !cfg || typeof cfg.url !== 'string') {
+    return { selfRef: false };
+  }
+  let parsed;
+  try {
+    parsed = new URL(cfg.url);
+  } catch {
+    return { selfRef: false };
+  }
+  const port = Number.parseInt(parsed.port || (parsed.protocol === 'https:' ? '443' : '80'), 10);
+  if (port !== selfPort) return { selfRef: false };
+  const localHosts = new Set(['127.0.0.1', 'localhost', '0.0.0.0', '::1']);
+  if (!localHosts.has(parsed.hostname)) return { selfRef: false };
+  return {
+    selfRef: true,
+    reason: `URL ${parsed.hostname}:${port} points back at mcp-shark's own proxy`,
+  };
+}
+
 export class ConfigError extends CompositeError {
   constructor(message, error) {
     super('ConfigError', message, error);
@@ -37,7 +67,8 @@ function parseConfig(configPath) {
   }
 }
 
-export function normalizeConfig(configPath) {
+export function normalizeConfig(configPath, options = {}) {
+  const { selfPort, logger, allowEmpty = false } = options;
   const parsedConfigResult = parseConfig(configPath);
   if (isError(parsedConfigResult)) {
     return parsedConfigResult;
@@ -45,29 +76,55 @@ export function normalizeConfig(configPath) {
 
   const normalized = parserFactory.normalizeToInternalFormat(parsedConfigResult, configPath);
   if (!normalized) {
+    if (allowEmpty) return {};
     return new ConfigError('No servers found in config');
   }
 
   // Convert to flat map format expected by MCP server
   const out = new Map();
+  const pruned = [];
+
+  function addEntry(name, cfg) {
+    const { selfRef, reason } = isSelfReferencingEntry(name, cfg, selfPort);
+    if (selfRef) {
+      pruned.push({ name, reason });
+      return;
+    }
+    const type = cfg.type ?? DEFAULT_TYPE;
+    out.set(name, { type, ...cfg });
+  }
 
   // Handle normalized mcpServers format
   if (normalized.mcpServers) {
     for (const [name, cfg] of Object.entries(normalized.mcpServers)) {
-      const type = cfg.type ?? DEFAULT_TYPE;
-      out.set(name, { type, ...cfg });
+      addEntry(name, cfg);
     }
   }
 
   // Handle normalized servers format (legacy)
   if (normalized.servers) {
     for (const [name, cfg] of Object.entries(normalized.servers)) {
-      const type = cfg.type ?? DEFAULT_TYPE;
-      out.set(name, { type, ...cfg });
+      addEntry(name, cfg);
+    }
+  }
+
+  if (pruned.length > 0 && logger?.warn) {
+    for (const { name, reason } of pruned) {
+      logger.warn(
+        { upstream: name, reason },
+        `[MCP-Shark] Skipping self-referencing upstream '${name}': ${reason}`
+      );
     }
   }
 
   if (out.size === 0) {
+    if (allowEmpty) {
+      logger?.warn?.(
+        { configPath },
+        '[MCP-Shark] No upstream MCP servers configured — running in monitoring-only mode'
+      );
+      return {};
+    }
     return new ConfigError('No servers found in config');
   }
 

package/core/models/RequestFilters.js

@@ -19,6 +19,9 @@ export class RequestFilters {
     this.limit = data.limit !== undefined ? Number.parseInt(data.limit) : Defaults.DEFAULT_LIMIT;
     this.offset =
       data.offset !== undefined ? Number.parseInt(data.offset) : Defaults.DEFAULT_OFFSET;
+    this.aauthPosture = data.aauthPosture || null;
+    this.aauthAgent = data.aauthAgent || null;
+    this.aauthMission = data.aauthMission || null;
   }
 
   /**

package/core/repositories/PacketRepository.js

@@ -234,4 +234,20 @@ export class PacketRepository {
     const stmt = this.db.prepare('SELECT MAX(timestamp_ns) as max_ts FROM packets');
     return stmt.get();
   }
+
+  /**
+   * Response packets whose JSON-RPC result likely includes a tools array (tools/list success).
+   * Used to replay cross-server toxic-flow analysis from captured proxy traffic.
+   */
+  listResponsesWithToolsList() {
+    const stmt = this.db.prepare(`
+      SELECT frame_number, session_id, remote_address, jsonrpc_result, body_json, body_raw, timestamp_ns
+      FROM packets
+      WHERE direction = 'response'
+        AND jsonrpc_result IS NOT NULL
+        AND jsonrpc_result LIKE '%"tools"%'
+      ORDER BY timestamp_ns ASC
+    `);
+    return stmt.all();
+  }
 }

package/core/services/AuditService.js

@@ -97,6 +97,7 @@ export class AuditService {
           frameNumber: result.frameNumber,
           body: options.body,
           sessionId: result.sessionId,
+          mcpServerName: options.remoteAddress || null,
         });
       } catch (error) {
         // Log but don't fail the request
@@ -172,6 +173,7 @@ export class AuditService {
           frameNumber: result.frameNumber,
           body: options.body,
           sessionId: result.sessionId,
+          mcpServerName: options.remoteAddress || null,
         });
       } catch (error) {
         // Log but don't fail the response

package/core/services/ConfigService.js

@@ -201,7 +201,15 @@ export class ConfigService {
         ? this.transformService.filterServers(baseConvertedConfig, selectedServices)
         : baseConvertedConfig;
 
-    if (Object.keys(convertedConfig.servers || {}).length === 0) {
+    // A zero-upstream config is a legitimate state (monitoring-only mode):
+    // mcp-shark still runs the audit/UI/AAuth surfaces, just without any
+    // upstreams to forward to. We only fail here if the *original* config
+    // file declared no servers at all (different from "all servers were
+    // self-references and got filtered out").
+    const originalHadAnyServer =
+      Object.keys(originalConfig.mcpServers || {}).length > 0 ||
+      Object.keys(originalConfig.servers || {}).length > 0;
+    if (!originalHadAnyServer) {
       return {
         success: false,
         error: 'No servers found in config',

package/core/services/ConfigTransformService.js

@@ -1,3 +1,29 @@
+// mcp-shark must never appear as an upstream of itself. The UI reads the
+// user's editor MCP config (e.g. ~/.cursor/mcp.json) — which legitimately
+// contains an `mcp-shark` entry pointing at the proxy port so the editor
+// routes calls through us — and copies it into ~/.mcp-shark/mcps.json as
+// the proxy's upstream list. Without this filter the proxy ends up with a
+// recursive self-reference that crashes startup.
+const RESERVED_PROXY_NAMES = new Set(['mcp-shark']);
+function isProxySelfReference(name, cfg) {
+  if (RESERVED_PROXY_NAMES.has(name)) return true;
+  if (!cfg || typeof cfg.url !== 'string') return false;
+  let parsed;
+  try {
+    parsed = new URL(cfg.url);
+  } catch {
+    return false;
+  }
+  const localHosts = new Set(['127.0.0.1', 'localhost', '0.0.0.0', '::1']);
+  if (!localHosts.has(parsed.hostname)) return false;
+  const port = Number.parseInt(parsed.port || (parsed.protocol === 'https:' ? '443' : '80'), 10);
+  // We don't have access to the runtime port here; the proxy default is
+  // 9851 and the UI always starts it on that port unless overridden via
+  // env. If the user runs on a different port they can still safely include
+  // a custom-named entry; the runtime config.js layer will catch true loops.
+  return port === 9851;
+}
+
 /**
  * Service for configuration transformations
  * Handles converting, filtering, and updating config structures
@@ -9,7 +35,9 @@ export class ConfigTransformService {
 
   /**
    * Convert MCP servers format to servers format
-   * Normalizes config first, then converts mcpServers to servers
+   * Normalizes config first, then converts mcpServers to servers.
+   * Self-referencing entries (mcp-shark itself) are dropped — they would
+   * create an infinite proxy loop if written to ~/.mcp-shark/mcps.json.
    */
   convertMcpServersToServers(config) {
     // Normalize config to ensure consistent format
@@ -22,12 +50,16 @@ export class ConfigTransformService {
 
     // Handle normalized servers (legacy format)
     if (normalized.servers) {
-      converted.servers = { ...normalized.servers };
+      for (const [name, cfg] of Object.entries(normalized.servers)) {
+        if (isProxySelfReference(name, cfg)) continue;
+        converted.servers[name] = cfg;
+      }
     }
 
     // Convert mcpServers to servers format
     if (normalized.mcpServers) {
       for (const [name, cfg] of Object.entries(normalized.mcpServers)) {
+        if (isProxySelfReference(name, cfg)) continue;
         const type = cfg.type || (cfg.url ? 'http' : cfg.command ? 'stdio' : 'stdio');
         converted.servers[name] = { type, ...cfg };
       }

package/core/services/RequestService.js

@@ -5,6 +5,53 @@ import { Defaults } from '../constants/Defaults.js';
  * HTTP-agnostic: accepts models, returns models
  */
 import { RequestFilters } from '../models/RequestFilters.js';
+import { parseAauthForPacket } from './security/aauthParser.js';
+
+/**
+ * Attach an `aauth` field to a packet record by parsing its headers_json.
+ * Pure function; no DB writes. Always returns a new object.
+ */
+function enrichWithAauth(packet) {
+  if (!packet) {
+    return packet;
+  }
+  try {
+    return { ...packet, aauth: parseAauthForPacket(packet) };
+  } catch {
+    return packet;
+  }
+}
+
+/**
+ * Filter a list of packets according to AAuth-derived filters that are not
+ * supported by the repository (which only knows about DB columns).
+ */
+function applyAauthFilters(packets, filters) {
+  if (!filters) {
+    return packets;
+  }
+  const { aauthPosture = null, aauthAgent = null, aauthMission = null } = filters;
+  if (!aauthPosture && !aauthAgent && !aauthMission) {
+    return packets;
+  }
+
+  return packets.filter((p) => {
+    const aauth = p?.aauth;
+    if (!aauth) {
+      return false;
+    }
+    if (aauthPosture && aauth.posture !== aauthPosture) {
+      return false;
+    }
+    if (aauthAgent && aauth.agent !== aauthAgent) {
+      return false;
+    }
+    if (aauthMission && aauth.mission !== aauthMission) {
+      return false;
+    }
+    return true;
+  });
+}
 
 export class RequestService {
   constructor(packetRepository) {
@@ -14,21 +61,27 @@ export class RequestService {
   /**
    * Get requests with filters
    * @param {RequestFilters} filters - Typed filter model
-   * @returns {Array} Array of packet objects (raw from repository)
+   * @returns {Array} Array of packet objects, each enriched with an `aauth` block.
    */
   getRequests(filters) {
     const repoFilters = filters.toRepositoryFilters();
-    return this.packetRepository.queryRequests(repoFilters);
+    const rows = this.packetRepository.queryRequests(repoFilters);
+    const enriched = rows.map(enrichWithAauth);
+    return applyAauthFilters(enriched, {
+      aauthPosture: filters.aauthPosture,
+      aauthAgent: filters.aauthAgent,
+      aauthMission: filters.aauthMission,
+    });
   }
 
   /**
    * Get request by frame number
    * @param {number} frameNumber - Frame number
-   * @returns {Object|null} Packet object or null if not found
+   * @returns {Object|null} Packet object enriched with an `aauth` block, or null.
    */
   getRequest(frameNumber) {
     const parsedFrameNumber = Number.parseInt(frameNumber);
-    return this.packetRepository.getByFrameNumber(parsedFrameNumber);
+    return enrichWithAauth(this.packetRepository.getByFrameNumber(parsedFrameNumber));
   }
 
   /**
@@ -51,6 +104,6 @@ export class RequestService {
       offset: Defaults.DEFAULT_OFFSET,
     });
     const repoFilters = exportFilters.toRepositoryFilters();
-    return this.packetRepository.queryRequests(repoFilters);
+    return this.packetRepository.queryRequests(repoFilters).map(enrichWithAauth);
   }
 }

package/core/services/ServerManagementService.js

@@ -1,6 +1,17 @@
+import path from 'node:path';
+
 import { Defaults } from '#core/constants/Defaults.js';
 import { initAuditLogger, startMcpSharkServer } from '#core/mcp-server/index.js';
 
+function isSamePath(a, b) {
+  if (!a || !b) return false;
+  try {
+    return path.resolve(a) === path.resolve(b);
+  } catch {
+    return a === b;
+  }
+}
+
 /**
  * Service for managing MCP Shark server lifecycle
  * Handles server startup, shutdown, and status
@@ -60,8 +71,34 @@ export class ServerManagementService {
     const { fileData, convertedConfig, updatedConfig } = setupResult;
     const mcpsJsonPath = this.configService.getMcpConfigPath();
 
-    // Write converted config to MCP Shark config path
-    this.configService.writeConfigAsJson(mcpsJsonPath, convertedConfig);
+    // The user can legitimately point the Setup panel at the proxy's own
+    // config file (~/.mcp-shark/mcps.json) when they just want to (re)start
+    // the proxy with whatever is already there — for example after
+    // `npm run testbed:up` has written upstreams directly. In that case the
+    // input *is* the output and the "patch the editor config" step at the
+    // end would rewrite every upstream URL into the proxy-local form
+    // (http://localhost:9851/mcp/<name>), turning mcps.json into a
+    // self-referential file that the next startup has to strip.
+    const sourceIsProxyConfig = isSamePath(fileData.resolvedFilePath, mcpsJsonPath);
+
+    // If the conversion produced zero upstreams (e.g. the user picked an
+    // already-patched ~/.cursor/mcp.json that only contains the mcp-shark
+    // self-reference, and no backup was available to restore), don't blow
+    // away whatever the proxy already has. A healthy existing mcps.json is
+    // strictly more useful than an empty new one.
+    const convertedUpstreamCount = Object.keys(convertedConfig?.servers || {}).length;
+    const existingHasUpstreams = this._existingMcpsHasUpstreams(mcpsJsonPath);
+    const skipWriteToPreserveExisting =
+      convertedUpstreamCount === 0 && existingHasUpstreams && !sourceIsProxyConfig;
+
+    if (skipWriteToPreserveExisting) {
+      this.logger?.warn(
+        { path: mcpsJsonPath, source: fileData.resolvedFilePath },
+        'Conversion yielded zero upstreams; preserving existing mcps.json instead of overwriting'
+      );
+    } else {
+      this.configService.writeConfigAsJson(mcpsJsonPath, convertedConfig);
+    }
 
     // Stop existing server if running
     if (this.serverInstance?.stop) {
@@ -86,9 +123,13 @@ export class ServerManagementService {
       },
     });
 
-    // Patch the original config file if it exists
+    // Patch the original config file if it exists. Skip this when the
+    // source IS our own proxy config — patching it would corrupt the
+    // upstream list we just wrote.
     const patchWarning =
-      fileData.resolvedFilePath && this.configService.fileExists(fileData.resolvedFilePath)
+      fileData.resolvedFilePath &&
+      this.configService.fileExists(fileData.resolvedFilePath) &&
+      !sourceIsProxyConfig
         ? this.configPatchingService.patchConfigFile(fileData.resolvedFilePath, updatedConfig)
             .warning || null
         : null;
@@ -104,6 +145,20 @@ export class ServerManagementService {
     };
   }
 
+  _existingMcpsHasUpstreams(mcpsJsonPath) {
+    try {
+      if (!this.configService.fileExists(mcpsJsonPath)) return false;
+      const content = this.configService.readConfigFile(mcpsJsonPath);
+      const parsed = this.configService.tryParseJson(content, mcpsJsonPath);
+      if (!parsed) return false;
+      const count =
+        Object.keys(parsed.servers || {}).length + Object.keys(parsed.mcpServers || {}).length;
+      return count > 0;
+    } catch {
+      return false;
+    }
+  }
+
   /**
    * Start MCP Shark server
    */

package/core/services/security/StaticRulesService.js

@@ -1,9 +1,72 @@
 /**
  * Static Rules Service
- * Executes pattern-based security rules against MCP server definitions and traffic
+ * Executes pattern-based security rules against MCP server definitions and traffic.
+ *
+ * Combines two rule sources:
+ *   1. JS plugin rules (structural/scored — from rules/index.js)
+ *   2. Declarative JSON rule packs (pattern-based — from DeclarativeRuleEngine)
  */
+import { loadDeclarativeRules } from '#core/cli/DeclarativeRuleEngine.js';
 import { getAllRuleMetadata, getEnabledRules } from './rules/index.js';
 
+let cachedCombinedRules = null;
+
+/**
+ * Clear cached combined rules (e.g. after downloading new declarative packs, or before watch re-scan).
+ */
+export function resetStaticRulesCache() {
+  cachedCombinedRules = null;
+}
+
+/**
+ * Load and cache the combined set of JS plugin + declarative rules.
+ */
+function getCombinedRules() {
+  if (cachedCombinedRules) {
+    return cachedCombinedRules;
+  }
+
+  const jsRules = getEnabledRules();
+  const declarativeRules = loadDeclarativeRules().map((rule) => ({
+    id: rule.ruleMetadata.id,
+    ...rule.ruleMetadata,
+    analyzeTool: rule.analyzeTool,
+    analyzePrompt: rule.analyzePrompt,
+    analyzeResource: rule.analyzeResource,
+    analyzePacket: rule.analyzePacket,
+  }));
+
+  const ruleMap = new Map();
+  for (const rule of jsRules) {
+    ruleMap.set(rule.id, rule);
+  }
+  for (const rule of declarativeRules) {
+    ruleMap.set(rule.id, rule);
+  }
+
+  cachedCombinedRules = [...ruleMap.values()];
+  return cachedCombinedRules;
+}
+
+/**
+ * Get combined metadata from JS plugins + declarative packs.
+ */
+function getCombinedMetadata() {
+  const jsMetadata = getAllRuleMetadata();
+  const declarativeRules = loadDeclarativeRules();
+  const declarativeMetadata = declarativeRules.map((r) => r.ruleMetadata);
+
+  const metaMap = new Map();
+  for (const m of jsMetadata) {
+    metaMap.set(m.id, m);
+  }
+  for (const m of declarativeMetadata) {
+    metaMap.set(m.id, m);
+  }
+
+  return [...metaMap.values()];
+}
+
 export class StaticRulesService {
   constructor(logger) {
     this.logger = logger;
@@ -13,7 +76,7 @@ export class StaticRulesService {
    * Get all available rule metadata
    */
   getRuleMetadata() {
-    return getAllRuleMetadata();
+    return getCombinedMetadata();
   }
 
   /**
@@ -21,7 +84,7 @@ export class StaticRulesService {
    */
   analyzeTool(tool, serverName = null) {
     const findings = [];
-    const rules = getEnabledRules();
+    const rules = getCombinedRules();
 
     for (const rule of rules) {
       try {
@@ -49,7 +112,7 @@ export class StaticRulesService {
    */
   analyzePrompt(prompt, serverName = null) {
     const findings = [];
-    const rules = getEnabledRules();
+    const rules = getCombinedRules();
 
     for (const rule of rules) {
       try {
@@ -77,7 +140,7 @@ export class StaticRulesService {
    */
   analyzeResource(resource, serverName = null) {
     const findings = [];
-    const rules = getEnabledRules();
+    const rules = getCombinedRules();
 
     for (const rule of rules) {
       try {
@@ -105,7 +168,7 @@ export class StaticRulesService {
    */
   analyzePacket(packet, sessionId = null) {
     const findings = [];
-    const rules = getEnabledRules();
+    const rules = getCombinedRules();
 
     for (const rule of rules) {
       try {
@@ -136,21 +199,18 @@ export class StaticRulesService {
     const serverName = serverConfig.name || 'unknown';
     const findings = [];
 
-    // Analyze tools
     if (serverConfig.tools && Array.isArray(serverConfig.tools)) {
       for (const tool of serverConfig.tools) {
         findings.push(...this.analyzeTool(tool, serverName));
       }
     }
 
-    // Analyze prompts
     if (serverConfig.prompts && Array.isArray(serverConfig.prompts)) {
       for (const prompt of serverConfig.prompts) {
         findings.push(...this.analyzePrompt(prompt, serverName));
       }
     }
 
-    // Analyze resources
     if (serverConfig.resources && Array.isArray(serverConfig.resources)) {
       for (const resource of serverConfig.resources) {
         findings.push(...this.analyzeResource(resource, serverName));
@@ -196,22 +256,18 @@ export class StaticRulesService {
     };
 
     for (const finding of findings) {
-      // By severity
       if (summary.bySeverity[finding.severity] !== undefined) {
         summary.bySeverity[finding.severity]++;
       }
 
-      // By OWASP ID
       if (finding.owasp_id) {
         summary.byOwasp[finding.owasp_id] = (summary.byOwasp[finding.owasp_id] || 0) + 1;
       }
 
-      // By server
       if (finding.server_name) {
         summary.byServer[finding.server_name] = (summary.byServer[finding.server_name] || 0) + 1;
       }
 
-      // By type
       if (summary.byType[finding.finding_type] !== undefined) {
         summary.byType[finding.finding_type]++;
       }

package/core/services/security/TrafficAnalysisService.js

@@ -4,10 +4,16 @@
  * Hooks into the audit logging pipeline
  */
 export class TrafficAnalysisService {
-  constructor(staticRulesService, securityFindingsRepository, logger) {
+  constructor(
+    staticRulesService,
+    securityFindingsRepository,
+    logger,
+    trafficToxicFlowService = null
+  ) {
     this.staticRulesService = staticRulesService;
     this.findingsRepository = securityFindingsRepository;
     this.logger = logger;
+    this.trafficToxicFlowService = trafficToxicFlowService;
     this.enabled = true;
   }
 
@@ -96,6 +102,18 @@ export class TrafficAnalysisService {
         );
       }
 
+      if (this.trafficToxicFlowService) {
+        try {
+          this.trafficToxicFlowService.ingestFromTrafficResponse({
+            mcpServerName: packetData.mcpServerName ?? null,
+            sessionId: packetData.sessionId ?? null,
+            body: packetData.body,
+          });
+        } catch (err) {
+          this.logger?.error({ error: err.message }, 'Traffic toxic flow ingest failed');
+        }
+      }
+
       return findings;
     } catch (error) {
       this.logger?.error({ error: error.message }, 'Error analyzing response packet');