MCP Security Analyzer

MCP安全分析器

一个用于分析模型上下文协议（MCP）服务器实现的全面安全测试框架。该框架能在隔离的Docker容器中自动运行MCP服务器，同时捕获并分析网络流量，以检测包括数据泄露、未经授权访问、命令注入和权限提升在内的安全漏洞。

🎯 概述

MCP Security Analyzer 帮助安全团队和开发人员通过以下方式验证 MCP 服务器实现的安全状况：

• 自动化测试对任何MCP服务器运行预定义的安全测试场景
• 网络监控在执行过程中捕获并分析所有网络流量
• 威胁检测识别可疑模式、敏感数据泄露以及未经授权的访问
• 基于人工智能的分析可选的Claude API集成，用于智能威胁评估
• 综合报告生成详细的HTML、JSON和CSV格式的安全报告

✨ 主要特性

🔒 安全测试

• 预配置的安全用例（文件访问、数据外泄、命令注入、权限提升）
• MCP协议方法测试（工具/调用，资源/列表，提示/列表）
• 敏感数据模式检测（凭证、API密钥、个人身份信息）
• 路径遍历和命令注入检测

🐳 Docker 隔离

• 带有资源限制的沙盒执行环境
• 网络隔离与监控
• 容器和资源的自动清理

📊 分析与报告

• 使用Scapy进行深度数据包检测
• 连接分析和有效载荷检查
• Claude AI驱动的威胁评估（可选）
• 多格式报告（HTML、JSON、CSV）

🚀 简单用法

• 无需复杂的工具定义
• 直接传递MCP服务器命令
• 从预定义的安全测试场景中选择
• 获取可操作的安全报告

📋 要求

系统要求

• python3.9或更高版本
• DockerDocker 引擎正在运行（已在 Docker 20.10+ 上测试过）
• 网络数据包捕获功能（在Linux/macOS上为libpcap，在Windows上为WinPcap/Npcap）
• 资源最低配置：4GB内存，10GB磁盘空间

平台支持

• ✅ LinuxUbuntu 20.04及以上版本，RHEL 8及以上版本，CentOS 8及以上版本，Debian 11及以上版本
• ✅ macOS（发音：/ˈmækOS/，中文常译为“苹果电脑操作系统”或简称“苹果系统”）10.15（Catalina）或更高版本
• ✅ WindowsWindows 10+ 系统，配备 WSL2（推荐）或原生支持但功能有限

🚀 安装

1. 安装系统依赖项

Ubuntu/Debian（这两个都是Linux发行版的名称，直接翻译为中文即保持原样，因为它们在中文语境下也是广为人知的Linux发行版名称）

sudo apt-get update
sudo apt-get install -y python3 python3-pip docker.io libpcap-dev tcpdump
sudo systemctl start docker
sudo usermod -aG docker $USER

macOS（发音：/ˈmækɒs/，中文常译作“麦奥斯”或直接沿用英文原名）

# Install Homebrew if not already installed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install dependencies
brew install python@3.9
brew install libpcap
brew install --cask docker

# Start Docker Desktop
open -a Docker

Windows（WSL2）

# Install WSL2 and Ubuntu
wsl --install

# Inside WSL2, follow Ubuntu instructions above

2. 安装MCP安全分析器

来自源（推荐）

# Clone the repository
git clone https://github.com/yair4data/mcp-security-analyzer.git
cd mcp-security-analyzer

# Create virtual environment
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -e .

验证安装

# Check Docker is running
docker version

# Verify analyzer installation
mcp-security-analyzer --version

3. 可选：配置Claude AI

对于基于人工智能的威胁分析：

export CLAUDE_API_KEY="your-anthropic-api-key"
# Or add to ~/.bashrc or ~/.zshrc for persistence

从以下网址获取您的API密钥：https://console.anthropic.com/

📖 使用方法

快速入门（30秒）

# 1. Copy example configuration
cp config/simple-usecases.yaml config/my-config.yaml

# 2. Run security inspection
mcp-security-analyzer --config config/my-config.yaml inspect \
    "npx -y @modelcontextprotocol/server-filesystem /tmp" \
    --use-case basic_security_scan

# 3. View report
open ./mcp_analysis/security_report.html

基本命令

检查MCP服务器

使用预定义的安全场景测试任何MCP服务器：

# Run specific security test
mcp-security-analyzer inspect \
    "npx -y @modelcontextprotocol/server-filesystem /tmp" \
    --use-case sensitive_file_access

# Run all available security tests
mcp-security-analyzer inspect \
    "python my_mcp_server.py"

# Custom output directory
mcp-security-analyzer inspect \
    "node mcp-server.js" \
    --use-case data_exfiltration \
    --output ./security_reports

借助AI分析

export CLAUDE_API_KEY="your-key"

mcp-security-analyzer inspect \
    "npx -y @modelcontextprotocol/server-brave-search" \
    --use-case basic_security_scan

禁用AI分析

mcp-security-analyzer inspect \
    "python server.py" \
    --use-case command_injection \
    --no-ai

可用的安全用例

该工具包含5个预配置的安全测试场景：

示例：测试官方MCP服务器

# Test filesystem server
mcp-security-analyzer inspect \
    "npx -y @modelcontextprotocol/server-filesystem /tmp" \
    --use-case sensitive_file_access

# Test GitHub server
mcp-security-analyzer inspect \
    "npx -y @modelcontextprotocol/server-github" \
    --use-case basic_security_scan

# Test Brave Search server
mcp-security-analyzer inspect \
    "npx -y @modelcontextprotocol/server-brave-search" \
    --use-case data_exfiltration

示例：测试自定义Python MCP服务器

mcp-security-analyzer inspect \
    "python /path/to/my_mcp_server.py" \
    --use-case basic_security_scan \
    --output ./my_server_analysis

📊 理解报告

运行分析后，你会发现：

mcp_analysis/
├── security_report.html    # Interactive HTML report (open in browser)
├── security_report.json    # Machine-readable JSON data
├── findings.csv            # Tabular security findings
└── mcp_traffic.pcap        # Network traffic capture (for deep analysis)

报告部分

HTML 报告包括：

• ✅ 执行摘要
• ✅ 检查器执行结果
• ✅ 网络流量分析
• ✅ 按严重程度划分的安全发现（关键/高/中/低）
• ✅ 基于AI的威胁分析（如已启用）
• ✅ 整改建议

严重程度等级

• 🔴（红色圆圈） 关键的；至关重要的即时安全威胁（例如，凭证泄露、远程代码执行）
• 🟠（橙色） 高重大风险（例如，未经授权的文件访问、SQL注入攻击）
• 黄色（表示警告、注意或某种状态的指示） 中等适度担忧（例如，信息泄露）
• 🟢 翻译为中文是“绿对勾”或“勾选标志（绿色）”。 低次要问题（例如，冗长的错误信息）

⚙️ 配置

最小配置

创建 config/my-config.yaml：

# Use cases (test scenarios)
use_cases:
  - name: 'basic_security_scan'
    description: 'Basic security checks'
    tools: []  # No tool definitions needed!
    test_actions:
      - method: 'tools/list'
        timeout: 30
      - method: 'resources/list'
        timeout: 30
    expected_threats:
      - 'Unexpected tool exposure'
    duration: 120

# Optional: Claude AI settings
claude:
  api_key: null  # Set via CLAUDE_API_KEY environment variable

# Optional: Network monitoring
network:
  interface: 'any'
  max_packets: 50000

# Optional: Docker settings
docker:
  memory_limit: '1024m'
  cpu_limit: '1.0'

创建自定义用例

在您的配置中添加自定义安全测试：

use_cases:
  - name: 'my_custom_test'
    description: 'Custom security test scenario'
    tools: []
    test_actions:
      # List available tools
      - method: 'tools/list'
        timeout: 30

      # Call specific tool
      - method: 'tools/call'
        tool_name: 'read_file'
        arguments:
          path: '/etc/passwd'
        timeout: 30

      # List resources
      - method: 'resources/list'
        timeout: 30

    expected_threats:
      - 'Unauthorized file access'
      - 'Sensitive data exposure'

    duration: 180

可用的测试方法

• tools/list - 列出所有可用工具
• tools/call - 使用参数执行特定工具
• resources/list - 列出可用资源
• resources/read - 读取特定资源
• prompts/list - 列出可用的提示
• prompts/get - 获取特定的提示模板

🏗️ 建筑学

┌─────────────────────────────────────────────────────────────┐
│                   MCP Security Analyzer CLI                  │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                  SimpleMCPOrchestrator                       │
│  • Coordinates security testing workflow                     │
│  • Manages Docker lifecycle                                  │
│  • Synchronizes packet capture with execution               │
└──────────┬────────────────────┬──────────────────┬──────────┘
           │                    │                  │
           ▼                    ▼                  ▼
┌──────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│ SimpleMCPInspector│  │ PacketCapture   │  │ ClaudeAnalyzer │
│ • Runs MCP       │  │ • Network       │  │ • AI-powered   │
│   Inspector      │  │   monitoring    │  │   threat       │
│ • Executes tests │  │ • Deep packet   │  │   analysis     │
│ • Parses results │  │   inspection    │  │ • Remediation  │
└──────────────────┘  └─────────────────┘  └─────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│                     Docker Container                         │
│  ┌────────────────────────────────────────────────────────┐ │
│  │          MCP Inspector (Official Tool)                 │ │
│  │  • Protocol-compliant MCP client                       │ │
│  │  • Executes user's MCP server                          │ │
│  │  • Captures all MCP interactions                       │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │          User's MCP Server                             │ │
│  │  • Filesystem server, API client, database, etc.       │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│                    Security Reporter                         │
│  • Generates HTML/JSON/CSV reports                          │
│  • Severity classification                                  │
│  • Remediation recommendations                              │
└─────────────────────────────────────────────────────────────┘

🧪 开发

运行测试

# Run all tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

# Run specific test module
pytest tests/core/inspector/test_inspector_config.py -v

# Run integration tests (requires Docker)
pytest -m integration

代码质量

# Format code
black src tests

# Sort imports
isort src tests

# Lint
flake8 src tests

# Type checking
mypy src

🔧 故障排除

Docker 未运行

Error: Cannot connect to Docker daemon
Solution: Start Docker and verify with `docker version`

拒绝访问（数据包捕获）

Error: Permission denied when capturing packets
Solution: Run with sudo or add user to docker group

未找到用例

Error: Use case 'my-test' not found in configuration
Solution: Check config file has the use case defined, or use example config:
  cp config/simple-usecases.yaml config/my-config.yaml

克劳德API错误

Error: AI analysis failed: API key not configured
Solution: Set environment variable:
  export CLAUDE_API_KEY="your-key"
Or disable AI: --no-ai

未找到MCP检查器

Error: npx command not found in container
Solution: Ensure the Docker image includes Node.js and npm

📚 额外资源

• MCP规范https://modelcontextprotocol.io/（该网址可直接翻译为“模型上下文协议.io”，但通常网址内容不直接翻译，保持原样即可）
• MCP 检查器https://github.com/modelcontextprotocol/inspector（可译为：“GitHub上的ModelContextProtocol/inspector项目”）
• Anthropic Claude APIhttps://www.anthropic.com/api（该网址可译为：“Anthropic公司的API页面”，但通常网址本身不直接翻译，这里提供的是对其内容的简要说明）
• Docker 文档https://docs.docker.com/ 的中文翻译是：“Docker 官方文档网站”

🤝 贡献

欢迎投稿！请：

1. 为仓库创建分支（或：克隆仓库）
2. 创建一个特性分支（git checkout -b feature/amazing-feature）
3. 做出你的更改
4. 为新功能添加测试
5. 确保所有测试通过（pytest）
6. 运行代码质量检查（black， isort， flake8， mypy）
7. 提交您的更改（git commit -m 'Add amazing feature'）
8. 推送到分支（git push origin feature/amazing-feature)
9. 提交一个拉取请求

📄 许可证

这个项目遵循MIT许可证授权——详见 许可证 文件中有详细信息。

🔐 安全

这个工具是为……设计的 仅进行防御性安全测试请负责任地使用，并且仅在您获得测试权限的系统上进行测试。请私下向项目维护者报告安全漏洞。

🙏 致谢

• “Anthropic”翻译成中文是“人类中心的”或“以人类为中心的”。这个词汇通常用于描述一种观点或立场，即认为人类在宇宙或自然界中占据核心或特殊地位 为Claude API
• 模型上下文协议 针对MCP规范
• MCP 检查员 用于官方测试工具
• Scapy 用于数据包处理和分析
• 用于集装箱化技术

📞 支持

• 问题:
• 讨论：

______________________________________________________________________

为安全社区倾心打造