mcpsec 0.1.0

package/src/scanner/config-scanner.ts

@@ -0,0 +1,262 @@
+/**
+ * Sentinel MCP - Configuration Scanner
+ *
+ * Discovers and parses MCP configuration files from known client locations:
+ * - Claude Desktop (claude_desktop_config.json)
+ * - Cursor (.cursor/mcp.json)
+ * - VS Code (settings.json with mcp servers)
+ * - Claude Code (.claude/settings.json or .mcp.json)
+ * - Windsurf, Cline, etc.
+ */
+
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+import type { MCPConfigFile, MCPServerConfig, Finding } from '../lib/types';
+
+// ============================================================================
+// Known MCP Config Locations
+// ============================================================================
+
+interface ConfigLocation {
+  client: string;
+  paths: string[];
+  parser: (raw: unknown) => Record<string, MCPServerConfig> | null;
+}
+
+function getConfigLocations(): ConfigLocation[] {
+  const home = homedir();
+  const platform = process.platform;
+
+  return [
+    // Claude Desktop
+    {
+      client: 'Claude Desktop',
+      paths: [
+        platform === 'darwin'
+          ? join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json')
+          : platform === 'win32'
+            ? join(home, 'AppData', 'Roaming', 'Claude', 'claude_desktop_config.json')
+            : join(home, '.config', 'claude', 'claude_desktop_config.json'),
+      ],
+      parser: parseClaudeDesktopConfig,
+    },
+    // Claude Code (project-level)
+    {
+      client: 'Claude Code',
+      paths: [
+        join(process.cwd(), '.mcp.json'),
+        join(home, '.claude', 'settings.json'),
+      ],
+      parser: parseClaudeCodeConfig,
+    },
+    // Cursor
+    {
+      client: 'Cursor',
+      paths: [
+        join(home, '.cursor', 'mcp.json'),
+      ],
+      parser: parseCursorConfig,
+    },
+    // VS Code
+    {
+      client: 'VS Code',
+      paths: [
+        platform === 'darwin'
+          ? join(home, 'Library', 'Application Support', 'Code', 'User', 'settings.json')
+          : platform === 'win32'
+            ? join(home, 'AppData', 'Roaming', 'Code', 'User', 'settings.json')
+            : join(home, '.config', 'Code', 'User', 'settings.json'),
+      ],
+      parser: parseVSCodeConfig,
+    },
+    // Windsurf
+    {
+      client: 'Windsurf',
+      paths: [
+        join(home, '.codeium', 'windsurf', 'mcp_config.json'),
+      ],
+      parser: parseClaudeDesktopConfig, // Same format
+    },
+    // Cline
+    {
+      client: 'Cline',
+      paths: [
+        join(home, '.cline', 'mcp_settings.json'),
+      ],
+      parser: parseClineConfig,
+    },
+  ];
+}
+
+// ============================================================================
+// Config Parsers
+// ============================================================================
+
+function parseClaudeDesktopConfig(raw: unknown): Record<string, MCPServerConfig> | null {
+  const config = raw as Record<string, unknown>;
+  if (config?.mcpServers && typeof config.mcpServers === 'object') {
+    return config.mcpServers as Record<string, MCPServerConfig>;
+  }
+  return null;
+}
+
+function parseClaudeCodeConfig(raw: unknown): Record<string, MCPServerConfig> | null {
+  const config = raw as Record<string, unknown>;
+  // .mcp.json format
+  if (config?.mcpServers && typeof config.mcpServers === 'object') {
+    return config.mcpServers as Record<string, MCPServerConfig>;
+  }
+  // settings.json format
+  if (config?.mcpServers && typeof config.mcpServers === 'object') {
+    return config.mcpServers as Record<string, MCPServerConfig>;
+  }
+  return null;
+}
+
+function parseCursorConfig(raw: unknown): Record<string, MCPServerConfig> | null {
+  const config = raw as Record<string, unknown>;
+  if (config?.mcpServers && typeof config.mcpServers === 'object') {
+    return config.mcpServers as Record<string, MCPServerConfig>;
+  }
+  return null;
+}
+
+function parseVSCodeConfig(raw: unknown): Record<string, MCPServerConfig> | null {
+  const config = raw as Record<string, unknown>;
+  // VS Code uses "mcp.servers" key
+  const mcpConfig = config?.['mcp'] as Record<string, unknown> | undefined;
+  if (mcpConfig?.servers && typeof mcpConfig.servers === 'object') {
+    return mcpConfig.servers as Record<string, MCPServerConfig>;
+  }
+  return null;
+}
+
+function parseClineConfig(raw: unknown): Record<string, MCPServerConfig> | null {
+  const config = raw as Record<string, unknown>;
+  if (config?.mcpServers && typeof config.mcpServers === 'object') {
+    return config.mcpServers as Record<string, MCPServerConfig>;
+  }
+  return null;
+}
+
+// ============================================================================
+// Discovery
+// ============================================================================
+
+/**
+ * Discover all MCP configuration files on the system
+ */
+export function discoverConfigs(): MCPConfigFile[] {
+  const configs: MCPConfigFile[] = [];
+  const locations = getConfigLocations();
+
+  for (const location of locations) {
+    for (const configPath of location.paths) {
+      if (!existsSync(configPath)) continue;
+
+      try {
+        const content = readFileSync(configPath, 'utf-8');
+        const raw = JSON.parse(content);
+        const servers = location.parser(raw);
+
+        if (servers && Object.keys(servers).length > 0) {
+          configs.push({
+            path: configPath,
+            client: location.client,
+            servers,
+            raw,
+          });
+        }
+      } catch {
+        // Skip unparseable configs
+      }
+    }
+  }
+
+  return configs;
+}
+
+// ============================================================================
+// Config-Level Security Checks
+// ============================================================================
+
+/**
+ * Scan config files for configuration-level security issues
+ */
+export function scanConfigs(configs: MCPConfigFile[]): Finding[] {
+  const findings: Finding[] = [];
+  let findingId = 0;
+
+  for (const config of configs) {
+    for (const [serverName, server] of Object.entries(config.servers)) {
+      // Check for stdio transport with absolute paths to unknown binaries
+      if (server.command) {
+        // npx/bunx with unknown packages
+        if (/^(npx|bunx|pnpx)\s/.test(server.command)) {
+          const pkg = server.command.split(/\s+/)[1];
+          if (pkg && !pkg.startsWith('@anthropic') && !pkg.startsWith('@modelcontextprotocol')) {
+            findings.push({
+              id: `CFG-${++findingId}`,
+              severity: 'medium',
+              category: 'supply-chain',
+              title: `Unverified npm package: ${pkg}`,
+              description: `Server "${serverName}" uses npx/bunx to run "${pkg}". This package is downloaded and executed at runtime without integrity verification.`,
+              server: serverName,
+              configFile: config.path,
+              evidence: `command: ${server.command}`,
+              remediation: 'Pin the package version and verify its integrity. Consider installing locally instead of using npx.',
+            });
+          }
+        }
+
+        // Docker without security flags
+        if (/^docker\s+run\b/.test(server.command) && !/--security-opt|--cap-drop/.test(server.command)) {
+          findings.push({
+            id: `CFG-${++findingId}`,
+            severity: 'medium',
+            category: 'excessive-permissions',
+            title: `Docker container without security restrictions`,
+            description: `Server "${serverName}" runs a Docker container without --security-opt or --cap-drop flags.`,
+            server: serverName,
+            configFile: config.path,
+            evidence: `command: ${server.command}`,
+            remediation: 'Add --security-opt=no-new-privileges and --cap-drop=ALL to the docker run command.',
+          });
+        }
+
+        // Privileged docker
+        if (/docker\s+run\b.*--privileged/.test(server.command)) {
+          findings.push({
+            id: `CFG-${++findingId}`,
+            severity: 'critical',
+            category: 'excessive-permissions',
+            title: `Privileged Docker container`,
+            description: `Server "${serverName}" runs a Docker container with --privileged, giving it full host access.`,
+            server: serverName,
+            configFile: config.path,
+            evidence: `command: ${server.command}`,
+            remediation: 'Remove --privileged flag and use specific --cap-add flags for required capabilities only.',
+          });
+        }
+      }
+
+      // Check for HTTP (non-HTTPS) transport URLs
+      if (server.url && server.url.startsWith('http://')) {
+        findings.push({
+          id: `CFG-${++findingId}`,
+          severity: 'high',
+          category: 'insecure-transport',
+          title: `Unencrypted HTTP transport`,
+          description: `Server "${serverName}" uses HTTP instead of HTTPS. API keys and conversation data are transmitted in cleartext.`,
+          server: serverName,
+          configFile: config.path,
+          evidence: `url: ${server.url}`,
+          remediation: 'Use HTTPS (wss:// or https://) for the server URL.',
+        });
+      }
+    }
+  }
+
+  return findings;
+}

package/src/scanner/credential-scanner.ts

@@ -0,0 +1,200 @@
+/**
+ * Sentinel MCP - Credential Scanner
+ *
+ * Detects hardcoded credentials, API keys, and tokens in MCP configurations.
+ * Maps to OWASP MCP Top 10: Token/Credential Mismanagement.
+ */
+
+import type { MCPConfigFile, Finding, Scanner } from '../lib/types';
+
+// ============================================================================
+// Credential Patterns
+// ============================================================================
+
+interface CredentialPattern {
+  name: string;
+  pattern: RegExp;
+  description: string;
+}
+
+const CREDENTIAL_PATTERNS: CredentialPattern[] = [
+  // API Keys
+  { name: 'Anthropic API Key', pattern: /sk-ant-api\d{2}-[A-Za-z0-9_-]{20,}/, description: 'Anthropic API key' },
+  { name: 'OpenAI API Key', pattern: /sk-proj-[A-Za-z0-9_-]{20,}/, description: 'OpenAI project API key' },
+  { name: 'OpenAI Legacy Key', pattern: /sk-[A-Za-z0-9]{48}/, description: 'OpenAI legacy API key' },
+  { name: 'Google API Key', pattern: /AIzaSy[A-Za-z0-9_-]{33}/, description: 'Google API key' },
+  { name: 'AWS Access Key', pattern: /AKIA[A-Z0-9]{16}/, description: 'AWS access key ID' },
+  { name: 'GitHub Token', pattern: /gh[ps]_[A-Za-z0-9]{36,}/, description: 'GitHub personal access token' },
+  { name: 'GitHub Fine-grained', pattern: /github_pat_[A-Za-z0-9_]{20,}/, description: 'GitHub fine-grained PAT' },
+  { name: 'Slack Token', pattern: /xox[bporas]-[A-Za-z0-9-]+/, description: 'Slack API token' },
+  { name: 'Stripe Key', pattern: /sk_live_[A-Za-z0-9]{24,}/, description: 'Stripe live secret key' },
+  { name: 'Supabase Key', pattern: /eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+/, description: 'JWT token (possibly Supabase/auth)' },
+  { name: 'Perplexity Key', pattern: /pplx-[A-Za-z0-9]{48,}/, description: 'Perplexity API key' },
+  { name: 'Twilio SID', pattern: /AC[a-f0-9]{32}/, description: 'Twilio Account SID' },
+  { name: 'SendGrid Key', pattern: /SG\.[A-Za-z0-9_-]{22}\.[A-Za-z0-9_-]{43}/, description: 'SendGrid API key' },
+  { name: 'Mailgun Key', pattern: /key-[a-f0-9]{32}/, description: 'Mailgun API key' },
+  { name: 'HuggingFace Token', pattern: /hf_[A-Za-z0-9]{34,}/, description: 'Hugging Face API token' },
+  { name: 'Replicate Token', pattern: /r8_[A-Za-z0-9]{37,}/, description: 'Replicate API token' },
+
+  // Generic patterns
+  { name: 'Bearer Token', pattern: /Bearer\s+[A-Za-z0-9_.-]{20,}/, description: 'Bearer authentication token' },
+  { name: 'Basic Auth', pattern: /Basic\s+[A-Za-z0-9+/=]{20,}/, description: 'Basic authentication header' },
+  { name: 'Private Key', pattern: /-----BEGIN\s+(RSA\s+)?PRIVATE\s+KEY-----/, description: 'Private key material' },
+  { name: 'Password in URL', pattern: /:\/\/[^:]+:[^@]+@/, description: 'Credentials embedded in URL' },
+];
+
+// Environment variable names that commonly hold secrets
+const SENSITIVE_ENV_NAMES = [
+  /api[_-]?key/i,
+  /api[_-]?secret/i,
+  /auth[_-]?token/i,
+  /access[_-]?token/i,
+  /secret[_-]?key/i,
+  /private[_-]?key/i,
+  /password/i,
+  /passwd/i,
+  /credential/i,
+  /db[_-]?(pass|pwd|password)/i,
+  /database[_-]?url/i,
+  /connection[_-]?string/i,
+];
+
+// ============================================================================
+// Scanner
+// ============================================================================
+
+export const credentialScanner: Scanner = {
+  name: 'Credential Scanner',
+
+  async scan(configs: MCPConfigFile[]): Promise<Finding[]> {
+    const findings: Finding[] = [];
+    let findingId = 0;
+
+    for (const config of configs) {
+      // Stringify the whole config to catch credentials anywhere
+      const configStr = JSON.stringify(config.raw, null, 2);
+
+      for (const [serverName, server] of Object.entries(config.servers)) {
+        // Check command + args for hardcoded credentials
+        const commandStr = [
+          server.command || '',
+          ...(server.args || []),
+        ].join(' ');
+
+        for (const cred of CREDENTIAL_PATTERNS) {
+          if (cred.pattern.test(commandStr)) {
+            findings.push({
+              id: `CRED-${++findingId}`,
+              severity: 'critical',
+              category: 'credential-exposure',
+              title: `Hardcoded ${cred.name} in command`,
+              description: `Server "${serverName}" has a ${cred.description} hardcoded in its command/args. This is exposed to any process and in config file backups.`,
+              server: serverName,
+              configFile: config.path,
+              evidence: maskCredential(commandStr, cred.pattern),
+              remediation: 'Move credentials to environment variables or a secrets manager. Use the "env" field in server config.',
+            });
+          }
+        }
+
+        // Check environment variables for hardcoded values
+        if (server.env) {
+          for (const [envName, envValue] of Object.entries(server.env)) {
+            // Check if env var name suggests it's a secret
+            const isSensitiveName = SENSITIVE_ENV_NAMES.some((p) => p.test(envName));
+
+            // Check if the value matches a known credential pattern
+            for (const cred of CREDENTIAL_PATTERNS) {
+              if (cred.pattern.test(envValue)) {
+                findings.push({
+                  id: `CRED-${++findingId}`,
+                  severity: 'critical',
+                  category: 'credential-exposure',
+                  title: `Hardcoded ${cred.name} in env config`,
+                  description: `Server "${serverName}" has a ${cred.description} hardcoded in env.${envName}. Config files are often committed to git or backed up unencrypted.`,
+                  server: serverName,
+                  configFile: config.path,
+                  evidence: `${envName}=${maskCredential(envValue, cred.pattern)}`,
+                  remediation: 'Reference system environment variables instead of hardcoding values. Use ${ENV_VAR} syntax or a .env file excluded from version control.',
+                });
+                break; // One match per env var is enough
+              }
+            }
+
+            // Warn about sensitive-looking env vars even without pattern match
+            if (isSensitiveName && envValue.length > 10 && !findings.some((f) => f.evidence?.includes(envName))) {
+              findings.push({
+                id: `CRED-${++findingId}`,
+                severity: 'high',
+                category: 'credential-exposure',
+                title: `Potential secret in env: ${envName}`,
+                description: `Server "${serverName}" has a value in env.${envName} that appears to be a secret based on the variable name.`,
+                server: serverName,
+                configFile: config.path,
+                evidence: `${envName}=${envValue.substring(0, 4)}${'*'.repeat(Math.min(envValue.length - 4, 20))}`,
+                remediation: 'Use system environment variables or a secrets manager instead of config file values.',
+              });
+            }
+          }
+        }
+
+        // Check URL for embedded credentials
+        if (server.url) {
+          const urlCredPattern = /:\/\/([^:]+):([^@]+)@/;
+          if (urlCredPattern.test(server.url)) {
+            findings.push({
+              id: `CRED-${++findingId}`,
+              severity: 'critical',
+              category: 'credential-exposure',
+              title: `Credentials embedded in server URL`,
+              description: `Server "${serverName}" has credentials embedded in the URL. These appear in logs, browser history, and referrer headers.`,
+              server: serverName,
+              configFile: config.path,
+              evidence: server.url.replace(urlCredPattern, '://$1:****@'),
+              remediation: 'Pass credentials via environment variables or authentication headers instead of URL.',
+            });
+          }
+        }
+      }
+
+      // Scan raw config for credentials not in server definitions
+      for (const cred of CREDENTIAL_PATTERNS) {
+        const matches = configStr.match(cred.pattern);
+        if (matches) {
+          // Check if we already found this credential in a server-specific check
+          const alreadyFound = findings.some((f) =>
+            f.configFile === config.path && f.title.includes(cred.name)
+          );
+          if (!alreadyFound) {
+            findings.push({
+              id: `CRED-${++findingId}`,
+              severity: 'high',
+              category: 'credential-exposure',
+              title: `${cred.name} found in config file`,
+              description: `Config file contains what appears to be a ${cred.description}.`,
+              configFile: config.path,
+              evidence: maskCredential(matches[0], cred.pattern),
+              remediation: 'Move credentials out of config files into environment variables or a secrets manager.',
+            });
+          }
+        }
+      }
+    }
+
+    return findings;
+  },
+};
+
+// ============================================================================
+// Helpers
+// ============================================================================
+
+/**
+ * Mask a credential value for safe display
+ */
+function maskCredential(text: string, pattern: RegExp): string {
+  return text.replace(pattern, (match) => {
+    if (match.length <= 8) return '****';
+    return match.substring(0, 4) + '*'.repeat(Math.min(match.length - 8, 20)) + match.substring(match.length - 4);
+  });
+}