medohosny94/Sigma-Aitumation
GitHub: medohosny94/Sigma-Aitumation
将 SigmaHQ 检测规则自动转换为 Microsoft Defender XDR 自定义检测规则并保持持续同步的自动化流水线工具。
Stars: 0 | Forks: 0
# sigma-defender-sync
自动将 [SigmaHQ/sigma](https://github.com/SigmaHQ/sigma) 检测规则转换为 Microsoft Defender XDR **自定义检测规则**，随着每次新的 Sigma 发布保持同步，并允许您随时升级规则层级。
## 工作原理
```
GitHub Actions (daily cron)
|
v
1. fetch_release -> latest SigmaHQ/sigma release, download the configured
asset (sigma_core.zip / sigma_core+.zip / sigma_core++.zip)
|
v
2. sigma_convert -> for every rule file, run `sigma convert -t kusto
-p microsoft_xdr` (pySigma + pySigma-backend-kusto) to
get a Defender Advanced Hunting KQL query. Rules whose
logsource/fields aren't mapped by the backend, or that
use constructs Advanced Hunting can't express
(e.g. cross-table correlation), are skipped and logged
- not everything in Sigma has a 1:1 Defender equivalent.
|
v
3. state diff -> compare each rule's (title + description + query +
severity) against state/pipeline_state.json to decide
create / update / unchanged, keyed by the Sigma rule's
own `id:` field.
|
v
4. sync_defender -> POST new rules / PATCH changed rules via Microsoft
Graph (/beta/security/rules/detectionRules), using the
alert's title/description straight from the Sigma rule.
|
v
5. commit state -> pipeline_state.json is committed back to the repo so
the next run knows what's already deployed.
```
规则默认以 `status: disabled` 部署（参见下方的“审查工作流”），因此未经您首先查看，任何内容都不会在您的租户中生效。
## 一次性设置
### 1. 创建 Entra 应用注册
在 [Entra 管理中心](https://entra.microsoft.com) > **应用注册** > **新建注册**中：
1. 将其命名为例如 `sigma-defender-sync`，单租户，无需重定向 URI。
2. **API 权限** > **添加权限** > **Microsoft Graph** > **应用程序权限** > 搜索 `CustomDetection` > 选择 `CustomDetection.ReadWrite.All` > **添加权限**。
3. 为您的租户点击**授予管理员同意**（需要全局管理员或特权角色管理员）。
4. **证书和密码** > **新建客户端密钥** > 立即复制值（它不会再次显示）。
5. 记下：**应用程序(客户端) ID**、**目录(租户) ID** 以及**客户端密钥**值。
这里的权限模型是 Defender 的 Unified RBAC - `CustomDetection.ReadWrite.All` 是 Graph API 唯一检查的权限，但请根据 [Microsoft 文档](https://learn.microsoft.com/defender-xdr/custom-detection-rules#required-permissions-for-managing-custom-detections) 确认应用也具有分配的角色（安全管理员，或者如果关闭了 Unified RBAC 则为安全操作员）。
### 2. 将此项目推送到仓库并添加 secrets
如果您首先在 GitHub 上创建了仓库（即使是空仓库，或者是带有自动生成的 README/license 的仓库），它已经拥有了自己的历史记录 - 这是当您在本地运行 `git init` 并尝试直接推送到该仓库时导致 `src refspec main does not match any` 或 `! [rejected] (fetch first)` 错误的常见原因。首先克隆仓库可以避免这两种情况：
```
git clone https://github.com/medohosny94/Sigma-Aitumation.git
```
将此 `sigma-defender-sync` 项目中的所有文件复制到刚刚克隆创建的 `Sigma-Aitumation` 文件夹中（以便 `config.yaml`、`scripts/`、`.github/` 等位于其根目录，与 GitHub 已经放置在那里的任何内容并列），然后：
```
cd Sigma-Aitumation
git add .
git commit -m "Initial commit: sigma-defender-sync"
git push origin main
```
如果该推送被拒绝，因为远程仓库有本地克隆没有的提交（例如 GitHub 自动生成的 README），但您不想合并 - 因为流水线自己的文件应该直接接管仓库 - 请使用以下方法解决：
```
git pull origin main --allow-unrelated-histories --no-rebase
# 如果出现提示，解决任何冲突标记，然后：
git add .
git commit -m "Merge Sigma sync pipeline into repo"
git push origin main
```
已经在本地运行了 `git init` 并遇到错误？只需将现有的本地仓库指向 GitHub 并在推送前拉取，而不是重新开始 - **在拉取之前提交您的文件**，否则 git 在本地没有任何内容可以与远程的历史记录进行合并，并拒绝处理您的未跟踪文件：
```
git branch -M main
git remote add origin https://github.com/medohosny94/Sigma-Aitumation.git
git add .
git commit -m "Initial commit: sigma-defender-sync"
git pull origin main --allow-unrelated-histories --no-rebase
```
这很可能会在 `README.md` 中因合并冲突而停止（双方都有一个）。打开它，删除 `<<<<<<<` / `=======` / `>>>>>>>` 冲突标记以及您不想保留的任何一方的内容（通常您希望保留此项目的 README，而不是 GitHub 自动生成的 README），然后：
```
git add README.md
git commit -m "Merge Sigma sync pipeline into repo"
git push -u origin main
```
在仓库中，**Settings > Secrets and variables > Actions > New repository secret**，添加：
| Secret | 值 |
|---|---|
| `AZURE_TENANT_ID` | Directory (tenant) ID |
| `AZURE_CLIENT_ID` | Application (client) ID |
| `AZURE_CLIENT_SECRET` | 客户端密钥值 |
（不想存储长期密钥？将 `scripts/lib/graph_client.py` 中的客户端凭据流替换为 [GitHub OIDC 联合凭据](https://learn.microsoft.com/entra/workload-id/workload-identity-federation-create-trust-github) - 除了获取 token 的方式外，无需更改代码。）
### 3. 首次运行 - 先在本地执行
在信任每日的 Action 之前，自己使用 `--dry-run` 运行它，这样目前还不会对您的租户进行任何操作：
```
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt
export AZURE_TENANT_ID=...
export AZURE_CLIENT_ID=...
export AZURE_CLIENT_SECRET=...
python scripts/run_pipeline.py --dry-run
```
检查 `state/last_run_report.md` 中的已创建/更新/跳过计数，并抽查几个被跳过的规则，以了解哪些未被转换。当您满意后，去掉 `--dry-run` 并真正运行它，或者就让计划的工作流来完成它（`.github/workflows/sigma-defender-sync.yml`，每天 UTC 时间 06:00）。
## 审查工作流
新的和更改后的规则会以 **status = disabled**（`config.yaml` 中的 `defender.initial_status`）进入 Defender。要审查并启用它们：
1. Microsoft Defender 门户 > **调查与响应** > **自定义检测**。
2. 筛选由同步应用创建/编辑的规则，或按名称搜索 - 每个规则的描述都以一个页脚结尾，指出它是由此流水线部署的，并链接回源 Sigma 规则 ID。
3. 阅读查询，检查 `falsepositives`（已带入描述中），如果看起来适合您的环境，则切换到**已启用**。
重新运行流水线**绝不会**重置现有规则的 `status` - 仅更新查询/标题/描述/严重性/策略，因此分析师的启用/禁用选择将始终保留。
如果您希望规则立即生效而无需审查步骤，请在 `config.yaml` 中将 `defender.initial_status` 更改为 `enabled`。
## 升级规则层级
`sigma_core.zip`（默认）< `sigma_core+.zip`（增加中等置信度规则）< `sigma_core++.zip`（也增加实验性规则 - 误报风险最高）。
**一次性单次运行：** GitHub Actions 选项卡 > 此工作流 > **运行工作流** > 在 `tier` 下拉菜单中选择一个层级。
**永久生效：** 可以在相同的 manual run 上勾选 `persist_tier`，或者直接编辑 `config.yaml` 中的 `sigma.package` 并提交。升级后新纳入范围的规则会在下次运行时自动获取（相同的创建/更新/跳过逻辑，以 Sigma 规则 ID 为键 - 无需特殊情况的代码）。
降级也是安全的：落入较小层级的规则**不会**被自动删除或自动禁用（自动删除实时检测比留下过时的检测运行风险更大）。流水线会在运行报告中将它们记录为“stale”，以便您手动决定。
## 已知限制
- **并非所有 Sigma 规则都能转换。** pySigma-backend-kusto 的 `microsoft_xdr` 流水线仅映射其具有映射关系的 logsources/fields。Correlation 规则、一些没有 Defender Advanced Hunting 对应项的日志源，以及包含流水线无法识别的字段的规则将转换失败，并显示在运行报告中的“已跳过”下，而不是悄悄消失。
- **Graph 的自定义检测 API 是 `/beta`。** Microsoft 可以在没有 `/v1.0` 的版本控制保证的情况下更改属性/枚举值。严重性映射（`informational/low/medium/high`）和 `scripts/lib/mapping.py` 中的 MITRE 战术枚举在构建时已根据当前文档进行了验证 - 如果 Microsoft 发布了破坏性更新，请重新检查它们。
- **MITRE 战略/技术映射是尽力而为的。** 像 `attack.execution` 和 `attack.t1059`/`attack.t1059.001` 这样的 Sigma 标签被解析为 Graph 的嵌套结构 - 每个 `mitreTactic`（例如 `execution`）带有其自己的 `techniques`（例如 `{technique: "T1059", subTechniques: ["T1059.001"]}`），与 Defender 门户显示的“战术/技术”相匹配。问题在于：Sigma 的标签列表是扁平的，并且没有记录哪个技术属于哪个战术，因此当规则具有多个战术标签时，在规则上找到的每个技术都会附加到存在的每个战术上 - 对于常见的单战术情况是准确的，否则只是近似值。不是公认的战术或 `attack.tNNNN[.NNN]` 技术的标签（例如 `attack.tool`、`attack.test`）将被忽略而不是被猜测。
- **一个 Sigma 规则文件 = 一个 Defender 规则。** 多文档 Sigma“集合”文件（罕见）将被跳过；如果需要，请在上游将它们拆分为单独的规则文件。
- **计划频率、严重性、描述长度上限（`displayName`/`description` 被截断为 Graph 的限制），以及用于每个受管规则的 `id_prefix` 都在 `config.yaml` 中** - 在首次实际运行前进行审查。
## 项目布局
```
config.yaml tier, schedule, severity map, etc.
requirements.txt
.github/workflows/sigma-defender-sync.yml daily cron + manual dispatch
scripts/run_pipeline.py orchestrator / CLI entrypoint
scripts/lib/github_release.py fetch + extract the release asset
scripts/lib/sigma_convert.py find rule files, shell out to sigma-cli
scripts/lib/mapping.py Sigma -> Graph field mapping
scripts/lib/graph_client.py MSAL auth + create/update detectionRules
scripts/lib/state_store.py JSON state file load/save
state/pipeline_state.json committed by the workflow after each run
state/last_run_report.md human-readable summary of the last run
```
标签：AMSI绕过, KQL, Microsoft Defender, 威胁检测, 安全运营, 扫描框架, 逆向工具