@mcp-shark/mcp-shark 1.5.13 → 1.7.2

package/core/cli/ScanService.js

@@ -0,0 +1,200 @@
+import { StaticRulesService } from '#core/services/security/StaticRulesService.js';
+/**
+ * Scan Service
+ * Orchestrates: config detection → rule analysis → toxic flows → shark score
+ * Pure business logic, no HTTP knowledge, no CLI formatting.
+ *
+ * Server-level checks are registry-driven — add a new check by
+ * appending to SERVER_CONFIG_CHECKS, no other edits needed.
+ */
+import { analyzeConfigPermissions } from '#core/services/security/rules/scans/configPermissions.js';
+import { analyzeAllServerToolNames } from '#core/services/security/rules/scans/duplicateToolNames.js';
+import { analyzeServerTransport } from '#core/services/security/rules/scans/insecureTransport.js';
+import { analyzeServerContainment } from '#core/services/security/rules/scans/missingContainment.js';
+import { analyzeServerShellRisk } from '#core/services/security/rules/scans/shellEnvInjection.js';
+import { analyzeServerDefaults } from '#core/services/security/rules/scans/unsafeDefaults.js';
+import { getAllServers, scanIdeConfigs } from './ConfigScanner.js';
+import { detectHardcodedSecrets } from './SecretDetector.js';
+import { calculateSharkScore, countBySeverity } from './SharkScoreCalculator.js';
+import { analyzeToxicFlows } from './ToxicFlowAnalyzer.js';
+import { applyYamlRules, loadYamlRules } from './YamlRuleEngine.js';
+
+/**
+ * Registry of server-level config checks.
+ * Each entry takes (serverName, config) and returns Finding[].
+ * To add a new check: import it and append here.
+ */
+const SERVER_CONFIG_CHECKS = [
+  analyzeServerContainment,
+  analyzeServerShellRisk,
+  analyzeServerTransport,
+  analyzeServerDefaults,
+];
+
+/**
+ * Run a full security scan on all detected MCP configurations
+ * @param {object} options
+ * @param {string} [options.ide] - Filter to specific IDE
+ * @param {boolean} [options.strict] - Count advisory findings in score
+ * @param {string} [options.rulesPath] - Path to custom YAML rules
+ * @returns {object} Complete scan result
+ */
+export function runScan(options = {}) {
+  const startTime = Date.now();
+
+  const ideResults = scanIdeConfigs({ ide: options.ide });
+  const servers = getAllServers(ideResults);
+
+  const rulesService = new StaticRulesService(null);
+  const ruleMetadata = rulesService.getRuleMetadata();
+
+  const allFindings = analyzeAllServers(servers, rulesService, ideResults);
+
+  const yamlRules = loadYamlRules(options.rulesPath);
+  if (yamlRules.length > 0) {
+    const yamlFindings = applyYamlRules(yamlRules, servers);
+    allFindings.push(...yamlFindings);
+  }
+
+  const toxicFlows = analyzeToxicFlows(servers);
+
+  const scorableFindings = options.strict
+    ? allFindings
+    : allFindings.filter((f) => f.confidence !== 'possible');
+
+  const scoreResult = calculateSharkScore(scorableFindings, toxicFlows);
+  const severityCounts = countBySeverity(allFindings);
+  const elapsedMs = Date.now() - startTime;
+
+  const totalToolCount = servers.reduce(
+    (sum, s) => sum + (Array.isArray(s.tools) ? s.tools.length : 0),
+    0
+  );
+
+  return {
+    ideResults,
+    servers,
+    findings: allFindings,
+    findingsByServer: groupFindingsByServer(allFindings),
+    toxicFlows,
+    scoreResult,
+    severityCounts,
+    ruleCount: ruleMetadata.length,
+    totalToolCount,
+    serverCount: servers.length,
+    elapsedMs,
+    cleanServers: getCleanServers(servers, allFindings),
+  };
+}
+
+/**
+ * Analyze all servers with the static rules engine + config-level checks
+ */
+function analyzeAllServers(servers, rulesService, ideResults) {
+  const findings = [];
+
+  for (const server of servers) {
+    const serverFindings = analyzeServer(server, rulesService);
+    findings.push(...serverFindings);
+  }
+
+  const dupFindings = analyzeAllServerToolNames(servers);
+  findings.push(...dupFindings);
+
+  const permFindings = analyzeIdePermissions(ideResults);
+  findings.push(...permFindings);
+
+  return findings;
+}
+
+/**
+ * Check permissions on all found IDE config files
+ */
+function analyzeIdePermissions(ideResults) {
+  const findings = [];
+  for (const ide of ideResults) {
+    if (!ide.found || !ide.permissions) {
+      continue;
+    }
+    const permFindings = analyzeConfigPermissions(ide.configPath, ide.permissions);
+    findings.push(...permFindings);
+  }
+  return findings;
+}
+
+/**
+ * Analyze a single server's tools with the rules engine
+ */
+function analyzeServer(server, rulesService) {
+  const findings = [];
+
+  const configFindings = runServerConfigChecks(server);
+  findings.push(...configFindings);
+
+  if (Array.isArray(server.tools)) {
+    for (const tool of server.tools) {
+      const toolObj = typeof tool === 'string' ? { name: tool } : tool;
+      const toolFindings = rulesService.analyzeTool(toolObj, server.name);
+      for (const f of toolFindings) {
+        findings.push({
+          ...f,
+          ide: server.ide,
+          config_path: server.configPath,
+        });
+      }
+    }
+  }
+
+  const serverConfig = server.config || {};
+  if (serverConfig.env) {
+    const secretFindings = detectHardcodedSecrets(serverConfig.env, server);
+    findings.push(...secretFindings);
+  }
+
+  return findings;
+}
+
+/**
+ * Run all registered server-level config checks against a single server.
+ * Iterates SERVER_CONFIG_CHECKS registry — no manual calls needed.
+ */
+function runServerConfigChecks(server) {
+  const config = server.config || {};
+  const findings = [];
+
+  for (const check of SERVER_CONFIG_CHECKS) {
+    const checkFindings = check(server.name, config);
+    for (const f of checkFindings) {
+      findings.push({
+        ...f,
+        ide: server.ide,
+        config_path: server.configPath,
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Group findings by server name
+ */
+function groupFindingsByServer(findings) {
+  const grouped = {};
+  for (const finding of findings) {
+    const key = finding.server_name || 'unknown';
+    if (!grouped[key]) {
+      grouped[key] = [];
+    }
+    grouped[key].push(finding);
+  }
+  return grouped;
+}
+
+/**
+ * Get list of servers with no findings
+ */
+function getCleanServers(servers, findings) {
+  const serversWithFindings = new Set(findings.map((f) => f.server_name));
+  return servers.filter((s) => !serversWithFindings.has(s.name)).map((s) => s.name);
+}

package/core/cli/SecretDetector.js

@@ -0,0 +1,92 @@
+/**
+ * Hardcoded Secret Detection
+ * Detects API keys, tokens, and credentials hardcoded in MCP server env vars.
+ *
+ * Patterns are loaded from data/secret-patterns.json (built-in)
+ * and merged with user overrides from .mcp-shark/secrets.yaml.
+ */
+import { loadBuiltinJson, loadUserYamlList } from './DataLoader.js';
+
+const BUILTIN_PATTERNS = loadBuiltinJson('secret-patterns.json');
+const USER_PATTERNS = loadUserYamlList('secrets.yaml');
+
+const SECRET_PATTERNS = compilePatterns([...BUILTIN_PATTERNS, ...USER_PATTERNS]);
+
+/**
+ * Compile raw pattern definitions into regex objects
+ * @param {Array<{pattern: string, name: string, severity: string}>} rawPatterns
+ * @returns {Array<{pattern: RegExp, name: string, severity: string}>}
+ */
+function compilePatterns(rawPatterns) {
+  const compiled = [];
+  for (const entry of rawPatterns) {
+    try {
+      compiled.push({
+        pattern: new RegExp(entry.pattern),
+        name: entry.name,
+        severity: entry.severity,
+      });
+    } catch (_err) {
+      // skip malformed patterns from user overrides
+    }
+  }
+  return compiled;
+}
+
+/**
+ * Detect hardcoded secrets in server environment variables
+ * @param {object} envVars - Environment variables from server config
+ * @param {object} server - Server context (name, ide, configPath)
+ * @returns {Array} Findings
+ */
+export function detectHardcodedSecrets(envVars, server) {
+  const findings = [];
+  if (!envVars || typeof envVars !== 'object') {
+    return findings;
+  }
+
+  for (const [key, value] of Object.entries(envVars)) {
+    if (typeof value !== 'string') {
+      continue;
+    }
+    if (value.startsWith('${')) {
+      continue;
+    }
+    if (/^\$[A-Za-z_][A-Za-z0-9_]*$/.test(value)) {
+      continue;
+    }
+
+    for (const { pattern, name, severity } of SECRET_PATTERNS) {
+      if (pattern.test(value)) {
+        const masked = maskSecret(value);
+        findings.push({
+          rule_id: 'hardcoded-secret',
+          category: 'MCP01',
+          severity,
+          confidence: 'definite',
+          title: `${name} hardcoded in config`,
+          description: `${key}=${masked} — use environment variable reference instead`,
+          server_name: server.name,
+          ide: server.ide,
+          config_path: server.configPath,
+          fixable: true,
+          fix_type: 'env_var_replacement',
+          fix_data: { key, original: value },
+        });
+        break;
+      }
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Mask a secret value for display
+ */
+function maskSecret(value) {
+  if (value.length <= 8) {
+    return '****';
+  }
+  return `${value.slice(0, 4)}****`;
+}

package/core/cli/SharkScoreCalculator.js

@@ -0,0 +1,109 @@
+/**
+ * Shark Score Calculator
+ * Transparent, reproducible scoring formula for MCP security posture
+ *
+ * Formula: Shark Score = max(0, 100 - Σ finding_weights)
+ *
+ * Finding weights:
+ *   CRITICAL: 25 points
+ *   HIGH:     15 points
+ *   MEDIUM:    5 points
+ *   LOW:       2 points
+ *   Toxic flow (HIGH):   10 points
+ *   Toxic flow (MEDIUM):  5 points
+ *
+ * Grades:
+ *   90-100  A  Excellent
+ *   75-89   B  Good
+ *   50-74   C  Needs work
+ *   25-49   D  Poor
+ *   0-24    F  Critical risk
+ */
+
+const FINDING_WEIGHTS = {
+  critical: 25,
+  high: 15,
+  medium: 5,
+  low: 2,
+};
+
+const TOXIC_FLOW_WEIGHTS = {
+  high: 10,
+  medium: 5,
+  low: 2,
+};
+
+const GRADES = [
+  { min: 90, grade: 'A', label: 'Excellent' },
+  { min: 75, grade: 'B', label: 'Good' },
+  { min: 50, grade: 'C', label: 'Needs work' },
+  { min: 25, grade: 'D', label: 'Poor' },
+  { min: 0, grade: 'F', label: 'Critical risk' },
+];
+
+/**
+ * Calculate the Shark Score from findings and toxic flows
+ * @param {Array} findings - Array of security findings with severity
+ * @param {Array} toxicFlows - Array of toxic flow results with risk level
+ * @returns {{ score: number, grade: string, label: string, breakdown: object }}
+ */
+export function calculateSharkScore(findings, toxicFlows = []) {
+  const confirmedFindings = findings.filter((f) => f.confidence !== 'possible');
+
+  const findingDeductions = confirmedFindings.reduce((sum, finding) => {
+    const severity = (finding.severity || finding.risk_level || '').toLowerCase();
+    const weight = FINDING_WEIGHTS[severity] || 0;
+    return sum + weight;
+  }, 0);
+
+  const flowDeductions = toxicFlows.reduce((sum, flow) => {
+    const risk = (flow.risk || '').toLowerCase();
+    const weight = TOXIC_FLOW_WEIGHTS[risk] || 0;
+    return sum + weight;
+  }, 0);
+
+  const totalDeductions = findingDeductions + flowDeductions;
+  const score = Math.max(0, 100 - totalDeductions);
+  const gradeInfo = getGrade(score);
+
+  return {
+    score,
+    grade: gradeInfo.grade,
+    label: gradeInfo.label,
+    breakdown: {
+      findingDeductions,
+      flowDeductions,
+      totalDeductions,
+      confirmedCount: confirmedFindings.length,
+      flowCount: toxicFlows.length,
+    },
+  };
+}
+
+/**
+ * Get grade from score
+ */
+function getGrade(score) {
+  for (const g of GRADES) {
+    if (score >= g.min) {
+      return g;
+    }
+  }
+  return GRADES[GRADES.length - 1];
+}
+
+/**
+ * Count findings by severity
+ * @param {Array} findings
+ * @returns {{ critical: number, high: number, medium: number, low: number }}
+ */
+export function countBySeverity(findings) {
+  const counts = { critical: 0, high: 0, medium: 0, low: 0 };
+  for (const f of findings) {
+    const severity = (f.severity || f.risk_level || '').toLowerCase();
+    if (counts[severity] !== undefined) {
+      counts[severity] += 1;
+    }
+  }
+  return counts;
+}

package/core/cli/ToolClassifications.js

@@ -0,0 +1,51 @@
+/**
+ * Tool Classification Database
+ * Maps known MCP server tools to their capability categories.
+ *
+ * Built-in classifications loaded from data/tool-classifications.json.
+ * User overrides merged from .mcp-shark/classifications.yaml.
+ *
+ * Categories:
+ *   ingests_untrusted - reads external/public data
+ *   writes_code       - modifies source code, pushes commits
+ *   sends_external    - sends data to external endpoints
+ *   reads_secrets     - accesses sensitive local data
+ *   modifies_infra    - changes infrastructure state
+ */
+import { loadBuiltinJson, loadUserYamlMap } from './DataLoader.js';
+
+const BUILTIN = loadBuiltinJson('tool-classifications.json');
+const USER_OVERRIDES = loadUserYamlMap('classifications.yaml');
+
+const UNSAFE_CLASSIFICATION_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+export const TOOL_CLASSIFICATIONS = mergeClassifications(BUILTIN, USER_OVERRIDES);
+
+/**
+ * Deep-merge user overrides into built-in classifications.
+ * User entries for existing servers extend (not replace) the tool map.
+ * New servers are added wholesale.
+ * @param {Record<string, Record<string, string>>} builtin
+ * @param {Record<string, unknown>} overrides
+ */
+export function mergeClassifications(builtin, overrides) {
+  const merged = { ...builtin };
+  for (const [server, tools] of Object.entries(overrides)) {
+    if (UNSAFE_CLASSIFICATION_KEYS.has(server)) {
+      continue;
+    }
+    if (!tools || typeof tools !== 'object' || Array.isArray(tools)) {
+      continue;
+    }
+    const safeTools = { ...tools };
+    for (const k of UNSAFE_CLASSIFICATION_KEYS) {
+      delete safeTools[k];
+    }
+    if (merged[server]) {
+      merged[server] = { ...merged[server], ...safeTools };
+    } else {
+      merged[server] = { ...safeTools };
+    }
+  }
+  return merged;
+}

package/core/cli/ToxicFlowAnalyzer.js

@@ -0,0 +1,212 @@
+/**
+ * Toxic Flow Analyzer
+ * Detects dangerous cross-server composition risks by classifying
+ * tools by capability and identifying pairs that create attack paths
+ * through the shared LLM context window.
+ *
+ * Flow rules are loaded from data/toxic-flow-rules.json (built-in),
+ * optional toxic_flow_rules inside rule-pack JSON under data/rule-packs/ and
+ * .mcp-shark/rule-packs/, and user overrides from .mcp-shark/flows.yaml.
+ *
+ * Catalog references: §1.1, §1.2, §1.3, §1.7, §1.10, §1.12, §1.13, §1.14
+ */
+import { join } from 'node:path';
+import { loadBuiltinJson, loadToxicFlowRulesFromPacksDir, loadUserYamlList } from './DataLoader.js';
+import { TOOL_CLASSIFICATIONS } from './ToolClassifications.js';
+
+const BUILTIN_PACKS_DIR = join(import.meta.dirname, 'data', 'rule-packs');
+const USER_PACKS_DIR = join(process.cwd(), '.mcp-shark', 'rule-packs');
+
+const BUILTIN_FLOWS = loadBuiltinJson('toxic-flow-rules.json');
+const PACK_FLOWS_BUILTIN = loadToxicFlowRulesFromPacksDir(BUILTIN_PACKS_DIR);
+const PACK_FLOWS_USER = loadToxicFlowRulesFromPacksDir(USER_PACKS_DIR);
+const USER_FLOWS = loadUserYamlList('flows.yaml');
+const TOXIC_FLOW_RULES = [
+  ...BUILTIN_FLOWS,
+  ...PACK_FLOWS_BUILTIN,
+  ...PACK_FLOWS_USER,
+  ...USER_FLOWS,
+];
+
+/**
+ * Classify a tool's capability based on known classifications and heuristics
+ */
+function classifyTool(serverName, toolName) {
+  const serverClassifications = TOOL_CLASSIFICATIONS[serverName];
+  if (serverClassifications?.[toolName]) {
+    return serverClassifications[toolName];
+  }
+
+  const nameLower = (toolName || '').toLowerCase();
+
+  if (
+    matchesPatterns(nameLower, ['send_message', 'post_message', 'send_email', 'send_notification'])
+  ) {
+    return 'sends_external';
+  }
+  if (
+    matchesPatterns(nameLower, [
+      'write_file',
+      'create_file',
+      'push',
+      'commit',
+      'create_pr',
+      'create_pull',
+    ])
+  ) {
+    return 'writes_code';
+  }
+  if (
+    matchesPatterns(nameLower, ['read_file', 'get_file', 'list_dir', 'get_config', 'get_secret'])
+  ) {
+    return 'reads_secrets';
+  }
+  if (
+    matchesPatterns(nameLower, [
+      'get_issue',
+      'get_ticket',
+      'list_messages',
+      'search',
+      'fetch',
+      'scrape',
+    ])
+  ) {
+    return 'ingests_untrusted';
+  }
+  if (matchesPatterns(nameLower, ['deploy', 'kubectl', 'docker', 'transfer', 'scale', 'restart'])) {
+    return 'modifies_infra';
+  }
+
+  return null;
+}
+
+/**
+ * Check if a name matches any of the patterns
+ */
+function matchesPatterns(name, patterns) {
+  for (const pattern of patterns) {
+    if (name.includes(pattern)) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Classify all tools in a server and return capabilities
+ */
+function classifyServer(server) {
+  const capabilities = new Set();
+  const classifiedTools = {};
+
+  const toolNames = extractToolNames(server);
+
+  for (const toolName of toolNames) {
+    const capability = classifyTool(server.name, toolName);
+    if (capability) {
+      capabilities.add(capability);
+      classifiedTools[toolName] = capability;
+    }
+  }
+
+  return { capabilities: [...capabilities], classifiedTools };
+}
+
+/**
+ * Extract tool names from a server definition
+ */
+function extractToolNames(server) {
+  if (Array.isArray(server.tools)) {
+    return server.tools.map((t) => t.name || t);
+  }
+  if (server.tools && typeof server.tools === 'object') {
+    return Object.keys(server.tools);
+  }
+  return [];
+}
+
+/**
+ * Interpolate a scenario template string with source/target context.
+ * Replaces {source}, {target}, {source_ide}, {target_ide} placeholders.
+ */
+function interpolateScenario(template, src, tgt) {
+  return template
+    .replace(/\{source_ide\}/g, src.ide || 'IDE')
+    .replace(/\{target_ide\}/g, tgt.ide || 'IDE')
+    .replace(/\{source\}/g, src.name)
+    .replace(/\{target\}/g, tgt.name);
+}
+
+/**
+ * Analyze toxic flows across all servers
+ * @param {Array} servers - Flat list of server objects with { name, ide, config, tools }
+ * @returns {Array} Array of toxic flow results
+ */
+export function analyzeToxicFlows(servers) {
+  const classifiedServers = servers.map((server) => ({
+    ...server,
+    ...classifyServer(server),
+  }));
+
+  const flows = [];
+
+  for (const rule of TOXIC_FLOW_RULES) {
+    const sources = classifiedServers.filter((s) => s.capabilities.includes(rule.source));
+    const targets = classifiedServers.filter((s) => s.capabilities.includes(rule.target));
+
+    for (const src of sources) {
+      for (const tgt of targets) {
+        if (src.name === tgt.name) {
+          continue;
+        }
+
+        flows.push({
+          source: src.name,
+          sourceIde: src.ide,
+          target: tgt.name,
+          targetIde: tgt.ide,
+          risk: rule.risk,
+          title: rule.title,
+          scenario: interpolateScenario(rule.scenario, src, tgt),
+          catalog: rule.catalog,
+          owasp: rule.owasp,
+          sourceCapability: rule.source,
+          targetCapability: rule.target,
+        });
+      }
+    }
+  }
+
+  return deduplicateFlows(flows);
+}
+
+/**
+ * Remove duplicate flows (same source, target, IDE pair, capability pair, and title; keep highest risk)
+ */
+function deduplicateFlows(flows) {
+  const seen = new Map();
+  for (const flow of flows) {
+    const key = [
+      flow.source,
+      flow.sourceIde,
+      flow.target,
+      flow.targetIde,
+      flow.sourceCapability,
+      flow.targetCapability,
+      flow.title,
+    ].join('\u2192');
+    const existing = seen.get(key);
+    if (!existing || riskLevel(flow.risk) > riskLevel(existing.risk)) {
+      seen.set(key, flow);
+    }
+  }
+  return [...seen.values()];
+}
+
+/**
+ * Convert risk string to numeric level for comparison
+ */
+function riskLevel(risk) {
+  const levels = { HIGH: 3, MEDIUM: 2, LOW: 1 };
+  return levels[risk] || 0;
+}