alisterrodrigues/soc-threat-detection-pipeline
GitHub: alisterrodrigues/soc-threat-detection-pipeline
基于 Python 的 Windows Sysmon 日志行为威胁检测引擎，将原始端点遥测数据通过 MITRE ATT&CK 映射规则转换为带风险评分的 Incident 并生成分析报告。
Stars: 0 | Forks: 0
# SOC 威胁检测流水线
[](https://github.com/alisterrodrigues/soc-threat-detection-pipeline/actions/workflows/ci.yml)
一个基于 Python 的 Windows Sysmon 日志行为威胁检测引擎。该引擎摄取原始端点遥测数据，根据映射到 MITRE ATT&CK 的检测规则评估事件，将告警关联为带评分的Incident，并通过终端仪表板、分析人员分类 CLI 和独立的 HTML 报告展示结果 — 完成从原始日志到已处置Incident的完整分析人员工作流程，完全离线运行。
## 功能覆盖
该流水线对完整的 SOC 分析人员工作流程进行端到端建模：
- **检测** — 涵盖进程创建、网络连接、注册表修改和进程访问事件的 15 条行为规则，每条规则映射到特定的 MITRE ATT&CK 技术，并记录了误报指南
- **关联** — 在可配置时间窗口内同一主机上的告警被分组为Incident，标注攻击链覆盖范围，并进行 0-100 的风险评分
- **分析人员工作流程** — 告警持久化到 SQLite 并支持处置；分类 CLI 允许分析人员标记真/假阳性并跟踪各规则的误报率随时间的变化
- **报告** — 独立的 HTML 报告总结Incident、匹配字段和 ATT&CK 覆盖范围，无需任何外部工具即可打开
示例数据集包含两台主机和两个不同的攻击场景 — Word 宏加载程序链和 Excel 宏持久化链 — 因此关联器开箱即用产生两个具有不同风险配置文件的独立Incident。
## 架构
```
flowchart TD
A[("Sysmon XML\n/ EVTX")] --> B["parser.py\nevtx_parser.py"]
B --> C["enricher.py\nProcess tree + parent flag"]
C --> D["rule_engine.py\nCondition evaluation"]
K[("rules/*.yaml\n15 ATT&CK rules")] --> D
L[("config/config.yaml")] --> D
D --> E[("alert_store.py\nSQLite")]
D --> F["correlator.py\nHost + time window"]
F --> G["scorer.py\n0–100 risk score"]
E --> H["terminal_ui.py\nRich dashboard"]
E --> I["reporter.py\nHTML report"]
E --> J["triage.py\nAnalyst CLI"]
G --> I
G --> H
```
## 快速开始
**要求：** Python 3.11+
```
git clone https://github.com/alisterrodrigues/soc-threat-detection-pipeline.git
cd soc-threat-detection-pipeline
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
# 对包含的示例数据运行
python -m cli.main --input sample_data/sysmon_events_sample.xml --benchmark
# 运行测试
pip install -r requirements-dev.txt
pytest tests/ -v
```
示例数据集包含 30 个 Sysmon 事件，分布在两台主机和两个攻击场景中。正常运行会在两台主机上产生 25 个告警，关联器将其分组为两个不同的Incident。
## CLI 参考
### 主流水线 — `python -m cli.main`
| 标志 | 描述 |
|------|-------------|
| `--input FILE` | Sysmon XML 或 EVTX 日志文件的路径 **（必需）** |
| `--evtx` | 将 `--input` 视为 `.evtx` 文件 — 需要 `pip install python-evtx` |
| `--config FILE` | config.yaml 的路径 `[默认：config/config.yaml]` |
| `--output-dir DIR` | 输出文件的目录 `[默认：output/]` |
| `--severity LEVEL` | 存储的最低严重级别：`low\|medium\|high\|critical` |
| `--benchmark` | 完成后打印吞吐量和告警摘要 |
| `--export FORMAT` | 处理后导出告警：`json\|csv\|both` |
| `--report` | 生成独立的 `output/incident_report.html` |
| `--no-dashboard` | 无头模式 — 将告警 JSON 流式输出到 stdout |
| `--live` | 实时尾部仪表板 — 轮询数据库直到 Ctrl+C |
| `--explain` | 打印每个告警的条件匹配细分 |
| `--correlate` | 运行关联引擎并将Incident摘要打印到 stdout |
| `--hunt TERMS` | 在所有告警字段中搜索逗号分隔的关键字 |
### 分析人员分类 — `python -m cli.triage`
| 标志 | 描述 |
|------|-------------|
| `--db PATH` | 告警数据库的路径 `[默认：output/alerts.db]` |
| `--rule RULE_ID` | 过滤到特定规则 ID（例如 `PROC-001`） |
| `--severity LEVEL` | 最低严重级别过滤器：`low\|medium\|high\|critical` — 显示此级别及以上的告警 |
| `--undispositioned` | 仅显示尚未审查的告警 |
| `--stats` | 打印每个规则的 TP/FP 摘要表并退出 |
### Sigma 转换器 — `python tools/sigma_converter.py`
| 标志 | 描述 |
|------|-------------|
| `--input PATH` | Sigma `.yml` 文件或规则目录 **（必需）** |
| `--output PATH` | 输出文件或目录 — 如果省略则打印到 stdout |
| `--verbose` | 显示所有转换警告 |
## 检测规则
15 条规则涵盖四个 Sysmon 事件类别。每条规则映射到特定的 ATT&CK 技术，记录已知的误报来源，并包含用于未来允许列表集成的 `tuning_tag`。
| 规则 ID | 名称 | 事件 | 技术 | 战术 | 严重级别 |
|---------|------|:-----:|-----------|--------|:--------:|
| PROC-001 | 可疑的 PowerShell 编码命令 | 1 | T1059.001 | 执行 | 高 |
| PROC-002 | Office 应用程序生成命令 Shell | 1 | T1059.003 | 执行 | 高 |
| PROC-003 | Net User 或组枚举 | 1 | T1087.001 | 发现 | 中 |
| PROC-004 | Whoami 执行 | 1 | T1033 | 发现 | 低 |
| PROC-005 | Certutil 用于文件下载或解码 | 1 | T1105 | 命令与控制 | 高 |
| PROC-006 | MSHTA 执行 | 1 | T1218.005 | 防御规避 | 高 |
| NET-001 | 浏览器非标准端口出站 | 3 | T1571 | 命令与控制 | 中 |
| NET-002 | 无主机名的 IP 地址连接 | 3 | T1071 | 命令与控制 | 中 |
| NET-003 | 脚本宿主网络连接 | 3 | T1059.005 | 执行 | 高 |
| REG-001 | Run 键持久化 | 13 | T1547.001 | 持久化 | 高 |
| REG-002 | 通过注册表禁用 Windows Defender | 13 | T1562.001 | 防御规避 | 严重 |
| REG-003 | 通过注册表的 UAC 绕过 | 13 | T1548.002 | 权限提升 | 严重 |
| PA-001 | LSASS 内存访问 | 10 | T1003.001 | 凭证访问 | 严重 |
| PA-002 | LSASS 上的高权限访问掩码 | 10 | T1003.001 | 凭证访问 | 严重 |
| PA-003 | 非系统二进制文件访问敏感进程 | 10 | T1055 | 防御规避 | 高 |
规则以纯 YAML 格式存放在 `rules/` 目录中。引擎在启动时发现所有 `*.yaml` 文件 — 添加或修改检测无需更改代码。完整的规则架构和操作符参考请参阅 [`docs/rule_authoring_guide.md`](
标签：AMSI绕过, Cloudflare, Conpot, EDR, HTML报告, IP 地址批量处理, MITRE ATT&CK, Object Callbacks, PE 加载器, Python安全工具, SQLite, Sysmon, Windows安全, 告警关联, 威胁情报, 威胁检测, 安全运营, 开发者工具, 恶意宏, 扫描框架, 搜索语句（dork）, 无线安全, 注册表监控, 端点检测响应, 网络钓鱼, 脆弱性评估, 行为检测, 误报分析, 请求拦截, 风险评分