安全分析器

Name: 安全分析器
Author: yair4Data

作者：yair4Data2 星标更新：2025-10-23

安装使用来源：spider==github.com

项目介绍

MCP 安全分析器

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

🎯 概述

MCP安全分析器帮助安全团队和开发者验证MCP服务器实现的安全状态：

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

✨ 主要功能

🔒 安全测试

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

🐳 Docker隔离

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

📊 分析与报告

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

🚀 简单使用

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

📋 要求

系统要求

Python：3.9或更高版本
Docker：正在运行的Docker引擎（已测试Docker 20.10+）
网络：数据包捕获能力（Linux/macOS上的libpcap，Windows上的WinPcap/Npcap）
资源：至少4GB内存，10GB磁盘空间

平台支持

✅ Linux：Ubuntu 20.04+，RHEL 8+，CentOS 8+，Debian 11+
✅ macOS：10.15（Catalina）或更高版本
✅ Windows：Windows 10+（推荐使用WSL2），或原生使用（有限制）

🚀 安装

1. 安装系统依赖项

Ubuntu/Debian

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

# 如果尚未安装Homebrew，请安装
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# 安装依赖项
brew install python@3.9
brew install libpcap
brew install --cask docker

# 启动Docker Desktop
open -a Docker

Windows (WSL2)

# 安装WSL2和Ubuntu
wsl --install

# 在WSL2内部，按照Ubuntu说明进行操作

2. 安装MCP安全分析器

从源代码安装（推荐）

# 克隆仓库
git clone https://github.com/yair4data/mcp-security-analyzer.git
cd mcp-security-analyzer

# 创建虚拟环境
python3 -m venv venv
source venv/bin/activate  # 在Windows上：venv\Scripts\activate

# 安装依赖项
pip install -e .

验证安装

# 检查Docker是否运行
docker version

# 验证分析器安装
mcp-security-analyzer --version

3. 可选：配置Claude AI

对于AI驱动的威胁分析：

export CLAUDE_API_KEY="your-anthropic-api-key"
# 或者添加到~/.bashrc或~/.zshrc以持久化

获取您的API密钥：https://console.anthropic.com/

📖 使用

快速开始（30秒）

# 1. 复制示例配置
cp config/simple-usecases.yaml config/my-config.yaml

# 2. 运行安全检查
mcp-security-analyzer --config config/my-config.yaml inspect \
    "npx -y @modelcontextprotocol/server-filesystem /tmp" \
    --use-case basic_security_scan

# 3. 查看报告
open ./mcp_analysis/security_report.html

基本命令

检查MCP服务器

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

# 运行特定的安全测试
mcp-security-analyzer inspect \
    "npx -y @modelcontextprotocol/server-filesystem /tmp" \
    --use-case sensitive_file_access

# 运行所有可用的安全测试
m
cp-security-analyzer inspect \
    "python my_mcp_server.py"

# 自定义输出目录
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服务器

# 测试文件系统服务器
mcp-security-analyzer inspect \
    "npx -y @modelcontextprotocol/server-filesystem /tmp" \
    --use-case sensitive_file_access

# 测试GitHub服务器
mcp-security-analyzer inspect \
    "npx -y @modelcontextprotocol/server-github" \
    --use-case basic_security_scan

# 测试Brave搜索服务器
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    # 交互式HTML报告（在浏览器中打开）
├── security_report.json    # 机器可读的JSON数据
├── findings.csv            # 表格形式的安全发现
└── mcp_traffic.pcap        # 网络流量捕获（用于深入分析）

报告部分

HTML报告包括：

✅ 执行摘要
✅ 检查器执行结果
✅ 网络流量分析
✅ 按严重性分类的安全发现（关键/高/中/低）
✅ AI驱动的威胁评估（如果启用）
✅ 缓解建议

严重性级别

🔴 关键：立即的安全威胁（例如，凭证暴露、远程代码执行）
🟠 高：显著的风险（例如，未经授权的文件访问、SQL注入）
🟡 中：适度的关注点（例如，信息泄露）
🟢 低：轻微的问题（例如，冗余错误消息）

⚙️ 配置

最小配置

创建config/my-config.yaml：

# 测试场景（测试场景）
use_cases:
  - name: 'basic_security_scan'
    description: '基本安全检查'
    tools: []  # 不需要工具定义！
    test_actions:
      - method: 'tools/list'
        timeout: 30
      - method: 'resources/list'
        timeout: 30
    expected_threats:
      - '意外的工具暴露'
    duration: 120

# 可选：Claude AI设置
claude:
  api_key: null  # 通过CLAUDE_API_KEY环境变量设置

# 可选：网络监控
network:
  interface: 'any'
  max_packets: 50000

# 可选：Docker设置
docker:
  memory_limit: '1024m'
  cpu_limit: '1.0'

创建自定义用例

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

use_cases:
  - name: 'my_custom_test'
    description: '自定义安全测试场景'
    tools: []
    test_actions:
      # 列出可用工具
      - method: 'tools/list'
        timeout: 30

      # 调用特定工具
      - method: 'tools/call'
        tool_name: 'read_file'
        arguments:
          path: '/etc/passwd'
        timeout: 30

      # 列出资源
      - method: 'resources/list'
        timeout: 30

    expected_threats:
      - '未经授权的文件访问'
      - '敏感数据暴露'

    duration: 180

可用的测试方法

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

🏗️ 架构

┌─────────────────────────────────────────────────────────────┐
│                   MCP安全分析器CLI                           │
└──────────────────────┬──────────────────────────────────────┘
                       │
                       ▼
┌─────────────────────────────────────────────────────────────┐
│                  SimpleMCPOrchestrator                       │
│  • 协调安全测试工作流                                       │
│  • 管理Docker生命周期                                       │
│  • 同步数据包捕获与执行                                     │
└──────────┬────────────────────┬──────────────────┬──────────┘
           │                    │                  │
           ▼                    ▼                  ▼
┌──────────────────┐  ┌─────────────────┐  ┌─────────────────┐
│ SimpleMCPInspector│  │ PacketCapture   │  │ ClaudeAnalyzer │
│ • 运行MCP         │  │ • 网络          │  │ • AI驱动的     │
│   检查器          │  │   监控          │  │   威胁评估     │
│ • 执行测试        │  │ • 深度包检查    │  │ • 缓解建议     │
│ • 解析结果        │  │                 │  │                 │
└──────────────────┘  └─────────────────┘  └─────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│                     Docker容器                               │
│  ┌────────────────────────────────────────────────────────┐ │
│  │          MCP检查器（官方工具）                         │ │
│  │  • 符合协议的MCP客户端                                 │ │
│  │  • 执行用户的MCP服务器                                  │ │
│  │  • 捕获所有MCP交互                                      │ │
│  └────────────────────────────────────────────────────────┘ │
│  ┌────────────────────────────────────────────────────────┐ │
│  │          用户的MCP服务器                                │ │
│  │  • 文件系统服务器、API客户端、数据库等                  │ │
│  └────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────┘
           │
           ▼
┌─────────────────────────────────────────────────────────────┐
│                    安全报告器                                │
│  • 生成HTML/JSON/CSV报告                                    │
│  • 严重性分类                                              │
│  • 缓解建议                                                │
└─────────────────────────────────────────────────────────────┘

🧪 开发

运行测试

# 运行所有测试
pytest

# 运行覆盖率测试
pytest --cov=src --cov-report=html

# 运行特定测试模块
pytest tests/core/inspector/test_inspector_config.py -v

# 运行集成测试（需要Docker）
pytest -m integration

代码质量

# 格式化代码
black src tests

# 排序导入
isort src tests

# 代码检查
flake8 src tests

# 类型检查
mypy src

🔧 故障排除

Docker未运行

错误：无法连接到Docker守护进程
解决方案：启动Docker并使用`docker version`验证

权限被拒绝（数据包捕获）

错误：捕获数据包时权限被拒绝
解决方案：使用sudo运行或添加用户到docker组

用例未找到

错误：配置中未找到用例'my-test'
解决方案：检查配置文件是否定义了该用例，或使用示例配置：
  cp config/simple-usecases.yaml config/my-config.yaml

Claude API错误

错误：AI分析失败：API密钥未配置
解决方案：设置环境变量：
  export CLAUDE_API_KEY="your-key"
或者禁用AI：--no-ai

MCP检查器未找到

错误：容器中未找到npx命令
解决方案：确保Docker镜像包含Node.js和npm

📚 额外资源

MCP规范：https://modelcontextprotocol.io/
MCP检查器：https://github.com/modelcontextprotocol/inspector
Anthropic Claude API：https://www.anthropic.com/api
Docker文档：https://docs.docker.com/

🤝 贡献

欢迎贡献！请：

分叉仓库
创建功能分支（git checkout -b feature/amazing-feature）
进行更改
为新功能添加测试
确保所有测试通过（pytest）
运行代码质量检查（black，isort，flake8，mypy）
提交更改（git commit -m '添加惊人的功能'）
推送到分支（git push origin feature/amazing-feature）
打开拉取请求

📄 许可

本项目根据MIT许可发布 - 详情见LICENSE文件。

🔐 安全

此工具仅用于防御性安全测试。请负责任地使用，并且仅在您有权测试的系统上使用。私下向项目维护人员报告安全漏洞。

🙏 致谢

Anthropic 为Claude API
Model Context Protocol 为MCP规范
MCP检查器为官方测试工具
Scapy 为数据包操作和分析
Docker 为容器化技术

📞 支持

问题：GitHub问题
讨论：GitHub讨论

为安全社区制作 ❤️