emeka68/soc-triage-bot
GitHub: emeka68/soc-triage-bot
一个用于自动化 SOC 警报分类、严重性评分与优先级路由的 Python 机器人，帮助安全团队减少告警噪音并加速事件响应。
Stars: 0 | Forks: 0
# SOC Triage Bot 🤖
**自动化安全运营中心 (SOC) 警报分类与事件响应自动化。**
一个 Python 机器人，用于从 Wazuh、SIEM 系统或通用 webhook 源接入安全警报，自动进行严重性评分、威胁类型分类、分配优先级，并通过 Telegram 和 Slack 向您的安全团队发送丰富的通知。
## 应用场景
- **没有完整 SOAR 平台的小型安全团队** — 无需部署 Splunk SOAR、Cortex XSOAR 或类似平台，即可获得严重性评分、分类和优先级路由。
- **需要更好警报分类的 Wazuh 部署** — 通过自动评分并将低优先级警报批量汇总到摘要中，而不是对所有内容都进行寻呼，从而减少原始 Wazuh 警报带来的噪音。
- **精简事件响应 (IR) 团队的值班轮换** — P1/P2 警报会立即通过 Telegram/Slack 发送；P3/P4 警报将批量汇总为每小时摘要，避免值班人员被淹没。
- **接入来自没有原生 SIEM 集成的工具的警报** — 通用的 JSON webhook endpoint 接受来自任何可以 POST JSON 的源（自定义脚本、其他监控工具、EDR 代理）的警报。
- **学习/原型化 SOC 自动化概念** — 一个小而清晰的参考实现，涵盖了严重性评分、MITRE ATT&CK 标记和优先级分级响应路由。
## 功能
✅ **多源警报接入**
- Wazuh API 集成 (SIEM)
- 通用 JSON webhook 支持
- 带有真实示例警报的演示模式
- 自动去重（10分钟时间窗口）
✅ **智能严重性评分** (0-100)
- 基于警报类别的上下文感知评分
- 身份验证失败累积（>50 = 严重，>20 = 高，>5 = 中）
- 恶意软件/rootkit 自动升级
- 权限提升检测
- 端口扫描和横向移动标记
✅ **警报分类**
- 身份验证（登录失败、SSH 暴力破解）
- 网络（端口扫描、横向移动、出站连接）
- 终端（文件修改、进程执行、cron jobs）
- 恶意软件（病毒/rootkit 特征）
- 合规性（策略违规、访问控制）
✅ **优先级分配**
- **P1 (严重)**：需要立即响应
- **P2 (高)**：15分钟内响应
- **P3 (中)**：1小时内响应
- **P4 (低)**：在下一个工作日响应
✅ **自动化响应**
- P1/P2：立即通过 Telegram + Slack 发送包含完整上下文的警报
- P3/P4：批量汇总为每小时摘要通知
- 严重性徽章、MITRE ATT&CK 战术、建议操作
- 防止重复通知
✅ **丰富的 CLI 仪表板**
- `status` — 按严重性查看活动警报
- `summary` — 24小时统计和趋势
- `list` — 过滤并浏览活动警报
- `clear` — 将警报标记为已解决
- `details` — 包含分类决策的完整警报上下文
✅ **灵活的部署**
- 用于测试的 `--demo` 模式（无需 Wazuh）
- 用于单次运行执行的 `--once`
- 用于持续监控的 `--daemon`
- 可配置的检查间隔
## 快速开始
### 1. 克隆并安装
```
git clone https://github.com/emeka68/soc-triage-bot.git
cd soc-triage-bot
pip install -r requirements.txt
```
### 2. 配置
将 `.env.example` 复制到 `.env` 并填入您的凭据：
```
cp .env.example .env
# 使用你的 Wazuh、Telegram 和 Slack 详情编辑 .env
```
或者更新 `config.yaml` 以应用您的设置。
### 3. 运行演示
使用示例警报进行测试（无需外部 API 调用）：
```
python bot.py once --demo
```
您应该会看到类似如下的输出：
```
[*] Starting single triage run...
[+] Loaded 25 alerts from demo_alerts.json
[+] P1 - prod-web-01: SSH brute force attack detected (95 attempts)
[+] P1 - app-server-02: Privilege escalation via sudo detected
[+] P1 - workstation-05: Malware signature match: Trojan.Generic.AXA
[*] Triage complete. Active alerts: 23
```
### 4. 查看仪表板
```
python dashboard.py status
python dashboard.py summary
python dashboard.py list-alerts --severity critical
```
### 5. 在生产环境中运行
**针对 Wazuh 的单次运行：**
```
python bot.py once
```
**持续监控（daemon 模式）：**
```
python bot.py daemon --interval 300
```
**使用 screen/tmux 进行后台执行：**
```
screen -S soc-bot
python bot.py daemon --demo --interval 300
# 按 Ctrl+A 然后按 D 来 detach
```
## 架构
```
┌─────────────────────────────────────────────────────────┐
│ SOC TRIAGE BOT │
├─────────────────────────────────────────────────────────┤
│ │
│ ┌──────────┐ ┌─────────────┐ ┌──────────────┐ │
│ │ INGESTER │────→│TRIAGE ENGINE│───→│ RESPONDER │ │
│ └──────────┘ └─────────────┘ └──────────────┘ │
│ │ │ │ │
│ Wazuh API Severity Scoring Telegram │
│ Webhooks Categorization Slack │
│ Demo File Priority Assignment Digest │
│ │ │ │ │
│ └──────────────────┴────────────────────┘ │
│ │ │
│ ┌──────────┐ │
│ │ DASHBOARD│ │
│ └──────────┘ │
│ CLI / API │
│ │
└─────────────────────────────────────────────────────────┘
```
### 组件
| 模块 | 用途 |
|--------|---------|
| **ingester.py** | 从 Wazuh、webhook 或文件接入警报；去重 |
| **triage_engine.py** | 严重性评分、分类、优先级分配、MITRE 映射 |
| **responder.py** | Telegram/Slack 通知、摘要批处理、防止重复 |
| **dashboard.py** | 用于警报查看和管理的 CLI 界面 |
| **bot.py** | 主编排器；运行分类循环并协调组件 |
## 配置
### config.yaml
```
wazuh:
host: "wazuh.example.com"
user: "admin"
password: "${WAZUH_PASSWORD}" # From .env
enabled: false # Set true to connect to Wazuh
notifications:
telegram_token: "${TELEGRAM_BOT_TOKEN}"
telegram_chat_id: "${TELEGRAM_CHAT_ID}"
slack_webhook: "${SLACK_WEBHOOK_URL}"
severity_thresholds:
critical: 85
high: 65
medium: 40
low: 0
category_assignees:
Authentication: "Security Team"
Network: "Network Team"
Endpoint: "Incident Response"
Malware: "SOC Lead"
Compliance: "Compliance Team"
check_interval: 300 # seconds
dedup_window_minutes: 10
retention_days: 30
```
## 使用示例
### 演示模式（无 API Keys）
非常适合测试或演示：
```
python bot.py once --demo
python bot.py daemon --demo --interval 60
```
### 结合 Wazuh 的生产环境
```
# 针对 Wazuh 的单次检查
python bot.py once
# 每 5 分钟持续监控
python bot.py daemon --interval 300
```
### 仪表板命令
```
# 按 severity 查看所有 critical/high alerts
python dashboard.py status
# 获取 24 小时摘要统计
python dashboard.py summary
# 按 severity 过滤 alerts
python dashboard.py list-alerts --severity critical
python dashboard.py list-alerts --severity high
# 按 category 过滤
python dashboard.py list-alerts --category Authentication
# 获取某个 alert 的完整详情
python dashboard.py details --id auth_001
# 将 alert 标记为已解决
python dashboard.py clear --id auth_001
```
### Webhook 集成
运行 webhook HTTP 服务器，然后从 Splunk、Elastic 或自定义源接入警报：
```
python bot.py serve --port 8000
```
```
curl -X POST http://localhost:8000/webhook \
-H "Content-Type: application/json" \
-H "X-API-Key: ${WEBHOOK_API_KEY}" \
-d '{
"id": "alert_123",
"timestamp": "2026-03-20T19:00:00Z",
"source_ip": "203.0.113.45",
"destination_ip": "192.168.1.100",
"hostname": "app-server-01",
"rule_name": "SSH_BRUTE_FORCE",
"severity_raw": "7",
"description": "SSH brute force attack",
"category": "Authentication"
}'
```
在 `.env` 中设置 `WEBHOOK_API_KEY` 以要求包含 `X-API-Key` header（推荐用于
localhost 测试之外的任何环境）；对于本地/演示使用，请将其留空。
## 警报流
```
┌──────────────┐
│ Raw Alert │
│ (any source) │
└───────┬──────┘
│
▼
┌──────────────┐
│ Normalize │
│ Deduplicate │
│ (10 min) │
└───────┬──────┘
│
▼
┌──────────────┐
│ Category: │
│ Auth/Network │
│ /Endpoint │
└───────┬──────┘
│
▼
┌──────────────┐
│ Severity │
│ Score │
│ (0-100) │
└───────┬──────┘
│
▼
┌──────────────┐
│ Priority: │
│ P1/P2/P3/P4 │
└───────┬──────┘
│
┌───┴───┐
│ │
┌───────▼──┐ ┌─▼─────────┐
│ P1/P2: │ │ P3/P4: │
│ Immediate│ │ Digest │
│ Alert │ │ (Hourly) │
└──────────┘ └───────────┘
```
## 严重性评分逻辑
### 身份验证类别
- 基础分：每条规则 0-10
- **1小时内登录失败 >50 次** → +40 (严重)
- **1小时内登录失败 >20 次** → +30 (高)
- **1小时内登录失败 >5 次** → +15 (中)
### 恶意软件类别
- 始终在基础分上 **+50**（自动升级）
- Rootkit/勒索软件 → 最高紧急程度
### 终端类别
- 权限提升 → +35
- 修改 /etc 下的文件 → +20
### 网络类别
- 检测到端口扫描 → +25
- 出站连接至已知恶意 IP → +20
- 横向移动 → +25
### 最终映射
- **85-100** → P1 (严重) — 立即响应
- **65-84** → P2 (高) — 15分钟内响应
- **40-64** → P3 (中) — 1小时内响应
- **0-39** → P4 (低) — 下一个工作日响应
## 日志与监控
### 日志文件
- `soc_triage_bot.log` — 主应用程序日志
- `.alerts.json` — 警报存储（已解决的警报会在此跟踪）
### 指标
仪表板提供：
- 按严重性划分的活动警报数量
- 24小时警报趋势
- 类别明细
- 优先级层级分布
- 平均严重性评分
## 集成
### ✅ 已实现
- **Wazuh** (SIEM)
- **Telegram**（通知）
- **Slack**（通知）
- **通用 JSON** (webhooks)
### 🔜 计划中
- Splunk/Elastic webhook 接入
- PagerDuty 升级
- ServiceNow 工单创建
- Incident.io 集成
- 自定义 HTTP 回调
## 错误处理
| 错误 | 恢复 |
|-------|----------|
| Wazuh 无法连接 | 记录错误，跳过接入，继续循环 |
| Telegram/Slack 离线 | 批处理至待定摘要，在下个周期重试 |
| 无效的 JSON payload | 记录并跳过，不会导致崩溃 |
| 缺少配置文件 | 使用硬编码的默认值，继续运行 |
## 性能与可扩展性
- **去重**：内存缓存（10分钟时间窗口）防止重复处理
- **警报保留**：可配置（默认 30 天）
- **吞吐量**：在现代硬件上约为 100 个警报/秒
- **内存**：基准约为 50MB + 每个警报约 1KB
- **CPU**：极低；主要受 I/O 限制（API 调用、通知）
## 安全
⚠️ **重要提示**
- **.env 文件**：切勿提交至 git；添加到 `.gitignore` 中
- **API Keys**：存储在环境变量中，不要写在代码里
- **HTTPS**：所有 Wazuh/Slack API 调用均使用 TLS
- **日志**：可能包含 IP 地址；请确保日志文件访问安全
- **Webhook 认证**：在生产环境中添加认证中间件
### .gitignore
```
.env
.alerts.json
*.log
__pycache__/
*.pyc
.DS_Store
```
## 故障排除
### "ModuleNotFoundError: No module named 'X'"
安装依赖项：
```
pip install -r requirements.txt
```
### "Wazuh 连接失败"
1. 检查 `.env` 中的 `WAZUH_HOST`
2. 验证凭据
3. 确保 Wazuh API 可访问（端口 55000）
4. 先尝试演示模式：`python bot.py once --demo`
### "Telegram 未发送"
1. 验证 `TELEGRAM_BOT_TOKEN` 是否有效（格式：`123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11`）
2. 检查 `TELEGRAM_CHAT_ID` 是否为数字
3. 确保机器人有权限发送到该聊天
### "没有显示任何 alerts"
1. 演示模式：`python bot.py once --demo` 应加载 25 个测试警报
2. Wazuh 模式：检查 Wazuh 是否有最近的警报
3. 检查当前目录下是否存在 `demo_alerts.json`
## 演示数据
`demo_alerts.json` 文件包含 25 个真实的混合警报：
- SSH 暴力破解尝试 (6)
- 权限提升 (2)
- 端口扫描 (2)
- 恶意软件/rootkit 检测 (2)
- 文件修改 (1)
- 横向移动 (1)
- 合规违规 (1)
- 用户账户创建 (1)
- 身份验证失败 (2)
- 出站连接至已知恶意 IP (1)
- 侦察活动 (1)
- 可疑的 cron jobs (1)
混合了 P1/P2/P3/P4 优先级，用于测试完整的 pipeline。
## 作者
**Nnaemeka Duru**
安全工程师 | SOC 自动化专家
emekaduru09@gmail.com
## 许可证
MIT License - 随意 fork、修改并在您的组织中使用。
## 贡献
发现了 bug？有功能请求？
1. 提交一个 issue
2. 创建功能分支 (`git checkout -b feature/amazing-thing`)
3. 提交您的更改 (`git commit -m 'Add amazing thing'`)
4. 推送到分支 (`git push origin feature/amazing-thing`)
5. 发起一个 Pull Request
## 路线图
- [x] Webhook HTTP 服务器 (FastAPI)
- [ ] PagerDuty 升级策略
- [ ] ServiceNow 工单自动创建
- [ ] Splunk/Elastic 接入适配器
- [ ] 警报关联引擎（多警报模式）
- [ ] 自定义响应 playbook
- [ ] Web UI 仪表板 (React)
- [ ] 数据库后端 (PostgreSQL)
- [ ] Kubernetes/Docker 部署
- [ ] 警报历史/取证存储
**用 ❤️ 为值得拥有更好工具的安全团队而打造。**
标签：PE 加载器, Python, SIEM集成, Web报告查看器, 告警分诊, 安全告警, 安全运营, 扫描框架, 插件系统, 无后门, 自动化响应, 逆向工具