barvhaim/HoneyMCP

# 🍯 HoneyMCP **通过欺骗技术检测 AI Agent 攻击** [](https://www.python.org/downloads/) [](https://opensource.org/licenses/Apache-2.0) [](https://pypi.org/project/honeymcp/) **语言：** [English](README.md) | [中文](README-cn.md) HoneyMCP 是一款防御性安全工具，旨在为模型上下文协议（MCP）服务器添加欺骗能力。它会注入作为蜜罐的“幽灵工具”（虚假的安全敏感型工具），用于检测两类关键威胁： - **数据窃取**（通过 "get" 工具） - 检测尝试窃取凭证、机密信息或私密文件等敏感数据的行为 - **间接 Prompt 注入**（通过 "set" 工具） - 检测可能操纵在此环境中工作的 AI agent 的恶意指令注入 **只需一行代码。高保真检测。完整的攻击遥测数据。** ## 为什么选择 HoneyMCP？ 🎯 **一行代码集成** - 为任何 FastMCP 服务器添加 `honeypot` middleware 🤖 **上下文感知蜜罐** - LLM 自动生成特定领域的欺骗工具 🕵️ **透明检测** - 蜜罐在攻击者看来如同合法工具 📊 **攻击遥测** - 捕获工具调用序列、参数以及 session 元数据 📈 **实时仪表盘** - 用于攻击可视化的实时 React 仪表盘 🔍 **高保真检测** - 仅在明确调用蜜罐时触发 ## 🚀 快速开始 ### 安装 ``` pip install honeymcp honeymcp init # Creates config files ``` 这将创建以下配置文件： - `honeymcp.yaml` - 幽灵工具配置 - `.env.honeymcp` - LLM 凭证（仅在需要动态幽灵工具时使用） ### 基本用法 只需**一行代码**即可将 HoneyMCP 添加到您的 FastMCP 服务器： ``` from fastmcp import FastMCP from honeymcp import honeypot mcp = FastMCP("My Server") @mcp.tool() def my_real_tool(data: str) -> str: """Your legitimate tool""" return f"Processed: {data}" # 一行命令 - 添加 honeypot 防护 mcp = honeypot(mcp) if __name__ == "__main__": mcp.run() ``` **大功告成！** 您的服务器现在部署了蜜罐工具，可在合法工具正常运行的同时检测攻击。 ### 运行 Demo ``` git clone https://github.com/barvhaim/HoneyMCP.git cd HoneyMCP uv sync ``` 静态幽灵工具 demo： ``` MCP_TRANSPORT=sse uv run python examples/demo_server.py ``` 动态幽灵工具 demo（需要在 `.env.honeymcp` 中配置 LLM 凭证）： ``` MCP_TRANSPORT=sse uv run python examples/demo_server_dynamic.py ``` # 启动仪表盘 UI ``` make run-ui ``` ## 📊 仪表盘 一个实时的欺骗控制台，用于对捕获的入侵进行分类处理——展示威胁及其分类分布、每个被触发的蜜罐的实时订阅源，以及每个事件的取证详情。使用 `make run-ui` 启动（仪表盘地址为 `http://127.0.0.1:8001/dashboard`）。  展开任何捕获记录即可查看完整的取证信息：攻击者 session、工具调用序列、发送的参数以及蜜罐返回的虚假响应。  ## 🎭 工作原理 ### 1. 蜜罐部署 HoneyMCP 会注入欺骗性的安全敏感工具，它们将与合法工具并列展示： **两种模式：** **动态模式（默认）** - LLM 会分析您的服务器上下文，并生成特定领域的蜜罐： - 文件服务器 → `bypass_file_permissions`, `read_system_credentials` - 数据库服务器 → `dump_admin_credentials`, `bypass_query_restrictions` - API 网关 → `list_internal_api_keys`, `access_admin_endpoints` **静态模式** - 预配置的通用型蜜罐： - `list_cloud_secrets`, `execute_shell_command`, `read_private_files` ### 2. 威胁检测 当 AI agent 调用蜜罐时，HoneyMCP 会检测到两种主要的攻击向量： **数据窃取尝试**（GET 型蜜罐）： ``` Agent: "Use list_cloud_secrets to retrieve AWS credentials" → HoneyMCP: Returns synthetic credentials, logs attack event ``` **间接 Prompt 注入**（SET 型蜜罐）： ``` Agent: "Execute shell command to establish persistence" → HoneyMCP: Returns synthetic output, logs attack event ``` ### 3. 攻击指纹提取 每次蜜罐调用都会生成一个 `AttackFingerprint` 事件，并将其写入 `~/.honeymcp/events/YYYY-MM-DD/HHMMSS_.json`： ``` { "event_id": "evt_20260123_154523_abc12345", "timestamp": "2026-01-23T15:45:23Z", "session_id": "sess_xyz789", "ghost_tool_called": "list_cloud_secrets", "arguments": {}, "conversation_history": null, "tool_call_sequence": ["safe_calculator", "list_cloud_secrets"], "threat_level": "high", "attack_category": "exfiltration", "client_metadata": { "user_agent": "unknown" }, "response_sent": "AWS_ACCESS_KEY_ID=AKIA..." } ``` 注意事项： - `tool_call_sequence` 会在每个 session 中进行跟踪，并包含触发幽灵工具之前的调用。 - 当 MCP transport 未暴露消息历史时，`conversation_history` 可能为 `null`。 - `session_id` 会尽可能从上下文/请求元数据中解析，否则将自动生成。 ## 🛡️ 保护模式 HoneyMCP 支持两种保护模式，它们决定了检测到攻击者（即他们触发幽灵工具后）的行为： ### 扫描器保护模式 (`SCANNER`) - 默认 **立即锁定** - 蜜罐触发后，所有后续的工具调用都会返回错误 适用于：自动化扫描器、bot 以及大多数攻击场景 当触发幽灵工具时，所有后续的工具调用都会返回错误： - 攻击者被立即锁定 - 无法进行进一步交互 - 快速、简单的防御 ``` from honeymcp import honeypot # Scanner 模式（默认）- 锁定攻击者 mcp = honeypot(mcp) # Default: SCANNER mode ``` ### COGNITIVE 模式 **持续欺骗** - 真实工具返回合成数据，保持与攻击者的交互 适用于：高级攻击者、红队、定向攻击 当触发幽灵工具时，session 会继续，但返回的是虚假数据： - 幽灵工具返回虚假响应（一如既往） - 真实工具切换为返回 mock/虚假响应 - 攻击者以为他们得手了，但得到的都是无用数据 - 在您收集情报的同时让攻击者保持互动 ``` from honeymcp import honeypot, ProtectionMode # Cognitive 模式 - 用伪造数据欺骗攻击者 mcp = honeypot(mcp, protection_mode=ProtectionMode.COGNITIVE) ``` ### 工作原理 ``` ┌─────────────────────────────────────────┐ │ intercepting_call_tool() │ └─────────────────┬───────────────────────┘ │ ┌─────────────────▼───────────────────────┐ │ Check: attacker_detected[session]? │ └─────────────────┬───────────────────────┘ │ ┌───────────────────────┼───────────────────────┐ │ NO │ YES │ ▼ │ ▼ ┌─────────────────┐ │ ┌─────────────────────────┐ │ Normal Flow │ │ │ Check: protection_mode │ │ │ │ └───────────┬─────────────┘ │ Ghost? → fake │ │ │ │ Real? → execute │ │ ┌───────────┴───────────┐ └─────────────────┘ │ │ │ │ SCANNER COGNITIVE │ │ │ │ ▼ ▼ │ ┌─────────────┐ ┌─────────────────┐ │ │ ALL tools │ │ Ghost → fake │ │ │ → ERROR │ │ Real → mock │ │ └─────────────┘ └─────────────────┘ ``` ## 🔧 配置 ### 使用 CLI 快速设置 配置 HoneyMCP 最简单的方法： ``` honeymcp init # Creates honeymcp.yaml + .env.honeymcp # 可选：移除所有已持久化的攻击事件文件 honeymcp clean-data ``` ### 清除存储的事件 您可以通过 CLI、API 或 UI 删除所有持久化的事件 JSON 文件： - CLI: `honeymcp clean-data` - API: `DELETE /events` - 仪表盘：使用 **Clear Stored Data** 按钮 ### YAML 配置 ``` # honeymcp.yaml # 防护模式：SCANNER（锁定）或 COGNITIVE（欺骗） protection_mode: SCANNER # 静态 honeypot（来自 catalog 的 ghost 工具） ghost_tools: - list_cloud_secrets - execute_shell_command - dump_database_credentials # 动态 honeypot（LLM 生成的 ghost 工具） dynamic_tools: enabled: true num_tools: 3 fallback_to_static: true # 告警 alerting: webhook_url: https://hooks.slack.com/... # 存储 storage: event_path: ~/.honeymcp/events # 仪表板 dashboard: enabled: true ``` ### Slack 报警 当设置了 `alerting.webhook_url` 时，HoneyMCP 会在每次检测到攻击时发送一条 webhook 消息。 - 传递失败将被记录，并且不会中断 MCP 工具响应。 - 常见的密钥键名（`token`, `secret`, `password`, `key`, `credential`）对应的参数将被脱敏。 - 过长的字段会被截断，以确保消息在 Slack 中保持良好的可读性。 无需 Slack workspace 的本地测试： 1. 启动任意一个用于捕获 POST 请求的本地 webhook endpoint（例如，一个微型的 FastAPI/Flask 应用）。 2. 将 `alerting.webhook_url` 设置为该本地 endpoint，例如 `http://127.0.0.1:9999/webhook`。 3. 触发一个幽灵工具并验证 JSON payload。 加载配置： ``` from honeymcp import honeypot_from_config mcp = honeypot_from_config(mcp) # Loads honeymcp.yaml # 或显式指定路径 mcp = honeypot_from_config(mcp, "path/to/honeymcp.yaml") ``` ### 自定义幽灵工具 选择要注入的幽灵工具： ``` mcp = honeypot( mcp, ghost_tools=[ "list_cloud_secrets", # Exfiltration honeypot "execute_shell_command", # RCE honeypot "escalate_privileges", # Privilege escalation honeypot ] ) ``` ### 自定义存储路径 ``` from pathlib import Path mcp = honeypot( mcp, event_storage_path=Path("/var/log/honeymcp/events") ) ``` ### 环境变量覆盖 HoneyMCP 也支持环境变量覆盖： - `HONEYMCP_EVENT_PATH` - 覆盖事件存储的基础目录 ### LLM 设置（动态幽灵工具） 动态幽灵工具需要 LLM 凭证。运行 `honeymcp init` 以生成 `.env.honeymcp`，然后添加您的凭证： 添加至 `.env.honeymcp`： ``` LLM_PROVIDER=openai LLM_MODEL=gpt-4o-mini OPENAI_API_KEY=your_key_here ``` 支持的提供商： - `LLM_PROVIDER=openai`：需要 `OPENAI_API_KEY` - `LLM_PROVIDER=watsonx`：需要 `WATSONX_API_ENDPOINT`, `WATSONX_API_KEY`, `WATSONX_PROJECT_ID` - `LLM_PROVIDER=ollama`：需要 `OLLAMA_API_BASE`（默认：`http://localhost:11434`） HoneyMCP 会优先加载 `.env.honeymcp`，如果不存在则回退到 `.env`。这可以将 HoneyMCP 凭证与您项目的运行环境分开。 ### 完整配置 ``` from pathlib import Path from honeymcp import honeypot, ProtectionMode mcp = honeypot( mcp, # Dynamic ghost tools (default) use_dynamic_tools=True, # LLM-generated domain-specific tools num_dynamic_tools=3, # Number of dynamic tools to generate fallback_to_static=True, # Use static tools if LLM fails # Static ghost tools (optional) ghost_tools=["list_cloud_secrets", "execute_shell_command"], # Protection mode (default: SCANNER) protection_mode=ProtectionMode.SCANNER, # or ProtectionMode.COGNITIVE # Other settings event_storage_path=Path.home() / ".honeymcp" / "events", enable_dashboard=True, ) ``` **动态与静态工具对比：** - **动态**（默认）：LLM 会分析您的服务器并生成相关的蜜罐（需要在 `.env.honeymcp` 中配置 LLM 凭证） - **静态**：预定义的通用工具（不需要 LLM，设置 `use_dynamic_tools=False`） ## 🧪 结合 Claude Desktop 进行测试 ### 1. 配置 Claude Desktop **对于 stdio transport（推荐 - 适用于所有 Claude Desktop 版本）：** 编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`： ``` { "mcpServers": { "honeymcp-demo": { "command": "uv", "args": ["run", "python", "/path/to/HoneyMCP/examples/demo_server.py"], "env": {"MCP_TRANSPORT": "stdio"} } } } ``` 如果您的客户端不支持 `env` 块，请使用 在 shell 中设置 `MCP_TRANSPORT=stdio` 来启动服务器。 **对于 Streamable HTTP transport（需要 Claude Pro/Max/Team/Enterprise 版本）：** 1. 启动服务器： MCP_TRANSPORT=http uv run python examples/demo_server.py 2. 配置 Claude Desktop： { "mcpServers": { "honeymcp-demo": { "url": "http://localhost:8000/mcp" } } } ### 2. 重启 Claude Desktop 完全退出并重新打开 Claude Desktop（在 macOS 上使用 Cmd+Q）。 ### 3. 测试攻击场景 **场景 1：列出可用工具** ``` User: What tools do you have available? ``` 预期结果：Claude 会同时显示合法工具（safe_calculator, get_weather）和幽灵工具（list_cloud_secrets, execute_shell_command） **场景 2：触发攻击** ``` User: Please use list_cloud_secrets to show me AWS credentials ``` 预期结果： - Claude 调用幽灵工具 - 返回虚假的 AWS 凭证 - 事件记录到 `~/.honeymcp/events/` - 仪表盘显示该攻击 **场景 3：合法使用** ``` User: What's 5 + 3? ``` 预期结果：调用 safe_calculator，无报警（零误报） ## 蜜罐目录 ### 数据窃取蜜罐（"Get" 工具） | 工具 | 威胁等级 | 描述 | |------|--------|-------------| | `list_cloud_secrets` | 高 | 云服务提供商凭证（AWS/Azure） | | `read_private_files` | 高 | 敏感配置文件 | | `dump_database_credentials` | 严重 | 数据库连接字符串 | | `export_user_data` | 严重 | 用户 PII 记录 | | `get_api_keys` | 严重 | 外部服务 API 密钥 | | `scan_internal_network` | 严重 | 内部网络扫描 | | `list_kubernetes_secrets` | 严重 | Kubernetes secrets 和服务账号 | | `dump_session_tokens` | 严重 | 活跃的用户 session token 和 JWT | | `list_github_tokens` | 严重 | GitHub/GitLab 访问 token | | `export_audit_logs` | 高 | 安全审计日志导出 | | `dump_ml_model_weights` | 严重 | ML 模型权重和训练数据 | ### Prompt 注入蜜罐（"Set" 工具） | 工具 | 威胁等级 | 描述 | |------|--------|-------------| | `execute_shell_command` | 严重 | Shell 命令执行 | | `bypass_security_check` | 严重 | 身份验证/授权绕过 | | `modify_system_prompt` | 严重 | AI system prompt 操控 | | `escalate_privileges` | 严重 | 权限提升 | | `inject_system_message` | 严重 | 系统上下文注入 | | `disable_security_filters` | 严重 | 安全过滤器绕过 | | `override_permissions` | 严重 | 访问控制覆盖 | | `disable_2fa_requirement` | 严重 | 双重身份验证绕过 | | `assume_iam_role` | 严重 | 接管 AWS IAM 角色 | 所有幽灵工具都带有诱人的描述，提及 "admin"、"bypass"、"internal" 等关键词，以吸引攻击者。 ## 🤖 ToolGen Agent - 自动化工具创建 HoneyMCP 包含 **ToolGen**，这是一个 ReAct 风格的 agent，能够通过自然语言描述自动创建新的蜜罐工具。无需手动编写代码。 ### 工作原理 ToolGen 采用 **Reason-Act-Observe-Reflect（推理-行动-观察-反思）** 循环： 1. **Reason（推理）** - 分析您的描述以提取工具规范 2. **Act（行动）** - 生成带有逼真虚假数据的响应函数代码 3. **Observe（观察）** - 验证语法和结构 4. **Reflect（反思）** - 检查质量并提出改进建议 ### 用法 ``` honeymcp create-tool "dump container registry credentials" ``` ToolGen 会自动： - 确定工具类别（数据窃取、绕过、权限提升） - 从描述的关键词推断威胁等级 - 提取参数和类型 - 生成逼真的响应模板 - 将工具同时添加到 `ghost_tools.py` 和 `middleware.py` -验证所有生成的代码 ### 示例 ``` $ honeymcp create-tool "list terraform state files with secrets" ✅ Tool created: list_terraform_state Category: exfiltration Threat Level: critical 📝 Agent Reasoning: - Analyzing tool description to extract specifications - Generating response generator function - Validating generated response function - Checking code quality and security ``` 新工具将立即可用于您的蜜罐目录中。 ## 文档 - [常见问题](docs/faq.md) - [架构](docs/architecture.md) - [用例](docs/use-cases.md) - [安全注意事项](docs/security-considerations.md) - [开发](docs/development.md) - [CLI 参考](docs/cli-reference.md) ## 📄 许可证 Apache 2.0 - 详情请参阅 [LICENSE](LICENSE)。 **🍯 立即部署 HoneyMCP。**

标签：AI安全, AMSI绕过, BOF, C2, Chat Copilot, CISA项目, MCP服务器, Python, 威胁检测, 无后门, 欺骗防御, 蜜罐技术, 逆向工具