PhantomTrap
具备行为指纹识别、攻击活动检测和实时仪表板的高交互蜜罐框架。
## 概述
PhantomTrap 部署了逼真的 SSH、HTTP 和 MySQL 蜜罐，旨在与真实服务毫无区别。它捕获攻击者会话，关联跨服务的活动，识别已知的攻击工具，并通过实时 Web 仪表板呈现所有内容。
**核心功能：**
- **反指纹识别** — 跨所有服务保持一致的系统身份（内核、主机名、用户、/proc）。攻击者通过 SSH 执行 `uname -a` 获取的内核信息，将与 HTTP `phpinfo()` 和 MySQL `@@version_comment` 中显示的一致。
- **行为分析** — 命令执行时间分类（自动化与人类操作）、n-gram 指纹识别、凭据模式检测（字典攻击、撞库、定向攻击）。
- **攻击活动检测** — 通过共享的凭据列表和命令序列进行跨 IP 关联。识别来自僵尸网络和扫描活动的协同攻击。
- **C2 识别** — 对 Cobalt Strike、Metasploit、Empire、Mirai 及其他框架进行签名匹配。
- **实时仪表板** — 基于 WebSocket 的单页应用（SPA），提供实时攻击流、会话深入分析、攻击者画像和攻击活动时间线。
## 架构
```
┌──────────────────────────┐
│ HoneypotManager │
│ (core/manager.py) │
│ │
│ SystemProfile │
│ RateLimiter │
│ SessionDatabase │
│ ThreatAnalyzer │
│ SessionCorrelator │
│ BehavioralFingerprinter │
└────┬────┬────┬────┬──────┘
│ │ │ │
┌──────────────┘ │ │ └──────────────┐
▼ ▼ ▼ ▼
┌─────────────┐ ┌────────────┐ ┌─────────────┐ ┌───────────┐
│ SSH :22 │ │ HTTP :80 │ │ MySQL :3306 │ │ Dashboard │
│ asyncssh │ │ aiohttp │ │ raw TCP │ │ :8080 │
└─────────────┘ └────────────┘ └─────────────┘ └───────────┘
```
## 快速开始
```
# Clone 仓库
git clone https://github.com/SP1R4/PhantomTrap.git
cd PhantomTrap
# 创建虚拟环境
python3 -m venv .venv
source .venv/bin/activate
# 安装依赖
pip install -r requirements.txt
# 创建数据目录
mkdir -p data/{malware,signatures,sessions,logs}
# 生成 SSH host key（SSH honeypot 必需）
ssh-keygen -t rsa -b 2048 -f data/ssh_host_key -N ""
# 运行
sudo python3 core/manager.py
```
仪表板将通过 `http://127.0.0.1:8080` 访问（默认凭据：`admin` / `changeme123`）。
## 配置
所有设置均位于 `config/honeypot_config.json` 中。主要部分：
### 服务
```
{
"honeypots": [
{"type": "ssh", "port": 22, "enabled": true, "accept_after_failures": 3},
{"type": "http", "port": 80, "enabled": false, "personality": "apache"},
{"type": "mysql", "port": 3306, "enabled": false}
]
}
```
HTTP 蜜罐支持 `apache`、`nginx` 和 `iis` 个性化配置。所有的 header、错误页面和默认页面均与所选的服务器类型相匹配。
### 告警
```
{
"alerts": {
"min_threat_level": 3,
"channels": {
"console": {"enabled": true},
"file": {"enabled": true, "path": "data/alerts.log"},
"email": {"enabled": false, "smtp_server": "smtp.gmail.com", "...": "..."},
"telegram": {"enabled": false, "bot_token": "...", "chat_id": "..."},
"webhook": {"enabled": false, "url": "https://..."}
}
}
}
```
### 仪表板
```
{
"dashboard": {
"enabled": true,
"port": 8080,
"bind_address": "127.0.0.1",
"username": "admin",
"password": "changeme123"
}
}
```
## 项目结构
```
.
├── core/
│ ├── manager.py # Main orchestrator
│ ├── database.py # SQLite session storage (async)
│ ├── system_profile.py # Consistent randomized system identity
│ └── rate_limiter.py # Per-IP sliding window rate limiter
│
├── honeypots/
│ ├── ssh_honeypot.py # SSH — 30+ commands, pipes, redirects, shell chaining
│ ├── http_honeypot.py # HTTP — server personalities, session cookies, stateful login
│ ├── mysql_honeypot.py # MySQL — extended protocol, SHOW responses, error codes
│ └── fake_filesystem.py # In-memory Ubuntu 22.04 filesystem (~500 files)
│
├── analysis/
│ ├── threat_analyzer.py # 35+ malicious patterns, C2 detection, advanced scoring
│ ├── correlator.py # Cross-session IP correlation, campaign clustering
│ ├── behavioral.py # Timing analysis, n-gram fingerprinting, tool identification
│ ├── c2_patterns.py # Cobalt Strike, Metasploit, Empire, Mirai signatures
│ ├── signature_gen.py # YARA rule generation
│ ├── alert_system.py # Multi-channel alerting
│ └── intelligence.py # GeoIP, IP reputation
│
├── dashboard/
│ ├── server.py # REST API + WebSocket server
│ └── static/ # SPA frontend (HTML/CSS/JS, no build step)
│
├── config/
│ └── honeypot_config.json # Main configuration
│
├── tests/ # 158 tests (pytest)
├── requirements.txt # runtime dependencies
├── requirements-dev.txt # + test/lint tooling
├── Dockerfile
└── LICENSE
```
## 蜜罐详情
### SSH 蜜罐
- 包含 30 多个命令（`ls`、`cat`、`wget`、`curl`、`ps`、`netstat`、`df`、`free`、`top`、`ifconfig`、`find`、`grep` 等）的交互式 shell
- Shell 特性：管道符（`|`）、重定向（`>`、`>>`）、链式命令（`&&`、`||`、`;`）、环境变量、命令替换
- 逼真的 `/proc` 文件系统（cpuinfo、meminfo、uptime —— 均派生自 SystemProfile）
- 包含 21 个用户的 `/etc/passwd`，一致的 `/etc/hostname`、`/etc/os-release`
- `.bash_history` 随攻击者的命令动态增长
- 可配置的凭据接收（`credentials` 列表），并提供“失败 N 次后接收”的诱导机制（`accept_after_failures`）
- 可选的实时 payload 捕获：当设置 `fetch_downloads: true` 时，如果使用 `wget`/`curl`
获取 URL，蜜罐主机会获取并存储该文件（以 SHA256 命名，存储于
`data/malware/`），并将其输入到 YARA/告警 pipeline 中。**默认关闭** —— 因为这会
发出出站请求，所以仅建议在严格的出站流量控制下启用。
受 `max_download_bytes` 和 `download_timeout` 限制。
### HTTP 蜜罐
- 服务器个性化系统（Apache/nginx/IIS） —— header、错误页面和默认页面全部匹配
- 攻击路径响应：`/wp-admin`、`/.env`、`/.git/HEAD`、`/phpinfo.php`、`/phpmyadmin`、`/actuator`、`/api/`
- 会话 cookie（`PHPSESSID`）及有状态的登录流程
- 动态 header：`ETag`、`Last-Modified`、`X-Request-ID`、`Cache-Control`
- 模拟真实服务器响应时间的时序差异
### MySQL 蜜罐
- MySQL 线协议（wire protocol）实现，支持 8 个 COM_* 命令
- `SHOW DATABASES`、`SHOW TABLES`、`SHOW ENGINES`、`SHOW VARIABLES`、`SHOW STATUS`、`SHOW PROCESSLIST`
- 各个数据库的表结构（webapp、customers、mysql、information_schema、performance_schema）
- 针对伪造数据的 `SELECT` 查询，以及 `information_schema` 查询
- 符合规范的 MySQL 错误代码（1064、1146、1049）及 SQL 状态
- 递增的连接 ID
## 分析 Pipeline
每个会话都会经过以下处理：
1. **威胁分析器** — 针对 35 个以上的指标进行模式匹配（反弹 shell、下载器、提权、横向移动、容器逃逸、编码 payload）
2. **会话关联器** — 关联来自同一 IP 的会话，通过共享的凭据和命令指纹检测攻击活动
3. **行为指纹识别器** — 对时序进行分类（自动化/人类操作）、分析凭据策略（字典/撞库/定向攻击），并识别工具（Mirai、挖矿木马、人工操作者）
4. **C2 检测器** — 与已知的 C2 框架签名进行匹配
5. **数据库** — 所有数据持久化存储到 SQLite，用于仪表板查询和历史分析
## 测试
```
source .venv/bin/activate
pip install -r requirements-dev.txt
python -m pytest tests/ -v
```
```
158 passed
```
CI 会在 Python 3.9–3.12 环境下运行测试套件，并在每次
push 和 pull request 时使用 `black` 检查代码格式（`.github/workflows/ci.yml`）。
| 测试套件 | 测试数 | 覆盖范围 |
|------------------------|-------|--------------------------------------------------|
| test_behavioral.py | 18 | 时序、n-gram、凭据模式、工具识别 |
| test_correlator.py | 8 | IP 关联、攻击活动检测 |
| test_dashboard.py | 19 | API endpoint、身份验证、WebSocket、分页 |
| test_database.py | 15 | 会话 CRUD、画像、攻击活动、统计、告警 |
| test_fake_filesystem.py| 25 | /proc、ls、通配符、路径、文件操作、内容 |
| test_http_honeypot.py | 19 | 路由、cookie、header、个性化配置 |
| test_mysql_honeypot.py | 18 | 协议、COM_PING、SHOW、错误、连接 ID |
| test_rate_limiter.py | 6 | 基于 IP 的限制、全局泛洪上限、重置 |
| test_ssh_auth.py | 5 | 凭据接收、失败后接收机制 |
| test_threat_analyzer.py| 15 | 模式匹配、分类、评分 |
## 部署
### Docker
```
# 构建
docker build -t phantomtrap .
# 运行 — 映射 honeypot 端口并保持 dashboard 为本地访问。
# 容器以 non-root 用户运行；-p 映射 host 端口无需 host root 权限。
docker run -d --name phantomtrap \
-p 22:22 \
-p 127.0.0.1:8080:8080 \
-v phantomtrap-data:/opt/phantomtrap/data \
phantomtrap
```
捕获的会话、恶意软件和签名将持久化存储在 `phantomtrap-data`
数据卷中。为了实现安全隔离，请将其运行在隔离的网络中并限制出站流量（见
下文的网络建议） —— 如果您启用了 SSH
下载捕获功能，这一点尤为重要。
### Systemd（生产环境）
```
# /etc/systemd/system/phantomtrap.service
[Unit]
Description=PhantomTrap Honeypot
After=network.target
[Service]
Type=simple
User=root
WorkingDirectory=/opt/phantomtrap
ExecStart=/opt/phantomtrap/.venv/bin/python3 core/manager.py
Restart=always
RestartSec=5
[Install]
WantedBy=multi-user.target
```
```
sudo systemctl enable phantomtrap
sudo systemctl start phantomtrap
```
### 网络建议
- 部署在专用的虚拟机或隔离的 VLAN 上
- 仅允许入站到蜜罐端口的流量
- 阻止或限制出站流量（DNS、NTP、告警除外）
- 将仪表板绑定到 `127.0.0.1`，并通过 SSH 隧道访问
## 法律声明
**仅用于授权的安全研究和网络防御。** 请仅在您拥有或已获得明确书面授权进行监控的基础设施上进行部署。确保采取适当的隔离措施，以防止蜜罐被用作跳板。遵守所有适用的法律法规。
## 许可证
MIT 许可证。详情请参阅 [LICENSE](LICENSE)。