saadabbasi-playground/detectionvalidation
GitHub: saadabbasi-playground/detectionvalidation
一个多 SIEM 检测规则验证平台，通过模拟真实 CVE 攻击并捕获内核遥测数据，自动验证 Sigma/SPL/KQL 检测规则的有效性并映射 MITRE ATT&CK 覆盖情况。
Stars: 0 | Forks: 0
# detection-validator
在单台搭载 Apple Silicon 的 MacBook 上，针对 Linux 受害者模拟真实的基于 CVE 的攻击，捕获真正的内核级审计事件，并测试你的检测规则是否真正触发。
```
Vagrant VM (Ubuntu 22.04 ARM64) Mac host
┌─────────────────────────┐ ┌──────────────────────────────────────┐
│ auditd │ │ Docker │
│ victim-agent │──────▶ │ OpenSearch (localhost:9200) │
│ vector (shipper) │ HEC │ Splunk mock (localhost:8000/8088) │
└─────────────────────────┘ └──────────────────────────────────────┘
▲ │
│ dv attack │ dv validate
└─ simulate CVE exploit steps └─ query for rule hits
```
## 最快上手 —— 一条命令
### macOS（需要 Docker Desktop、Vagrant、vagrant-qemu、Python 3.12）
```
git clone https://github.com/saadabbasi-playground/detectionvalidation.git detection-validator
cd detection-validator
uv venv && uv pip install -e ".[dev]"
source .venv/bin/activate
export OPENSEARCH_INITIAL_ADMIN_PASSWORD="DetectVal123!"
dv demo
```
`dv demo` 会启动 Docker stack，引导 VM，运行金丝雀检查，触发 Log4Shell 漏洞利用，等待遥测数据，并验证 9 条 Sigma 规则 —— 一步到位。预期结果：**7 PASS / 2 FAIL**（此场景中故意排除了 LSASS 和 Nmap）。
### Windows（需要 Docker Desktop + WSL2、Git Bash、Python 3.12、uv）
```
# PowerShell
git clone https://github.com/saadabbasi-playground/detectionvalidation.git detection-validator
cd detection-validator
uv venv; uv pip install -e ".[dev]"
.\.venv\Scripts\Activate.ps1
$env:PYTHONUTF8 = "1"; $env:PYTHONIOENCODING = "utf-8"; chcp 65001 | Out-Null
$env:OPENSEARCH_INITIAL_ADMIN_PASSWORD = "DetectVal123!"
```
```
# Git Bash — 启动 Docker stack
docker network create detectval-lab 2>/dev/null || true
OPENSEARCH_INITIAL_ADMIN_PASSWORD="DetectVal123!" bash ./dv up lab --siem opensearch --profile standard
```
```
# PowerShell — 运行攻击 + 验证（在容器健康后）
dv attack --cve CVE-2021-44228 --target docker --mode simulate
dv validate examples/detections/sigma/ --since 1
```
预期结果：**5 PASS / 3 FAIL**（LSASS、MSHTA 和 Nmap 需要 Windows 目标或主动的 Nmap 扫描）。完整详情请参阅 [docs/windows-quickstart.md](docs/windows-quickstart.md)。
## 什么是 `dv`？
有两个独立的工具，都叫 `dv`：
| 工具 | 文件 | 功能 |
|---|---|---|
| `./dv` | 项目根目录下的 Shell 脚本 | 启动/停止 Docker 容器（`./dv up`、`./dv down`） |
| `dv` | 安装到 `.venv/` 的 Python CLI | 运行攻击，验证规则，生成报告 |
## 前置条件
在运行任何内容之前，你需要先安装这些。
### macOS
| 工具 | 要求版本 | 安装命令 |
|---|---|---|
| Docker Desktop | ≥ 24 | [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop/) |
| Python | 3.12 | `brew install python@3.12` |
| uv（Python 包管理器） | 任意 | `brew install uv` |
| Vagrant | 任意 | `brew install vagrant` |
| vagrant-qemu 插件 | 任意 | `vagrant plugin install vagrant-qemu` |
### Windows
| 工具 | 要求版本 | 安装命令 |
|---|---|---|
| Docker Desktop | ≥ 24（WSL2 后端） | [docker.com/products/docker-desktop](https://www.docker.com/products/docker-desktop/) |
| Git + Git Bash | 任意 | [git-scm.com](https://git-scm.com/downloads) |
| Python | 3.12 | `winget install Python.Python.3.12` |
| uv（Python 包管理器） | 任意 | `winget install astral-sh.uv` |
| Vagrant | 可选 | `winget install HashiCorp.Vagrant`（需要 Hyper-V） |
完整的 Windows 设置演练请参阅 [docs/windows-quickstart.md](docs/windows-quickstart.md)。
## 安装说明
### macOS / Linux
按顺序运行以下命令一次：
```
# 1. 克隆仓库
git clone https://github.com/saadabbasi-playground/detectionvalidation.git detection-validator
cd detection-validator
# 2. 创建 Python 虚拟环境并安装该工具
uv venv
uv pip install -e ".[dev]"
# 3. 激活虚拟环境
source .venv/bin/activate
# 4. 确认 CLI 可用
dv --help
```
### Windows
```
# 1. 克隆仓库
git clone https://github.com/saadabbasi-playground/detectionvalidation.git detection-validator
cd detection-validator
# 2. 创建 Python 虚拟环境并安装该工具
uv venv
uv pip install -e ".[dev]"
# 3. 激活虚拟环境
.\.venv\Scripts\Activate.ps1
# 4. 启用 UTF-8（必需 — dv 在输出中使用 Unicode 符号）
$env:PYTHONUTF8 = "1"
$env:PYTHONIOENCODING = "utf-8"
chcp 65001 | Out-Null
# 5. 确认 CLI 可用
dv --help
```
完整的 Windows 演练（包括 Docker stack 设置和已知问题）请参阅 [docs/windows-quickstart.md](docs/windows-quickstart.md)。
## 第 1 步 —— 检查你的环境
在开始任何操作之前，运行预检查：
```
dv doctor
```
这将检查 Python、Docker、Vagrant、Docker 网络、正在运行的容器、受害者代理和本地情报缓存。在继续之前修复任何 ✗ 错误。⚠ 警告不会造成阻塞。
一切安装并运行后的预期输出：
```
dv doctor — environment pre-flight check
✓ Python 3.12.5
✓ uv 0.11.13
✓ Docker 28.3.2
✓ Docker daemon running
✓ Docker network detectval-lab
✓ Vagrant 2.4.9
✓ Vagrant plugin vagrant-qemu
✓ Vagrant VM running
✓ OPENSEARCH_INITIAL_ADMIN_PASSWORD set
✓ OpenSearch reachable (HTTP 200)
✓ Splunk mock reachable (HTTP 200)
✓ Victim agent reachable on port 9098 (Vagrant)
✓ ATT&CK KB: 858 techniques
✓ KEV cache: 1243 entries
All checks passed.
```
`dv doctor --fix` 会自动下载空的情报缓存（ATT&CK 知识库、CVE 数据）。
## 第 2 步 —— 启动 Docker stack
Docker stack 运行 OpenSearch（即 SIEM）、一个 Splunk mock 接收器、Vector（日志转发器）和一个 Linux 受害者容器。
### macOS
```
# 永久保存 OpenSearch 管理员密码（运行一次）
echo 'export OPENSEARCH_INITIAL_ADMIN_PASSWORD="DetectVal123!"' >> ~/.zshrc
source ~/.zshrc
# 启动实验环境 stack
./dv up lab --siem opensearch --profile standard
```
### Windows (Git Bash)
```
# 创建 Docker network（一次性设置）
docker network create detectval-lab
# 启动实验环境 stack
OPENSEARCH_INITIAL_ADMIN_PASSWORD="DetectVal123!" bash ./dv up lab --siem opensearch --profile standard
```
等待大约 60 秒让容器变得健康，然后检查：
```
docker ps --format "table {{.Names}}\t{{.Status}}"
```
预期输出（`standard` 配置，无 dashboards）：
```
NAMES STATUS
dv-linux-victim Up 2 minutes (healthy)
dv-vector Up 2 minutes (healthy)
dv-opensearch Up 2 minutes (healthy)
dv-redis Up 2 minutes (healthy)
```
每个容器都应显示 `(healthy)`。如果显示 `(starting)`，请再等待 30 秒并重新检查。
验证 OpenSearch 正在接受连接：
```
dv siem status
```
预期：
```
✓ OpenSearch 2.14.0 at https://localhost:9200
dv-telemetry-*: 0 documents
```
## 第 3 步 —— 启动 Vagrant VM
Vagrant VM 运行带有 `auditd` 的真实 Ubuntu 22.04 内核。这为你提供了真正的 syscall 级别遥测 —— 检测规则真正需要针对其触发的那种遥测。Mac 上的 Docker 容器无法公开内核审计子系统，这就是需要 VM 的原因。
```
cd vagrant
vagrant up
```
首次运行大约需要 5 分钟来下载 box 文件并配置 VM。随后的运行大约需要 ~30 秒。你会看到大量输出 —— 这是正常的。
完成后，验证 VM 内的服务是否正在运行：
```
vagrant ssh -c "systemctl status victim-agent vector --no-pager"
```
两者都应显示 `active (running)`。
验证从你的 Mac 可以连接到该代理：
```
curl http://localhost:9098/health
```
预期：
```
{"status": "ok", "host": "dv-victim", "mode": "vm"}
```
现在返回项目根目录：
```
cd ..
```
## 第 4 步 —— 运行攻击
有两种模式可用。使用 `--mode exploit`（向易受攻击的服务发送真实的 HTTP payload）以获得最真实的遥测数据，或者省略它以进行轻量级模拟。
### 模式：exploit（推荐 —— 真实内核事件，仅限 macOS/Linux）
向 VM 上运行的故意保留漏洞的服务发送实际的 HTTP 漏洞利用 payload。该服务触发真实的 `curl`、`id` 和 `/etc/passwd` 读取 —— 被 auditd 捕获为真正的内核 syscall 事件。
```
dv attack --cve CVE-2021-44228 --target vagrant --mode exploit
dv attack --cve CVE-2021-26855 --target vagrant --mode exploit
```
Log4Shell 的预期输出：
```
⚔ Running attack scenario cve=CVE-2021-44228 target=vagrant
Mode: exploit — sending real HTTP payloads to http://localhost:9088
Log4Shell JNDI injection via X-Api-Version header
✓ T1190 + T1059.004 status=exploited
uid=33(www-data) gid=33(www-data) groups=33(www-data)
✓ 1 exploit(s) delivered.
```
在攻击之前验证易受攻击的服务是否可达：
```
curl http://localhost:9088/health
# 预期结果：{"status": "vulnerable"}
```
### 模式：simulate（轻量级 —— 合成事件）
将手工制作的审计记录直接发布给受害者代理。不执行真正的漏洞利用。当你只需要快速获取遥测数据而不关心真实性时非常有用。
macOS（Vagrant 目标）：
```
dv attack --cve CVE-2021-44228 --target vagrant --agent-port 9098 --watch
dv attack --cve CVE-2021-34527 --target vagrant --agent-port 9098 --watch
dv attack --cve CVE-2021-26855 --target vagrant --agent-port 9098 --watch
```
Windows（Docker 目标）：
```
dv attack --cve CVE-2021-44228 --target docker --mode simulate
dv attack --cve CVE-2021-34527 --target docker --mode simulate
dv attack --cve CVE-2021-26855 --target docker --mode simulate
```
### 可用的 CVE 场景
| CVE | 漏洞 | ATT&CK 技术 |
|---|---|---|
| `CVE-2021-44228` | Log4Shell RCE | T1190, T1059.004 |
| `CVE-2021-34527` | PrintNightmare | T1068, T1547.012, T1574.001 |
| `CVE-2021-26855` | ProxyLogon SSRF | T1190, T1505.003, T1078, T1552.001 |
## 第 5 步 —— 验证你的检测
```
dv validate examples/detections/sigma/ --since 1
```
这会加载该目录中的每个 Sigma 规则，为每个规则构建查询，在 OpenSearch 上运行它，并报告 PASS 或 FAIL：
```
Rule Techniques Hits SIEM Status
LSASS Memory Dump via TM T1003.001 0 opensearch ✗ FAIL
Log4Shell JNDI Injection T1190, T1059.004 156 opensearch ✓ PASS
Log4Shell RCE - Outbound Conn T1190, T1059.004 1 opensearch ✓ PASS
MSHTA Spawning Windows Shell T1218.005, T1059.001 94 opensearch ✓ PASS
Nmap Port Scan Detected T1046 0 opensearch ✗ FAIL
PrintNightmare Spooler Abuse T1068, T1547.012 14 opensearch ✓ PASS
ProxyLogon Exchange SSRF T1190, T1505.003 62 opensearch ✓ PASS
ProxyLogon - Sensitive File T1190, T1552.001 32 opensearch ✓ PASS
Results: 8 rule(s) 6 PASS 2 FAIL 0 ERROR 0 SKIP
```
### 规则如何通过
验证器使用三层策略：
1. **Sigma 字段级转换** —— 将 `detection:` 块转换为 OpenSearch 查询并运行它。最精确。
2. **技术 ID 匹配** —— 将 `technique` 字段与规则标签中的 ATT&CK ID 进行匹配。
3. **关键字匹配** —— 跨 `proctitle`、`cmd_output` 和 `message` 进行自由文本搜索。
### 时间窗口
`--since 1` 表示“查看过去 1 小时”。如果你运行攻击的时间超过了 1 小时，请增大时间窗口：
```
dv validate examples/detections/sigma/ --since 24 # last 24 hours
dv validate examples/detections/sigma/ --since 48 # last 48 hours
```
## 第 6 步 —— 生成报告
### CLI 摘要
```
dv validate examples/detections/sigma/ --since 24 --format json | dv report
```
输出：
```
╭─────── Validation Summary ────────╮
│ Rules: 7 │
│ Pass: 4 (57%) │
│ Fail: 3 │
│ Error: 0 │
│ Skip: 0 │
│ │
│ Techniques: 8 covered / 12 total │
│ Generated: 2026-05-26 04:26 UTC │
╰───────────────────────────────────╯
Failing rules
Rule Techniques SIEM Status
LSASS Memory Dump T1003.001 opensearch ✗ FAIL
MSHTA Spawning T1218.005,T1059 opensearch ✗ FAIL
Nmap Port Scan T1046 opensearch ✗ FAIL
ATT&CK Tactic Coverage
Tactic Coverage Techniques covered
Credential Access 0/1 (0%) —
Defense Evasion 1/2 (50%) T1078
Execution 1/2 (50%) T1059.004
Impact 1/1 (100%) T1499
Initial Access 1/1 (100%) T1190
Persistence 2/2 (100%) T1505.003, T1547.012
Privilege Escalation 2/2 (100%) T1068, T1574.001
Passing rules (4): Log4Shell JNDI Injection, PrintNightmare, ProxyLogon, Test
```
### HTML 报告
```
dv validate examples/detections/sigma/ --since 24 --format json | dv report --format html -o report.html
open report.html
```
### SARIF（用于 GitHub Code Scanning）
```
dv validate examples/detections/sigma/ --since 24 --format json | dv report --format sarif -o scan.sarif
```
将 `scan.sarif` 上传到 GitHub Code Scanning，未通过的规则将作为注解显示在 pull request 上。
### 先保存结果，稍后再生成报告
```
# 将结果保存到文件
dv validate examples/detections/sigma/ --since 24 --format json -o results.json
# 稍后渲染已保存的结果
dv report --results results.json
dv report --results results.json --format html -o report.html
```
## 第 7 步 —— 离线匹配（无需 SIEM）
`dv match` 针对本地 JSONL 文件评估规则，而不是查询实时 SIEM。在 CI 中或 Docker stack 未运行时使用此功能。
### 从 Vagrant VM 导出事件
```
vagrant ssh -c "sudo cat /var/log/audit/audit-events.jsonl" > events.jsonl
```
### 从 OpenSearch 导出事件
```
curl -sk -u "admin:${OPENSEARCH_INITIAL_ADMIN_PASSWORD}" \
"https://localhost:9200/dv-telemetry-*/_search?size=1000" \
-H 'Content-Type: application/json' \
-d '{"query":{"term":{"source.keyword":"auditd-agent"}}}' \
| python3 -c "
import json, sys
for h in json.load(sys.stdin)['hits']['hits']:
print(json.dumps(h['_source']))
" > events.jsonl
```
### 运行匹配
```
dv match --events events.jsonl examples/detections/sigma/ --since 0 --format json | dv report
```
`--since 0` 表示“使用文件中的所有事件，不考虑时间戳”。请注意评估时间 —— 通常在 0.05 秒以下，因为所有操作都在内存中运行，没有网络调用。
## 离线分析流水线
此序列完全在磁盘上解析、映射并丰富你的规则 —— 无需 SIEM 或网络。
```
# 1. 将所有规则文件解析为统一的 JSON 格式
dv ingest examples/detections/sigma/ -o canonical.jsonl
# 2. 验证规则并映射到 ATT&CK 技术
dv map -i canonical.jsonl -o mapped.jsonl
# 3. 填充技术名称、CVE 元数据和严重性评分
dv enrich -i mapped.jsonl -o enriched.jsonl
```
丰富后你可以：
```
# 生成 ATT&CK Navigator 层（显示你覆盖了哪些技术）
dv navigator -d enriched.jsonl -o layer.json
# 打开 https://mitre-attack.github.io/attack-navigator/
# 点击 "Open Existing Layer" → "Upload from local" → 选择 layer.json
# 生成覆盖率徽章
dv badge -d enriched.jsonl --format json # JSON metrics
dv badge -d enriched.jsonl -o coverage.svg # SVG badge
```
## CVE 覆盖率分析
此工作流回答：*“我是否有针对攻击者利用此 CVE 时所使用技术的检测？”*
```
# 1. 更新本地情报缓存（运行一次；每月重新运行）
dv intel update --source attack
dv intel update --source cve
# 2. 构建增强语料库（与上述 pipeline 相同）
dv ingest examples/detections/ -o canonical.jsonl
dv map -i canonical.jsonl -o mapped.jsonl
dv enrich -i mapped.jsonl -o enriched.jsonl
# 3. 分析一个或多个 CVE 的覆盖率
dv cve-coverage --cve CVE-2021-44228 -d enriched.jsonl
dv cve-coverage --cve CVE-2021-44228,CVE-2021-34527,CVE-2021-26855 -d enriched.jsonl
```
示例输出：
```
CVE-2021-44228 KEV CVSS=10.0 EPSS=0.945 coverage=100% residual_risk=0.000
✓ T1059 execution conf=0.85 ← Log4Shell JNDI Injection Attempt
✓ T1190 initial-access conf=0.80 ← Log4Shell JNDI Injection Attempt
✓ T1499 impact conf=0.60 ← Test
```
**阅读输出：**
| 字段 | 含义 |
|---|---|
| **KEV** | 此 CVE 在 CISA 的已知被利用漏洞目录中 —— 正在野外被积极利用 |
| **CVSS** | 来自 NVD 的严重性评分（0–10，分数越高越严重） |
| **EPSS** | 未来 30 天内的漏洞利用概率（来源：FIRST.org） |
| **coverage** | 至少被一个检测覆盖的已映射技术的百分比 |
| **residual_risk** | `CVSS × EPSS × (1 − coverage)` —— 剩余的未覆盖风险；越低越好 |
| **conf** | 映射置信度：1.0 = 显式规则标签；~0.85 = CTID 数据集；CWE 推断则不固定 |
### 弥补覆盖率差距
如果 `cve-coverage` 对某项技术显示 ✗，请将该技术添加到规则中：
```
# 在你的 Sigma 规则的 tags 部分中：
tags:
- attack.T1499 # the technique you want to cover
- cve.2021.44228 # links this rule to the CVE in coverage reports
```
然后重新运行 `ingest → map → enrich → cve-coverage` 以确认差距已弥补。
## 格式转换（migrate）
在无需触及 SIEM 的情况下转换检测规则的格式：
```
# Sigma → Splunk savedsearches.conf
dv migrate sigma splunk --rules examples/detections/sigma/ -o searches.conf
# Sigma → KQL (Azure Sentinel / Microsoft Defender)
dv migrate sigma kql --rules examples/detections/sigma/ -o queries.kql
# 规范化并重新导出为干净的 Sigma YAML
dv migrate sigma sigma --rules examples/detections/sigma/ -o normalised/
```
## 使用现有的 SIEM
你可以将 `dv` 指向一个你已经在运行的 SIEM —— 本地部署的 OpenSearch、Elastic Cloud、内部 Splunk 实例等 —— 以替代（或附加于）本地 Docker 实例。
凭据存储在 `~/.detectionvalidator/siems.yaml` 中，永远不会触及项目目录。
### 第 1 步 —— 注册 SIEM
```
# OpenSearch / AWS OpenSearch Service
dv siem add prod \
--type opensearch \
--url https://opensearch.example.com:9200 \
--username admin --password secret
# 自签名或内部证书？添加 --no-verify-tls
dv siem add internal \
--type opensearch \
--url https://192.168.1.50:9200 \
--username admin --password secret \
--no-verify-tls
# Elastic Cloud
dv siem add elastic-cloud \
--type elasticsearch \
--url https://my-deployment.es.us-east-1.aws.elastic.co:9243 \
--api-key YOUR_API_KEY_HERE
# Splunk (HTTP Event Collector)
dv siem add splunk-prod \
--type splunk \
--url https://splunk.example.com:8088 \
--token YOUR_HEC_TOKEN_HERE
```
使用相同名称第二次运行 `dv siem add` 将覆盖该条目。
### 第 2 步 —— 验证连通性
```
# 列出所有已注册的内容
dv siem list
# 测试命名连接 — 检查认证、统计文档数、显示 3 个示例事件
dv siem test prod
```
### 第 3 步 —— 针对它验证规则
将注册的名称传递给 `--siem`，而不是 `opensearch` 或 `splunk`：
```
dv validate examples/detections/sigma/ --siem prod --since 24
```
### 第 4 步 —— 将遥测数据发送给它（可选）
如果你希望 Vagrant VM 将其 auditd 事件发送到你的 SIEM 以及本地 Docker OpenSearch 中，请运行：
```
dv siem attach prod
```
这会通过 SSH 连接到 VM，将一个新的 sink 附加到 `/etc/vector/vector.toml`，验证配置，然后重启 Vector。本地流水线继续运行 —— `attach` 只是添加了第二个输出。新的 sink 使用 `when_full = "drop_newest"`，因此缓慢的外部 SIEM 永远不会阻塞本地流水线。
### Index pattern
默认情况下 `dv` 查询 `dv-telemetry-*`。如果你的 SIEM 使用不同的索引或数据流，请在注册时覆盖它：
```
dv siem add prod \
--type opensearch \
--url https://opensearch.example.com:9200 \
--username admin --password secret \
--index logs-endpoint-*
```
或针对每个命令进行覆盖：
```
dv validate examples/detections/sigma/ --siem prod --index logs-endpoint-* --since 24
```
## 部署规则到实时 SIEM
直接将规则推送到运行中的 SIEM，以便它们在新事件上自动触发。
```
# 始终先预览 — 这不会进行任何更改
dv deploy examples/detections/sigma/ --siem opensearch --dry-run
# 正式部署 — 为每条规则创建一个 OpenSearch Alerting monitor
dv deploy examples/detections/sigma/ --siem opensearch
# 部署到 Splunk — 创建带有每小时计划的 saved searches
dv deploy examples/detections/sigma/ --siem splunk
```
## 使用 watch 进行实时规则开发
`dv watch` 会轮询你的规则目录，并在你每次保存文件时重新运行验证：
```
# 快速离线反馈 — 每次保存时针对本地事件文件重新匹配
dv watch examples/detections/sigma/ --events events.jsonl
# 实时反馈 — 每次保存时重新查询 OpenSearch
dv watch examples/detections/sigma/ --siem opensearch --since 1
# 在活跃开发期间增加轮询频率
dv watch examples/detections/sigma/ --events events.jsonl --interval 2
```
按 `Ctrl+C` 停止。
## 检查运行中的 stack
```
# 检查 OpenSearch 版本、连接性和文档计数
dv siem status
# 运行测试查询并显示最新事件
dv siem test --size 5
# 检查受害端 agent 健康状况
dv agent status
# 一行命令检查 SIEM 和 agent
dv siem status && dv agent status
```
## 在 OpenSearch Dashboards 中查看遥测数据
在浏览器中打开 `https://localhost:5601`。使用用户名 `admin` 和你在 `OPENSEARCH_INITIAL_ADMIN_PASSWORD` 中设置的密码登录。
转到 **Discover** 并选择 `dv-telemetry-*` 索引模式。设置时间范围（右上角）以覆盖你最近的一次攻击运行。
实用的 KQL 查询：
| 查询 | 显示内容 |
|---|---|
| `host: dv-victim` | 来自 Vagrant VM 的所有事件 |
| `technique.keyword: T1190` | 漏洞利用事件 |
| `technique.keyword: T1059.004` | Shell 执行事件 |
| `technique.keyword: T1068` | 权限提升事件 |
| `proctitle: jnd` | 针对 Log4Shell payload 的自由文本搜索 |
### 直接 API 访问
```
# 列出最近的 5 个事件
curl -sk -u "admin:${OPENSEARCH_INITIAL_ADMIN_PASSWORD}" \
"https://localhost:9200/dv-telemetry-*/_search?size=5&sort=timestamp:desc&pretty"
# 搜索特定技术
curl -sk -u "admin:${OPENSEARCH_INITIAL_ADMIN_PASSWORD}" \
"https://localhost:9200/dv-telemetry-*/_search?pretty" \
-H 'Content-Type: application/json' \
-d '{"query": {"term": {"technique.keyword": "T1190"}}}'
```
## 遥测字段参考
受害者代理写入的事件包含以下字段：
| 字段 | 示例 | 含义 |
|---|---|---|
| `technique` | `T1190` | 模拟的 ATT&CK 技术 ID |
| `key` | `network_connect` | 触发的审计规则 |
| `exe` | `/usr/bin/curl` | 运行进程的完整路径 |
| `uid` | `33` | 进程的数字 UID（33 = www-data） |
| `cmd_output` | `uid=0(root)...` | 捕获的命令输出 |
| `host` | `dv-victim` | 源机器的主机名 |
| `cve` | `CVE-2021-44228` | 生成此事件的 CVE 场景 |
| `timestamp` | `2026-05-26T04:26:00Z` | ISO 8601 UTC |
## 编写检测规则
规则位于 `examples/detections/sigma/`。每个都是一个 YAML 文件。
最小化可用规则：
```
title: My Detection Rule
id: a1b2c3d4-e5f6-7890-abcd-ef1234567890
status: experimental
description: Detects something suspicious
logsource:
category: process_creation
detection:
keywords:
- suspicious_process
condition: keywords
tags:
- attack.T1059.004
level: high
```
关键字段：
| 字段 | 功能 |
|---|---|
| `id` | 唯一的 UUID。生成一个：`python3 -c "import uuid; print(uuid.uuid4())"` |
| `tags` | 将规则链接到 ATT&CK 技术（`attack.T1234`）和 CVE（`cve.2021.44228`） |
| `detection.keywords` | 针对事件字段的简单字符串匹配 |
| `level` | 严重性：`informational` / `low` / `medium` / `high` / `critical` |
编写规则后，立即对其进行测试：
```
# 离线 — 即时，无需 SIEM
dv match --events events.jsonl examples/detections/sigma/ --since 0
# 或实时针对 OpenSearch
dv validate examples/detections/sigma/ --since 24
```
## Vagrant VM 参考
```
cd vagrant
vagrant up # create and provision VM (~5 min on first run)
vagrant ssh # open a shell inside the VM
vagrant halt # stop the VM (preserves disk)
vagrant destroy -f # delete the VM entirely
# 在编辑文件/或 provision.sh 后重新运行配置
vagrant provision
# 检查 VM 内的所有三个服务
vagrant ssh -c "systemctl status victim-agent vector auditd --no-pager"
# 实时查看到达的审计事件
vagrant ssh -c "tail -f /var/log/audit/audit-events.jsonl"
```
## Docker stack 参考
```
# 启动带 OpenSearch 的实验环境（推荐）
./dv up lab --siem opensearch --profile standard
# 启动 Splunk Enterprise（仅限 amd64 — 在 Apple Silicon 上不可用）
./dv up lab --siem splunk --profile standard
# 同时启动两个 SIEM
./dv up lab --siem opensearch,splunk
# 停止所有内容
./dv down lab --siem opensearch
# 检查状态
./dv status
# 追踪容器的日志
./dv logs dv-opensearch -f
./dv logs dv-vector -f
./dv logs dv-linux-victim -f
```
### 资源配置
| 配置 | 每个服务的内存 | 推荐用于 |
|---|---|---|
| `standard` | ~1 GB | 默认 —— 推荐用于大多数 Mac |
| `tiny` | ~600 MB | 仅在容器因内存不足不断重启时使用 |
| `full` | 2 GB+ | CI 服务器或专用机器 |
## GitHub Actions
将检测验证添加到你的 CI 流水线中：
```
name: Validate detections
on: [push, pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install detection-validator
run: pip install uv && uv pip install --system .
- name: Match offline
run: |
dv match --events tests/fixtures/events.jsonl \
detections/ --since 0 --format json | \
dv report --format sarif -o scan.sarif
- name: Upload SARIF
uses: github/codeql-action/upload-sarif@v3
with:
sarif_file: scan.sarif
```
## 故障排除
### `dv: command not found`
虚拟环境未激活。运行：
```
source .venv/bin/activate
```
或者使用完整路径：`.venv/bin/dv`
### `dv doctor` 显示 "OpenSearch auth failed"
确保密码环境变量与启动 OpenSearch 时使用的相匹配：
```
export OPENSEARCH_INITIAL_ADMIN_PASSWORD="DetectVal123!"
dv siem status # confirms the password works
```
### OpenSearch 容器启动失败 —— `vm.max_map_count too low`
```
docker run --rm --privileged alpine sysctl -w vm.max_map_count=262144
./dv up lab --siem opensearch --profile standard
```
### 容器重启或内存不足
在 Docker Desktop → Settings → Resources → Memory 中：设置为至少 **8 GB**。
如果仍然不稳定，请使用 `tiny` 配置（跳过 OpenSearch Dashboards，使用更少的内存）：
```
./dv down lab --siem opensearch
./dv up lab --siem opensearch --profile tiny
```
### Vagrant VM 启动失败 —— QEMU / HVF 错误
确保 Docker Desktop 和终端在系统设置 → 隐私与安全性中拥有完整的磁盘访问权限。
```
vagrant plugin update vagrant-qemu
cd vagrant && vagrant destroy -f && vagrant up
```
### `dv validate` 显示所有规则的匹配数为 0
默认的 `--since 1` 窗口只回顾过去 1 小时。如果你的攻击是在更早的时候运行的，请扩大窗口：
```
dv validate examples/detections/sigma/ --since 24
```
同时确认事件已进入 OpenSearch：
```
dv siem status # check document count
dv siem test --size 5 # show sample events
```
### `dv match` 返回 0 个匹配
检查你的事件文件不为空且是有效的 JSON：
```
wc -l events.jsonl # should be > 0
head -1 events.jsonl | python3 -m json.tool # should print valid JSON
```
## 检测示例
`examples/detections/` 中即用型规则：
| 格式 | 文件 | CVE | 技术 |
|---|---|---|---|
| Sigma | `sigma/log4shell_jndi_injection.yml` | CVE-2021-44228 | T1190, T1059.004 |
| Sigma | `sigma/log4shell_process_exec.yml` | CVE-2021-44228 | T1190, T1059.004 |
| Sigma | `sigma/printnightmare_spooler_abuse.yml` | CVE-2021-34527 | T1068, T1547.012, T1574.001 |
| Sigma | `sigma/proxylogon_exchange_ssrf.yml` | CVE-2021-26855 | T1190, T1505.003, T1078 |
| Sigma | `sigma/proxylogon_process_exec.yml` | CVE-2021-26855 | T1190, T1552.001, T1078 |
| Sigma | `sigma/credential_dump_lsass.yml` | — | T1003.001 |
| Sigma | `sigma/network_scan_nmap.yml` | — | T1046 |
| Splunk | `splunk/savedsearches.conf` | — | T1059.001, T1570 |
| KQL | `kql/sentinel_aad_password_spray.yml` | — | T1110.003 |
## 命令参考
| 命令 | 功能 |
|---|---|
| `dv demo` | 一条命令端到端演示：stack → VM → 金丝雀 → 漏洞利用 → 验证 |
| `dv doctor` | 预检查：Python、Docker、Vagrant、SIEM、代理、缓存 |
| `dv doctor --fix` | 同上，加上自动下载空的情报缓存 |
| `dv attack` | 针对受害者 VM 执行 CVE 漏洞利用步骤 |
| `dv validate` | 查询实时 SIEM 的规则命中情况，报告 PASS/FAIL |
| `dv match` | 针对本地 JSONL 事件文件执行相同的离线评估 |
| `dv report` | 将结果渲染为 CLI 摘要 / SARIF / HTML |
| `dv watch` | 每当规则文件改变时自动重新验证 |
| `dv ingest` | 将 Sigma/Splunk/KQL/YARA/EQL 规则解析为规范的 JSONL |
| `dv map` | 将解析后的规则映射到 ATT&CK 技术 |
| `dv enrich` | 填充技术名称、CVE 元数据和严重性 |
| `dv migrate` | 在不同格式之间转换规则（sigma → splunk / kql / sigma） |
| `dv deploy` | 将规则作为告警监视器或保存的搜索推送到实时 SIEM |
| `dv badge` | 生成 SVG 或 JSON 的 ATT&CK 覆盖率徽章 |
| `dv siem add` | 注册外部 SIEM（OpenSearch / Elasticsearch / Splunk） |
| `dv siem list` | 列出所有已注册的 SIEM 连接 |
| `dv siem attach` | 配置 VM 上的 Vector，使其同时将事件发送到已注册的 SIEM |
| `dv siem status` | 检查 SIEM 连接性和文档计数 |
| `dv siem test` | 运行测试查询并显示样本事件 |
| `dv agent status` | 检查受害者代理健康端点 |
| `dv agent logs` | 从受害者代理获取最近的事件 |
| `dv cve-coverage` | 分析每个 CVE 的检测覆盖率缺口 |
| `dv navigator` | 从检测语料库导出 ATT&CK Navigator 层 |
| `dv intel update` | 刷新本地 ATT&CK、CVE、EPSS、KEV 缓存 |
## 架构
```
┌─ Python CLI (dv) ──────────────────────────────────────────────┐
│ dv doctor — pre-flight check: tools, containers, caches │
│ dv attack — simulate CVE exploit steps on victim │
│ dv validate — query live SIEM, report PASS/FAIL per rule │
│ dv match — same evaluation offline against a JSONL file│
│ dv report — render results as CLI / SARIF / HTML │
│ dv watch — re-validate on rule file changes │
│ dv ingest — parse Sigma/Splunk/KQL/YARA/EQL to JSONL │
│ dv map — map rules to ATT&CK techniques │
│ dv enrich — fill technique names, CVE metadata, severity│
│ dv migrate — convert rules between formats │
│ dv deploy — push rules to OpenSearch / Splunk │
│ dv badge — generate SVG / JSON coverage badge │
│ dv siem — check connectivity, run test queries │
│ dv agent — check agent health, fetch recent events │
│ dv cve-coverage — analyze coverage gaps per CVE │
│ dv navigator — export ATT&CK Navigator layer │
└────────────────────────────────────────────────────────────────┘
┌─ Shell script (./dv) ──────────────────────────────────────────┐
│ ./dv up lab --siem opensearch — start Docker containers │
│ ./dv down lab — stop Docker containers │
│ ./dv status — show running services │
│ ./dv logs — tail container logs │
└────────────────────────────────────────────────────────────────┘
┌─ Telemetry pipeline ───────────────────────────────────────────┐
│ Vagrant VM (Ubuntu 22.04 ARM64) │
│ auditd → /var/log/audit/audit-events.jsonl │
│ victim-agent (port 9099) ← dv attack │
│ vector → OpenSearch (9200) + Splunk HEC (8088) │
│ │
│ Docker linux-victim container (synthetic events) │
│ stdout → vector → OpenSearch + Splunk HEC │
└────────────────────────────────────────────────────────────────┘
┌─ SIEMs ────────────────────────────────────────────────────────┐
│ OpenSearch localhost:9200 Dashboards: localhost:5601 │
│ Splunk mock localhost:8088 UI: localhost:8000 │
└────────────────────────────────────────────────────────────────┘
```
## Windows 注意事项
完整的 Windows 指南请参阅 [docs/windows-quickstart.md](docs/windows-quickstart.md)。主要区别：
- 在 **Git Bash** 中而不是 PowerShell 中运行 `./dv up` / `./dv down`。
- 在使用 `dv` 之前，在 PowerShell 中设置 `$env:PYTHONUTF8 = "1"` 和 `$env:PYTHONIOENCODING = "utf-8"`。
- 攻击时使用 `--target docker --mode simulate`（无需 Vagrant）。
- 预期结果：**5 PASS / 3 FAIL**（LSASS、MSHTA、Nmap 需要 Windows 受害者或 Nmap 扫描）。
## Apple Silicon 注意事项
所有核心服务都原生在 ARM64 上运行。没有模拟开销。
| 组件 | ARM64 状态 |
|---|---|
| OpenSearch + Dashboards | ✅ 原生 |
| Splunk mock (HEC) | ✅ 原生（基于 Python） |
| 通过 QEMU/HVF 的 Vagrant VM | ✅ 原生 ARM64 内核 |
| Docker Linux 受害者 | ✅ 原生 |
| Splunk Enterprise | ❌ 仅限 amd64 —— 请改用 `--siem opensearch` |
**端口布局**（Mac 宿主机 → VM/容器）：
| 宿主机端口 | 目的地 | 说明 |
|---|---|---|
| `9200` | Docker | OpenSearch API |
| `5601` | Docker | OpenSearch Dashboards |
| `8000` | Docker | Splunk mock UI |
| `8088` | Docker | Splunk HEC（事件摄取） |
| `9098` | VM 端口 9099 | 受害者代理 HTTP API |
| `9088` | VM 端口 8888 | 故意保留漏洞的服务 |
## 许可证
Apache 2.0
标签：Docker, PB级数据处理, Vagrant, XXE攻击, 安全运维, 安全防御评估, 搜索引擎查询, 攻击模拟, 规则检测, 请求拦截, 逆向工具, 配置修复, 驱动签名利用