poojakira/mcp-security-gateway-monitor

# MCP Security Gateway 监控 一个实时安全监控器，旨在保护 AI 工具调用（MCP 协议）免受 prompt 注入、数据泄露、隐藏 BCC 攻击等威胁。完全基于 Python 标准库构建，零 runtime 依赖。 ## 本项目的作用 当 AI 助手使用外部工具（电子邮件、文件访问、API）时，这些工具可能会被劫持。在 2026 年年中，一个 MCP server 在发出的电子邮件中悄悄添加了隐藏的 BCC，将副本转发给了攻击者。本项目为可见的工具调用和出站流量信号添加了监控与拦截控制，但不能保证完全防御。 **MCP Security Gateway Monitor** 旨在部署在 AI 及其工具之间。在配置的代理路径中，工具调用最多可以经过 10 个防御层，这些防御层会在可疑活动触达外部环境之前对其进行检查、分析和拦截。可以将它看作是专为 AI 与工具通信设计的防火墙。 它将： - 拦截隐藏在工具参数内部的 prompt 注入 - 捕捉隐藏的电子邮件收件人（真实的 Postmark BCC 攻击） - 检测通过编码的 payload 或可疑 URL 进行数据泄露的行为 - 标记未经授权的网络连接和 DNS 查询 - 生成实时 HTML 安全仪表盘，展示被捕捉到的威胁 ## 快速开始 ### 单行测试（全平台） ``` git clone https://github.com/poojakira/mcp-security-gateway-monitor.git && cd mcp-security-gateway-monitor && pip install -e ".[dev]" && python -m pytest tests/ -v ``` ### Ubuntu / Linux / macOS ``` # 1. Clone repository git clone https://github.com/poojakira/mcp-security-gateway-monitor.git cd mcp-security-gateway-monitor # 2. 创建 virtual environment（推荐） python3 -m venv .venv source .venv/bin/activate # 3. 使用 dev dependencies 安装 package python3 -m pip install -e ".[dev]" # 4. 运行所有测试 python3 -m pytest tests/ -v # 5. 运行 coverage python3 -m pytest tests/ --cov=mcp_monitor --cov-report=term-missing # 6. 运行 security dashboard python3 run_dashboard.py ``` ### Windows PowerShell ``` # 1. Clone repository git clone https://github.com/poojakira/mcp-security-gateway-monitor.git cd mcp-security-gateway-monitor # 2. 创建 virtual environment（推荐） python -m venv .venv .\.venv\Scripts\Activate.ps1 # 3. 使用 dev dependencies 安装 package python -m pip install -e ".[dev]" # 4. 运行所有测试 python -m pytest tests/ -v # 5. 运行 coverage python -m pytest tests/ --cov=mcp_monitor --cov-report=term-missing # 6. 运行 security dashboard python run_dashboard.py ``` ### Windows Command Prompt (cmd.exe) ``` REM 1. Clone the repository git clone https://github.com/poojakira/mcp-security-gateway-monitor.git cd mcp-security-gateway-monitor REM 2. Create a virtual environment (recommended) python -m venv .venv .venv\Scripts\activate.bat REM 3. Install the package with dev dependencies REM NOTE: Do NOT quote .[dev] in cmd.exe python -m pip install -e .[dev] REM 4. Run all tests python -m pytest tests/ -v REM 5. Run with coverage python -m pytest tests/ --cov=mcp_monitor --cov-report=term-missing REM 6. Run the security dashboard python run_dashboard.py ``` ## 10 个防御层的工作原理 本项目实现了一个包含 10 个防御层的纵深防御架构，这些防御层协同工作，在多个节点捕捉攻击： | 层级 | 名称 | 作用 | |-------|------|--------------| | 1 | **Audit Log** | 在 SHA-256 哈希链式日志中记录工具调用。验证哈希链时可以检测到是否存在篡改。 | | 2 | **Inline Proxy Gateway** | 拦截所有工具调用。在可疑调用执行前应用规则、进行风险评分，并拦截/隔离这些调用。 | | 3 | **Kernel Monitor** | 监控 syscall 级别行为：网络连接、DNS 查询、文件访问、进程生成。强制执行针对每个 server 的策略。 | | 4 | **Semantic Intent Analyzer** | 理解工具调用的真实意图。检测 BCC 同义词、数据泄露模式、编码电子邮件以及可疑字段。 | | 5 | **Network Egress Policy** | 控制每个 server 可以访问的目标。默认拒绝，并配有显式的允许规则。拦截已知的恶意域名和超大 payload。 | | 6 | **ML Threat Classifier** *(BETA)* | 实验性 scikit-learn 模型（TF-IDF 字符 n-grams + LogisticRegression），基于内置的合成语料库训练。仅作为补充信号——关于测得的留存性能，请参阅下文的 BETA 说明。 | | 7 | **Rate Limiter** | 通过强制执行收件人白名单和每分钟速率上限来限制爆炸半径。阻止大规模数据泄露。 | | 8 | **Honeypot Vault** | 在工具响应中植入 canary token。如果某个 token 出现在不该出现的地方，即可确认存在数据泄露路径。 | | 9 | **Docker Sandbox** | 在网络受限的 container 中隔离不受信任的 MCP server。互联网访问受配置的 container 策略限制，并应在部署时进行验证。 | | 10 | **Network Monitor + DPI** | 深度包检测，将声明的 MCP 意图与实际的 HTTP 流量进行比较。捕捉对发送内容进行欺骗的工具。 | 前 5 个防御层在每次工具调用时都会运行，且无任何外部依赖。防御层 6-10 为生产环境部署添加了 ML、沙盒和深度检测功能。 ## 项目结构 ``` mcp-security-gateway-monitor/ ├── README.md <- You are here ├── run_dashboard.py <- Run this to see the security dashboard ├── pyproject.toml <- Package config, dependencies ├── CHANGELOG.md <- Version history ├── RESEARCH_REPORT.md <- Technical research background ├── src/ │ └── mcp_monitor/ │ ├── __init__.py <- Package root │ ├── monitor.py <- MCPSecurityMonitor orchestrator │ ├── detectors/ │ │ ├── prompt_injection.py <- 12 regex patterns for jailbreak detection │ │ ├── pii_detector.py <- 9 PII types with redaction │ │ ├── shadow_server.py <- Unregistered server detection │ │ └── exfiltration.py <- BCC injection, payload size, base64, URLs │ ├── audit/ │ │ ├── log.py <- SHA-256 hash-chained audit log │ │ └── wal.py <- Write-ahead log for crash recovery │ ├── advanced/ │ │ ├── manifest.py <- Cryptographic tool manifest signing │ │ ├── drift.py <- Behavioral drift detection │ │ ├── correlation.py <- Multi-step attack correlation │ │ ├── invariants.py <- Declarative security policies │ │ └── canary.py <- Active behavioral probes │ ├── layers/ │ │ ├── proxy.py <- Layer 2: Inline Proxy Gateway │ │ ├── kernel.py <- Layer 3: Kernel Monitor │ │ ├── semantic.py <- Layer 4: Semantic Intent Analyzer │ │ ├── egress.py <- Layer 5: Network Egress Policy │ │ └── orchestrator.py <- FiveLayerDefense orchestrator │ ├── dashboard/ │ │ ├── terminal.py <- Terminal-based live dashboard │ │ └── report.py <- HTML report generator │ ├── redteam/ │ │ ├── simulator.py <- Attack simulation engine │ │ └── payloads.py <- Real-world attack catalog │ └── defense10/ │ ├── ml_classifier.py <- ML threat classifier │ ├── rate_limiter.py <- Rate limiting + recipient whitelist │ ├── honeypot.py <- Canary token vault │ ├── sandbox.py <- Docker sandbox isolation │ ├── network_monitor.py <- /proc/net/tcp + eBPF monitor │ ├── egress_proxy.py <- DPI egress inspection │ └── orchestrator10.py <- Full 10-layer orchestrator └── tests/ ├── test_prompt_injection.py ├── test_pii_detector.py ├── test_shadow_server.py ├── test_exfiltration.py ├── test_audit_log.py ├── test_advanced_*.py ├── test_cross_platform.py └── test_coverage_100.py ``` ## 运行仪表盘 ``` python run_dashboard.py ``` 该脚本将执行以下操作： 1. 设置包含 InlineProxyGateway、KernelMonitor、SemanticIntentAnalyzer 和 NetworkEgressPolicy 的 5 层防御 2. 运行内置的红队攻击目录 3. 打印带有颜色编码的终端报告，显示每次攻击及其是否被成功拦截 4. 将交互式 HTML 仪表盘保存至 `security_dashboard.html` 5. 在默认浏览器中打开该仪表盘 ## 输出示例 ``` from mcp_monitor.layers import ( InlineProxyGateway, KernelMonitor, SemanticIntentAnalyzer, NetworkEgressPolicy, FiveLayerDefense, ) from mcp_monitor.redteam import AttackSimulator from mcp_monitor.dashboard import TerminalDashboard proxy = InlineProxyGateway() kernel = KernelMonitor() semantic = SemanticIntentAnalyzer() egress = NetworkEgressPolicy(default_deny=True) defense = FiveLayerDefense(proxy=proxy, kernel=kernel, semantic=semantic, egress=egress) simulator = AttackSimulator(defense) report = simulator.run_full_catalog() print(f"Detection Rate: {report.detection_rate:.1f}%") print(f"Blocked: {report.blocked}/{report.total_attacks}") ``` ## 故障排除 | 问题 | 原因 | 解决方案 | |---------|-------|----------| | `ModuleNotFoundError: No module named 'mcp_monitor'` | 未安装 package | 在项目根目录下运行 `pip install -e ".[dev]"` | | `No module named 'pytest'` | 缺少开发依赖 | 运行 `pip install -e ".[dev]"`（包含 pytest） | | `ERROR: .[dev] is not a valid requirement` | 在 cmd.exe 中使用了引号 | 移除引号：`pip install -e .[dev]` | | `python3: command not found` (Windows) | Windows 使用 `python` 而非 `python3` | 使用 `python` 替代 `python3` | | 在 Linux/macOS 上提示 `Permission denied` | 需要写入权限以进行安装 | 使用虚拟环境：`python3 -m venv .venv && source .venv/bin/activate` | | 在 Python 3.9 或更低版本上出现 `SyntaxError` | 项目要求 Python 3.10+ | 将 Python 升级至 3.10 或更高版本 | | `ImportError: cannot import name 'MLThreatClassifier'` | 未安装 scikit-learn | 运行 `pip install -e ".[ml]"` 以获取 ML 功能 | | 测试显示 `0% coverage` | 从错误的目录运行了 pytest | 确保您位于项目根目录下 | | `webbrowser.open` 无效果 | 无头（headless）环境中没有 GUI 浏览器 | 在浏览器中手动打开 `security_dashboard.html` | | HTML 仪表盘为空白 | 脚本未运行完毕 | 检查终端输出是否有错误；重新运行 `python run_dashboard.py` | ## 测试结果 ``` Current local validation snapshot (Windows, Python 3.12.9, 2026-07-14): 472 tests passed | 0 pytest warnings | 23.66s runtime with `-W error` 472 tests passed | 82% total coverage | 43.64s runtime with coverage Docker image build validated locally with `docker build -t mcp-monitor:ci .`. ``` ## 零 Runtime 依赖 核心监控器和所有 5 个防御层仅使用 Python 标准库： ``` [project] dependencies = [] # Zero runtime deps ``` 用于高级功能的可选扩展： - `pip install -e ".[dev]"` -- 包含 pytest、coverage、PyYAML 和 scikit-learn，用于本地验证 - `pip install -e ".[ml]"` -- 包含 scikit-learn，用于 ML 分类器（防御层 6） - `pip install -e ".[dpi]"` -- 包含 mitmproxy，用于深度包检测（防御层 10） ## 许可证 MIT

标签：AI安全, Chat Copilot, Docker镜像, MCP协议, Python, 大模型防护, 数据泄露防护, 无后门, 网关监控, 网络探测, 请求拦截, 逆向工具