mcpsec 0.1.0

package/src/scanner/live-scanner.ts

@@ -0,0 +1,375 @@
+/**
+ * Sentinel MCP - Live Server Scanner
+ *
+ * Connects to running MCP servers and scans their tool descriptions,
+ * resource URIs, and prompt templates for security issues:
+ *
+ * - Tool poisoning (hidden instructions in tool descriptions)
+ * - Tool shadowing (tools impersonating other tools)
+ * - Data exfiltration patterns in tool descriptions
+ * - SSRF in resource URIs
+ * - Prompt injection in prompt templates
+ * - Excessive permissions / dangerous capabilities
+ */
+
+import type { MCPConfigFile, Finding, Scanner } from '../lib/types';
+import {
+  connectStdio,
+  connectHTTP,
+  type MCPServerInfo,
+  type MCPTool,
+  type MCPResource,
+  type MCPPrompt,
+} from '../lib/mcp-client';
+import {
+  analyzeForInjection,
+  INJECTION_PATTERNS,
+  TOOL_POISONING_PATTERNS,
+} from '../lib/injection-patterns';
+import { validateURL } from '../lib/url-validator';
+
+// ============================================================================
+// Dangerous Tool Patterns
+// ============================================================================
+
+/**
+ * Tool names/descriptions that indicate dangerous capabilities
+ */
+const DANGEROUS_TOOL_PATTERNS = [
+  { pattern: /\b(exec|execute|run|shell|bash|cmd|command|system)\b/i, risk: 'Command execution capability' },
+  { pattern: /\b(eval|evaluate)\b/i, risk: 'Code evaluation capability' },
+  { pattern: /\b(sudo|root|admin|privilege)/i, risk: 'Elevated privilege operations' },
+  { pattern: /\b(delete|remove|drop|truncate|destroy)\s+(all|every|database|table|collection)/i, risk: 'Bulk destructive operations' },
+  { pattern: /\b(send|post|upload)\s+(to|email|message|webhook)/i, risk: 'External communication capability' },
+  { pattern: /\b(install|download)\s+(package|module|binary|executable)/i, risk: 'Software installation capability' },
+];
+
+/**
+ * Known-safe tool name prefixes (reduce false positives)
+ */
+const SAFE_TOOL_PREFIXES = [
+  '@modelcontextprotocol/',
+  '@anthropic/',
+  'mcp-server-',
+];
+
+// ============================================================================
+// Live Scanner
+// ============================================================================
+
+export const liveScanner: Scanner = {
+  name: 'Live Server Scanner',
+
+  async scan(configs: MCPConfigFile[]): Promise<Finding[]> {
+    const findings: Finding[] = [];
+    let findingId = 0;
+
+    for (const config of configs) {
+      for (const [serverName, serverConfig] of Object.entries(config.servers)) {
+        // Connect to the server
+        let info: MCPServerInfo;
+
+        process.stderr.write(`  Connecting to ${serverName}...`);
+
+        if (serverConfig.url) {
+          info = await connectHTTP(serverConfig, serverName);
+        } else {
+          info = await connectStdio(serverConfig, serverName);
+        }
+
+        if (info.error) {
+          process.stderr.write(` \x1b[33mfailed\x1b[0m (${info.error})\n`);
+          findings.push({
+            id: `LIVE-${++findingId}`,
+            severity: 'info',
+            category: 'configuration',
+            title: `Could not connect to server`,
+            description: `Server "${serverName}" could not be reached: ${info.error}`,
+            server: serverName,
+            configFile: config.path,
+            remediation: 'Verify the server command/URL is correct and the server is running.',
+          });
+          continue;
+        }
+
+        const toolCount = info.tools.length;
+        const resourceCount = info.resources.length;
+        const promptCount = info.prompts.length;
+        process.stderr.write(
+          ` \x1b[32mconnected\x1b[0m (${info.connectTimeMs}ms) ` +
+          `[${toolCount} tools, ${resourceCount} resources, ${promptCount} prompts]\n`
+        );
+
+        // Scan tools
+        for (const tool of info.tools) {
+          const toolFindings = scanTool(tool, serverName, config.path, findingId);
+          findingId += toolFindings.length;
+          findings.push(...toolFindings);
+        }
+
+        // Scan for tool shadowing across servers
+        const toolNames = info.tools.map((t) => t.name);
+        const duplicateNames = findDuplicateToolNames(toolNames);
+        for (const dup of duplicateNames) {
+          findings.push({
+            id: `LIVE-${++findingId}`,
+            severity: 'high',
+            category: 'tool-poisoning',
+            title: `Duplicate tool name: "${dup}"`,
+            description: `Server "${serverName}" exposes multiple tools named "${dup}". This may indicate tool shadowing.`,
+            server: serverName,
+            configFile: config.path,
+            remediation: 'Investigate why the server has duplicate tool names. This is unusual and may indicate a compromised server.',
+          });
+        }
+
+        // Scan resources
+        for (const resource of info.resources) {
+          const resourceFindings = scanResource(resource, serverName, config.path, findingId);
+          findingId += resourceFindings.length;
+          findings.push(...resourceFindings);
+        }
+
+        // Scan prompts
+        for (const prompt of info.prompts) {
+          const promptFindings = scanPrompt(prompt, serverName, config.path, findingId);
+          findingId += promptFindings.length;
+          findings.push(...promptFindings);
+        }
+
+        // Check for excessive capabilities
+        if (info.capabilities) {
+          const capFindings = scanCapabilities(info.capabilities, serverName, config.path, findingId);
+          findingId += capFindings.length;
+          findings.push(...capFindings);
+        }
+      }
+    }
+
+    return findings;
+  },
+};
+
+// ============================================================================
+// Tool Scanning
+// ============================================================================
+
+function scanTool(tool: MCPTool, serverName: string, configFile: string, startId: number): Finding[] {
+  const findings: Finding[] = [];
+  let findingId = startId;
+
+  const description = tool.description || '';
+  const schemaStr = tool.inputSchema ? JSON.stringify(tool.inputSchema) : '';
+  const fullText = `${tool.name} ${description} ${schemaStr}`;
+
+  // Check tool description for injection patterns
+  if (description.length > 10) {
+    const analysis = analyzeForInjection(description, [INJECTION_PATTERNS, TOOL_POISONING_PATTERNS]);
+
+    if (analysis.detected) {
+      for (const match of analysis.matches) {
+        findings.push({
+          id: `LIVE-${++findingId}`,
+          severity: match.severity,
+          category: match.category.includes('Shadowing') || match.category.includes('hidden') || match.category.includes('Exfiltration')
+            ? 'tool-poisoning'
+            : 'prompt-injection',
+          title: `${match.name} in tool "${tool.name}"`,
+          description: `Tool "${tool.name}" on server "${serverName}" has a suspicious pattern in its description: ${match.name}.`,
+          server: serverName,
+          configFile,
+          evidence: truncate(description, 150),
+          remediation: 'This tool description contains patterns associated with tool poisoning attacks. Review the MCP server source code.',
+        });
+      }
+    }
+  }
+
+  // Check for dangerous tool capabilities
+  for (const dangerous of DANGEROUS_TOOL_PATTERNS) {
+    if (dangerous.pattern.test(tool.name) || dangerous.pattern.test(description)) {
+      findings.push({
+        id: `LIVE-${++findingId}`,
+        severity: 'medium',
+        category: 'excessive-permissions',
+        title: `${dangerous.risk}: "${tool.name}"`,
+        description: `Tool "${tool.name}" on server "${serverName}" has ${dangerous.risk.toLowerCase()}. Ensure this is expected and properly sandboxed.`,
+        server: serverName,
+        configFile,
+        evidence: truncate(`${tool.name}: ${description}`, 150),
+        remediation: 'Verify this tool capability is expected. Consider restricting its scope or adding authorization checks.',
+      });
+    }
+  }
+
+  // Check input schema for suspicious default values
+  if (tool.inputSchema && typeof tool.inputSchema === 'object') {
+    const schemaAnalysis = analyzeForInjection(schemaStr, [INJECTION_PATTERNS]);
+    if (schemaAnalysis.detected) {
+      findings.push({
+        id: `LIVE-${++findingId}`,
+        severity: 'high',
+        category: 'prompt-injection',
+        title: `Injection pattern in tool schema: "${tool.name}"`,
+        description: `Tool "${tool.name}" input schema contains injection patterns. Default values or descriptions may be poisoned.`,
+        server: serverName,
+        configFile,
+        evidence: truncate(schemaStr, 150),
+        remediation: 'Review the tool input schema for hidden instructions in default values or field descriptions.',
+      });
+    }
+  }
+
+  return findings;
+}
+
+// ============================================================================
+// Resource Scanning
+// ============================================================================
+
+function scanResource(resource: MCPResource, serverName: string, configFile: string, startId: number): Finding[] {
+  const findings: Finding[] = [];
+  let findingId = startId;
+
+  // Check resource URI for SSRF
+  if (resource.uri.startsWith('http://') || resource.uri.startsWith('https://')) {
+    const urlResult = validateURL(resource.uri);
+    if (!urlResult.valid) {
+      findings.push({
+        id: `LIVE-${++findingId}`,
+        severity: urlResult.severity || 'high',
+        category: 'ssrf',
+        title: `Unsafe resource URI on "${serverName}"`,
+        description: `Resource "${resource.name || resource.uri}" has an unsafe URI: ${urlResult.reason}`,
+        server: serverName,
+        configFile,
+        evidence: `uri: ${resource.uri}`,
+        remediation: 'Review the resource URI. It may point to internal services or metadata endpoints.',
+      });
+    }
+  }
+
+  // Check resource description for injection
+  if (resource.description && resource.description.length > 10) {
+    const analysis = analyzeForInjection(resource.description, [INJECTION_PATTERNS, TOOL_POISONING_PATTERNS]);
+    if (analysis.detected) {
+      findings.push({
+        id: `LIVE-${++findingId}`,
+        severity: analysis.risk === 'critical' ? 'critical' : 'high',
+        category: 'prompt-injection',
+        title: `Injection in resource description: "${resource.name || resource.uri}"`,
+        description: `Resource description on "${serverName}" contains suspicious patterns.`,
+        server: serverName,
+        configFile,
+        evidence: truncate(resource.description, 150),
+        remediation: 'Review the resource description for hidden instructions.',
+      });
+    }
+  }
+
+  return findings;
+}
+
+// ============================================================================
+// Prompt Scanning
+// ============================================================================
+
+function scanPrompt(prompt: MCPPrompt, serverName: string, configFile: string, startId: number): Finding[] {
+  const findings: Finding[] = [];
+  let findingId = startId;
+
+  const description = prompt.description || '';
+
+  if (description.length > 10) {
+    const analysis = analyzeForInjection(description, [INJECTION_PATTERNS, TOOL_POISONING_PATTERNS]);
+    if (analysis.detected) {
+      for (const match of analysis.matches) {
+        findings.push({
+          id: `LIVE-${++findingId}`,
+          severity: match.severity,
+          category: 'prompt-injection',
+          title: `${match.name} in prompt "${prompt.name}"`,
+          description: `Prompt "${prompt.name}" on server "${serverName}" contains suspicious patterns in its description.`,
+          server: serverName,
+          configFile,
+          evidence: truncate(description, 150),
+          remediation: 'Review the prompt template for hidden instructions or injection payloads.',
+        });
+      }
+    }
+  }
+
+  // Check argument descriptions
+  if (prompt.arguments) {
+    for (const arg of prompt.arguments) {
+      if (arg.description && arg.description.length > 10) {
+        const argAnalysis = analyzeForInjection(arg.description, [INJECTION_PATTERNS]);
+        if (argAnalysis.detected) {
+          findings.push({
+            id: `LIVE-${++findingId}`,
+            severity: 'high',
+            category: 'prompt-injection',
+            title: `Injection in prompt argument "${arg.name}"`,
+            description: `Prompt "${prompt.name}" argument "${arg.name}" on "${serverName}" contains injection patterns.`,
+            server: serverName,
+            configFile,
+            evidence: truncate(arg.description, 150),
+            remediation: 'Review prompt argument descriptions for hidden instructions.',
+          });
+        }
+      }
+    }
+  }
+
+  return findings;
+}
+
+// ============================================================================
+// Capabilities Scanning
+// ============================================================================
+
+function scanCapabilities(
+  capabilities: Record<string, unknown>,
+  serverName: string,
+  configFile: string,
+  startId: number
+): Finding[] {
+  const findings: Finding[] = [];
+  let findingId = startId;
+
+  // Check for sampling capability (server can make LLM calls)
+  if (capabilities.sampling) {
+    findings.push({
+      id: `LIVE-${++findingId}`,
+      severity: 'medium',
+      category: 'excessive-permissions',
+      title: `Server requests sampling capability`,
+      description: `Server "${serverName}" requests the sampling capability, allowing it to make LLM calls through the client. This could be used for prompt injection amplification.`,
+      server: serverName,
+      configFile,
+      evidence: `capabilities.sampling: ${JSON.stringify(capabilities.sampling)}`,
+      remediation: 'Verify the server needs sampling capability. This allows the server to influence LLM behavior.',
+    });
+  }
+
+  return findings;
+}
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+function truncate(s: string, maxLen: number): string {
+  if (s.length <= maxLen) return s;
+  return s.substring(0, maxLen) + '...';
+}
+
+function findDuplicateToolNames(names: string[]): string[] {
+  const seen = new Set<string>();
+  const duplicates = new Set<string>();
+  for (const name of names) {
+    if (seen.has(name)) duplicates.add(name);
+    seen.add(name);
+  }
+  return [...duplicates];
+}

package/src/scanner/report.ts

@@ -0,0 +1,248 @@
+/**
+ * Sentinel MCP - Report Generator
+ *
+ * Generates security scan reports with scoring, findings, and remediation.
+ */
+
+import type { ScanReport, ScanSummary, Finding, MCPConfigFile, ScanStatus } from '../lib/types';
+
+const VERSION = '0.1.0';
+
+// ============================================================================
+// Score Calculation
+// ============================================================================
+
+/**
+ * Calculate security score (0-100, higher is better)
+ *
+ * Scoring:
+ * - Start at 100
+ * - Critical finding: -25 points
+ * - High finding: -15 points
+ * - Medium finding: -8 points
+ * - Low finding: -3 points
+ * - Info finding: -0 points
+ * - Minimum score: 0
+ */
+function calculateScore(findings: Finding[]): number {
+  let score = 100;
+
+  for (const finding of findings) {
+    switch (finding.severity) {
+      case 'critical': score -= 25; break;
+      case 'high': score -= 15; break;
+      case 'medium': score -= 8; break;
+      case 'low': score -= 3; break;
+      case 'info': break;
+    }
+  }
+
+  return Math.max(0, score);
+}
+
+/**
+ * Determine overall scan status from score
+ */
+function getStatus(score: number): ScanStatus {
+  if (score >= 80) return 'pass';
+  if (score >= 50) return 'warn';
+  return 'fail';
+}
+
+/**
+ * Generate a summary from findings
+ */
+function summarize(findings: Finding[], configs: MCPConfigFile[]): ScanSummary {
+  const totalServers = configs.reduce(
+    (sum, c) => sum + Object.keys(c.servers).length, 0
+  );
+
+  return {
+    totalServers,
+    totalFindings: findings.length,
+    critical: findings.filter((f) => f.severity === 'critical').length,
+    high: findings.filter((f) => f.severity === 'high').length,
+    medium: findings.filter((f) => f.severity === 'medium').length,
+    low: findings.filter((f) => f.severity === 'low').length,
+    info: findings.filter((f) => f.severity === 'info').length,
+  };
+}
+
+// ============================================================================
+// Report Generation
+// ============================================================================
+
+/**
+ * Generate a full scan report
+ */
+export function generateReport(
+  configs: MCPConfigFile[],
+  findings: Finding[]
+): ScanReport {
+  const score = calculateScore(findings);
+
+  return {
+    timestamp: new Date().toISOString(),
+    version: VERSION,
+    score,
+    status: getStatus(score),
+    configFiles: configs,
+    findings: findings.sort((a, b) => severityOrder(a.severity) - severityOrder(b.severity)),
+    summary: summarize(findings, configs),
+  };
+}
+
+function severityOrder(s: string): number {
+  const order: Record<string, number> = { critical: 0, high: 1, medium: 2, low: 3, info: 4 };
+  return order[s] ?? 5;
+}
+
+// ============================================================================
+// Console Output
+// ============================================================================
+
+const COLORS = {
+  reset: '\x1b[0m',
+  bold: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+  white: '\x1b[37m',
+  bgRed: '\x1b[41m',
+  bgGreen: '\x1b[42m',
+  bgYellow: '\x1b[43m',
+};
+
+function severityColor(severity: string): string {
+  switch (severity) {
+    case 'critical': return COLORS.bgRed + COLORS.white;
+    case 'high': return COLORS.red;
+    case 'medium': return COLORS.yellow;
+    case 'low': return COLORS.blue;
+    case 'info': return COLORS.dim;
+    default: return COLORS.reset;
+  }
+}
+
+function scoreColor(score: number): string {
+  if (score >= 80) return COLORS.green;
+  if (score >= 50) return COLORS.yellow;
+  return COLORS.red;
+}
+
+function statusBadge(status: ScanStatus): string {
+  switch (status) {
+    case 'pass': return `${COLORS.bgGreen}${COLORS.white} PASS ${COLORS.reset}`;
+    case 'warn': return `${COLORS.bgYellow}${COLORS.white} WARN ${COLORS.reset}`;
+    case 'fail': return `${COLORS.bgRed}${COLORS.white} FAIL ${COLORS.reset}`;
+  }
+}
+
+/**
+ * Print the scan report to console
+ */
+export function printReport(report: ScanReport): void {
+  const { summary, findings, score, status, configFiles } = report;
+
+  // Header
+  console.log();
+  console.log(`${COLORS.bold}${COLORS.cyan}  Sentinel MCP Security Scanner v${VERSION}${COLORS.reset}`);
+  console.log(`${COLORS.dim}  ${'─'.repeat(50)}${COLORS.reset}`);
+  console.log();
+
+  // Config files found
+  if (configFiles.length === 0) {
+    console.log(`  ${COLORS.yellow}No MCP configuration files found.${COLORS.reset}`);
+    console.log(`  ${COLORS.dim}Checked: Claude Desktop, Cursor, VS Code, Claude Code, Windsurf, Cline${COLORS.reset}`);
+    console.log();
+    return;
+  }
+
+  console.log(`  ${COLORS.bold}Configurations Found${COLORS.reset}`);
+  for (const config of configFiles) {
+    const serverCount = Object.keys(config.servers).length;
+    console.log(`  ${COLORS.cyan}${config.client}${COLORS.reset} (${serverCount} server${serverCount !== 1 ? 's' : ''})`);
+    console.log(`  ${COLORS.dim}${config.path}${COLORS.reset}`);
+
+    for (const serverName of Object.keys(config.servers)) {
+      console.log(`    ${COLORS.dim}└─${COLORS.reset} ${serverName}`);
+    }
+  }
+  console.log();
+
+  // Score
+  console.log(`  ${COLORS.bold}Security Score${COLORS.reset}`);
+  console.log(`  ${scoreColor(score)}${COLORS.bold}${score}/100${COLORS.reset}  ${statusBadge(status)}`);
+  console.log();
+
+  // Summary bar
+  if (summary.totalFindings > 0) {
+    const parts: string[] = [];
+    if (summary.critical > 0) parts.push(`${COLORS.bgRed}${COLORS.white} ${summary.critical} CRITICAL ${COLORS.reset}`);
+    if (summary.high > 0) parts.push(`${COLORS.red}${summary.high} high${COLORS.reset}`);
+    if (summary.medium > 0) parts.push(`${COLORS.yellow}${summary.medium} medium${COLORS.reset}`);
+    if (summary.low > 0) parts.push(`${COLORS.blue}${summary.low} low${COLORS.reset}`);
+    if (summary.info > 0) parts.push(`${COLORS.dim}${summary.info} info${COLORS.reset}`);
+    console.log(`  ${parts.join('  ')}`);
+    console.log();
+  }
+
+  // Findings
+  if (findings.length === 0) {
+    console.log(`  ${COLORS.green}No security issues found.${COLORS.reset}`);
+    console.log();
+    return;
+  }
+
+  console.log(`  ${COLORS.bold}Findings${COLORS.reset}`);
+  console.log(`  ${COLORS.dim}${'─'.repeat(50)}${COLORS.reset}`);
+
+  for (const finding of findings) {
+    const sev = severityColor(finding.severity);
+    const sevLabel = finding.severity.toUpperCase().padEnd(8);
+
+    console.log();
+    console.log(`  ${sev}${sevLabel}${COLORS.reset} ${COLORS.bold}${finding.title}${COLORS.reset}  ${COLORS.dim}[${finding.id}]${COLORS.reset}`);
+
+    if (finding.server) {
+      console.log(`  ${COLORS.dim}Server:${COLORS.reset} ${finding.server}`);
+    }
+
+    console.log(`  ${finding.description}`);
+
+    if (finding.evidence) {
+      console.log(`  ${COLORS.dim}Evidence: ${finding.evidence}${COLORS.reset}`);
+    }
+
+    if (finding.remediation) {
+      console.log(`  ${COLORS.green}Fix: ${finding.remediation}${COLORS.reset}`);
+    }
+  }
+
+  console.log();
+  console.log(`  ${COLORS.dim}${'─'.repeat(50)}${COLORS.reset}`);
+  console.log(`  ${summary.totalServers} server${summary.totalServers !== 1 ? 's' : ''} scanned across ${configFiles.length} config file${configFiles.length !== 1 ? 's' : ''}`);
+  console.log(`  ${summary.totalFindings} finding${summary.totalFindings !== 1 ? 's' : ''} reported`);
+  console.log();
+}
+
+/**
+ * Output report as JSON
+ */
+export function printReportJSON(report: ScanReport): void {
+  // Strip raw config data to avoid leaking secrets in JSON output
+  const safeReport = {
+    ...report,
+    configFiles: report.configFiles.map((c) => ({
+      path: c.path,
+      client: c.client,
+      servers: Object.keys(c.servers),
+    })),
+  };
+
+  console.log(JSON.stringify(safeReport, null, 2));
+}