edwardjgriggs/detection-as-code

# 检测即代码 (Detection as Code)     ## 核心理念 大多数检测内容都以复制粘贴的查询形式存在于 SIEM 控制台中，没有历史记录、没有审查，也没有测试。当出现问题时，没人知道改了什么或为什么改。检测即代码（Detection as code）通过借鉴软件工程几十年前就已确立的实践来解决了这个问题：以可移植的格式编写检测规则，将其存储在版本控制系统中，通过 pull request 审查变更，并在合并前自动验证所有内容。 这个仓库是我该工作流的一个运行模型。一条检测规则以 Sigma 规则的形式输入，通过 CI pipeline 进行语法检查并转换为 KQL，只有通过验证后才会合并。每一条检测及其每一次调整变更的历史记录都被完好保留。 ## 为什么这对 SOC 很重要 - **可移植性。** 一条 Sigma 规则可以转换为 Sentinel KQL、Defender XDR、Elastic 或 Splunk。一次编写，即可部署到多个后端。 - **审查。** 检测变更需要通过 pull request，因此逻辑是经过同行审查的，而不是在控制台中默默地被编辑。 - **测试。** 错误的语法永远不会到达生产环境，因为 CI 会率先将其拦截。 - **可审计性。** Git 历史记录是一份完整的、带有时间戳的变更记录，这在任何受合规性驱动的环境中都至关重要。 ## 检测如何通过 pipeline ``` flowchart LR A[Author Sigma rule] --> B[Open pull request] B --> C[CI validates syntax] C --> D[CI converts to KQL] D --> E[Review and merge] E --> F[Deploy to Sentinel] ``` ## 仓库结构 ``` detection-as-code/ rules/ credential-access/ password-spray.yml persistence/ malicious-inbox-rule.yml .github/ workflows/ validate-detections.yml # CI: lint, validate, convert pipelines/ sentinel.yml # pySigma processing pipeline config build/ kql/ # generated queries (CI output) ``` ## Sigma 格式的检测 这与我 [detection-engineering](https://github.com/edwardjgriggs/detection-engineering) 仓库中相同的密码喷洒 (password-spray) 逻辑，只是以可移植的、独立于后端的格式编写了一次。 ``` title: Azure AD Password Spray From Single Source id: 7f1c2e90-3b4a-4d77-9b21-2c6f5a8e1d44 status: experimental description: > Detects a single source address failing authentication across many distinct accounts in a short window, the signature of a password spray. references: - https://attack.mitre.org/techniques/T1110/003/ author: Edward Griggs date: 2026/06/23 logsource: product: azure service: signinlogs detection: selection: ResultType: - '50126' # invalid username or password - '50053' # account locked condition: selection timeframe: 30m fields: - IPAddress - UserPrincipalName - ResultType falsepositives: - Shared corporate egress IP behind NAT - Applications replaying stale credentials level: high tags: - attack.credential-access - attack.t1110.003 ``` ## CI pipeline 在每个涉及规则的 pull request 中，GitHub Actions 都会验证 Sigma 语法并将规则转换为 KQL。如果验证失败，则不会进行任何合并。 ``` name: validate-detections on: pull_request: paths: [ 'rules/**' ] push: branches: [ main ] jobs: validate: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Set up Python uses: actions/setup-python@v5 with: python-version: '3.12' - name: Install Sigma tooling run: pip install sigma-cli pysigma-backend-kusto - name: Validate rule syntax run: sigma check rules/ - name: Convert rules to KQL run: sigma convert -t kusto -p pipelines/sentinel.yml rules/ -o build/kql/ - name: Upload generated queries uses: actions/upload-artifact@v4 with: name: kql-detections path: build/kql/ ``` ## 测试策略 语法验证只是底线，而非上限。路线图旨在将 CI 扩展至行为置信度层面： 1. **语法和 schema 验证**（已实现）：每条规则都是格式良好的 Sigma 规则。 2. **字段验证**（路线图）：引用的字段存在于目标日志 schema 中。 3. **转换验证**（已实现）：每条规则都能编译为有效的 KQL。 4. **检测测试**（路线图）：将每条规则与一个 Atomic Red Team 测试配对，并断言转换后的查询能在实验室数据中返回预期事件。 ## 这展示了什么 - 超越单纯编写查询的检测工程：涵盖生命周期、版本控制和自动化 - 将应用于安全内容的实用 CI/CD 与 GitHub Actions 相结合 - 熟练运用 Sigma 和 pySigma 实现后端可移植的检测 - 区分检测工程师与规则编写者的工程成熟度 ## 关于 由 Edward Griggs 构建和维护。已获得 Security+ 认证，正在考取 SC-200，正从系统与安全管理基础出发，向检测工程师角色迈进。 [LinkedIn](https://www.linkedin.com/in/edward-griggs/) · [GitHub](https://github.com/edwardjgriggs)

标签：GitHub Actions, Sigma规则, 安全运营, 扫描框架, 检测即代码, 目标导入, 自动笔记, 逆向工具