redhoundinfosec/honeytrap-ai
GitHub: redhoundinfosec/honeytrap-ai
一款 AI 驱动的跨平台蜜罐框架，通过模拟多种不安全网络设备吸引并分析攻击者行为。
Stars: 0 | Forks: 0
# 🍯 HoneyTrap AI
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/downloads/)
[](https://github.com/redhoundinfosec/honeytrap-ai/actions/workflows/ci.yml)
[](https://github.com/redhoundinfosec/honeytrap-ai)
**AI 驱动的跨平台蜜罐框架**，通过模拟不安全的网络设备来吸引、交互并分析攻击者。在 Linux 和 Windows 上运行表现完全一致，使用基于 LLM 的动态响应以根据攻击者来源进行调整，并提供实时终端仪表盘和自动生成的攻击报告。
## ✨ 特性
- 🌐 **多协议蜜罐** — HTTP, SSH, FTP, SMB（以及可选的 SMTP, Telnet, MySQL）
- 🤖 **AI 驱动响应** — 基于规则的引擎 + 可选 LLM（OpenAI / Ollama / 自定义 endpoint）
- 🗺️ **地理感知角色** — 攻击者根据其来源国家看到不同的服务器角色设定
- 📊 **实时终端仪表盘** — 基于 Rich/Textual 构建，实时连接可视化
- 📈 **自动化报告** — 头号攻击者、凭据分析、地理分布、新型模式
- 💾 **智能日志管理** — 分级保留、轮换、GZIP 压缩、SQLite 持久化
- 🔌 **零配置启动** — 交互式 CLI 菜单：选择一个设备配置文件，开始监听
- 🛡️ **跨平台** — 在 Linux、Windows、macOS (Python 3.10+) 上行为一致
- 🧱 **插件式设备配置** — YAML 定义的设备类型，轻松添加新配置
## 🚀 快速开始
```
# 安装
pip install honeytrap-ai
# 或者从源码安装
git clone https://github.com/redhoundinfosec/honeytrap-ai
cd honeytrap-ai
pip install -e .
# 运行交互式设置
honeytrap
```
### 示例会话
```
🍯 HoneyTrap AI v0.1.0
──────────────────────────
What device would you like to simulate?
[1] 🌐 Web Server — Apache with exposed admin panels (HTTP/SSH)
[2] 📁 File Share — NAS with open SMB shares (SMB/FTP)
[3] 📷 IoT Camera — IP camera with default creds (HTTP/Telnet)
[4] 🗄️ Database Server — MySQL with phpMyAdmin (MySQL/HTTP/SSH)
[5] 📧 Mail Server — Open relay mail server (SMTP/POP3/IMAP)
[6] 🔧 Custom — Load a custom profile YAML
Select [1-6]: 1
AI Response Engine:
[1] Offline (rule-based only)
[2] OpenAI API
[3] Ollama (local LLM)
[4] Custom endpoint
Select [1-4]: 1
✓ Starting Web Server honeypot on 0.0.0.0
✓ HTTP listener on :80
✓ SSH listener on :22
✓ GeoIP resolver ready
✓ Dashboard starting...
```
### 仪表盘模型
```
╔══════════════════════════════════════════════════════════════════╗
║ 🍯 HoneyTrap AI — Live Dashboard Profile: web_server ║
╠══════════════════════════════════════════════════════════════════╣
║ ACTIVE CONNECTIONS (3) STATS (last 24h) ║
║ ┌──────────────────────────┐ ┌────────────────────────┐ ║
║ │ 185.220.101.4 (DE) → :80│ │ Total connections: 847 │ ║
║ │ 45.134.26.11 (RU) → :22 │ │ Unique IPs: 234 │ ║
║ │ 103.89.91.2 (CN) → :445 │ │ Brute force: 156 │ ║
║ └──────────────────────────┘ └────────────────────────┘ ║
║ ║
║ LIVE EVENT LOG ║
║ 23:41:02 [HTTP ] 185.220.101.4 GET /wp-login.php ║
║ 23:41:01 [SSH ] 45.134.26.11 AUTH root:admin123 ║
║ 23:40:58 [SMB ] 103.89.91.2 LIST \\Finance ║
╚══════════════════════════════════════════════════════════════════╝
[Q]uit [R]eport [P]ause [F]ilter [E]xport
```
### 仪表盘模式
使用 ``--dashboard-mode`` 选择一种仪表盘风格：
| 模式 | 描述 |
| -------- | ---------------------------------------------------------------------------------------- |
| ``textual`` | 带有筛选、搜索、暂停、会话详情模态框的全屏 Textual TUI（默认）。 |
| ``rich`` | 旧版 Rich Live 仪表盘（单滚动面板）。 |
| ``none`` | 无头模式 — 没有 UI，仅包含监听器和日志。 |
如果选择了 ``textual`` 但未安装相关依赖，CLI
将回退到 ``rich`` 并发出警告。
### Textual TUI 键盘快捷键
| 按键 | 动作 |
| --------- | -------------------------------------------------------- |
| ``q`` | 退出 |
| ``f`` | 切换事件日志筛选（全部 / HTTP / SSH / FTP / SMB / Telnet / SMTP / MySQL） |
| ``s`` 或 ``/`` | 打开事件日志的子字符串搜索 |
| ``r`` | 生成报告（终端 + HTML）并显示提示 |
| ``p`` | 暂停 / 恢复实时更新（蜜罐继续运行） |
| ``tab`` / ``shift+tab`` | 在面板之间循环切换焦点 |
| ``enter`` | 打开所选连接的会话详情模态框 |
| ``escape``| 关闭会话详情模态框或隐藏搜索栏 |
## 📦 安装
### 最小化安装（仅限基于规则的引擎）
```
pip install honeytrap-ai
```
### 包含可选附加组件
```
# 添加 LLM 集成
pip install "honeytrap-ai[ai]"
# 添加 MaxMind GeoIP 支持
pip install "honeytrap-ai[geo]"
# 通过 impacket 添加 SMB
pip install "honeytrap-ai[smb]"
# 全部
pip install "honeytrap-ai[full]"
```
### 平台说明
- **Linux**: 低于 1024 的端口需要 root 权限或 `cap_net_bind_service`。如果绑定失败，CLI 会建议备选的高端口。
- **Windows**: 以管理员身份运行以使用低端口号，或者接受自动建议的高端口号回退（HTTP=8080, SSH=2222, FTP=2121, SMB=4450）。
- **macOS**: 与 Linux 相同。
## 🧩 设备配置文件
内置了五个配置文件；它们都是普通的 YAML 文件，您可以编辑或克隆它们。
| 配置文件 | 服务 | 描述 |
|---|---|---|
| `web_server` | HTTP (80), SSH (22) | 存在路径遍历漏洞的 Apache，暴露了管理面板 |
| `file_share` | SMB (445), FTP (21) | 具有开放共享和弱密码的 NAS 设备 |
| `iot_camera` | HTTP (8080), Telnet (23) | 使用默认凭据的 IP 摄像头 |
| `database_server` | MySQL (3306), HTTP (80) | 暴露了 phpMyAdmin 的 MySQL 数据库 |
| `mail_server` | SMTP (25) | 配置不当的开放中继邮件服务器 |
创建您自己的配置文件：复制 `profiles/` 中的任意 YAML 文件，并使用选项 `[6] Custom` 加载它。
## 🗺️ 地理感知响应
系统可以解析攻击者来源（通过 ip-api.com 免费层或本地 MaxMind 数据库），并根据其国家/地区呈现不同的服务器角色设定。这有助于研究攻击者行为的变化：
| 来源 | 角色 | 示例内容 |
|---|---|---|
| 俄罗斯 | 俄罗斯 SMB | ООО "ТехноГрупп"，西里尔文文件名 |
| 中国 | 中国企业 | 华信科技有限公司，zh-CN 区域设置 |
| 美国 | 美国初创企业 | TechNova Inc.，en-US 区域设置 |
| 德国 | 德国工业 | Müller Maschinenbau GmbH |
| 默认 | 美国初创企业 | TechNova Inc. |
在 `honeytrap.yaml` 中使用 `geo.vary_responses: true` 进行切换。
## 📊 报告
可随时生成终端或 HTML 报告：
```
honeytrap report --format html --out report.html
honeytrap report --format terminal
```
报告包含：执行摘要、头号攻击者、地理分布、凭据分析、攻击模式、新型/标记行为、地理响应对比以及时间轴。
## 📦 部署
HoneyTrap AI 为 Docker、Docker Compose、Helm、原始 Kubernetes 和
systemd 提供了相应的配置方案（位于 `deploy/` 目录下）。所有目标均暴露一个小型的健康检查接口
（`/healthz`、`/readyz`、`/metrics`），默认绑定到回环
接口 — 如果您希望它在外部可被访问（在 pod 或容器之外），请谨慎覆盖 `--health-host`。
### 健康检查与指标端点
| 路径 | 用途 |
| ---------- | ----------------------------------------------------------------------- |
| `/healthz` | 存活状态。只要进程存在就始终返回 200。返回 JSON 载荷。 |
| `/readyz` | 就绪状态。只要资源守护进程未拒绝连接就返回 200。 |
| `/metrics` | 连接/事件计数器和仪表的 Prometheus 文本格式输出。 |
CLI 标志：`--health-host`（默认 `127.0.0.1`）、`--health-port`（默认
`9200`）、`--health-disabled` 用于完全关闭此服务器。
### Docker
```
docker build -t honeytrap-ai:local .
docker run --rm -p 127.0.0.1:9200:9200 -p 127.0.0.1:8080:80 \
honeytrap-ai:local --profile web_server --dashboard-mode none --health-host 0.0.0.0
```
运行时镜像基于 `python:3.12-slim` 构建，包含非 root
`honeytrap` (UID 10001) 用户，并内置了请求
`/healthz` 的 HEALTHCHECK。最终镜像大小预计在 240-280 MB 左右。
### Docker Compose
```
docker compose -f deploy/docker-compose.yml up -d
# 可选：使用内置的 Prometheus 容器抓取 /metrics
docker compose -f deploy/docker-compose.yml --profile with-prometheus up -d
```
所有蜜罐端口默认发布在 `127.0.0.1`，因此在您
选择绑定到 `0.0.0.0` 之前，不会向外部暴露任何内容。
### Kubernetes (Helm)
```
helm install ht ./deploy/helm/honeytrap-ai -f my-values.yaml
```
内置了用于 Prometheus Operator 的 `ServiceMonitor` 和可选的
`NetworkPolicy`。Pod 在运行时使用 `runAsNonRoot`、只读的根
文件系统以及 `capabilities.drop: [ALL]`。
### Kubernetes (原始清单)
```
kubectl apply -k deploy/k8s
```
### systemd
```
sudo ./deploy/systemd/install.sh
sudo systemctl status honeytrap.service
```
该单元通过 `ProtectSystem=strict`、
`MemoryDenyWriteExecute=yes`、系统调用过滤器和严格的
`ReadWritePaths` 进行了加固。绑定到特权端口需要取消注释
`AmbientCapabilities=CAP_NET_BIND_SERVICE`。
## 🚨 告警
HoneyTrap AI 可以在发生有趣事件（暴力破解爆发、默认凭据命中、
Shell 执行、已知的恶意 IOC、关键 ATT&CK 技术等）时，
将结构化告警推送到运维工具。告警是插件化的，按通道进行速率限制，并遵循
最低严重级别阈值。
### 支持的通道
| 通道 | 传输方式 | 备注 |
|-------------------|--------------------|----------------------------------------------------------|
| Slack | Incoming webhook | 富文本块 + 按严重性着色的附件 |
| Discord | Incoming webhook | 带有严重性颜色的 Embed |
| Microsoft Teams | Incoming webhook | MessageCard JSON |
| 通用 Webhook | HTTPS POST | 可选的 HMAC-SHA256 `X-HoneyTrap-Signature` 请求头 |
| Email (SMTP) | SMTP + STARTTLS | 多部分文本 + HTML，可配置的发件人/收件人地址 |
### 配置
在您的 `honeytrap.yaml` 或配置文件中启用告警。密钥
应通过 `*_env` 键从环境变量中获取，这样它们就
永远不会被提交：
```
alerts:
enabled: true
min_severity: medium # info|low|medium|high|critical
dry_run: false # log payloads instead of sending
channels:
- type: slack
name: soc-slack
webhook_url_env: HONEYTRAP_SLACK_WEBHOOK_URL
min_severity: high
rate_limit_per_minute: 20
- type: webhook
name: siem
url_env: HONEYTRAP_WEBHOOK_URL
secret_env: HONEYTRAP_WEBHOOK_SECRET
headers: { X-Env: prod }
- type: email
smtp_host: smtp.example.com
smtp_port: 587
from_addr: honeytrap@example.com
to_addrs: [soc@example.com]
username_env: HONEYTRAP_SMTP_USER
password_env: HONEYTRAP_SMTP_PASS
starttls: true
```
### 环境变量
将 `.env.example` 复制到 `.env` 并填写您实际
使用的端点：
```
HONEYTRAP_SLACK_WEBHOOK_URL=
HONEYTRAP_DISCORD_WEBHOOK_URL=
HONEYTRAP_TEAMS_WEBHOOK_URL=
HONEYTRAP_WEBHOOK_URL=
HONEYTRAP_WEBHOOK_SECRET=
HONEYTRAP_SMTP_USER=
HONEYTRAP_SMTP_PASS=
```
### CLI 标志
```
--alerts-enabled / --no-alerts override alerts.enabled
--alerts-min-severity {info,low,medium,high,critical}
--alerts-dry-run log payloads instead of POSTing
```
### 安全
- 通道密钥**仅**从环境变量中读取。缺少环境变量会导致发出警告并跳过
该通道 — 绝不会引发崩溃。
- 当提供 `secret_env` 时，通用 Webhook 通道会使用 HMAC-SHA256 签名
JSON 主体；接收端需验证
`X-HoneyTrap-Signature: sha256=`。
- HTTP 投递在遇到 5xx / 网络错误时，会使用指数
退避（0.5s、1s、2s）进行重试，并遵循 `Retry-After`。4xx 响应
**不会**被重试。
- 每个通道的令牌桶速率限制（默认 20次/分钟）可防止
嘈杂事件淹没通道。
- 投递并发运行；一个失败的通道永远不会阻塞
其他通道。
### 指标
在 `/metrics` 上暴露了两个 Prometheus 计数器：
- `honeytrap_alerts_sent_total{channel,severity}`
- `honeytrap_alerts_dropped_total{reason}` — `reason` 包含
`rate-limited`、`below-min-severity`、`no-channels` 或 `error`。
## 🕵 TLS 指纹识别 (JA3 / JA4)
HoneyTrap 从第一个 TLS ClientHello 识别攻击者工具，
**在任何握手完成之前**。处理流程如下：
```
+-------------+ peek 16 KB +----------------+
| TCP listener|--------------->| tls_peek helper|
+-------------+ +-------+--------+
|
v
+---------+----------+
| ClientHello parser |
+------+------+------+
| |
v v
JA3 JA4
| |
v v
+----------------------+
| FingerprintDatabase | <- bundled YAML
+----------+-----------+ (33+ entries)
|
v
ATT&CK mapping - alerts - IOC SNI - Prom metrics - reports
```
目前支持的指纹（**内置 33 种**）：curl、Python requests /
urllib3 / aiohttp、Go net/http、OpenSSL、nmap、masscan、zgrab2、
Firefox、Chrome、Safari、wget、Java HttpClient、Node.js、Cobalt
Strike Beacon、Metasploit Meterpreter、sqlmap、Burp Suite、Empire、
Havoc、Sliver、Merlin、Mirai/Mozi 变种等等。
### CLI 标志
- `--tls-fingerprint-db PATH` — 在内置数据库之上
叠加一个自定义 YAML。
- `--disable-tls-fingerprinting` — 完全关闭此子系统。
### YAML 条目格式
```
fingerprints:
- name: "Cobalt Strike Malleable C2 (default)"
category: malware # scanner | library | browser |
# malware | pentest_tool | bot | unknown
confidence: high # high | medium | low
ja3: "72a589da586844d7f0818ce684948eea"
ja4: "t13d1516h2_8daaf6152771_e5627efa2ab1" # optional
references:
- "https://www.cobaltstrike.com/"
```
### Prometheus 指标
- `honeytrap_tls_fingerprint_total{ja3_hash,category,name}` — 上限为
前 100 个 JA3；超出部分折叠为
`ja3_hash="other",name="other"`。
## 🎬 取证与回放
每个攻击者会话都会被逐字节捕获，并可以回放、
搜索，或导出为 PCAP 供下游取证工具使用。
记录器是被动的 — 如果被禁用或在资源压力下，它会静默丢弃帧而不影响引擎。完整操作指南请参阅
[`docs/forensics.md`](docs/forensics.md)。
```
forensics:
enabled: true
store: jsonl # jsonl | sqlite
path: ./sessions
max_session_bytes: 10485760 # 10 MiB per session
max_daily_bytes: 1073741824 # 1 GiB per day
retention_days: 30
record_tls_handshake: true
```
### 从 CLI 导出
```
honeytrap export list
honeytrap export pcap --session ssh-7c1a8b --out cap.pcap
honeytrap export jsonl --session ssh-7c1a8b --out cap.jsonl.gz
honeytrap export timeline --session ssh-7c1a8b
honeytrap export pcap --ip 198.51.100.7 --since 2026-04-22T00:00:00Z --out campaign.pcap
```
### 在 TUI 中回放
打开仪表盘，在会话行上按 Enter 键，然后切换到
Replay 标签页：
| 按键 | 动作 |
|---------|-----------------------------|
| `space` | 播放 / 暂停 |
| `right` | 快进一帧 |
| `left` | 后退一帧 |
| `>` | 提高播放速度 |
| `<` | 降低播放速度 |
| `e` | 将会话导出为 PC |
| `E` | 将会话导出为 JSONL |
速度在 `0.25x, 0.5x, 1.0x, 2.0x, 4.0x, 8.0x` 之间循环。
### PCAP-lite
PCAP 写入器生成有效的 libpcap 捕获文件（特征值 `0xa1b2c3d4`，
以太网链路类型 `1`），可在 Wireshark 和 `tshark` 中正常打开。
由于引擎看到的是应用层帧，写入器
合成了缺失的传输层：一个 SYN / SYN-ACK / ACK 握手，
具有单调递增序列号的 MSS 大小 TCP 报文段，正确的
二进制反码校验和、IPv4 *和* IPv6，以及 FIN / ACK 拆解。
IDS 规则和内容提取可像在真实捕获中一样工作；但不支持 RTT 或
重传分析。
### Prometheus 指标
- `honeytrap_sessions_recorded_total{protocol}`
- `honeytrap_sessions_truncated_total{reason}`
- `honeytrap_session_bytes_total{protocol,direction}`
- `honeytrap_pcap_exports_total`
- `honeytrap_session_duration_seconds` (histogram)
## 🧪 开发
```
git clone https://github.com/redhoundinfosec/honeytrap-ai
cd honeytrap-ai
pip install -e ".[dev,full]"
pytest
ruff check .
```
## 🔒 安全
蜜罐应运行在**隔离的网络**或**专用的云虚拟机**上。有关负责任的部署指南和披露政策，请参阅 [SECURITY.md](SECURITY.md)。
## 🤝 贡献
欢迎贡献 — 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 📜 许可证
MIT — 请参阅 [LICENSE](LICENSE)。
由 [redhoundinfosec](https://github.com/redhoundinfosec) 维护 · 由 [@jph4cks](https://github.com/jph4cks) 构建
标签：AI风险缓解, CISA项目, DLL 劫持, FTP蜜罐, HTTP蜜罐, IP 地址批量处理, MySQL蜜罐, OISF, PE 加载器, Python, SMB蜜罐, SMTP蜜罐, SQLite, SSH蜜罐, Telnet蜜罐, YAML配置, 人工智能, 凭证分析, 动态响应, 地理感知, 大语言模型, 威胁情报, 子域名突变, 开发者工具, 插件系统, 攻击者画像, 攻防研究, 无后门, 无控制台执行, 日志管理, 用户模式Hook绕过, 终端仪表盘, 网络安全, 网络设备模拟, 自动化报告, 自定义请求头, 蜜罐框架, 请求拦截, 进程注入, 连接可视化, 逆向工具, 隐私保护, 零配置