HoneyPot-MCP

# 蜂巢系统 MCP [](https://github.com/tohudgins/HoneyPot-MCP/actions/workflows/ci.yml) [](LICENSE) [](pyproject.toml) 一个模型上下文协议服务器，允许Claude（或任何MCP客户端）部署诱饵系统、植入诱饵令牌、监控警报和分析攻击者行为 — 所有这些都可以通过自然语言实现。构建于 [FastMCP](https://github.com/jlowin/fastmcp) 之上，支持异步Python 3.11+。 您可以直接用英语下达指令；它会部署真正的诱饵系统（14种协议）、捕获攻击者实际采取的行动、丰富每个命中结果并提供威胁情报，并将结果发送到您的SIEM或生成报告。 ``` > 在22端口部署一个SSH诱饵系统。 > 生成一个假的AWS凭证令牌，并告诉我在哪里植入它。 > 重建IP地址1.2.3.4在所有诱饵系统中的旅程。 > 导出一个iptables阻塞列表，用于IP地址中命中次数超过10次的记录。 ``` > **请先阅读：** [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md) — 坦率地说明哪些功能有效（Cowrie SSH、HTTP personas、canary URLs、凭证交叉引用）和哪些功能无效（PDF令牌在Acrobat中提示；云密钥令牌需要审计日志转发器）。承认这些限制是重点。 > > **部署到互联网？** [docs/DEPLOY.md](docs/DEPLOY.md) — "$5 VPS → 真实的攻击流量在30分钟内"，带有安全防护栏。 --- ## 诱饵系统 十四种协议。SSH是Cowrie（工业级）；其余是自定义异步引擎，捕获实际的攻击，而不是仅仅连接。服务器身份在每次部署时都会随机化（personas），以抵抗指纹识别。 | 协议（默认端口） | 它捕获的内容 | |---|---| | **SSH + Telnet** （22/23） | Cowrie — 完整的会话、命令、文件上传、凭证 | | **HTTP/HTTPS** （80/443） | 利用签名（Log4Shell、SQLi、遍历、webshell、RCE…）、凭证、侦察升级 | | **SMB** （445） | EternalBlue / DoublePulsar 利用探测 | | **RDP** （3389） | X.224 握手 + TLS 升级 MCS 客户端指纹 | | **FTP** （21） | 凭证 + 上传的恶意软件（SHA-256 编码 + 分类） | | **SMTP** （25） | 凭证（AUTH LOGIN/PLAIN）、消息体、开放中继探测 | | **MySQL / PostgreSQL / MSSQL** （3306/5432/1433） | 登录凭证 + 认证后 RCE 查询（`INTO OUTFILE`、`COPY FROM PROGRAM`） | | **Redis** （6379） | 完整的未经身份验证的 RCE 投递链 — 攻击者的 SSH 密钥 + 目标路径 | | **MongoDB** （27017） | 未授权命令、`dropDatabase`、勒索软件笔记 | | **Elasticsearch** （9200） | 侦察 + 数据流失查询模式 | | **DNS** （53） | 隧道/流失 + 侦察（AXFR、`version.bind`、ANY） | | **VNC** （5900） | RFB 认证挑战/响应 | ## 平台 | 类别 | 能力 | |---|---| | **诱饵令牌** | 假的AWS密钥、canary URLs、凭证对（在每个诱饵系统登录时自动匹配 — 包括哈希的MySQL/VNC认证）、PDF/DOCX文件令牌、SSH密钥、JWT、DB行、kubeconfigs、Slack webhook、Azure/GCP云凭证 | | **检测管道** | 批量异步摄入 → 抑制（CIDR/通配符 + 速率限制）→ 诱饵令牌交叉引用（自动关键）→ 关键警报的自动丰富（VT + AbuseIPDB + GeoIP/ASN/反向DNS，TTL缓存） | | **分析** | MITRE ATT&CK 映射、攻击者画像 + 风险评分、SSH会话重建、跨诱饵系统杀伤链时间线、活动关联、丰富的XSS安全HTML/Markdown报告 | | **SIEM交付** | JSON（HMAC签名）、Splunk HEC、Elastic ECS、ArcSight CEF、Syslog RFC 5424（UDP/TCP）、Grafana Loki、Datadog — 按订阅的严重性阈值 + 交付健康统计 | | **响应** | 阻塞列表推送到Cloudflare / pfSense / AWS WAFv2、阻塞列表 + STIX 2.1导出、AbuseIPDB报告 | | **操作** | 健康观察、按需保留扫描、每IP连接上限、重启协调、端到端自检、Prometheus `/metrics`、Alembic迁移、JSON日志、Grafana仪表盘 | | **云诱饵令牌** | HMAC签名 `/cloud-event` 摄入 + 可部署的CloudTrail/Azure/GCP转发器位于 [`examples/cloud-forwarders/`](examples/cloud-forwarders/) | 317个单元测试覆盖了安全关键路径；严格的mypy通过。 --- ## 快速入门 **先决条件：** Python 3.11+，[uv](https://docs.astral.sh/uv/) （或pip），Docker Desktop（仅需用于Cowrie SSH诱饵系统）。 ```bash git clone https://github.com/tohudgins/HoneyPot-MCP.git cd HoneyPot-MCP uv sync --extra dev # 或：pip install -e ".[dev]" cp .env.example .env # 可选的API密钥 — 参见下文 uv run python -m honeypot_mcp.server # 或仅：honeypot-mcp ``` > `--extra dev` 引入pytest/ruff/mypy。如果您使用pip安装，请在README中的每个命令中删除 `uv run` 前缀。 **可选集成** （所有功能都可以在没有它们的情况下正常运行）： - `VIRUSTOTAL_API_KEY` — IP声誉（[免费](https://www.virustotal.com)） - `ABUSEIPDB_API_KEY` — 滥用报告（[免费，每日1k检查](https://www.abuseipdb.com)） - `GEOIP_DB_PATH` — [GeoLite2-City.mmdb](https://dev.maxmind.com/geoip/geolite2-free-geolocation-data) （免费注册） - `config/mitre_attack.json` — [enterprise-attack.json](https://github.com/mitre/cti) 用于完整的ATT&CK技术描述（内置正则表达式映射器无需它） --- ## 连接MCP客户端 以两种方式之一运行： - **本地（stdio）** — Claude Desktop/Code在每次聊天时启动服务器。最适合尝试，但服务器和诱饵系统仅在聊天期间存在。下面会介绍。 - **持久守护进程（HTTP）** — 24/7运行，以便诱饵系统独立于任何聊天：这是在实际部署中使用的模式；参见下面的[部署](#deploy--catching-traffic)。 ### Claude 代码 已配置：存储库附带了 `.claude/settings.json`，其中包含服务器条目。 在Claude Code中打开存储库，运行一次 `uv sync --extra dev`，然后聊天中就会出现这些工具。 ### Claude 桌面版 将以下内容添加到 `claude_desktop_config.json` （macOS: `~/Library/Application Support/Claude/`，Windows: `%APPDATA%\Claude\`）： ```json { "mcpServers": { "honeypot-mcp": { "command": "uv", "args": ["run", "--project", "/path/to/HoneyPot-MCP", "honeypot-mcp"], "cwd": "/path/to/HoneyPot-MCP" } } } ``` 完全退出并重新启动Claude Desktop（系统托盘 → 退出，而不仅仅是关闭窗口）。 ### 验证 在新的聊天中： ``` 在端口8080上部署一个HTTP诱饵系统，然后在其上运行honeypot_self_test。 ``` 预期结果：部署返回 `{status: "running"}`，自检报告 `alert_received: True` — 确认整个管道（探测 → 引擎 → 抑制 → 缓冲区 → 数据库）。 **故障排除** - **工具未出现** — Claude Desktop找不到 `uv`。将 `"command": "uv"` 替换为 `which uv` / `where.exe uv` 的绝对路径。检查帮助 → 显示日志。 - **`alert_received: False`** — 运行 `honeypot_health`；如果存活，检查 `suppression_list` 中是否有规则正在消耗事件。 - **Canary回调未触发** — 端口8888已被占用（通常是一个独立的服务器）。非致命，但canary令牌不会触发。 --- ## 部署 — 捕获流量 根据您要捕获的内容选择： | 目标 | 运行它 | 努力程度 | |---|---|---| | 尝试/查看仪表盘 | 您的笔记本电脑 | ~5分钟（[演示栈](#docker-stack--grafana-demo)） | | 在您自己的网络上捕获攻击 **在您自己的网络上** | 您LAN上的备用盒子/虚拟机 | ~15分钟 | | 捕获**真实的互联网攻击流量** | 一个廉价的临时VPS（$5/月） | ~30分钟（[docs/DEPLOY.md](docs/DEPLOY.md)） | 两种“真实”路径都使用**持久守护进程**，因此诱饵系统可以24/7运行，独立于任何聊天： ```bash # 在主机上，在.env中： MCP_TRANSPORT=http MCP_AUTH_TOKEN=$(openssl rand -hex 32) sudo cp deploy/honeypot-mcp.service /etc/systemd/system/ # 编辑里面的路径 sudo systemctl enable --now honeypot-mcp # 从您的笔记本电脑 — 隧道控制端口（永远不要防火墙暴露它）： ssh -N -L 8000:127.0.0.1:8000 you@host & claude mcp add --transport http honeypot-mcp http://127.0.0.1:8000/mcp \ --header "Authorization: Bearer <your-MCP_AUTH_TOKEN>" ``` 然后只需要求Claude部署诱饵系统并观察警报滚入。 **在您自己的网络中（内部触发器）。** 在您网络中部署诱饵系统，端口上没有任何其他内容。您网络中任何连接到它们的设备 — 受损的笔记本电脑扫描开放的SSH/SMB/Redis，内部人员窥探 — 按照定义不是合法的，因此**每个命中都是高信号**。在真实主机和文件共享上植入凭证诱饵和canary URL，以便横向移动触发它们。无需暴露于互联网。 **在公共互联网上（捕获真实攻击者）。** 在一个您不关心的VPS上运行守护进程，并将诱饵系统端口（22、80、443、445、3389...）开放给互联网 — 您将立即看到Mirai/Hydra SSH暴力破解、RDP/SMB漏洞扫描器和Web漏洞探测。**安全：使用专用的临时主机，首先将管理SSH移出端口22，并且永远不要重用生产密钥。** 完整的防护演练（防火墙、警报、持续操作）位于 [docs/DEPLOY.md](docs/DEPLOY.md)。 --- ## MCP 工具 ### 诱饵系统 | 工具 | 描述 | |---|---| | `honeypot_deploy` | 部署（ssh, http, smtp, ftp, dns, rdp, vnc, redis, mysql, elasticsearch, smb, postgresql, mongodb, mssql） | | `honeypot_list` / `honeypot_status` | 列出所有/详细 + 最近的事件 | | `honeypot_stop` / `honeypot_pause` / `honeypot_resume` | 生命周期控制 | | `honeypot_configure` / `honeypot_clone` / `honeypot_logs` / `honeypot_templates` | 配置、克隆、原始日志、配置文件 | | `honeypot_health` | 探测端口/容器 — 捕获静默死亡 | | `honeypot_self_test` | 端到端管道检查：合成探测 → 警报在数据库中 | ### 诱饵令牌 | 工具 | 描述 | |---|---| | `honeytoken_create` | 创建任意类型的令牌 | | `honeytoken_generate_aws` / `honeytoken_generate_credentials` | 假的AWS密钥对/用户名-密码集 | | `honeytoken_embed_file` | 带有canary跟踪器的PDF/DOCX | | `honeytoken_list` / `honeytoken_status` / `honeytoken_revoke` / `honeytoken_export` | 管理 + 格式化以种植 | ### 警报 | 工具 | 描述 | |---|---| | `alerts_recent` / `alerts_get` / `alerts_search` | 分类（按IP/严重性/类型过滤）、详细信息、子字符串搜索 | | `alerts_stats` / `alerts_export` / `alerts_acknowledge` / `alerts_prune` | 统计数据、JSON/CSV导出、审查工作流、保留 | ### 分析 | 工具 | 描述 | |---|---| | `enrich_ip` | VT + AbuseIPDB + GeoIP（并行、缓存） | | `analyze_attacker` / `analyze_session` / `analyze_attacker_journey` | 概要 + 风险评分 / Cowrie会话重建 / 跨诱饵系统ATT&CK时间线 | | `analyze_campaign` / `map_ttps` / `threat_timeline` | 活动关联、MITRE映射、时间线 | | `generate_report` | XSS安全HTML或Markdown报告 | | `export_blocklist` / `export_stix` / `report_ip_abuse` | 普通/iptables/fail2ban/cidr、STIX 2.1包、AbuseIPDB提交 | ### 集成 | 工具 | 描述 | |---|---| | `alert_subscribe` / `alert_unsubscribe` / `alert_subscriptions_list` | SIEM/网络钩子交付，附带健康统计 | | `suppression_add` / `suppression_remove` / `suppression_list` | 丢弃或速率限制噪音（精确IP/CIDR/事件类型通配符） | | `suppression_load_preset` / `suppression_list_presets` | 捆绑预设（shodan、censys、内部rfc1918） | | `blocklist_push_cloudflare` / `blocklist_push_pfsense` / `blocklist_push_aws_waf` | 将攻击者IP推送到实时设备（幂等，`dry_run`） | ### MCP 资源 `honeypot://active` · `alerts://stream` · `honeytoken://triggered` · `stats://dashboard` --- ## SIEM 集成 `alert_subscribe(url=..., format=...)` 选择正文格式和身份验证方案。`hmac_secret` 字段包含格式所需的凭证： | `format` | 正文 | 认证（`hmac_secret` 是...） | |---|---|---| | `json` （默认） | 原生 JSON 信封 | HMAC 密钥 → `X-HoneyPot-Signature` （GitHub 网络钩子约定） | | `splunk_hec` | HEC `{time, host, sourcetype, event}` | HEC 令牌 → `Authorization: Splunk <token>` | | `elastic_ecs` | ECS 文档（`source.ip`、`event.action`、`@timestamp`、原始有效载荷在 `event.original` 中） | API 密钥 → `Authorization: ApiKey <key>` | | `cef` | ArcSight CEF 行（与 QRadar Universal CEF Connector 兼容） | — | | `syslog` | RFC 5424；URL 方案选择传输（`udp://host:514` 或 `tcp://host:514`） | — | | `loki` | Loki 推送 API，字符串化为 ns 时间戳 | 预编码的 `base64(userid:token)` → `Authorization: Basic` | | `datadog` | 日志 API v2 列表 | API 密钥 → `DD-API-KEY` | 示例 — Splunk： ```text > alert_subscribe( url="https://splunk.example.com:8088/services/collector/event", label="splunk-prod", severity_threshold="medium", hmac_secret="<your-HEC-token>", format="splunk_hec" ) ``` 相同的格式适用于每种格式 — 交换 `url`、`format` 和凭证。对于 Slack / Discord / PagerDuty / SOAR 平台，请使用默认的 `json` 格式；传递 `hmac_secret=""` 会自动生成并返回一个 32 字节的签名密钥。您可以在任何时候通过 `alert_subscriptions_list` （`delivery_count`、`failure_count`、`last_error` 每订阅）检查交付健康状况。 注意： - **Syslog** 使用设施 16（`local0`）；严重性映射 CRITICAL→2，HIGH→3，MEDIUM→4，LOW→6。MSG 正文为 JSON，因此 SIEM 仍然可以获取结构化字段。 - **Loki** 流标签携带 `severity`、`event_type`、`source_ip`、`job=honeypot-mcp`。自托管的 Loki 忽略身份验证头。 - **Datadog** 区域端点（EU/AP1）工作相同 — 交换 URL 前缀。 --- ## Docker 栈 + Grafana 演示 查看整个系统的最快方法 — 一个一体化演示栈（服务器 + 静态诱饵系统 + Prometheus + Grafana）： ```bash cd docker docker compose up -d --build # 种子 ~5,000 个现实的演示攻击事件，历时 24 小时 docker compose exec honeypot-mcp python scripts/seed_demo_data.py # Grafana: admin / honeypot （覆盖 GRAFANA_ADMIN_PASSWORD） open http://localhost:3000 ``` 三个预先配置的仪表盘：**概览**（严重性堆栈、顶级攻击者）、**威胁地图**（地理位置的攻击者 IP）、**MITRE ATT&CK 覆盖**。种子脚本在 24 小时内传播事件跨越现实的源国，因此地图立即亮起。 > 此一体化 `docker-compose.yml` 文件用于演示和仪表盘。对于**公共部署**，由自然语言驱动的服务器作为持久守护进程运行在主机上，并使用 `docker-compose.observability.yml` 仅用于 Grafana + Prometheus，而非守护进程的数据 — 参见 [docs/DEPLOY.md](docs/DEPLOY.md)。 | 服务 | 目的 | 端口 | |---|---|---| | `honeypot-mcp` | MCP 服务器，canary 回调，`/metrics` | 8888 (canary)，9090 (metrics, localhost) | | `socket-proxy` | 限制 Docker API — MCP 容器在不暴露主机套接字的情况下管理 Cowrie | 内部 | | `cowrie-ssh` / `http-honeypot` | 诱饵系统 | 2222 / 8080 | | `prometheus` / `grafana` | 指标 + 仪表盘 | 9091 (localhost) / 3000 | Grafana 以只读方式读取 SQLite 警报数据库，而服务器写入（WAL 模式使此操作安全）。 --- ## 云诱饵令牌检测（可选） 生成的 AWS / Azure / GCP 凭证令牌仅在云审计日志转发到canary服务器的 `/cloud-event` 端点（HMAC签名）时触发： ```bash # .env CLOUD_EVENT_HMAC_SECRET=$(openssl rand -hex 32) ``` 可部署的转发器位于 [`examples/cloud-forwarders/`](examples/cloud-forwarders/)：AWS（Lambda + Terraform + EventBridge）、Azure（Function App + Bicep）、GCP（Cloud Function + Log Sink via `deploy.sh`）。每个都有自己的README。当攻击者使用植入的凭证时，生成的CloudTrail / Activity Log / Audit Log事件通过转发器路由并触发关键警报。 如果没有转发器，云凭证令牌就是令人信服的诱饵，没有回调 — 参见 [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md). --- ## 日常操作 ```text > alerts_recent severity=high # 快速分类 > analyze_attacker_journey ip=1.2.3.4 # 跨诱饵系统时间线 > enrich_ip 1.2.3.4 # VT + AbuseIPDB + GeoIP > generate_report format=markdown # 每周报告 > export_blocklist format=iptables hits=10 # 针对 top 攻击者的防火墙规则 > alerts_prune older_than_days=30 # 一次性修剪（或为自动设置 RETENTION_DAYS） ``` 进入生产环境：用 PostgreSQL 替换 `DATABASE_URL`（无需代码更改），将 `CANARY_PUBLIC_URL` 指向公共地址（ngrok / Cloudflare Tunnel / 真实域名），加载已知扫描器的抑制预设，在上线前启动，设置 `RETENTION_DAYS` 以使数据库保持有界，并订阅一个关键阈值的网络钩子，以便您看到 `honeypot_health_failed` 看门狗警报。完整的演练： [docs/DEPLOY.md](docs/DEPLOY.md). --- ## 开发 ```bash uv run pytest tests/unit/ -v # 317 测试 uv run ruff check src/ tests/ uv run mypy src/ ``` **模式迁移** 由 Alembic 管理；服务器在启动时运行 `alembic upgrade head`。更改模型后： ```bash uv run alembic revision --autogenerate -m "what changed" # 检查生成的 文件，然后它会在下次启动时自动应用 ``` ### 项目结构 ``` src/honeypot_mcp/ ├── server.py — FastMCP 应用程序、生命周期、MCP 资源 ├── canary.py — 回调服务器：canary URLs、PDF 跟踪器、/cloud-event ├── webhooks.py — 外发 SIEM/网络钩子交付工作程序（HMAC、重试） ├── suppression.py — 丢弃/速率限制规则引擎 ├── credential_match.py — 植入凭证交叉引用（自动关键） ├── credential_verify.py — 哈希认证（MySQL 混淆、VNC DES） ├── watchdog.py — 周期性健康检查 + 可选保留扫描 ├── reconcile.py — 在服务器重启时重新建立 RUNNING 诱饵系统 ├── engines/ — 诱饵系统引擎（插件 ABC：HoneypotEngine） ├── tokens/ — 诱饵令牌提供者（插件 ABC：HoneytokenProvider） ├── storage/ — 模型、异步数据库层、批量事件缓冲区 ├── intel/ — VirusTotal、AbuseIPDB、GeoIP、MITRE（TTL 缓存） ├── analysis/ — 相关性、分析器、Jinja2 报告 ├── tools/ — MCP 工具模块 └── migrations/ — Alembic 版本 ``` 架构细节（事件管道、角色系统、插件模式）记录在 [CLAUDE.md](CLAUDE.md). --- ## 这是什么 / 不是什么 **合适的应用场景：** SOC 研究和培训实验室、内部诱饵系统、 小型到中型 SOC 警报管道，以及在公共 IP 上捕获互联网规模的自动化攻击流量。引擎捕获真实的攻击工件 — Redis RCE 投递链（攻击者的 SSH 密钥 + 目标路径）、FTP 恶意软件上传（哈希 + 分类）、MySQL `INTO OUTFILE` web shell 丢弃、SMB EternalBlue/DoublePulsar 探测、MongoDB 勒索软件笔记 — 丰富（地理位置、ASN、反向 DNS、VT/AbuseIPDB 声誉）并发送到您的 SIEM。 **不适合直接应用：** 通过手动探测来欺骗熟练的人。SSH 是 Cowrie（高保真）；自定义协议引擎专注于检测而不是完整的协议栈，因此手动专家可以最终指纹识别它们。对于跨更多协议的最大保真欺骗，请参阅 [T-Pot](https://github.com/telekom-security/tpotce)、[OpenCanary](https://github.com/thinkst/opencanary) 或 [Thinkst Canary](https://canary.tools/)。 完整的诚实总结在 [KNOWN_LIMITATIONS.md](KNOWN_LIMITATIONS.md). --- ## 许可证 在 [MIT 许可证](LICENSE) 下发布。