MCP安全分析器

![Python 3.9+](https://www.python.org/downloads/) ![License: MIT](https://opensource.org/licenses/MIT)

一个用于分析模型上下文协议（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个预配置的安全测试场景：

用例	描述	测试操作	持续时间
`basic_security_scan`	服务器功能概览	3	约2分钟
`sensitive_file_access`	文件权限测试	3	约3分钟
`data_exfiltration`	数据盗窃场景	2	约3分钟
`command_injection`	注入漏洞测试	2	约2分钟
`privilege_escalation`	提权尝试	2次	约2分钟

示例：测试官方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 官方文档网站”

🤝 贡献

欢迎投稿！请：

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

📄 许可证

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

🔐 安全

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

🙏 致谢

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

📞 支持

问题:
讨论：

______________________________________________________________________

为安全社区倾心打造

MCP Security Analyzer

快速接入

详细介绍