PeakCoder-Here/threat-hunter
GitHub: PeakCoder-Here/threat-hunter
结合 Isolation Forest 异常检测与多 Agent AI 自动化调查的自主式威胁狩猎系统，帮助安全团队从网络日志中发现异常并生成取证事件报告。
Stars: 1 | Forks: 0
# 🛡 Threat Hunter — 自主式 AI 驱动的威胁狩猎 Agent
一个完整的 **SIEM 伴侣**，可以摄取网络日志，使用机器学习来检测异常，并部署多 Agent 的 AI 系统来调查警报并生成取证事件报告。
## 架构
```
┌─────────────────────────────────────────────────────────────────┐
│ THREAT HUNTER │
│ │
│ ┌──────────┐ ┌───────────────┐ ┌──────────────────────┐ │
│ │ Log │ │ ML Anomaly │ │ Multi-Agent AI │ │
│ │ Ingestor │──▶│ Detector │──▶│ Investigation │ │
│ │ │ │ (Isolation │ │ │ │
│ │ Synthetic│ │ Forest) │ │ Agent 1: Researcher │ │
│ │ or Real │ │ │ │ Agent 2: Forensics │ │
│ │ Logs │ │ Score & Flag │ │ Agent 3: Reporter │ │
│ └──────────┘ └───────────────┘ └──────────┬───────────┘ │
│ │ │
│ ┌──────────────────────────────────────────────┐│ │
│ │ SOC Dashboard (FastAPI + HTML) ││ │
│ │ - Pipeline control - Alert management ││ │
│ │ - Live log stream - Incident reports ││ │
│ │ - Stats & severity - Remediation cmds │◀ │
│ └──────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
```
## 快速开始
```
# 1. 安装依赖
pip install -r requirements.txt
# 2. 运行系统
python main.py
# 3. 打开 dashboard
# http://localhost:8000
```
或者使用安装脚本：
```
chmod +x run.sh && ./run.sh
```
## Pipeline 步骤
### 步骤 1 — 日志摄取
生成模拟正常和异常流量（DoS、Exploits、Reconnaissance、Backdoor、Shellcode）的合成网络日志。你也可以加载真实数据集，如 UNSW-NB15 或 CICIDS2017。
### 步骤 2 — ML 异常检测
在 16 个网络特征上训练 **Isolation Forest**（200 个 estimator，StandardScaler 预处理）。该模型学习正常流量模式，并在不需要标记数据的情况下标记异常值。
**使用的特征：** duration、packets (src/dst)、bytes (src/dst)、rate、TTL、load、inter-packet time、jitter、connection counts。
### 步骤 3 — 异常评分
对所有未处理的日志进行评分，并为超过异常阈值的日志创建警报。分配严重级别：critical、high、medium、low。
### 步骤 4 — 多 Agent AI 调查
当警报触发时，三个 AI Agent 按顺序工作：
| Agent | 角色 | 输出 |
|-------|------|--------|
| **Researcher** | 查询威胁情报 API，评估 IP 信誉 | 威胁评分、地理位置、类别、IOC |
| **Forensics Analyst** | 关联日志，构建 MITRE ATT&CK 时间线 | 攻击时间线、技术、kill chain |
| **Reporter** | 将调查结果汇编成事件报告 | Markdown 报告 + 防火墙命令 |
## 项目结构
```
threat-hunter/
├── main.py # Entry point
├── config.py # All configuration
├── db.py # Database models (SQLAlchemy + async)
├── requirements.txt
├── run.sh # Quick setup script
│
├── ingestion/
│ └── log_ingestor.py # Synthetic data gen + DB ingestion
│
├── ml/
│ ├── anomaly_detector.py # Isolation Forest pipeline
│ └── models/ # Saved model files
│
├── agents/
│ ├── llm_provider.py # LLM abstraction (Groq/Ollama/Mock)
│ ├── threat_intel.py # AlienVault OTX / VirusTotal client
│ └── threat_agents.py # Multi-agent orchestration
│
├── api/
│ └── server.py # FastAPI endpoints
│
├── static/
│ └── dashboard.html # SOC dashboard
│
└── reports/ # Generated incident reports
```
## LLM 配置
该系统支持三种 LLM 后端。通过环境变量进行设置：
```
# Mock 模式（默认，无需 API key — 非常适合演示）
LLM_PROVIDER=mock python main.py
# Groq Cloud（快速，提供免费额度）
LLM_PROVIDER=groq GROQ_API_KEY=gsk_... python main.py
# Ollama（完全本地化，隐私优先）
# 首先：ollama pull llama3
LLM_PROVIDER=ollama python main.py
```
## 威胁情报 API
可选 — 使用真实威胁数据丰富调查：
```
# AlienVault OTX（免费）
export OTX_API_KEY=your_key_here
# VirusTotal（免费额度：4 次查询/分钟）
export VT_API_KEY=your_key_here
```
## API Endpoint
| 方法 | Endpoint | 描述 |
|--------|----------|-------------|
| GET | `/` | SOC Dashboard |
| GET | `/api/status` | 系统状态 |
| POST | `/api/ingest/synthetic?n=5000` | 摄取合成日志 |
| POST | `/api/ingest/simulate-live` | 模拟实时批次 |
| POST | `/api/ml/train` | 训练异常模型 |
| GET | `/api/ml/metrics` | 模型评估 |
| POST | `/api/detect` | 运行异常检测 |
| GET | `/api/alerts` | 警报列表 |
| GET | `/api/alerts/{id}` | 警报详情 |
| POST | `/api/alerts/{id}/investigate` | AI 调查 |
| POST | `/api/alerts/investigate-all` | 批量调查 |
| GET | `/api/logs?flagged_only=true` | 浏览日志 |
| GET | `/api/logs/stats` | 聚合统计信息 |
交互式 API 文档可在 `/docs` (Swagger UI) 获取。
## 使用真实数据集
### UNSW-NB15
```
from ingestion.log_ingestor import load_unsw_csv, ingest_dataframe
df = load_unsw_csv("path/to/UNSW-NB15.csv")
await ingest_dataframe(df)
```
### CICIDS2017
需要列映射 — 摄取器会自动处理常见的 UNSW-NB15 列名。
## 性能
在合成数据集（3000 个样本，8% 异常率）上测试：
| 指标 | 数值 |
|--------|-------|
| Precision | 0.870 |
| Recall | 1.000 |
| F1 Score | 0.930 |
| Flagged | 9.2% |
| Training time | ~2s |
## 扩展系统
**添加新 Agent：** 在 `agents/threat_agents.py` 中创建新的 system prompt + handler，并将其接入 `investigate_anomaly()`。
**添加新的 LLM 提供者：** 在 `agents/llm_provider.py` 中添加新的异步函数，并在 `llm_complete()` 中注册。
**切换到 PostgreSQL：** 将 config.py 中的 `DATABASE_URL` 更改为 `postgresql+asyncpg://...` 并安装 `asyncpg`。
**切换到 ELK Stack：** 将 SQLite 摄取替换为为 Elasticsearch 提供数据的 Logstash pipeline，并在检测循环中查询 ES。
## License
教育项目。请负责任地使用。
标签：Apex, PB级数据处理, 多智能体, 安全运维, 安全运营中心, 异常检测, 机器学习, 网络映射, 逆向工具