AI导哈

MCP服务器安全扫描器

MCPGuard是一款针对MCP服务器的安全扫描器和运行时保护工具，能够静态分析配置文件并检测OWASP MCP Top 10漏洞。

  • by aryanjp1
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 aryanjp1/mcpguard

使用说明

MCPGuard

MCP服务器的安全扫描程序和运行时保护。

MCP正在成为AI代理的TCP/IP。MCPGuard确保它不会成为下一个Log4j。

MCPGuard扫描您的MCP服务器配置，以查找 OWASP MCP前10名 并提供运行时中间件，以在每次工具调用时强制执行安全策略。它在没有运行服务器的情况下工作——对配置文件进行纯静态分析。

安装

pip install mcpguard

快速开始

# Scan your Claude Desktop or Cursor MCP config (auto-detected)
mcpguard scan

# Scan a specific config
mcpguard scan --config ./claude_desktop_config.json

# Get a JSON report
mcpguard scan --format json --output report.json

程序化使用：

from mcpshield import scan

result = scan()
print(f"Score: {result.score}/100  ({result.rating})")
for finding in result.sorted_findings():
    print(f"[{finding.severity.value}] {finding.rule_id}: {finding.title}")

它检测到什么

MCPGuard涵盖了OWASP MCP Top 10的所有10个类别：

规则 严重性 OWASP 描述
MCPS-001 CRITICAL MCP01 环境变量中的硬编码API密钥和机密
MCPS-002 高 MCP03 可访问的文件系统服务器 / 或 ~/.ssh
MCPS-003 高 MCP08 npx -y 未经验证或未装箱的包裹
MCPS-004 关键 MCP04 启用命令注入的Shell调用
MCPS-005 高 MCP05 没有身份验证或TLS的HTTP/SSE服务器
MCPS-006 高 MCP03 通配符工具权限(files:*, admin:*)
MCPS-007 中等 MCP02 带有注入关键字或隐藏Unicode的工具描述
MCPS-008 中 MCP10 不带域分配（SSRF）的URL参数
MCPS-009 低 MCP09 缺少审核日志记录配置
MCPS-010 高 MCP06 无用户隔离的共享会话内存
MCPS-011 中等 MCP05 stdio服务器正在运行，没有沙盒
MCPS-012 关键 MCP08 已知CVE-mcp远程、mcp检查器、文件系统

命令行界面

# Scan auto-detected config
mcpguard scan

# Scan specific file
mcpguard scan --config ./mcp-config.json

# Output formats
mcpguard scan --format json --output report.json
mcpguard scan --format sarif --output report.sarif   # GitHub Security tab
mcpguard scan --format html --output report.html     # Shareable HTML

# Fail CI on critical/high findings
mcpguard scan --fail-on critical
mcpguard scan --fail-on high

# Skip specific rules
mcpguard scan --skip-rules MCPS-009,MCPS-011

# Check a package against the vulnerability database
mcpguard check-package mcp-remote
mcpguard check-package mcp-remote@0.1.7

# Generate a starter policy file
mcpguard init-policy --output policy.yaml

# Validate an existing policy
mcpguard validate-policy policy.yaml

运行时保护

使用策略强制在运行时保护MCP服务器的工具处理程序：

from mcpshield.runtime import MCPGuard, Policy

# Load security policy
policy = Policy.from_yaml("policy.yaml")

# Create guard
guard = MCPGuard(policy=policy)

# Protect tool handlers
@guard.protect
async def handle_tool_call(tool_name: str, arguments: dict) -> dict:
    # Blocked tools raise PolicyViolationError before reaching here
    # Path and domain restrictions are enforced automatically
    # Rate limits are checked per-tool
    ...

策略文件

# policy.yaml
version: "1.0"
rules:
  blocked_tools:
    - "execute_command"
    - "run_shell"

  tool_restrictions:
    filesystem_read:
      allowed_paths:
        - "/data/**"
        - "/public/**"
      blocked_paths:
        - "~/.ssh/**"
        - "~/.aws/**"
    http_request:
      allowed_domains:
        - "api.github.com"
      blocked_domains:
        - "169.254.169.254"  # AWS metadata
        - "localhost"

  rate_limits:
    default: 100/minute
    per_tool:
      database_query: 20/minute

  approval_required:
    - "delete_file"
    - "send_email"

  audit:
    enabled: true
    log_file: "mcpguard_audit.jsonl"
    log_level: "all"

CI/CD集成

添加 .github/workflows/security.yml:

name: MCP Security Scan

on: [push, pull_request]

jobs:
  mcpguard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - run: pip install mcpguard
      - name: Scan MCP config
        run: mcpguard scan --config ./claude_desktop_config.json --fail-on high
      - name: Generate SARIF report
        run: mcpguard scan --config ./claude_desktop_config.json --format sarif --output mcpguard.sarif
      - name: Upload to GitHub Security tab
        uses: github/codeql-action/upload-sarif@v3
        with:
          sarif_file: mcpguard.sarif

编写自定义规则

扩展 BaseRule 添加您自己的支票：

from mcpshield.scanner.rules.base import BaseRule
from mcpshield.scanner.finding import Finding, ServerConfig
from mcpshield.utils.severity import Severity

class MyCustomRule(BaseRule):
    rule_id = "CUSTOM-001"
    title = "My Security Check"
    owasp_mapping = "MCP01"

    def check(self, server: ServerConfig) -> list[Finding]:
        findings = []
        if "dangerous_pattern" in str(server.raw):
            findings.append(Finding(
                rule_id=self.rule_id,
                title=self.title,
                description="Dangerous pattern detected",
                severity=Severity.HIGH,
                owasp_mcp=self.owasp_mapping,
                server_name=server.name,
                location="config",
                remediation="Remove the dangerous pattern.",
                references=["https://owasp.org/www-project-mcp-top-10/"],
            ))
        return findings

# Use with the engine
from mcpshield.scanner.engine import ScanEngine
from mcpshield.scanner.rules import DEFAULT_RULES

engine = ScanEngine(rules=DEFAULT_RULES + [MyCustomRule])

安全评分

MCPGuard计算0-100的分数：

分数 评分
90-100 优秀
70-89 良好
50-69 公平
25-49岁 贫困
0-24 关键

每项关键发现扣25分，高扣15分，中扣8分，低扣3分。

参考文献

贡献

问题和拉取请求欢迎访问 https://aryanjp1/mcpguard.

要运行测试套件，请执行以下操作：

pip install -e ".[dev]"
pytest --cov

要添加新规则，请在中创建一个文件 src/mcpshield/scanner/rules/，延伸 BaseRule，并将其添加到 DEFAULT_RULES 在 src/mcpshield/scanner/rules/__init__.py.

许可证

麻省理工学院——见 许可证.

相关 MCP