mcpsec 0.1.0

package/src/lib/mcp-client.ts

@@ -0,0 +1,384 @@
+/**
+ * Sentinel MCP - Lightweight MCP Protocol Client
+ *
+ * Connects to MCP servers via stdio or HTTP transport,
+ * performs the initialization handshake, and queries
+ * tools/list, resources/list, prompts/list.
+ *
+ * Uses JSON-RPC 2.0 over newline-delimited JSON (stdio)
+ * or HTTP POST (streamable-http / SSE).
+ */
+
+import { spawn, type Subprocess } from 'bun';
+import type { MCPServerConfig } from './types';
+
+// ============================================================================
+// MCP Protocol Types
+// ============================================================================
+
+interface JsonRpcRequest {
+  jsonrpc: '2.0';
+  id: number;
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+interface JsonRpcResponse {
+  jsonrpc: '2.0';
+  id: number;
+  result?: unknown;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+export interface MCPTool {
+  name: string;
+  description?: string;
+  inputSchema?: Record<string, unknown>;
+}
+
+export interface MCPResource {
+  uri: string;
+  name?: string;
+  description?: string;
+  mimeType?: string;
+}
+
+export interface MCPPrompt {
+  name: string;
+  description?: string;
+  arguments?: Array<{ name: string; description?: string; required?: boolean }>;
+}
+
+export interface MCPServerInfo {
+  name?: string;
+  version?: string;
+  protocolVersion?: string;
+  capabilities?: Record<string, unknown>;
+  tools: MCPTool[];
+  resources: MCPResource[];
+  prompts: MCPPrompt[];
+  error?: string;
+  connectTimeMs?: number;
+}
+
+// ============================================================================
+// Stdio Transport
+// ============================================================================
+
+const CONNECT_TIMEOUT = 10_000; // 10s to connect + initialize
+const REQUEST_TIMEOUT = 5_000;  // 5s per request
+
+/**
+ * Connect to an MCP server via stdio transport
+ */
+export async function connectStdio(
+  config: MCPServerConfig,
+  serverName: string
+): Promise<MCPServerInfo> {
+  const startTime = Date.now();
+
+  if (!config.command) {
+    return { tools: [], resources: [], prompts: [], error: 'No command specified' };
+  }
+
+  // Parse command - first word is the binary, rest are initial args
+  const parts = config.command.split(/\s+/);
+  const cmd = parts[0];
+  const cmdArgs = [...parts.slice(1), ...(config.args || [])];
+
+  let proc: Subprocess | null = null;
+
+  try {
+    // Spawn the server process
+    proc = spawn({
+      cmd: [cmd, ...cmdArgs],
+      env: { ...process.env, ...(config.env || {}) },
+      stdin: 'pipe',
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+
+    const reader = new StdioReader(proc);
+    let messageId = 0;
+
+    // Helper: send JSON-RPC and wait for response
+    const sendRequest = async (method: string, params?: Record<string, unknown>): Promise<unknown> => {
+      const id = ++messageId;
+      const request: JsonRpcRequest = {
+        jsonrpc: '2.0',
+        id,
+        method,
+        params,
+      };
+
+      const line = JSON.stringify(request) + '\n';
+      proc!.stdin.write(line);
+      proc!.stdin.flush();
+
+      const response = await reader.waitForResponse(id, REQUEST_TIMEOUT);
+      if (response.error) {
+        throw new Error(`${method} failed: ${response.error.message}`);
+      }
+      return response.result;
+    };
+
+    // Helper: send notification (no response expected)
+    const sendNotification = (method: string, params?: Record<string, unknown>) => {
+      const notification = {
+        jsonrpc: '2.0' as const,
+        method,
+        params,
+      };
+      proc!.stdin.write(JSON.stringify(notification) + '\n');
+      proc!.stdin.flush();
+    };
+
+    // Step 1: Initialize
+    const initResult = await sendRequest('initialize', {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: {
+        name: 'sentinel-mcp',
+        version: '0.1.0',
+      },
+    }) as Record<string, unknown>;
+
+    // Step 2: Send initialized notification
+    sendNotification('notifications/initialized');
+
+    // Step 3: Query tools, resources, prompts in parallel
+    const info: MCPServerInfo = {
+      name: (initResult?.serverInfo as Record<string, string>)?.name,
+      version: (initResult?.serverInfo as Record<string, string>)?.version,
+      protocolVersion: initResult?.protocolVersion as string,
+      capabilities: initResult?.capabilities as Record<string, unknown>,
+      tools: [],
+      resources: [],
+      prompts: [],
+      connectTimeMs: Date.now() - startTime,
+    };
+
+    // Query tools
+    try {
+      const toolsResult = await sendRequest('tools/list') as { tools?: MCPTool[] };
+      info.tools = toolsResult?.tools || [];
+    } catch {
+      // Server may not support tools
+    }
+
+    // Query resources
+    try {
+      const resourcesResult = await sendRequest('resources/list') as { resources?: MCPResource[] };
+      info.resources = resourcesResult?.resources || [];
+    } catch {
+      // Server may not support resources
+    }
+
+    // Query prompts
+    try {
+      const promptsResult = await sendRequest('prompts/list') as { prompts?: MCPPrompt[] };
+      info.prompts = promptsResult?.prompts || [];
+    } catch {
+      // Server may not support prompts
+    }
+
+    return info;
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    return {
+      tools: [],
+      resources: [],
+      prompts: [],
+      error: `Failed to connect to "${serverName}": ${error}`,
+      connectTimeMs: Date.now() - startTime,
+    };
+  } finally {
+    // Clean up the process
+    if (proc) {
+      try {
+        proc.stdin.end();
+        proc.kill();
+      } catch {
+        // Process may have already exited
+      }
+    }
+  }
+}
+
+// ============================================================================
+// Stdio Reader - Parses newline-delimited JSON-RPC from stdout
+// ============================================================================
+
+class StdioReader {
+  private buffer = '';
+  private pendingResponses = new Map<number, {
+    resolve: (r: JsonRpcResponse) => void;
+    reject: (e: Error) => void;
+  }>();
+  private reader: ReadableStreamDefaultReader<Uint8Array>;
+  private decoder = new TextDecoder();
+  private reading = false;
+
+  constructor(proc: Subprocess) {
+    this.reader = (proc.stdout as ReadableStream<Uint8Array>).getReader();
+    this.startReading();
+  }
+
+  private async startReading() {
+    if (this.reading) return;
+    this.reading = true;
+
+    try {
+      while (true) {
+        const { done, value } = await this.reader.read();
+        if (done) break;
+
+        this.buffer += this.decoder.decode(value, { stream: true });
+        this.processBuffer();
+      }
+    } catch {
+      // Stream closed
+    }
+  }
+
+  private processBuffer() {
+    const lines = this.buffer.split('\n');
+    // Keep the last incomplete line in the buffer
+    this.buffer = lines.pop() || '';
+
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed) continue;
+
+      try {
+        const msg = JSON.parse(trimmed);
+        if (msg.id !== undefined && this.pendingResponses.has(msg.id)) {
+          const pending = this.pendingResponses.get(msg.id)!;
+          this.pendingResponses.delete(msg.id);
+          pending.resolve(msg as JsonRpcResponse);
+        }
+        // Ignore notifications from server (no id)
+      } catch {
+        // Skip non-JSON lines (server logs, etc.)
+      }
+    }
+  }
+
+  async waitForResponse(id: number, timeoutMs: number): Promise<JsonRpcResponse> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pendingResponses.delete(id);
+        reject(new Error(`Request ${id} timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+
+      this.pendingResponses.set(id, {
+        resolve: (r) => {
+          clearTimeout(timer);
+          resolve(r);
+        },
+        reject: (e) => {
+          clearTimeout(timer);
+          reject(e);
+        },
+      });
+    });
+  }
+}
+
+// ============================================================================
+// HTTP Transport
+// ============================================================================
+
+/**
+ * Connect to an MCP server via HTTP transport (SSE / streamable-http)
+ */
+export async function connectHTTP(
+  config: MCPServerConfig,
+  serverName: string
+): Promise<MCPServerInfo> {
+  const startTime = Date.now();
+
+  if (!config.url) {
+    return { tools: [], resources: [], prompts: [], error: 'No URL specified' };
+  }
+
+  try {
+    let messageId = 0;
+
+    const sendRequest = async (method: string, params?: Record<string, unknown>): Promise<unknown> => {
+      const request: JsonRpcRequest = {
+        jsonrpc: '2.0',
+        id: ++messageId,
+        method,
+        params,
+      };
+
+      const response = await fetch(config.url!, {
+        method: 'POST',
+        headers: {
+          'Content-Type': 'application/json',
+          ...(config.env?.AUTHORIZATION ? { Authorization: config.env.AUTHORIZATION } : {}),
+        },
+        body: JSON.stringify(request),
+        signal: AbortSignal.timeout(REQUEST_TIMEOUT),
+      });
+
+      if (!response.ok) {
+        throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+      }
+
+      const result = await response.json() as JsonRpcResponse;
+      if (result.error) {
+        throw new Error(`${method} failed: ${result.error.message}`);
+      }
+      return result.result;
+    };
+
+    // Initialize
+    const initResult = await sendRequest('initialize', {
+      protocolVersion: '2024-11-05',
+      capabilities: {},
+      clientInfo: { name: 'sentinel-mcp', version: '0.1.0' },
+    }) as Record<string, unknown>;
+
+    const info: MCPServerInfo = {
+      name: (initResult?.serverInfo as Record<string, string>)?.name,
+      version: (initResult?.serverInfo as Record<string, string>)?.version,
+      protocolVersion: initResult?.protocolVersion as string,
+      capabilities: initResult?.capabilities as Record<string, unknown>,
+      tools: [],
+      resources: [],
+      prompts: [],
+      connectTimeMs: Date.now() - startTime,
+    };
+
+    // Query tools
+    try {
+      const toolsResult = await sendRequest('tools/list') as { tools?: MCPTool[] };
+      info.tools = toolsResult?.tools || [];
+    } catch { /* not supported */ }
+
+    // Query resources
+    try {
+      const resourcesResult = await sendRequest('resources/list') as { resources?: MCPResource[] };
+      info.resources = resourcesResult?.resources || [];
+    } catch { /* not supported */ }
+
+    // Query prompts
+    try {
+      const promptsResult = await sendRequest('prompts/list') as { prompts?: MCPPrompt[] };
+      info.prompts = promptsResult?.prompts || [];
+    } catch { /* not supported */ }
+
+    return info;
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    return {
+      tools: [],
+      resources: [],
+      prompts: [],
+      error: `Failed to connect to "${serverName}" at ${config.url}: ${error}`,
+      connectTimeMs: Date.now() - startTime,
+    };
+  }
+}

package/src/lib/types.ts

@@ -0,0 +1,90 @@
+/**
+ * Sentinel MCP - Core Type Definitions
+ */
+
+// ============================================================================
+// Severity & Risk
+// ============================================================================
+
+export type Severity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+
+export type ScanStatus = 'pass' | 'warn' | 'fail';
+
+// ============================================================================
+// MCP Configuration
+// ============================================================================
+
+export interface MCPServerConfig {
+  command?: string;
+  args?: string[];
+  env?: Record<string, string>;
+  url?: string;
+  transport?: 'stdio' | 'sse' | 'streamable-http';
+}
+
+export interface MCPConfigFile {
+  path: string;
+  client: string;
+  servers: Record<string, MCPServerConfig>;
+  raw: unknown;
+}
+
+// ============================================================================
+// Scan Findings
+// ============================================================================
+
+export interface Finding {
+  id: string;
+  severity: Severity;
+  category: FindingCategory;
+  title: string;
+  description: string;
+  server?: string;
+  configFile?: string;
+  evidence?: string;
+  remediation?: string;
+}
+
+export type FindingCategory =
+  | 'credential-exposure'
+  | 'prompt-injection'
+  | 'tool-poisoning'
+  | 'ssrf'
+  | 'command-injection'
+  | 'insecure-transport'
+  | 'excessive-permissions'
+  | 'supply-chain'
+  | 'configuration';
+
+// ============================================================================
+// Scan Report
+// ============================================================================
+
+export interface ScanReport {
+  timestamp: string;
+  version: string;
+  score: number; // 0-100
+  status: ScanStatus;
+  configFiles: MCPConfigFile[];
+  findings: Finding[];
+  summary: ScanSummary;
+}
+
+export interface ScanSummary {
+  totalServers: number;
+  totalFindings: number;
+  critical: number;
+  high: number;
+  medium: number;
+  low: number;
+  info: number;
+}
+
+// ============================================================================
+// Scanner Interface
+// ============================================================================
+
+export interface Scanner {
+  name: string;
+  scan(configs: MCPConfigFile[]): Promise<Finding[]>;
+}

package/src/lib/url-validator.ts

@@ -0,0 +1,130 @@
+/**
+ * Sentinel MCP - URL Validation & SSRF Protection
+ *
+ * Validates URLs found in MCP server configurations for SSRF,
+ * insecure transports, and suspicious patterns.
+ */
+
+import type { Severity } from './types';
+
+export interface URLValidationResult {
+  valid: boolean;
+  reason?: string;
+  warnings: string[];
+  severity?: Severity;
+}
+
+// ============================================================================
+// SSRF Protection Configuration
+// ============================================================================
+
+const BLOCKED_HOSTS = [
+  'localhost',
+  '127.0.0.1',
+  '0.0.0.0',
+  '::1',
+  '[::1]',
+];
+
+const BLOCKED_IP_RANGES: RegExp[] = [
+  /^10\./,                          // 10.0.0.0/8 (RFC1918)
+  /^172\.(1[6-9]|2[0-9]|3[01])\./,  // 172.16.0.0/12 (RFC1918)
+  /^192\.168\./,                     // 192.168.0.0/16 (RFC1918)
+  /^169\.254\./,                     // 169.254.0.0/16 (link-local)
+  /^100\.(6[4-9]|[7-9][0-9]|1[01][0-9]|12[0-7])\./, // 100.64.0.0/10 (CGNAT)
+  /^198\.51\.100\./,                 // 198.51.100.0/24 (TEST-NET-2)
+  /^203\.0\.113\./,                  // 203.0.113.0/24 (TEST-NET-3)
+  /^224\./,                          // 224.0.0.0/4 (multicast)
+  /^240\./,                          // 240.0.0.0/4 (reserved)
+];
+
+const CLOUD_METADATA_ENDPOINTS = [
+  '169.254.169.254',   // AWS/GCP/Azure metadata
+  'metadata.google.internal',
+  'metadata.google',
+  '100.100.100.200',   // Alibaba Cloud metadata
+];
+
+// ============================================================================
+// Validation
+// ============================================================================
+
+/**
+ * Validate a URL for SSRF and security concerns
+ */
+export function validateURL(url: string): URLValidationResult {
+  const warnings: string[] = [];
+
+  let parsed: URL;
+  try {
+    parsed = new URL(url);
+  } catch {
+    return { valid: false, reason: 'Invalid URL format', warnings };
+  }
+
+  const hostname = parsed.hostname.toLowerCase();
+  const scheme = parsed.protocol.replace(':', '').toLowerCase();
+
+  // Check scheme
+  if (!['https', 'http'].includes(scheme)) {
+    return {
+      valid: false,
+      reason: `Unsafe scheme: ${scheme}`,
+      warnings,
+      severity: 'high',
+    };
+  }
+
+  // SSRF: blocked hosts
+  if (BLOCKED_HOSTS.includes(hostname)) {
+    return {
+      valid: false,
+      reason: `SSRF risk: blocked host ${hostname}`,
+      warnings,
+      severity: 'critical',
+    };
+  }
+
+  // SSRF: cloud metadata endpoints (check before generic IP ranges for specific messaging)
+  if (CLOUD_METADATA_ENDPOINTS.includes(hostname)) {
+    return {
+      valid: false,
+      reason: `SSRF risk: cloud metadata endpoint ${hostname}`,
+      warnings,
+      severity: 'critical',
+    };
+  }
+
+  // SSRF: blocked IP ranges
+  for (const range of BLOCKED_IP_RANGES) {
+    if (range.test(hostname)) {
+      return {
+        valid: false,
+        reason: `SSRF risk: private/reserved IP range`,
+        warnings,
+        severity: 'critical',
+      };
+    }
+  }
+
+  // HTTP without TLS
+  if (scheme === 'http') {
+    warnings.push('Transport uses HTTP (unencrypted) - credentials and tokens may be exposed');
+  }
+
+  // Embedded credentials
+  if (parsed.username || parsed.password) {
+    warnings.push('URL contains embedded credentials');
+  }
+
+  // Non-standard port
+  if (parsed.port && !['80', '443', '8080', '8443'].includes(parsed.port)) {
+    warnings.push(`Non-standard port: ${parsed.port}`);
+  }
+
+  return {
+    valid: true,
+    warnings,
+    severity: warnings.length > 0 ? 'medium' : undefined,
+  };
+}