Ganesh-403/honeycloud
GitHub: Ganesh-403/honeycloud
一个集成了实时可视化仪表盘与机器学习分析的可扩展蜜罐平台，用于捕获、分析 SSH/FTP/HTTP 攻击流量并对攻击者进行画像。
Stars: 1 | Forks: 0
# 🍯 Honey Cloud
## 目录
1. [架构](#architecture)
2. [项目结构](#project-structure)
3. [快速开始 (5 分钟)](#quick-start)
4. [演示脚本](#demo-script)
5. [配置](#configuration)
6. [API 参考](#api-reference)
7. [攻击者画像](#attacker-profiling)
8. [分析引擎](#analytics-engine)
9. [ML 引擎](#ml-engine)
10. [WebSocket 订阅流](#websocket-feed)
11. [仪表盘](#dashboard)
12. [蜜罐模块](#honeypot-modules)
13. [测试](#testing)
14. [部署](#deployment)
15. [安全说明](#security-notes)
## 架构
```
┌──────────────────────────────────────────────────────────────────────┐
│ Honey Cloud │
│ │
│ Browser FastAPI Backend Database │
│ ┌────────┐ HTTPS/WS ┌──────────────────────┐ ┌──────────────┐ │
│ │Dashboard│◄──────────►│ API Layer (v1) │ │SQLite / │ │
│ │(nginx) │ │ auth · events │ │Postgres │ │
│ └────────┘ │ analytics · profiles │◄─│ │ │
│ │ ml · reports │ └──────────────┘ │
│ Honeypots └──────┬───────────────┘ │
│ ┌───────┐ POST /ingest │ Services layer │
│ │SSH │──────────────► EventService │
│ │FTP │ ProfilerService │
│ │HTTP │ AlertService (Telegram) │
│ └───────┘ ReportService (CSV/XLSX) │
│ │ │
│ Attackers │ ML Engine │
│ (Internet) ──TCP──► Honeypots │ IsolationForest │
│ │ 10 semantic features │
│ Telegram ◄─── Alerts ─────────┘ │
└──────────────────────────────────────────────────────────────────────┘
```
**每次攻击事件的采集流水线：**
```
TCP → Honeypot → POST /ingest (201 ~50ms)
│
┌──────┴──────────────────────────────────┐
│ sync │ background
│ resolve IP │ update AttackerProfile
│ geo-enrich │ pattern detection
│ ML classify │ Telegram alert
│ DB persist │ WebSocket broadcast
└─────────────────────────────────────────┘
```
## 项目结构
```
honeycloud/
├── Makefile ← developer command centre
├── simulate_attacks.py ← demo / smoke-test script
├── docker-compose.yml ← production stack
├── docker-compose.dev.yml ← dev hot-reload overrides
├── .env.example ← copy → .env
├── .gitignore
├── README.md
│
├── backend/
│ ├── Dockerfile ← multi-stage (builder + runtime)
│ ├── requirements.txt
│ ├── pytest.ini
│ ├── tests/
│ │ ├── conftest.py ← fixtures, in-memory DB
│ │ ├── test_auth.py
│ │ ├── test_events.py
│ │ ├── test_analytics.py
│ │ ├── test_profiles.py
│ │ ├── test_ml.py
│ │ └── test_security.py
│ └── app/
│ ├── main.py ← factory, lifespan, middleware
│ ├── core/
│ │ ├── config.py ← pydantic-settings
│ │ ├── security.py ← JWT + bcrypt
│ │ ├── rate_limit.py ← slowapi limiter singleton
│ │ ├── logging.py ← structured logging
│ │ ├── exceptions.py ← hierarchy + handlers
│ │ └── websocket_manager.py ← WS connection registry
│ ├── api/deps.py ← DI providers
│ ├── api/v1/
│ │ ├── router.py ← aggregates all sub-routers
│ │ ├── auth.py ← login (rate-limited)
│ │ ├── events.py ← ingest · list · SSE · WebSocket
│ │ ├── analytics.py ← 7 analytics endpoints
│ │ ├── profiles.py ← attacker profiles + block/unblock
│ │ ├── ml.py ← train · status · predict
│ │ ├── stats.py
│ │ ├── reports.py
│ │ └── simulate.py
│ ├── schemas/ ← Pydantic models
│ ├── models/
│ │ ├── attack_event.py ← ORM: events table
│ │ └── attacker_profile.py ← ORM: per-IP profiles table
│ ├── db/session.py
│ ├── repositories/
│ │ ├── event_repository.py
│ │ ├── profile_repository.py
│ │ └── analytics_repository.py
│ ├── services/
│ │ ├── event_service.py ← ingest pipeline + BackgroundTasks
│ │ ├── profiler_service.py ← pattern detection engine
│ │ ├── alert_service.py
│ │ ├── geo_service.py
│ │ └── report_service.py
│ ├── honeypots/
│ │ ├── base.py ← BaseHoneypot ABC
│ │ ├── ssh_honeypot.py
│ │ ├── ftp_honeypot.py
│ │ └── http_honeypot.py
│ └── ml/
│ ├── detector.py ← IsolationForest wrapper
│ └── features.py ← 10-feature extraction pipeline
│
└── frontend/
├── Dockerfile
├── nginx.conf
├── index.html ← auth redirect
├── login.html ← login page
└── dashboard.html ← full analytics dashboard
```
## 快速开始
### 前置条件
- Docker ≥ 24 + Docker Compose v2（推荐）
- 或用于本地开发的 Python 3.11+
### 1. 克隆并配置
```
git clone https://github.com/your-org/honeycloud.git
cd honeycloud
cp .env.example .env
make gen-key # updates .env SECRET_KEY with a strong secret
# 查看 .env 以设置 DATABASE_URL、TELEGRAM_*、速率限制和 honeypot 端口。
```
### 2. 启动技术栈
```
make prod # production (background)
# 或
make dev # development (hot-reload, foreground)
```
| URL | 描述 |
|-----|-------------|
| http://localhost | 仪表盘 (登录: admin / admin123) |
| http://localhost:8000/docs | API 文档 (仅限 DEBUG 模式) |
| ws://localhost:8000/api/v1/events/ws?token=JWT | WebSocket 订阅流 |
### 3. 生成演示数据
```
make seed # 30 simulated attacks via the API
# 或
python simulate_attacks.py --count 50 --report
```
### 4. 训练 ML 模型
```
make train-ml # trains IsolationForest on stored events
```
### 默认凭据
| 用户名 | 密码 | 角色 |
|----------|----------|------|
| `admin` | `admin123` | 管理员 (完全访问) |
| `analyst` | `analyst123` | 分析员 (只读) |
## 快速 API 工作流 (curl 示例)
1. 登录并获取 token：
```
curl -s -X POST http://localhost:8000/api/v1/auth/login \
-d "username=admin" -d "password=admin123" \
-H "Content-Type: application/x-www-form-urlencoded" \
| jq -r '.access_token'
```
2. 模拟演示事件：
```
TOKEN="$(...login command...)"
curl -X POST "http://localhost:8000/api/v1/simulate?count=30" \
-H "Authorization: Bearer $TOKEN"
```
3. 训练 ML 模型：
```
curl -X POST http://localhost:8000/api/v1/ml/train \
-H "Authorization: Bearer $TOKEN"
```
4. 检查仪表盘统计：
```
curl -X GET http://localhost:8000/api/v1/stats/ \
-H "Authorization: Bearer $TOKEN"
```
### 故障排除
- `/api/v1/events/ws` 出现 `401 Unauthorized`：JWT 缺失、过期或查询参数格式错误。
- `/api/v1/ml/train` 出现 `422 Unprocessable Entity`：首先需要至少 50 个事件（可使用 `/api/v1/simulate`）。
- `/api/v1/reports/generate` 出现 `500`：确保 `REPORTS_DIR` 存在，并且在 `send_telegram=true` 时 `TELEGRAM_*` 配置正确。
## 演示脚本
`simulate_attacks.py` 是一个包含 7 个阶段的端到端演示：
```
Phase 1 – Direct Attack Injection (15 distinct attack templates × 5 IPs)
Phase 2 – Bulk Simulation (/simulate endpoint, N events)
Phase 3 – ML Training (IsolationForest on all stored events)
Phase 4 – Results Summary (totals, service breakdown)
Phase 5 – Attacker Profiles (top IPs, risk tiers, pattern flags)
Phase 6 – Credential Intelligence (top usernames & passwords)
Phase 7 – XLSX Report (optional) (--report flag)
```
```
# 包含报告的完整演示
python simulate_attacks.py --count 100 --report
# 自定义主机/端口
python simulate_attacks.py --host 192.168.1.10 --port 8000
```
## 配置
来自 `.env` 的所有设置（切勿将 `.env` 提交到 git）：
| 变量 | 默认值 | 必需 | 描述 |
|----------|---------|----------|-------------|
| `SECRET_KEY` | — | ✅ | JWT 签名密钥 (≥32 字符) |
| `DATABASE_URL` | `sqlite:///./data/honeycloud.db` | 否 | SQLAlchemy URL |
| `ENVIRONMENT` | `production` | 否 | `development`/`staging`/`production` |
| `DEBUG` | `false` | 否 | 显示 /docs，详细日志 |
| `ALLOWED_ORIGINS` | `["http://localhost:5173"]` | 否 | CORS 列表 |
| `RATE_LIMIT_PER_MINUTE` | `60` | 否 | 全局 API 速率限制 |
| `TELEGRAM_ALERTS_ENABLED` | `false` | 否 | Telegram 告警开关 |
| `TELEGRAM_BOT_TOKEN` | — | 否 | 来自 @BotFather |
| `TELEGRAM_CHAT_ID` | — | 否 | 目标聊天/频道 |
| `SSH_HONEYPOT_PORT` | `2222` | 否 | |
| `FTP_HONEYPOT_PORT` | `2121` | 否 | |
| `HTTP_HONEYPOT_PORT` | `8080` | 否 | |
## API 参考
所有受保护的路由都需要 `Authorization: Bearer `，除非另有说明。
### 认证
| 方法 | 路径 | 认证 | 描述 |
|--------|------|------|-------------|
| POST | `/api/v1/auth/login` | 无 | 返回 JWT (限速 10/分钟) |
| GET | `/api/v1/auth/me` | 必需 | 当前用户信息 |
| POST | `/api/v1/auth/logout` | 必需 | 撤销当前 token (通过 jti 加入黑名单) |
### 事件
| 方法 | 路径 | 认证 | 描述 |
|--------|------|------|-------------|
| POST | `/api/v1/events/ingest` | 无 | 采集事件 (蜜罐代理, 公开, 限速) |
| GET | `/api/v1/events/` | 必需 | 列表 (支持 limit, service, severity, time range 筛选) |
| GET | `/api/v1/events/stream` | 必需 | SSE 实时订阅流 (旧版) |
| WS | `/api/v1/events/ws?token=` | JWT 参数 | WebSocket 实时订阅流 (推荐) |
### 分析
| 方法 | 路径 | 认证 | 描述 |
|--------|------|------|-------------|
| GET | `/api/v1/analytics/summary` | 必需 | 概览数据 |
| GET | `/api/v1/analytics/timeline?mode=hourly\|daily` | 必需 | 时间序列 |
| GET | `/api/v1/analytics/geo` | 必需 | 按国家统计事件 |
| GET | `/api/v1/analytics/heatmap` | 必需 | 24×7 小时/天矩阵 |
| GET | `/api/v1/analytics/credentials` | 必需 | 热门用户名、密码、命令 |
| GET | `/api/v1/analytics/service-trend` | 必需 | SSH/FTP/HTTP 每日分布 |
### 攻击者画像
| 方法 | 路径 | 描述 |
|--------|------|-------------|
| GET | `/api/v1/analytics/summary` | 概览数据 |
| GET | `/api/v1/analytics/timeline?mode=hourly\|daily` | 时间序列 |
| GET | `/api/v1/analytics/geo` | 按国家统计事件 |
| GET | `/api/v1/analytics/heatmap` | 24×7 小时/天矩阵 |
| GET | `/api/v1/analytics/credentials` | 热门用户名、密码、命令 |
| GET | `/api/v1/analytics/service-trend` | SSH/FTP/HTTP 每日分布 |
### 攻击者画像
| 方法 | 路径 | 认证 | 描述 |
|--------|------|------|-------------|
| GET | `/api/v1/profiles/` | 必需 | 列出画像 (支持筛选) |
| GET | `/api/v1/profiles/summary` | 必需 | 风险层级计数 + 热门攻击者 |
| GET | `/api/v1/profiles/{ip}` | 必需 | 单个 IP 的完整画像 |
| POST | `/api/v1/profiles/{ip}/block` | 管理员 | 封禁 IP |
| POST | `/api/v1/profiles/{ip}/unblock` | 管理员 | 解除封禁 |
### ML 引擎
| 方法 | 路径 | 认证 | 描述 |
|--------|------|------|-------------|
| GET | `/api/v1/ml/status` | 必需 | 模型状态 + 特征 |
| POST | `/api/v1/ml/train` | 管理员 | 基于存储的事件进行训练 |
| POST | `/api/v1/ml/predict` | 必需 | 单次事件预测 (调试) |
### 报告与统计
| 方法 | 路径 | 认证 | 描述 |
|--------|------|------|-------------|
| GET | `/api/v1/stats/` | 必需 | 按 severity/service/AI 标签聚合计数 |
| POST | `/api/v1/reports/generate?fmt=csv\|xlsx\|txt&send_telegram=true|false` | 管理员 | 生成报告，可选通过 Telegram 发送 |
| GET | `/api/v1/reports/download?file=name` | 无 | 安全文件下载 (安全路径验证) |
| POST | `/api/v1/simulate/?count=N` | 必需 | 生成 N 个演示事件 (已认证用户) |
## 攻击者画像
HoneyCloud 会自动为每个唯一的攻击 IP 构建持久的 `AttackerProfile`。每次采集事件后，画像会在后台更新。
### 风险层级
| 层级 | 加权得分 | 描述 |
|------|---------------|-------------|
| UNKNOWN | 0–2 | 新近 / 最小活动 |
| LOW | 2–8 | 轻度探测 |
| MEDIUM | 8–20 | 主动扫描 |
| HIGH | 20–50 | 持续攻击 |
| CRITICAL | 50+ | 严重 / 持续威胁 |
| BLOCKED | — | 管理员封禁 |
得分公式：
```
score = (critical_events × 4) + (high_events × 2)
+ brute_force_bonus(15) + credential_stuffing_bonus(10)
+ scanner_bonus(8)
```
### 模式检测
| 模式 | 检测规则 |
|---------|----------------|
| 暴力破解 | 同一 IP 在 60 秒内 ≥ 10 个事件 |
| 凭据填充 | 同一 IP 在 5 分钟内 ≥ 5 个不同密码 |
| 端口扫描 | 同一 IP 在 5 分钟内 ≥ 3 个不同服务 |
## 分析引擎
7 个由优化的原生 SQL 查询支持的分析端点：
- **Timeline (时间线)**：按小时 (24h) 或按天 (30 天) 统计事件
- **Geo distribution (地理分布)**：按事件数和唯一 IP 统计的前 50 个国家
- **Heatmap (热力图)**：24×7 矩阵，显示攻击在*何时*达到高峰（非常适合调度）
- **Credential intelligence (凭据情报)**：最常尝试的用户名、密码和命令
- **Service trend (服务趋势)**：SSH/FTP/HTTP 每日分布，用于趋势分析
## ML 引擎
### 特征 (10 维)
```
service_port – protocol port (SSH=22, FTP=21, HTTP=80)
username_len – character length of attempted username
password_len – character length of attempted password
command_len – character length of command / path
source_port – originating port
hour_of_day – hour (0–23) from event timestamp
dangerous_pattern_count – count of matched dangerous regex patterns
is_root_user – 1 if username in {root, admin, administrator}
is_anonymous_user – 1 if username in {anonymous, guest, visitor}
has_command – 1 if command/path is non-empty
```
### 标签
| 标签 | 条件 |
|-------|-----------|
| `benign` | IsolationForest 内点 |
| `anomaly` | 离群点, 威胁得分 < 0.6 |
| `malicious` | 离群点, 威胁得分 ≥ 0.6 |
| `unknown` | 模型尚未训练 |
### 训练 / 重训练周期
```
# 在积累 ≥ 50 个事件后：
make train-ml
# 或通过 API：
curl -X POST http://localhost:8000/api/v1/ml/train \
-H "Authorization: Bearer $TOKEN"
```
模型持久化到 `data/ml_model.pkl` 并在重启时重新加载。
## WebSocket 订阅流
实时推送式事件流 —— 零轮询开销。
```
// Connect
const ws = new WebSocket(`ws://localhost:8000/api/v1/events/ws?token=${jwt}`);
// Receive events
ws.onmessage = ({ data }) => {
const msg = JSON.parse(data);
if (msg.type === 'new_attack') {
console.log(msg.data); // full event object
}
};
// Ping / connection count
ws.send(JSON.stringify({ type: 'ping' }));
// → { "type": "pong", "connections": 3 }
```
服务器每 30 秒发送一次 `{ "type": "heartbeat" }`。断开连接的客户端会自动重新连接（仪表盘每 4 秒重试一次）。
## 仪表盘
位于 `/dashboard.html` 的单文件 SPA —— 无需构建步骤。
| 页面 | 内容 |
|------|----------|
| **Overview (概览)** | 6 个统计卡片 + 4 个 Chart.js 图表 (时间线, 严重程度, 服务, AI)；自动刷新 15 秒 |
| **Live Feed (实时订阅)** | WebSocket 驱动的事件表；按服务/严重程度筛选；最多 200 行 |
| **Analytics (分析)** | 30 天时间线、服务趋势、地理前 12 柱状图 |
| **Profiles (画像)** | IP 风险表；封禁/解封操作；点击 IP 查看完整详情面板 |
| **Heatmap (热力图)** | 24×7 颜色渐变攻击时间矩阵 |
| **Credentials (凭据)** | 前 15 个用户名、密码和命令，带动画柱状图 |
## 蜜罐模块
均继承自 `BaseHoneypot`：
```
class BaseHoneypot(ABC):
protocol: str # "SSH" | "FTP" | "HTTP"
async def start(port: int): ...
async def stop(): ...
# Helpers available to all subclasses:
_build_event(source_ip, source_port, **kwargs) → dict
_post_event(event: dict) # fire-and-forget POST to /ingest
_classify_command(cmd) → str # "LOW" | "MEDIUM" | "HIGH" | "CRITICAL"
```
**添加新的蜜罐：**
1. 创建 `app/honeypots/myproto_honeypot.py` 继承 `BaseHoneypot`
2. 设置 `protocol = "MYPROTO"` 并实现 `start()` / `stop()`
3. 使用 `_build_event()` + `_post_event()` —— 无需其他更改
4. 在 `main.py` 生命周期块中注册
## 测试
```
# 安装测试依赖
cd backend && pip install pytest httpx pytest-asyncio
# 运行所有测试
make test
# 带覆盖率
make test-cov
# 快速（跳过 ML 测试）
make test-fast
```
测试套件覆盖：
| 模块 | 测试 | 范围 |
|--------|-------|-------| `test_auth.py` | 6 | 登录, JWT, 角色 |
| `test_events.py` | 10 | 采集, 筛选, schema, 边界情况 |
| `test_analytics.py` | 10 | 所有 7 个分析端点 |
| `test_profiles.py` | 9 | CRUD, 封禁/解封, RBAC |
| `test_ml.py` | 8 | 特征提取, 训练, 保存/加载 |
| `test_security.py` | 10 | 被篡改的 token, 路径遍历, 超大负载 |
## 部署
### 生产清单
- [ ] `SECRET_KEY` 为随机的 64 字符十六进制 (`make gen-key`)
- [ ] `ENVIRONMENT=production`, `DEBUG=false`
- [ ] `ALLOWED_ORIGINS` 锁定到您的实际域名
- [ ] Telegram token 已配置 (或 `TELEGRAM_ALERTS_ENABLED=false`)
- [ ] 蜜罐端口 (2222, 2121, 8080) 已暴露；API 端口 (8000) 仅限内部
- [ ] Nginx 终止 TLS；后端位于反向代理之后
- [ ] `data/` 和 `reports/` 卷已备份
- [ ] 积累真实流量后运行 `make train-ml`
### 切换到 PostgreSQL
```
# .env
DATABASE_URL=postgresql+psycopg2://honeycloud:password@db:5432/honeycloud
# requirements.txt – 添加：
# psycopg2-binary==2.9.9
# Analytics 查询使用 strftime() – 对 Postgres 更新为 date_trunc()：
# strftime('%Y-%m-%dT%H:00:00', timestamp) → to_char(date_trunc('hour', timestamp), 'YYYY-MM-DD"T"HH24:00:00')
```
## 安全说明
| 领域 | 实现 |
|------|---------------|
| Secrets | `pydantic-settings` + `.env`；源代码中无密钥 |
| 密码 | 通过 `passlib` 使用 bcrypt |
| JWT | HS256, 可配置过期时间, 每次请求验证 |
| Rate limiting | `slowapi` – 登录 10/分钟, 全局 60/分钟 |
| CORS | 显式 `ALLOWED_ORIGINS` (无通配符) |
| 输入验证 | 所有路由上的 Pydantic v2 字段验证器 |
| 路径遍历 | `ReportService.safe_path()` 使用 `Path.resolve()` 父级检查 |
| WebSocket 认证 | 连接升级前验证 JWT；`4001 Unauthorized` |
| 容器 | Dockerfile 中的 `USER appuser` (UID 1001) |
| RBAC | `analyst` → 只读；`admin` → 完全权限，包括 封禁/训练/报告 |
*基于 FastAPI · SQLAlchemy · scikit-learn · asyncio · WebSockets · Chart.js · Docker 构建*
标签：AMSI绕过, Apex, AV绕过, BOF, CISA项目, Dashboard, FastAPI, FTP监控, Honeypot, HTTP/HTTPS抓包, HTTP协议, ML, PE 加载器, PostgreSQL, Python, SOC工具, SQLite, SSH安全, WebSocket, 事件流, 仪表盘, 依赖分析, 入侵分析, 凭据窃取, 威胁情报, 威胁检测, 安全运营, 开发者工具, 异常流量, 态势感知, 扫描框架, 攻击分析, 攻击者画像, 无后门, 机器学习, 欺骗防御, 测试用例, 漏洞发现, 漏洞捕获, 网络安全, 蜜罐系统, 计算机取证, 请求拦截, 逆向工具, 隐私保护