kumavatvishal05/soar-ml-ir
GitHub: kumavatvishal05/soar-ml-ir
这是一个集成了机器学习与强化学习技术的SOAR平台，旨在实现从告警摄入到自动取证的全流程安全事件响应自动化。
Stars: 0 | Forks: 0
# SOAR-ML：利用 ML 驱动的 Playbook 执行实现自动化事件响应
**硕士项目 — Vishal Ramesh Chandora（学号 A-375）**
Guru Nanak Khalsa 学院，信息技术系
2025–2026 学年
## 项目概述
该系统实现了一个完整的 SOAR（安全编排、自动化和响应）平台，由机器学习和强化学习驱动。它在 6 个阶段中实现了整个事件响应生命周期的自动化：
| 阶段 | 组件 | 描述 |
|-------|-----------|-------------|
| 1 | **Alert Ingestion** | REST API 接收来自 SIEM/EDR/Firewall 的告警 |
| 2 | **ML Triage** | Gradient Boosting 对严重性和优先级进行分类 |
| 3 | **NLP Enrichment** | 从告警描述中提取 IOCs、TTPs |
| 4 | **Graph Correlation** | 将相关告警归组为事件 |
| 5 | **RL Playbook Execution** | Q-Learning 智能体选择最佳响应操作 |
| 6 | **Forensic Collection** | 自动保全证据并维护监管链 |
## 项目结构
```
soar-ml-incident-response/
├── main.py # Start the web API server
├── run_demo.py # Run full demo without any server
├── requirements.txt
├── src/
│ ├── config/settings.py # All configuration (env-driven)
│ ├── ingestion/
│ │ ├── api.py # FastAPI app (POST /ingest, GET /metrics …)
│ │ └── schemas/alert.py # Pydantic alert schema
│ ├── ml/
│ │ ├── triage_model.py # GradientBoosting wrapper
│ │ └── train_triage_model.py # Training script
│ ├── nlp/
│ │ └── threat_intel_parser.py # IOC/TTP extraction (regex + spaCy)
│ ├── correlation/
│ │ ├── graph_builder.py # Build NetworkX entity graph
│ │ └── incident_detector.py # Connected-component incident grouping
│ ├── rl/
│ │ ├── agent.py # Q-Learning agent (persistent Q-table)
│ │ ├── environment.py # Incident RL environment
│ │ └── trainer.py # Training loop + reward shaping
│ ├── playbooks/
│ │ ├── actions.py # Action enum (8 response actions)
│ │ └── executor.py # Simulated action execution
│ ├── forensics/
│ │ └── collector.py # Evidence collection + JSON reports
│ ├── storage/
│ │ ├── db.py # SQLAlchemy engine (SQLite)
│ │ ├── models.py # Alert, ActionLog, ForensicReport tables
│ │ └── repository.py # CRUD helpers
│ ├── metrics/
│ │ └── mttr.py # MTTD, MTTR, playbook success metrics
│ ├── message_queue/
│ │ └── queue.py # In-memory thread-safe queue (no Redis)
│ └── workers/
│ └── alert_worker.py # Main processing pipeline
```
## 在 Windows 上设置
### 前置条件
- Python 3.11 或 3.12（从 https://python.org 下载）
- Git（从 https://git-scm.com 下载）
### 步骤 1 — 克隆或设置项目文件夹
如果使用项目 zip 包，请解压。然后在项目文件夹中打开 **命令提示符** 或 **PowerShell**。
### 步骤 2 — 创建虚拟环境
```
python -m venv venv
venv\Scripts\activate
```
此时您的提示符应显示 `(venv)`。
### 步骤 3 — 安装依赖
```
pip install -r requirements.txt
```
### 步骤 4 — 下载 spaCy 语言模型（用于 NLP 阶段）
```
python -m spacy download en_core_web_sm
```
### 步骤 5 — 训练 ML 模型
```
python -m src.ml.train_triage_model
```
这将使用合成数据创建 `src/ml/artifacts/triage_model.pkl`（无需数据库）。
## 运行项目
### 选项 A — 完整演示（建议首次运行时使用）
在 3 个示例告警上运行所有 6 个阶段，打印指标，保存证据文件。
```
python run_demo.py
```
预期输出：
```
[Setup] Initialising SQLite database …
[Setup] Training model on synthetic data …
>>> Alert 1/3: MALWARE (severity=5)
[ML Triage] high_priority=1 confidence=0.91
[NLP] IOCs extracted: 3 TTPs: ['T1486']
[Correlation] incident_id=
[RL] best_action=Action.ISOLATE_HOST success=True
[Forensics] Evidence saved → forensics_evidence/forensic_...json
...
Metric Value
─────────────────────────────────────────
Total Alerts Processed 3
High Priority Alerts 2
Mean Time to Detect (MTTD) 0.00s
Mean Time to Respond (MTTR) 0.45s
Playbook Success Rate 83.3%
Analyst Workload Reduction 100.0%
```
### 选项 B — 启动 Web API 服务器
```
python main.py
```
然后打开您的浏览器：
- **Dashboard:** http://localhost:8000/dashboard
- **API docs:** http://localhost:8000/docs
- **Health check:** http://localhost:8000/health
### 选项 C — 通过 API 发送告警
在服务器运行的情况下，打开第二个终端并运行：
```
python -c "
import requests, uuid, json
from datetime import datetime, timezone
alert = {
'alert_id': str(uuid.uuid4()),
'source': 'edr',
'alert_type': 'malware',
'severity': 5,
'timestamp': datetime.now(timezone.utc).isoformat(),
'description': 'Ransomware detected contacting 185.220.101.45. Hash: abc123. Technique T1486.',
'entities': {'ip_addresses': ['185.220.101.45'], 'users': ['jsmith'], 'domains': [], 'file_hashes': [], 'hostnames': []},
'raw_event': {}
}
r = requests.post('http://localhost:8000/ingest', json=alert)
print(r.json())
"
```
## 配置
可以通过编辑 `src/config/settings.py` 或设置环境变量来更改所有设置：
| 变量 | 默认值 | 描述 |
|----------|---------|-------------|
| `ENABLE_ML_TRIAGE` | `true` | 启用 Gradient Boosting 分诊 |
| `ENABLE_NLP` | `true` | 启用 IOC/TTP 提取 |
| `ENABLE_CORRELATION` | `true` | 启用图事件归组 |
| `ENABLE_RL_PLAYBOOKS` | `true` | 启用 RL 操作选择 |
| `ENABLE_FORENSICS` | `true` | 启用证据收集 |
| `RL_EPISODES` | `30` | 每个事件的 Q-learning 回合数 |
| `DATABASE_URL` | `sqlite:///soar.db` | 数据库连接字符串 |
## 创建 GitHub 仓库
### 步骤 1 — 在 GitHub 上创建仓库
1. 访问 https://github.com 并登录
2. 点击 **New repository**（绿色按钮，右上角）
3. 命名：`soar-ml-incident-response`
4. 设置为 **Private**
5. 不要勾选 “Add README”（您已经有了）
6. 点击 **Create repository**
### 步骤 2 — 推送您的代码
在您的项目文件夹中（确保已激活 venv）：
```
git init
git add .
git commit -m "Initial commit: SOAR-ML Incident Response System"
git branch -M main
git remote add origin https://github.com/YOUR_USERNAME/soar-ml-incident-response.git
git push -u origin main
```
将 `YOUR_USERNAME` 替换为您的实际 GitHub 用户名。
### 步骤 3 — 验证
刷新您的 GitHub 仓库页面 —— 所有文件应该都可见。
## 评估指标（第 4.5 节）
| 指标 | 描述 | 预期结果 |
|--------|-------------|-----------------|
| MTTD | 平均检测时间 | ~0s（自动接收） |
| MTTR | 平均响应时间 | < 2s/告警 |
| Alert Precision | ML 分诊准确率 | 在合成数据上 > 85% |
| Playbook Success Rate | RL 操作成功率 | ~85–92% |
| Analyst Workload Reduction | 分析师工作量减少百分比 | 演示中 ~100% |
## 使用的技术
- **Python 3.11+** — 核心语言
- **FastAPI + Uvicorn** — REST API
- **scikit-learn** — Gradient Boosting 分类器
- **spaCy** — NLP 实体识别
- **NetworkX** — 基于图的关联
- **SQLAlchemy + SQLite** — 持久化（无需 Postgres/Redis）
- **Q-Learning** — 自适应 Playbook 选择
标签：Apex, AV绕过, Cybersecurity, EDR, FastAPI, Gradient Boosting, IOC提取, NetworkX图关联, NLP自然语言处理, Python, Q-Learning, SOAR, TTP分析, 事件分类, 取证, 告警关联, 威胁情报, 安全运营, 开发者工具, 强化学习, 扫描框架, 无后门, 机器学习, 特权检测, 网络安全, 脆弱性评估, 自动化应急响应, 逆向工具, 隐私保护