@mcp-shark/mcp-shark 1.5.13 → 1.6.0

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;
+}

package/core/cli/UpdateCommand.js

@@ -0,0 +1,188 @@
+/**
+ * Update Rules Command
+ * Downloads latest rule packs from a remote registry and caches locally.
+ *
+ * Security: HTTPS-only URLs (unless MCP_SHARK_INSECURE_HTTP_REGISTRY=1), manual redirects
+ * with re-validation, response size limits, safe pack filenames, optional SHA-256 in manifest.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import kleur from 'kleur';
+import { resetStaticRulesCache } from '#core/services/security/StaticRulesService.js';
+import { resolveRuleRegistryConfig } from './RuleRegistryConfig.js';
+import {
+  assertAllowedRegistryUrl,
+  assertSafePackId,
+  assertSha256,
+  fetchJsonSecure,
+  fetchUtf8Secure,
+} from './secureRegistryFetch.js';
+import { S } from './symbols.js';
+
+const MANIFEST_MAX_BYTES = 2 * 1024 * 1024;
+const PACK_MAX_BYTES = 25 * 1024 * 1024;
+
+/**
+ * Execute the update-rules command.
+ * @param {object} options
+ * @param {string} [options.source] - Custom manifest URL (CLI override)
+ * @param {boolean} [options.quiet] - Minimal output (e.g. before scan)
+ * @returns {Promise<number>} Exit code (0 success, 1 failure — for CI)
+ */
+export async function executeUpdateRules(options = {}) {
+  const { registryUrl, cacheDir } = resolveRuleRegistryConfig({
+    overrideUrl: options.source,
+  });
+
+  const quiet = Boolean(options.quiet);
+
+  if (!quiet) {
+    console.log('');
+    console.log(`  ${kleur.bold('mcp-shark update-rules')}`);
+    console.log(kleur.dim('  ─────────────────────────────────────'));
+    console.log('');
+    console.log(`  ${S.info} Registry: ${kleur.dim(registryUrl)}`);
+    console.log('');
+  }
+
+  let manifest;
+  try {
+    manifest = await fetchJsonSecure(registryUrl, MANIFEST_MAX_BYTES);
+  } catch (err) {
+    const msg = `Failed to fetch manifest: ${err.message}`;
+    if (quiet) {
+      console.log(`  ${S.warn} ${msg} (using built-in / cached packs)`);
+    } else {
+      console.log(`  ${S.fail} ${msg}`);
+      console.log(`  ${S.info} Rule packs are unchanged. Built-in packs still active.`);
+      console.log('');
+    }
+    return 1;
+  }
+
+  if (!manifest.packs || !Array.isArray(manifest.packs)) {
+    if (!quiet) {
+      console.log(`  ${S.fail} Invalid manifest format (missing "packs" array)`);
+      console.log('');
+    }
+    return 1;
+  }
+
+  ensureDir(cacheDir);
+
+  let updated = 0;
+  let skipped = 0;
+  let hadPackFailure = false;
+
+  for (const packRef of manifest.packs) {
+    if (!packRef || typeof packRef.id !== 'string' || typeof packRef.url !== 'string') {
+      if (!quiet) {
+        console.log(`  ${S.warn} Skipping invalid pack entry`);
+      }
+      continue;
+    }
+
+    try {
+      assertSafePackId(packRef.id);
+      assertAllowedRegistryUrl(packRef.url);
+    } catch (err) {
+      if (!quiet) {
+        console.log(`  ${S.warn} ${packRef.id}: ${err.message}`);
+      }
+      continue;
+    }
+
+    const localPath = join(cacheDir, `${packRef.id}.json`);
+    const localVersion = readLocalVersion(localPath);
+
+    if (localVersion && packRef.version && localVersion === packRef.version) {
+      if (!quiet) {
+        console.log(`  ${S.dot} ${packRef.id} v${packRef.version} ${kleur.dim('up to date')}`);
+      }
+      skipped++;
+      continue;
+    }
+
+    try {
+      const packText = await fetchUtf8Secure(packRef.url, PACK_MAX_BYTES);
+      assertSha256(packRef.sha256, packText);
+      const packData = JSON.parse(packText);
+      const toxicExtra = Array.isArray(packData.toxic_flow_rules) ? packData.toxic_flow_rules : [];
+      if (!packData.schema_version || !Array.isArray(packData.rules)) {
+        if (!quiet) {
+          console.log(`  ${S.warn} ${packRef.id}: invalid pack format, skipped`);
+        }
+        hadPackFailure = true;
+        continue;
+      }
+      if (packData.rules.length === 0 && toxicExtra.length === 0) {
+        if (!quiet) {
+          console.log(`  ${S.warn} ${packRef.id}: empty rules and toxic_flow_rules, skipped`);
+        }
+        hadPackFailure = true;
+        continue;
+      }
+
+      const packToWrite = { ...packData };
+      if (packRef.version && packToWrite.version == null) {
+        packToWrite.version = packRef.version;
+      }
+
+      writeFileSync(localPath, JSON.stringify(packToWrite, null, 2), 'utf-8');
+      resetStaticRulesCache();
+      const verb = localVersion ? 'updated' : 'downloaded';
+      const ruleCount = packData.rules.length;
+      const toxicCount = toxicExtra.length;
+      if (!quiet) {
+        const parts = [];
+        if (ruleCount > 0) {
+          parts.push(`${ruleCount} rules`);
+        }
+        if (toxicCount > 0) {
+          parts.push(`${toxicCount} toxic-flow rule${toxicCount !== 1 ? 's' : ''}`);
+        }
+        console.log(
+          `  ${S.pass} ${packRef.id} v${packRef.version} ${kleur.green(verb)} (${parts.join(', ')})`
+        );
+      }
+      updated++;
+    } catch (err) {
+      if (!quiet) {
+        console.log(`  ${S.fail} ${packRef.id}: ${err.message}`);
+      }
+      hadPackFailure = true;
+    }
+  }
+
+  if (!quiet) {
+    console.log('');
+    if (updated > 0) {
+      console.log(`  ${S.pass} ${updated} pack(s) updated, ${skipped} up to date`);
+    } else {
+      console.log(`  ${S.info} All ${skipped} pack(s) up to date`);
+    }
+    console.log(`  ${S.info} Cache: ${kleur.dim(cacheDir)}`);
+    console.log('');
+  }
+
+  return hadPackFailure ? 1 : 0;
+}
+
+function readLocalVersion(filePath) {
+  if (!existsSync(filePath)) {
+    return null;
+  }
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    const pack = JSON.parse(content);
+    return pack.version || null;
+  } catch (_err) {
+    return null;
+  }
+}
+
+function ensureDir(dirPath) {
+  if (!existsSync(dirPath)) {
+    mkdirSync(dirPath, { recursive: true });
+  }
+}