mcpsec 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rob Taylor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# Sentinel MCP
+
+**Security scanner for Model Context Protocol (MCP) servers.**
+
+Sentinel scans your MCP configurations for security vulnerabilities including hardcoded credentials, prompt injection, tool poisoning, SSRF, and insecure transport.
+
+## Quick Start
+
+```bash
+# Scan all detected MCP configurations
+bun run src/cli/index.ts scan
+
+# JSON output for CI/CD
+bun run src/cli/index.ts scan --json
+
+# Scan a specific config file
+bun run src/cli/index.ts scan --path ~/.cursor/mcp.json
+```
+
+## What It Scans
+
+| Check | Category | Severity |
+|-------|----------|----------|
+| Hardcoded API keys (Anthropic, OpenAI, GitHub, AWS, etc.) | Credential Exposure | Critical |
+| Prompt injection in tool descriptions | Tool Poisoning | Critical |
+| Tool shadowing / hidden instructions | Tool Poisoning | Critical |
+| SSRF via server URLs (localhost, private IPs, cloud metadata) | SSRF | Critical |
+| Command injection in server arguments | Command Injection | Critical |
+| Unencrypted HTTP transport | Insecure Transport | High |
+| Privileged Docker containers | Excessive Permissions | Critical |
+| Unverified npm packages via npx | Supply Chain | Medium |
+| Embedded credentials in URLs | Credential Exposure | Critical |
+| Sensitive environment variable values | Credential Exposure | High |
+
+## Supported Clients
+
+- Claude Desktop
+- Claude Code
+- Cursor
+- VS Code
+- Windsurf
+- Cline
+
+## Security Score
+
+Sentinel calculates a 0-100 security score:
+
+- **80-100**: PASS - No critical issues
+- **50-79**: WARN - Issues found, review recommended
+- **0-49**: FAIL - Critical vulnerabilities detected
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | No critical/high findings |
+| 1 | High severity findings |
+| 2 | Critical severity findings |
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run tests
+bun test
+
+# Type check
+bun run typecheck
+```
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "mcpsec",
+  "version": "0.1.0",
+  "description": "Security scanner for MCP (Model Context Protocol) servers - detects tool poisoning, credential exposure, prompt injection, and SSRF",
+  "license": "MIT",
+  "author": "Rob Taylor <robdtaylor@users.noreply.github.com>",
+  "type": "module",
+  "bin": {
+    "mcpsec": "./src/cli/index.ts"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "scan": "bun run src/cli/index.ts scan",
+    "test": "bun test",
+    "typecheck": "bun x tsc --noEmit"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.7.0"
+  },
+  "keywords": [
+    "mcp",
+    "security",
+    "scanner",
+    "model-context-protocol",
+    "ai-security",
+    "prompt-injection",
+    "ssrf",
+    "tool-poisoning",
+    "credential-scanner",
+    "mcpsec"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/robdtaylor/sentinel-mcp"
+  },
+  "homepage": "https://github.com/robdtaylor/sentinel-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/robdtaylor/sentinel-mcp/issues"
+  },
+  "engines": {
+    "bun": ">=1.0.0"
+  }
+}

package/src/cli/index.ts

@@ -0,0 +1,158 @@
+#!/usr/bin/env bun
+
+/**
+ * Sentinel MCP - CLI Entry Point
+ *
+ * Usage:
+ *   sentinel-mcp scan          Scan all detected MCP configurations
+ *   sentinel-mcp scan --json   Output results as JSON
+ *   sentinel-mcp scan --path   Scan a specific config file
+ */
+
+import { discoverConfigs, scanConfigs } from '../scanner/config-scanner';
+import { credentialScanner } from '../scanner/credential-scanner';
+import { toolScanner } from '../scanner/tool-scanner';
+import { liveScanner } from '../scanner/live-scanner';
+import { generateReport, printReport, printReportJSON } from '../scanner/report';
+import type { Finding, MCPConfigFile } from '../lib/types';
+
+// ============================================================================
+// CLI
+// ============================================================================
+
+const HELP = `
+  mcpsec - Security Scanner for Model Context Protocol
+
+  Usage:
+    mcpsec scan [options]
+
+  Options:
+    --live          Connect to running MCP servers and scan live
+    --json          Output results as JSON
+    --path <file>   Scan a specific config file
+    --no-color      Disable colored output
+    --help, -h      Show this help message
+    --version, -v   Show version
+
+  Examples:
+    mcpsec scan
+    mcpsec scan --live
+    mcpsec scan --json
+    mcpsec scan --path ~/.cursor/mcp.json
+`;
+
+async function main() {
+  const args = process.argv.slice(2);
+  const command = args[0];
+
+  if (!command || command === '--help' || command === '-h') {
+    console.log(HELP);
+    process.exit(0);
+  }
+
+  if (command === '--version' || command === '-v') {
+    console.log('mcpsec v0.1.0');
+    process.exit(0);
+  }
+
+  if (command !== 'scan') {
+    console.error(`Unknown command: ${command}`);
+    console.log(HELP);
+    process.exit(1);
+  }
+
+  // Parse scan options
+  const jsonOutput = args.includes('--json');
+  const liveMode = args.includes('--live');
+  const pathIndex = args.indexOf('--path');
+  const specificPath = pathIndex !== -1 ? args[pathIndex + 1] : undefined;
+
+  if (args.includes('--no-color')) {
+    // Disable colors by overriding environment
+    process.env.NO_COLOR = '1';
+  }
+
+  // Discover configs
+  let configs: MCPConfigFile[];
+
+  if (specificPath) {
+    // Scan a specific file
+    const { existsSync, readFileSync } = await import('fs');
+    if (!existsSync(specificPath)) {
+      console.error(`File not found: ${specificPath}`);
+      process.exit(1);
+    }
+
+    try {
+      const content = readFileSync(specificPath, 'utf-8');
+      const raw = JSON.parse(content);
+
+      // Try to detect format
+      const servers = raw.mcpServers || raw.mcp?.servers || {};
+      if (Object.keys(servers).length === 0) {
+        console.error(`No MCP servers found in ${specificPath}`);
+        process.exit(1);
+      }
+
+      configs = [{
+        path: specificPath,
+        client: 'Custom',
+        servers,
+        raw,
+      }];
+    } catch (e) {
+      console.error(`Failed to parse ${specificPath}: ${e}`);
+      process.exit(1);
+    }
+  } else {
+    configs = discoverConfigs();
+  }
+
+  // Run all scanners
+  const allFindings: Finding[] = [];
+
+  // Config-level checks
+  const configFindings = scanConfigs(configs);
+  allFindings.push(...configFindings);
+
+  // Credential scanner
+  const credFindings = await credentialScanner.scan(configs);
+  allFindings.push(...credFindings);
+
+  // Tool/injection scanner
+  const toolFindings = await toolScanner.scan(configs);
+  allFindings.push(...toolFindings);
+
+  // Live server scanner (connects to running servers)
+  if (liveMode) {
+    if (!jsonOutput) {
+      process.stderr.write('\n\x1b[1m🔴 Live Server Scan\x1b[0m\n');
+    }
+    const liveFindings = await liveScanner.scan(configs);
+    allFindings.push(...liveFindings);
+  }
+
+  // Generate report
+  const report = generateReport(configs, allFindings);
+
+  // Output
+  if (jsonOutput) {
+    printReportJSON(report);
+  } else {
+    printReport(report);
+  }
+
+  // Exit code based on findings
+  if (report.summary.critical > 0) {
+    process.exit(2); // Critical findings
+  } else if (report.summary.high > 0) {
+    process.exit(1); // High findings
+  }
+
+  process.exit(0);
+}
+
+main().catch((err) => {
+  console.error('Sentinel scan failed:', err);
+  process.exit(1);
+});

package/src/lib/injection-patterns.ts

@@ -0,0 +1,283 @@
+/**
+ * Sentinel MCP - Prompt Injection & Tool Poisoning Detection Patterns
+ *
+ * Adapted from production security infrastructure.
+ * Covers OWASP MCP Top 10 attack vectors.
+ */
+
+import type { Severity } from './types';
+
+export interface PatternCategory {
+  name: string;
+  severity: Severity;
+  patterns: RegExp[];
+  description: string;
+}
+
+// ============================================================================
+// Prompt Injection Patterns (in tool descriptions, prompts, resources)
+// ============================================================================
+
+export const INJECTION_PATTERNS: Record<string, PatternCategory> = {
+  instructionOverride: {
+    name: 'Instruction Override',
+    severity: 'critical',
+    description: 'Attempts to override system instructions via tool descriptions',
+    patterns: [
+      /ignore\s+(all\s+)?(previous|prior|above)\s+(instructions?|prompts?|rules?)/i,
+      /disregard\s+(all\s+)?(previous|prior|above)\s+(instructions?|prompts?)/i,
+      /forget\s+(all\s+)?(previous|prior|your)\s+(instructions?|training)/i,
+      /override\s+(all\s+)?(safety|security|restrictions?)/i,
+      /bypass\s+(all\s+)?(safety|security|filters?|restrictions?)/i,
+      /new\s+instruction[s]?:/i,
+      /system\s+prompt:/i,
+    ],
+  },
+
+  roleManipulation: {
+    name: 'Role Manipulation',
+    severity: 'high',
+    description: 'Attempts to change the AI agent role or mode',
+    patterns: [
+      /you\s+are\s+now\s+(in\s+)?([a-z]+\s+)?mode/i,
+      /enter\s+([a-z]+\s+)?mode/i,
+      /switch\s+to\s+([a-z]+\s+)?mode/i,
+      /pretend\s+(you\s+are|to\s+be)\s+/i,
+      /roleplay\s+as\s+/i,
+      /act\s+as\s+if\s+you\s+(are|were)\s+/i,
+    ],
+  },
+
+  systemPromptLeakage: {
+    name: 'System Prompt Leakage',
+    severity: 'high',
+    description: 'Attempts to extract system prompts or instructions',
+    patterns: [
+      /show\s+(me\s+)?your\s+(system\s+)?prompt/i,
+      /reveal\s+your\s+(system\s+)?instructions/i,
+      /what\s+(are|is)\s+your\s+(system\s+)?prompt/i,
+      /print\s+your\s+(initial\s+)?instructions/i,
+      /output\s+your\s+(hidden\s+)?prompt/i,
+    ],
+  },
+
+  delimiterAttacks: {
+    name: 'Delimiter Injection',
+    severity: 'critical',
+    description: 'LLM-specific delimiter injection (ChatML, Llama, etc.)',
+    patterns: [
+      /\[INST\]/i,
+      /\[\/INST\]/i,
+      /<\|im_start\|>/i,
+      /<\|im_end\|>/i,
+      /<\|system\|>/i,
+      /<\|user\|>/i,
+      /<\|assistant\|>/i,
+      /<<SYS>>/i,
+      /<\/SYS>/i,
+      /\[\[SYSTEM\]\]/i,
+    ],
+  },
+
+  jailbreakAttempts: {
+    name: 'Jailbreak Attempt',
+    severity: 'critical',
+    description: 'Known jailbreak techniques embedded in tool metadata',
+    patterns: [
+      /DAN\s*(mode)?/i,
+      /do\s+anything\s+now/i,
+      /maximum\s+mode/i,
+      /developer\s+mode/i,
+      /unrestricted\s+mode/i,
+      /no\s+restrictions?\s+mode/i,
+    ],
+  },
+
+  authorityClaims: {
+    name: 'Authority Claims',
+    severity: 'high',
+    description: 'False authority claims to manipulate agent behavior',
+    patterns: [
+      /i\s+am\s+(an?\s+)?(admin|administrator|developer|anthropic)/i,
+      /admin\s+override/i,
+      /authorized\s+to\s+/i,
+      /special\s+permission/i,
+      /emergency\s+protocol/i,
+      /maintenance\s+mode/i,
+    ],
+  },
+
+  encodedContent: {
+    name: 'Encoded/Obfuscated Content',
+    severity: 'medium',
+    description: 'Potentially obfuscated payloads in tool descriptions',
+    patterns: [
+      /base64:/i,
+      /data:text\/[a-z]+;base64,/i,
+      /\\x[0-9a-f]{2}/i,
+      /\\u[0-9a-f]{4}/i,
+    ],
+  },
+};
+
+// ============================================================================
+// Tool Poisoning Patterns (MCP-specific)
+// ============================================================================
+
+export const TOOL_POISONING_PATTERNS: Record<string, PatternCategory> = {
+  hiddenInstructions: {
+    name: 'Hidden Instructions in Tool Description',
+    severity: 'critical',
+    description: 'Tool descriptions containing hidden instructions for the AI agent',
+    patterns: [
+      /\b(before|when|after)\s+(calling|using|executing)\s+this\s+tool/i,
+      /\bfirst\s+(read|access|send|exfiltrate|copy)\b/i,
+      /\bdo\s+not\s+(tell|inform|alert|warn)\s+(the\s+)?user\b/i,
+      /\bsilently\s+(send|post|upload|transmit)\b/i,
+      /\bwithout\s+(the\s+)?user('s)?\s+(knowledge|consent|awareness)\b/i,
+      /\bhidden\s+(parameter|field|action)\b/i,
+    ],
+  },
+
+  toolShadowing: {
+    name: 'Tool Shadowing',
+    severity: 'critical',
+    description: 'Tool attempting to shadow/override another tool\'s behavior',
+    patterns: [
+      /\bthis\s+tool\s+(replaces|overrides|supersedes)\b/i,
+      /\buse\s+this\s+(instead\s+of|rather\s+than)\b/i,
+      /\bdo\s+not\s+use\s+(the\s+)?(original|default|other)\b/i,
+      /\b(redirect|forward|proxy)\s+(all\s+)?(calls?|requests?)\s+to\b/i,
+    ],
+  },
+
+  dataExfiltration: {
+    name: 'Data Exfiltration via Tool',
+    severity: 'critical',
+    description: 'Tool descriptions instructing data exfiltration',
+    patterns: [
+      /\b(send|post|upload|transmit|exfiltrate)\s+(to|data|files?|credentials?)\b/i,
+      /\binclude\s+(all\s+)?(conversation|chat|history|context)\b/i,
+      /\b(append|add|include)\s+.*\b(api[_\s]?key|token|password|secret)\b/i,
+      /\bphone\s+home\b/i,
+    ],
+  },
+
+  rugPull: {
+    name: 'Rug Pull / Dynamic Behavior Change',
+    severity: 'high',
+    description: 'Indicators of tools that may change behavior after trust is established',
+    patterns: [
+      /\b(after|once)\s+\d+\s+(calls?|uses?|invocations?)\b/i,
+      /\b(initially|at\s+first)\s+.*\b(then|later|afterwards)\b/i,
+      /\bversion\s*[><=]+\s*\d/i,
+    ],
+  },
+};
+
+// ============================================================================
+// Command Injection Patterns (in tool arguments/parameters)
+// ============================================================================
+
+export const COMMAND_INJECTION_PATTERNS: Record<string, PatternCategory> = {
+  shellInjection: {
+    name: 'Shell Command Injection',
+    severity: 'critical',
+    description: 'Shell metacharacters or command injection in tool parameters',
+    patterns: [
+      /;\s*(rm|curl|wget|nc|bash|sh|python|perl|ruby)\b/i,
+      /\|\s*(bash|sh|nc|curl)\b/i,
+      /`[^`]*`/,
+      /\$\([^)]*\)/,
+      /&&\s*(rm|curl|wget|nc|bash|sh)\b/i,
+    ],
+  },
+
+  pathTraversal: {
+    name: 'Path Traversal',
+    severity: 'high',
+    description: 'Directory traversal attempts in file paths',
+    patterns: [
+      /\.\.\//,
+      /\.\.%2[fF]/,
+      /\.\.\\(?!n|t|r)/,
+      /~\/\.(ssh|gnupg|aws|config|claude)/i,
+    ],
+  },
+
+  reverseShell: {
+    name: 'Reverse Shell',
+    severity: 'critical',
+    description: 'Reverse shell patterns in command arguments',
+    patterns: [
+      /bash\s+-i\s+>&\s*\/dev\/tcp/i,
+      /nc\s+(-e|--exec)\s+\/bin\/(ba)?sh/i,
+      /python.*socket.*connect/i,
+      /\|\s*\/bin\/(ba)?sh/i,
+      /socat.*exec/i,
+    ],
+  },
+};
+
+// ============================================================================
+// Analysis Functions
+// ============================================================================
+
+export interface InjectionAnalysis {
+  detected: boolean;
+  risk: 'none' | 'low' | 'medium' | 'high' | 'critical';
+  matches: Array<{
+    category: string;
+    name: string;
+    severity: Severity;
+    pattern: string;
+  }>;
+}
+
+/**
+ * Analyze text content for injection patterns across all categories
+ */
+export function analyzeForInjection(
+  content: string,
+  patternSets: Record<string, PatternCategory>[] = [
+    INJECTION_PATTERNS,
+    TOOL_POISONING_PATTERNS,
+    COMMAND_INJECTION_PATTERNS,
+  ]
+): InjectionAnalysis {
+  const matches: InjectionAnalysis['matches'] = [];
+
+  for (const patternSet of patternSets) {
+    for (const [categoryKey, category] of Object.entries(patternSet)) {
+      for (const pattern of category.patterns) {
+        if (pattern.test(content)) {
+          matches.push({
+            category: categoryKey,
+            name: category.name,
+            severity: category.severity,
+            pattern: pattern.source,
+          });
+          break; // One match per category is enough
+        }
+      }
+    }
+  }
+
+  // Determine overall risk
+  let risk: InjectionAnalysis['risk'] = 'none';
+  if (matches.some((m) => m.severity === 'critical')) {
+    risk = 'critical';
+  } else if (matches.some((m) => m.severity === 'high')) {
+    risk = 'high';
+  } else if (matches.some((m) => m.severity === 'medium')) {
+    risk = 'medium';
+  } else if (matches.length > 0) {
+    risk = 'low';
+  }
+
+  return {
+    detected: matches.length > 0,
+    risk,
+    matches,
+  };
+}