mcpscan (I Parikh1)

mcpscan

MCP（模型上下文协议）服务器和AI代理配置的安全扫描程序。

mcpscan可以帮助您在MCP服务器配置中的安全漏洞成为问题之前识别它们。它扫描硬编码凭据、命令注入风险、SSRF漏洞和其他特定于AI代理部署的安全问题。

为什么是mcpscan？

MCP（模型上下文协议）正在成为将AI代理连接到外部工具和数据源的标准。随着采用率的增长，安全风险也在增加：

• 492+易受攻击的MCP服务器 未进行身份验证
• 53%的MCP服务器 使用硬编码凭据
• 437000个开发人员环境 通过MCP漏洞泄露（CVE-2025-6514）

mcpscan在这些问题投入生产之前就发现了它们。

特性

• 凭证检测 -查找硬编码的API密钥、令牌和密码
• 指令注入分析 -识别外壳元字符和注射风险
• SSRF风险检测 -标记内部URL和元数据端点
• 路径遍历检查 -捕获目录遍历漏洞
• 身份验证审核 -无需身份验证即可识别远程服务器
• 基于机器学习的风险评分 -用于综合风险评估的机器学习模型
• 能力图分析 -确定特权升级路径
• 自动修复 -为常见漏洞生成修复程序
• CI/CD集成 -GitHub代码扫描的SARIF输出
• OWASP映射 -调查结果映射到OWASP MCP Top 10

安装

# Using pip
pip install mcpscan

# Using poetry
poetry add mcpscan

# From source
git clone https://github.com/IParikh1/mcpscan.git
cd mcpscan
poetry install

快速开始

# Scan current directory
mcpscan scan .

# Scan specific config file
mcpscan scan ./mcp.json

# Scan with ML-based risk scoring
mcpscan scan ./mcp.json --risk-score

# Scan with capability graph analysis
mcpscan scan ./mcp.json --graph

# Generate remediation for issues
mcpscan scan ./mcp.json --fix

# Output as JSON
mcpscan scan . --format json -o results.json

# Output as SARIF (for GitHub Code Scanning)
mcpscan scan . --format sarif -o results.sarif

# CI mode - exit with code 1 if findings found
mcpscan scan . --ci --fail-on high

命令

扫描与分析

ML模型管理

输出示例

╭───────────────────────────────────────╮
│ mcpscan v0.1.0 - MCP Security Scanner │
╰───────────────────────────────────────╯

Scanning: ./mcp.json

    Scan Summary
┏━━━━━━━━━━┳━━━━━━━┓
┃ Severity ┃ Count ┃
┡━━━━━━━━━━╇━━━━━━━┩
│ CRITICAL │     2 │
│ HIGH     │     3 │
│ MEDIUM   │     2 │
│ TOTAL    │     7 │
└──────────┴───────┘

⚠️  CRITICAL (2)

  MCP-002: Hardcoded Credentials Detected
  File: mcp.json:15
  → Detected: sk-proj-abc...xyz
  Found OpenAI API key in configuration file.
  Fix: Use environment variables instead of hardcoding credentials.

  MCP-001: No Authentication Configured
  File: mcp.json:25
  → url: http://localhost:3000/mcp
  Remote MCP server has no authentication configured.
  Fix: Configure OAuth 2.0, API keys, or other authentication.

╭───────────────────── Risk Analysis: mcp.json ─────────────────────╮
│ Overall Risk: HIGH (Score: 75.2%)                                 │
│ Confidence: 95.0%                                                 │
│                                                                   │
│ Category Breakdown:                                               │
│   MCP02_Privilege_Escalation: [███████████████░░░░░] 78.3%       │
│   MCP05_Command_Injection: [███████░░░░░░░░░░░░░] 36.5%          │
│   MCP01_Token_Exposure: [████░░░░░░░░░░░░░░░░] 23.3%             │
│                                                                   │
│ Top Risk Factors:                                                 │
│   • Cloud metadata endpoints accessible (+10.0%)                  │
│   • Privileged/admin tools configured (+10.0%)                    │
│   • Dangerous tool capabilities (+8.0%)                           │
╰───────────────────────────────────────────────────────────────────╯

安全规则

基于机器学习的风险评分

mcpscan包括一个用于全面风险评估的机器学习模型：

# Scan with ML risk scoring
mcpscan scan ./mcp.json --risk-score

# View standalone risk analysis
mcpscan risk ./mcp.json

# Show model information
mcpscan model-info

型号特点：

• 随机森林+孤立森林组合
• 31个安全相关功能
• 测试数据准确率93.2%
• OWASP MCP十大类别评分
• 异常配置的异常检测

看 docs/ML_MODEL.md 详细的模型文档。

能力图分析

分析特权升级路径和攻击向量：

# Run graph analysis
mcpscan graph ./mcp.json

# Include in scan output
mcpscan scan ./mcp.json --graph

检测：

• 凭证盗窃路径
• 特权升级向量
• 工具链风险
• 攻击面指标

自动修复

生成安全问题的修复程序：

# Preview fixes
mcpscan fix ./mcp.json

# Save fixed config to new file
mcpscan fix ./mcp.json -o fixed.json

# Apply fixes directly (creates backup)
mcpscan fix ./mcp.json --apply

自动修复：

• 将硬编码凭据替换为 ${ENV_VAR} 参考文献
• 删除shell元字符
• 将绝对路径转换为相对路径
• 生成 .env.example 模板

数据收集和模型训练

使用真实世界的数据改进ML模型：

# Collect configs from your system (anonymized)
mcpscan collect --scan-system

# Collect from specific directory
mcpscan collect --dir ./my-configs

# View collection statistics
mcpscan collect --stats

# Manually label configs for training
mcpscan label ./mcp.json critical

# Validate model on collected configs
mcpscan validate-model --collection

# Retrain model with more data
mcpscan train --samples 5000

所有收集的数据都会自动匿名（API密钥、路径等都会被编辑）。

CI/CD集成

GitHub操作

name: MCP Security Scan

on: [push, pull_request]

jobs:
  security-scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install mcpscan
        run: pip install mcpscan

      - name: Run security scan
        run: mcpscan scan . --format sarif -o results.sarif --ci --fail-on high

      - name: Upload SARIF results
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: results.sarif

GitLab 的

mcp-security:
  image: python:3.11
  script:
    - pip install mcpscan
    - mcpscan scan . --format json -o gl-sast-report.json --ci
  artifacts:
    reports:
      sast: gl-sast-report.json

预提交钩子

# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: mcpscan
        name: MCP Security Scan
        entry: mcpscan scan . --ci --fail-on high
        language: system
        pass_filenames: false

检测到配置文件

mcpscan会自动发现MCP配置文件：

• mcp.json / .mcp.json
• mcp_config.json
• claude_desktop_config.json
• .cursor/mcp.json
• .claude/mcp.json
• mcp-server*/config.json
• *_mcp.json / *mcp*.json

合规性映射

调查结果符合行业标准：

• OWASP MCP前10名：MCP01-MCP10漏洞类别
• OWASP LLM前10名（2025年）：LLM02、LLM05、LLM06
• 警戒与报警设备：CWE-22、CWE-78、CWE-250、CWE-306、CWE-312、CWE-798、CWE-918
• 米特地图集：即将推出

贡献

欢迎投稿！请阅读我们的 贡献指南 了解详情。

开发设置

# Clone the repository
git clone https://github.com/IParikh1/mcpscan.git
cd mcpscan

# Install dependencies
poetry install

# Run tests
poetry run pytest

# Run linting
poetry run ruff check .
poetry run black --check .
poetry run mypy mcpscan

路线图

• \[x\] v0.1：核心扫描、机器学习风险评分、补救
• \[ \] v0.2：快速注射测试
• \[ \] v0.3：越狱检测
• \[ \] v0.4：RAG安全分析
• \[ \] v0.5：多代理安全测试

许可证

Apache许可证2.0-请参阅 许可证 了解详情。

致谢

• OWASP LLM Top 10 用于脆弱性分类
• 米特地图集 用于攻击框架
• Anthropic MCP规范

______________________________________________________________________

专为AI安全社区打造。