scythe-io/sigma-regression-testing
GitHub: scythe-io/sigma-regression-testing
这是一个集成了规则验证、Splunk 转换及 Atomic Red Team 测试的 Sigma 规则自动化检测工程流水线。
Stars: 1 | Forks: 0
# Sigma 回归测试
一个用于开发、验证、部署和**回归测试** Sigma 规则的检测工程管道。本项目包含针对 Windows、Linux 和 Microsoft 365 环境的精选检测规则集合，以及用于将规则转换为 Splunk 格式、通过 REST API 部署并使用 Atomic Red Team 测试验证检测的自动化工具。
## 快速开始
```
git clone https://github.com/scythe-io/sigma-regression-testing.git
cd sigma-regression-testing
pip install -r requirements.txt
```
## 概览
| 指标 | 数量 |
|--------|-------|
| **总规则数** | 71 |
| **Windows 规则** | 38 |
| **Linux 规则** | 17 |
| **M365/Cloud 规则** | 7 |
### 规则分类
| 类别 | 描述 | 数量 |
|----------|-------------|-------|
| `proc_creation` | 进程创建事件 | 43 |
| `file_event` | 文件系统活动 | 6 |
| `m365_*` | Microsoft 365 审计日志 | 5 |
| `registry_set` | 注册表修改 | 4 |
| `net_connection` | 网络连接 | 3 |
| `azure_network` | Azure 网络防火墙变更 | 2 |
| `web_sharepoint` | SharePoint Web 活动 | 2 |
| `azure_firewall` | Azure 防火墙修改 | 1 |
| `azure_application` | Azure 应用安全变更 | 1 |
| `file_creation` | 文件创建事件 | 1 |
| `dns_query` | DNS 查询异常 | 1 |
| `wmi_event` | WMI 事件订阅监控 | 1 |
| `reg_set` | 注册表修改 | 1 |
## 规则设计理念
这些规则基于以下原则设计：
1. **低误报率** - 针对包管理器、配置管理工具和合法管理员活动进行过滤
2. **关注行为** - 检测技术，而不仅仅是 IOC（无硬编码哈希或 IP）
3. **生产就绪** - 所有规则均通过 `sigma check` 验证
4. **映射 MITRE ATT&CK** - 标记相关技术 ID
## 快速入门
### 安装依赖
```
# 安装所有依赖
pip install -r requirements.txt
# 或手动安装
pip install sigma-cli pysigma pysigma-backend-splunk pysigma-pipeline-windows PyYAML requests pywinrm
# 可选：为 regression-test.py 启用 tab 补全
pip install argcomplete
. ./scripts/Enable-TabCompletion.ps1 # PowerShell
```
### 验证规则
```
# requirements.txt 中包含 sigma-cli
# 验证所有规则
sigma check sigma_rules/*.yml
```
### 转换为 SIEM 格式
```
# 转换为 Splunk
sigma convert -t splunk sigma_rules/*.yml
# 转换为 Elastic
sigma convert -t elasticsearch sigma_rules/*.yml
# 转换为 Microsoft Sentinel
sigma convert -t microsoft365defender sigma_rules/*.yml
```
## 仓库结构
```
.
├── sigma_rules/ # QA-validated detection rules (43 Windows + Linux + M365)
│ ├── proc_creation_*.yml # Process creation rules
│ ├── file_event_*.yml # File event rules
│ ├── reg_set_*.yml # Registry rules
│ ├── net_connection_*.yml # Network rules
│ ├── m365_*.yml # Microsoft 365 rules
│ └── unmapped_rules/ # Rules without ART test mappings (not yet QA-validated)
├── scripts/
│ ├── update-readme-stats.py # Auto-update README statistics
│ ├── convert-to-splunk.py # Convert rules to Splunk format
│ ├── deploy-to-splunk.ps1 # Deploy saved searches to Splunk
│ ├── regression-test.py # Atomic Red Team regression testing (CLI)
│ └── regression-test-gui.py # GUI wrapper for regression-test.py
├── tests/
│ └── art_mapping.yaml # Atomic Red Team test to rule mappings
├── splunk_output/ # Generated Splunk artifacts (auto-updated)
│ ├── savedsearches.conf # Splunk saved searches (auto-generated)
│ └── conversion_report.json # Conversion statistics
├── wip/ # Work in progress (not production ready)
│ ├── aurora/ # Aurora EDR integration (coming soon)
│ └── scythe/ # SCYTHE integration (coming soon)
└── .github/workflows/
├── sigma-validate.yml # CI validation workflow
├── splunk-pipeline.yml # Splunk detection pipeline
└── deploy-rules.yml # Deployment workflow (WIP)
```
## CI/CD 管道
此仓库包含用于自动化验证和部署的 GitHub Actions 工作流。
### 验证工作流 (`sigma-validate.yml`)
在每次代码变更时自动验证规则。**当 `main` 分支上的验证通过时，它会自动触发 Splunk 检测管道。**
**触发条件：**
- 推送到 `main` 分支（当 `sigma_rules/**` 发生变更时）
- 针对 `main` 分支的 Pull Request
- 手动触发
**管道：**
```
┌─────────────────────────────────────────────────────────────┐
│ VALIDATE JOB (runs on every PR and push) │
├─────────────────────────────────────────────────────────────┤
│ 1. Checkout code │
│ 2. Install Python 3.11 + sigma-cli │
│ 3. Run: sigma check sigma_rules/*.yml │
│ 4. If errors found → FAIL (blocks PR merge) │
│ 5. If clean → PASS and display rule count │
└─────────────────────────────────────────────────────────────┘
│ │
▼ (only on merge) ▼ (only on merge)
┌──────────────────┐ ┌──────────────────────────────────────┐
│ RELEASE JOB │ │ UPDATE README JOB │
├──────────────────┤ ├──────────────────────────────────────┤
│ Package .yml │ │ Run update-readme-stats.py │
│ rules as │ │ Auto-commit updated rule counts │
│ artifact │ │ to README.md │
└──────────────────┘ └──────────────────────────────────────┘
│
│ on completion with conclusion == 'success'
▼
┌─────────────────────────────────────────────────────────────┐
│ SPLUNK DETECTION PIPELINE (auto-triggered) │
│ see below ↓ │
└─────────────────────────────────────────────────────────────┘
```
### 部署工作流 (`deploy-rules.yml`) - WIP
用于将经验证的规则部署到端点的模板。支持 Azure Blob、AWS S3 和 SSH 部署选项。
## Splunk 检测管道
一个完整的检测工程管道，用于将 Sigma 规则部署到 Splunk 并使用 [Atomic Red Team](https://atomicredteam.io/) 测试进行验证。
**触发条件：** 在 `main` 分支上 `Sigma Rules Validation` 成功后自动运行。也可以通过可选的 deploy/regression 标志手动触发。
### 管道概览
```
┌──────────────────────────────────┐
│ Sigma Rules Validation (pass) │
└────────────────┬─────────────────┘
│ workflow_run trigger
▼
┌─────────────────────────────────────────────────────────────┐
│ CONVERT JOB │
├─────────────────────────────────────────────────────────────┤
│ 1. Convert Windows rules to Splunk savedsearches.conf │
│ 2. Generate conversion report │
│ 3. Commit savedsearches.conf back to repository │
│ 4. Upload artifacts │
└─────────────────────────────────────────────────────────────┘
│
▼ (on workflow_run or manual deploy)
┌─────────────────────────────────────────────────────────────┐
│ DEPLOY JOB (requires secrets configured) │
├─────────────────────────────────────────────────────────────┤
│ 1. Download converted artifacts │
│ 2. Deploy saved searches to Splunk via REST API │
│ 3. Configure alerts (optional) │
└─────────────────────────────────────────────────────────────┘
│
▼ (manual trigger only)
┌─────────────────────────────────────────────────────────────┐
│ REGRESSION TEST JOB │
├─────────────────────────────────────────────────────────────┤
│ 1. Execute Atomic Red Team tests on target endpoint │
│ 2. Query Splunk for triggered rules │
│ 3. Report coverage and failures │
└─────────────────────────────────────────────────────────────┘
```
### 本地使用
**将规则转换为 Splunk 格式：**
```
# 安装依赖
pip install sigma-cli pysigma pysigma-backend-splunk pysigma-pipeline-windows PyYAML
# 列出兼容规则
python scripts/convert-to-splunk.py --list-compatible
# 转换所有规则
python scripts/convert-to-splunk.py -i sigma_rules -o splunk_output
```
**部署到 Splunk：**
```
# 部署保存的搜索（交互式）
.\scripts\deploy-to-splunk.ps1 -SplunkHost splunk.company.com -Username admin
# 部署并启用警报
.\scripts\deploy-to-splunk.ps1 -SplunkHost splunk.company.com -Username admin -EnableAlerts -AlertEmail soc@company.com
# 试运行（验证而不部署）
.\scripts\deploy-to-splunk.ps1 -SplunkHost splunk.company.com -Username admin -DryRun
```
**使用 Atomic Red Team 运行回归测试：**
```
# 试运行（显示测试用例而不执行）
python scripts/regression-test.py --splunk-host splunk.company.com --dry-run --test-config tests/art_mapping.yaml
# 通过 WinRM 在远程目标上运行测试（顺序模式）
python scripts/regression-test.py \
--splunk-host splunk.company.com \
--splunk-user admin \
--target 192.168.1.100 \
--winrm-user "DOMAIN\Administrator" \
--winrm-pass "password" \
--test-config tests/art_mapping.yaml \
--wait-time 60 \
--skip-atomic-check
# 批处理模式（更快 - 先运行所有测试，然后检查规则）
python scripts/regression-test.py \
--splunk-host splunk.company.com \
--splunk-user admin \
--target 192.168.1.100 \
--winrm-user "DOMAIN\Administrator" \
--winrm-pass "password" \
--test-config tests/art_mapping.yaml \
--wait-time 600 \
--lookback-window 60 \
--skip-atomic-check \
--batch
# 并行模式（最快 - 并发运行 5 个测试，意味着 --batch）
python scripts/regression-test.py \
--splunk-host splunk.company.com \
--splunk-user admin \
--target 192.168.1.100 \
--winrm-user "DOMAIN\Administrator" \
--winrm-pass "password" \
--test-config tests/art_mapping.yaml \
--wait-time 600 \
--lookback-window 60 \
--skip-atomic-check \
--parallel
```
**GUI 模式：**
还提供了一个图形界面，用于配置和运行测试，无需手动构建 CLI 命令：
```
python scripts/regression-test-gui.py
```
GUI 提供了四个选项卡（Splunk、目标、测试设置、过滤器）、一个实时的彩色编码输出面板、一个用于验证 Splunk 凭据的**测试连接**按钮，以及运行完成后打开 HTML 结果的提示。设置会自动保存到 `.gui_config.json`。
**测试输出：**
回归测试脚本会生成两个输出文件：
- `test_results.json` - 包含通过/失败状态、查询和计时的机器可读结果
- `test_results.html` - 带有过滤和可视摘要的交互式 HTML 报告
HTML 报告包括：
- 显示总测试数、通过数、失败数、通过率和未测试规则数的摘要卡片
- 用于快速查看通过/失败概览的可视化进度条
- 可按状态（全部/通过/失败）和搜索文本过滤的表格
- 每个测试的详细信息，包括预期规则、触发规则和缺失规则
- 每个预期规则的**可点击 Splunk 链接**，可直接在 Splunk 中打开保存的搜索（带最近 15 分钟的时间范围）
- **未测试规则部分**，显示哪些规则未被测试以及原因：
- 无测试映射（规则存在但未映射 Atomic 测试）
- 非 Windows/跳过（Linux、M365 或其他非 Windows 规则）
- 转换失败（Splunk 转换失败的规则）
- 测试错误（执行过程中遇到错误的测试）
**其他选项：**
| 选项 | 默认值 | 描述 |
|--------|---------|-------------|
| `--wait-time` | 60 | 测试后查询 Splunk 前等待的秒数 |
| `--lookback-window` | (自动) | 查询时在 Splunk 中回溯的分钟数；如果省略，则根据批次开始时间自动计算 |
| `--batch` | false | 先运行所有原子测试，然后检查规则（更快） |
| `--parallel` | false | 通过 WinRM 并发运行 5 个原子测试（隐含 --batch） |
| `--splunk-web-port` | 8000 | Splunk Web UI 端口（用于 HTML 报告链接） |
| `--splunk-app` | search | 保存搜索的 Splunk 应用上下文 |
| `--test-id` | (全部) | 按原子测试 GUID 过滤（可指定多个） |
| `--technique` | (全部) | 按 MITRE ATT&CK 技术 ID 过滤，例如 T1018（可指定多个） |
| `--expected-rule` | (全部) | 按预期规则名称过滤 - 部分匹配（可指定多个） |
| `--list` | false | 列出测试而不是运行它们（适用于过滤器） |
| `--fields` | name,technique,guid,rules | 与 --list 一起显示的字段（可指定多个） |
| `--format` | table | --list 的输出格式：table 或 csv |
| `--prompt-inputs` | false | 交互式提示输入参数 |
| `--inputs-file` | (无) | 从 YAML 文件加载输入参数 |
| `--use-defaults` | false | 忽略自定义输入，使用 ART 默认值 |
| `--conversion-report` | splunk_output/conversion_report.json | Sigma 转换报告的路径（用于跟踪未测试规则） |
| `--savedsearches` | splunk_output/savedsearches.conf | Splunk savedsearches.conf 的路径（用于跟踪未测试规则） |
| `--skip-untested-report` | false | 跳过生成未测试规则部分 |
**列出可用测试：**
```
# 列出配置中的所有测试
python scripts/regression-test.py --list --test-config tests/art_mapping.yaml
# 列出特定技术的测试
python scripts/regression-test.py --list --technique T1018 --test-config tests/art_mapping.yaml
# 列出具有特定字段的测试
python scripts/regression-test.py --list --fields name --fields technique --fields description --test-config tests/art_mapping.yaml
# 导出为 CSV
python scripts/regression-test.py --list --format csv --test-config tests/art_mapping.yaml > tests.csv
```
可用字段：`name`、`technique`、`guid`、`rules`、`description`、`cleanup`、`inputs`
**运行特定测试：**
```
# 通过 GUID 运行单个测试
python scripts/regression-test.py \
--splunk-host splunk.company.com \
--test-config tests/art_mapping.yaml \
--test-id f1bf6c8f-9016-4edf-aff9-80b65f5d711f \
--dry-run
# 为特定规则运行测试（部分匹配）
python scripts/regression-test.py \
--splunk-host splunk.company.com \
--test-config tests/art_mapping.yaml \
--expected-rule "Domain Discovery" \
--dry-run
# 为特定 MITRE 技术运行测试
python scripts/regression-test.py \
--splunk-host splunk.company.com \
--test-config tests/art_mapping.yaml \
--technique T1018 \
--dry-run
# 运行多个特定测试
python scripts/regression-test.py \
--splunk-host splunk.company.com \
--test-config tests/art_mapping.yaml \
--test-id f1bf6c8f-9016-4edf-aff9-80b65f5d711f \
--test-id 80887bec-5a9b-4efc-a81d-f83eb2eb32ab \
--skip-atomic-check
```
**自定义输入参数：**
```
# 交互式提示输入
python scripts/regression-test.py \
--splunk-host splunk.company.com \
--test-config tests/art_mapping.yaml \
--test-id bc8be0ac-475c-4fbf-9b1d-9fffd77afbde \
--prompt-inputs \
--skip-atomic-check
# 从文件加载输入
python scripts/regression-test.py \
--splunk-host splunk.company.com \
--test-config tests/art_mapping.yaml \
--inputs-file tests/inputs.yaml \
--skip-atomic-check
# 使用 ART 默认值（忽略测试配置中的自定义输入）
python scripts/regression-test.py \
--splunk-host splunk.company.com \
--test-config tests/art_mapping.yaml \
--use-defaults \
--skip-atomic-check
```
**输入文件格式 (`tests/inputs.yaml`)：**
```
# 按 atomic GUID
bc8be0ac-475c-4fbf-9b1d-9fffd77afbde:
username: "CustomUser"
# 或按测试名称
"Create Local User Account (PowerShell)":
username: "AnotherUser"
```
### 安装 Atomic Red Team
在测试端点上，将 Atomic Red Team 安装到系统范围的位置（WinRM 访问所必需）：
```
# 将 Invoke-AtomicRedTeam 模块安装到 C:\AtomicRedTeam
Set-ExecutionPolicy Bypass -Scope Process -Force
IEX (IWR 'https://raw.githubusercontent.com/redcanaryco/invoke-atomicredteam/master/install-atomicredteam.ps1' -UseBasicParsing)
Install-AtomicRedTeam -getAtomics -Force -InstallPath "C:\AtomicRedTeam"
# 验证安装
Import-Module "C:\AtomicRedTeam\invoke-atomicredteam\Invoke-AtomicRedTeam.psd1" -Force
Get-Command Invoke-AtomicTest
```
### GitHub Actions 设置
**转换是完全自动化的** — 将更改推送到 `sigma_rules/`，运行验证，如果通过，Splunk 管道会自动触发以重新生成并提交 `savedsearches.conf`。无需手动步骤。
若要启用自动**部署**到实时 Splunk 实例，请在仓库中配置这些密钥：
| 密钥 | 描述 |
|--------|-------------|
| `SPLUNK_HOST` | Splunk 服务器主机名 |
| `SPLUNK_PORT` | 管理端口（默认：8089） |
| `SPLUNK_USER` | Splunk 管理员用户名 |
| `SPLUNK_PASSWORD` | Splunk 管理员密码 |
| `SPLUNK_APP` | 目标应用（默认：search） |
### 测试映射配置
在 `tests/art_mapping.yaml` 中定义测试用例，以将 Atomic Red Team 测试映射到预期的 Sigma 规则：
```
tests:
- name: "Clear Security Event Log"
description: "Validates detection of log clearing via wevtutil"
technique_id: "T1070.001"
atomic_test_guid: "e6abb60e-26b8-41da-8aae-0c35174b0967"
expected_rules:
- "Windows Event Log Manipulation" # Must match Splunk saved search name exactly
cleanup: false
- name: "Create Local User Account"
description: "Creates a new local user"
technique_id: "T1136.001"
atomic_test_guid: "a524ce99-86de-4f6c-88f5-8c3439e21ed5"
expected_rules:
- "Local User Account Creation via New-LocalUser PowerShell Cmdlet"
input_arguments:
username: "TestUser"
password: "P@ssw0rd123!"
```
**重要：** `expected_rules` 值必须与 Splunk 保存的搜索名称完全匹配。这些是 YAML 文件中的 Sigma 规则标题。
在 [atomicredteam.io](https://atomicredteam.io/atomics/) 查找 Atomic Test GUID，或通过运行以下命令查找：
```
Import-Module "C:\AtomicRedTeam\invoke-atomicredteam\Invoke-AtomicRedTeam.psd1"
Invoke-AtomicTest T1070.001 -ShowDetailsBrief
```
## Aurora EDR 集成
这些规则与 Nextron Systems 的 [Aurora Agent](https://www.nextron-systems.com/aurora/) 兼容。
### 手动安装
将规则复制到 Aurora 的自定义签名文件夹：
```
Copy-Item .\sigma_rules\proc_creation_win_*.yml "C:\Program Files\Aurora-Agent\custom-signatures\"
Restart-Service "Aurora Agent"
```
自动同步和部署工具即将推出。
### 添加新规则
1. 在 `sigma_rules/` 中创建一个新的 `.yml` 文件
2. 遵循命名约定：`_.yml`
3. 确保规则通过验证：`sigma check your-rule.yml`
4. 提交 pull request
### 规则要求
- 必须通过 `sigma check` 验证
- 必须包含 MITRE ATT&CK 技术标签（例如 `attack.t1059.001`）
- 必须包含 `falsepositives` 部分
- 必须包含适当的 `level`（low/medium/high/critical）
- 应包含过滤器以减少误报
### 命名约定
```
__.yml
Examples:
proc_creation_win_susp_rundll32.yml
proc_creation_lnx_docker_priv.yml
file_event_win_archive_creation.yml
m365_mailbox_delegation.yml
```
## 参考资料
- [Sigma 规范](https://github.com/SigmaHQ/sigma-specification)
- [Sigma 规则仓库](https://github.com/SigmaHQ/sigma)
- [MITRE ATT&CK](https://attack.mitre.org/)
- [Atomic Red Team](https://atomicredteam.io/)
- [Aurora Agent 文档](https://aurora-agent-manual.nextron-systems.com/)
- [SCYTHE 平台](https://www.scythe.io/)
## 许可证
详情请参阅 [LICENSE](LICENSE)。
标签：AI合规, API部署, Atomic Red Team, Azure安全, CDN识别, Cloudflare, Conpot, DNS查询, M365, MITRE ATT&CK, SharePoint, Sigma规则, URL发现, Windows安全, WMI事件, 回归测试, 安全检测, 安全运营, 扫描框架, 数据泄露检测, 文件监控, 注册表监控, 目标导入, 网络连接, 自动化CI/CD, 规则转换, 误报控制, 进程创建, 逆向工具, 防火墙日志