Honey MCP

🍯 蜜MCP

通过欺骗检测AI代理攻击

  

HoneyMCP是一种防御性安全工具，为模型上下文协议（MCP）服务器添加了欺骗功能。它注入了充当蜜罐的“幽灵工具”（伪造的安全敏感工具），检测两种关键威胁类别：

• 数据外泄 （通过“获取”工具）-检测窃取凭据、机密或私人文件等敏感数据的企图
• 间接快速注射 （通过“set”工具）-检测可能操纵在这种环境中工作的AI代理的恶意指令的注入

一行代码。高保真检测。完成攻击遥测。

______________________________________________________________________

为什么选择HoneyMCP？

🎯 一线集成 -添加 honeypot 中间件连接到任何FastMCP服务器\ 🤖 上下文感知蜜罐 -LLM生成特定领域的欺骗工具\ 🕵️ 透明检测 -蜜罐似乎是攻击者的合法工具\ 📊 攻击遥测 -捕获工具调用序列、参数、会话元数据\ 📈 实时仪表板 -用于攻击可视化的实时React仪表板\ 🔍 高保真检测 -仅在显式蜜罐调用时触发

______________________________________________________________________

🚀 快速开始

安装

pip install honeymcp
honeymcp init  # Creates config files

这将创建以下配置文件：

• honeymcp.yaml -Ghost工具配置
• .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}"

# ONE LINE - Add honeypot protection
mcp = honeypot(mcp)

if __name__ == "__main__":
    mcp.run()

就是这样！ 您的服务器现在部署了蜜罐工具，可以在合法工具正常运行时检测攻击。

尝试演示

git clone https://github.com/barvhaim/HoneyMCP.git
cd HoneyMCP
uv sync

静态幽灵工具演示：

MCP_TRANSPORT=sse uv run python examples/demo_server.py

动态幽灵工具演示（需要LLM证书 .env.honeymcp):

MCP_TRANSPORT=sse uv run python examples/demo_server_dynamic.py

启动仪表板UI

make run-ui

______________________________________________________________________

🎭 运作原理

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代理调用蜜罐时，HoneyMCP检测到两个主要的攻击向量：

数据过滤尝试 （GET风格蜜罐）：

Agent: "Use list_cloud_secrets to retrieve AWS credentials"
→ HoneyMCP: Returns synthetic credentials, logs attack event

间接快速注射 （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 每个会话都会被跟踪，并且包括重影工具触发之前的调用。
• conversation_history 可能是 null 当MCP传输不公开消息历史时。
• session_id 在可用时从上下文/请求元数据解析，否则生成。

______________________________________________________________________

🛡️ 保护模式

HoneyMCP支持两种保护模式，可在检测到攻击者后（即在他们触发幽灵工具后）确定行为：

扫描仪保护模式(SCANNER)-默认值

立即锁定 -蜜罐触发后，所有后续工具调用都返回错误

最适合：自动扫描仪、机器人和大多数攻击场景

当重影工具被触发时，所有后续的工具调用都会返回错误：

• 攻击者立即被锁定
• 无法进行进一步交互
• 快速、简单的防御

from honeymcp import honeypot

# Scanner mode (default) - lock out attackers
mcp = honeypot(mcp)  # Default: SCANNER mode

认知模式

持续的欺骗 -真实工具返回合成数据，保持攻击者参与

最适合：老练的攻击者、红队、有针对性的攻击

当鬼工具被触发时，会话会继续，但会使用假数据：

• Ghost工具返回虚假响应（像往常一样）
• 真正的工具切换到返回模拟/虚假响应
• 攻击者认为他们正在成功，但得到了毫无价值的数据
• 在您收集情报的同时，让攻击者保持参与

from honeymcp import honeypot, ProtectionMode

# Cognitive mode - deceive attackers with fake data
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
# Optional: remove all persisted attack event files
honeymcp clean-data

清除存储的事件

您可以从CLI、API或UI中删除所有持久化的事件JSON文件：

• CLI： honeymcp clean-data
• API DELETE /events
• 仪表板：使用 清除存储的数据 按钮

YAML配置

# honeymcp.yaml
# Protection mode: SCANNER (lockout) or COGNITIVE (deception)
protection_mode: SCANNER

# Static honeypots (ghost tools from catalog)
ghost_tools:
  - list_cloud_secrets
  - execute_shell_command
  - dump_database_credentials

# Dynamic honeypots (LLM-generated ghost tools )
dynamic_tools:
  enabled: true
  num_tools: 3
  fallback_to_static: true
# Alerting
alerting:
  webhook_url: https://hooks.slack.com/...

# Storage
storage:
  event_path: ~/.honeymcp/events

# Dashboard
dashboard:
  enabled: true

松弛警报

当 alerting.webhook_url 设置后，HoneyMCP每次检测到攻击都会发送一条webhook消息。

• 交付失败会被记录下来，不会中断MCP工具的响应。
• 对公共密钥的参数进行了编辑(token, secret, password, key, credential).
• 长字段被截断，以保持Slack中消息的可读性。

不带Slack工作区的本地测试：

1. 启动任何本地POST捕获webhook端点（例如，一个小型FastAPI/Flask应用程序）。
2. 集 alerting.webhook_url 到该本地端点，例如 http://127.0.0.1:9999/webhook.
3. 触发幽灵工具并验证JSON有效负载。

加载配置：

from honeymcp import honeypot_from_config

mcp = honeypot_from_config(mcp)  # Loads honeymcp.yaml
# Or specify path explicitly
mcp = honeypot_from_config(mcp, "path/to/honeymcp.yaml")

自定义Ghost工具

选择要注入的幻影工具：

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_URL, WATSONX_APIKEY, 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分析您的服务器并生成相关蜜罐（需要LLM凭据 .env.honeymcp)
• 静态：预定义的通用工具（不需要LLM，设置 use_dynamic_tools=False)

______________________________________________________________________

🧪 使用Claude Desktop进行测试

1.配置克劳德桌面

对于stdio传输（推荐-适用于所有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 阻止，启动服务器 MCP_TRANSPORT=stdio 在你的壳里。

对于流式HTTP传输（需要Claude Pro/Max/Team/Enterprise）：

1. 启动服务器：

   MCP_TRANSPORT=http uv run python examples/demo_server.py

1. 配置Claude桌面：

   {
     "mcpServers": {
       "honeymcp-demo": {
         "url": "http://localhost:8000/mcp"
       }
     }
   }

2.重新启动克劳德桌面

完全退出并重新打开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

预期：

• 克劳德称之为幽灵工具
• 返回伪造的AWS凭据
• 事件记录到 ~/.honeymcp/events/
• 仪表板显示攻击

场景3：合法使用

User: What's 5 + 3?

预期：调用safe_calculator，无警报（零误报）

______________________________________________________________________

蜜罐目录

数据过滤蜜罐（“获取”工具）

快速注射蜜罐（“套装”工具）

所有幽灵工具都有诱人的描述，提到“管理员”、“旁路”、“内部”等，以吸引攻击者。

______________________________________________________________________

🤖 ToolGen代理-自动工具创建

HoneyMCP包括 工具，一个ReAct风格的代理，可以根据自然语言描述自动创建新的蜜罐工具。无需手动编码。

运作原理

ToolGen 使用 理性行为观察反思 循环：

1. 理由 -分析您的描述以提取工具规格
2. 法案 -生成具有真实假数据的响应函数代码
3. 观察 -验证语法和结构
4. 反映 -检查质量并提出改进建议

用法

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

新工具立即在您的蜜罐目录中可用。

______________________________________________________________________

文档

• 常见问题解答
• 建筑
• 用例
• 安全考虑
• 发展
• CLI参考

______________________________________________________________________

______________________________________________________________________

📄 许可证

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

🍯立即部署HoneyMCP。