EduardoRochaFernandes/detection-as-code-pipeline

# 检测即代码流水线 + AI 告警分诊助手 **将检测规则视为软件：进行版本控制，针对模拟的 MITRE ATT&CK 攻击进行自动化测试，并且只有在它们确实能捕捉到攻击且对正常活动无误报时才会被部署 —— 并配有一个 AI 辅助的分诊工具，能将原始告警转化为结构化的调查报告。** 大多数初级蓝队作品集只是一个静态的“家庭 SOC 实验室”：安装 Wazuh，添加 Sysmon，截取仪表盘的截图。这个项目重用了这些相同的组件，但将它们包装在一个*工程化流程*中 —— 版本控制、自动化的真阳性（true-positive）和假阳性（false-positive）测试，以及一个失败即阻断的 CI/CD 门禁 —— 因此它展示的是**构建**安全工具，而不仅仅是使用它。它可以在单台笔记本电脑上运行，并且完全使用免费/开源软件。 ## 架构 两个协调的子系统涵盖了完整的防御循环：**编写检测规则 → 证明它们有效 → 部署 → 捕捉告警 → 调查 → 记录文档。** ``` flowchart TD subgraph P1["Phase 1 — Detection-as-Code Pipeline"] A[GitHub Repo
Sigma rules + tests + CI] -->|git push / PR| B[GitHub Actions] B --> B1[Tier 1: lint YAML + metadata] B1 --> B2[Convert Sigma to backend query] B2 --> B3[Tier 2: detection FIRES on attack fixture] B3 --> B4[Tier 2: NO fire on clean baseline] B4 -->|all green| C{Deploy gate
needs: detection-tests} C -->|artifact / self-hosted runner| D[Wazuh Manager + Indexer] E[Windows endpoint
Sysmon + Atomic Red Team] -->|captured telemetry| A E -->|live logs| D end subgraph P2["Phase 2 — AI Alert Triage Assistant"] D -->|new alert| F[Ingest / normalize] F --> G[Enrich: VirusTotal / AbuseIPDB / OTX] G --> H[Correlate + timeline] H --> I[Deterministic severity score] I --> J[LLM narrative report] J --> K[Markdown/JSON + escalation webhook] end ``` 完整说明：[docs/architecture.md](docs/architecture.md)。 ## 60 秒上手体验 —— 无需 API 密钥、无需注册、无需实验室 以下所有内容均在**零外部账户**的情况下运行。无需 VirusTotal/AbuseIPDB/OTX/Anthropic 密钥，无需 Docker，也不需要 Windows VM —— 这是刻意为之的，这样审查者（或招聘人员）就可以克隆并验证整个项目是否有效，而无需向任何人索取凭证。 ``` git clone && cd detection-as-code-pipeline python -m pip install -r pipeline/requirements.txt python -m pytest tests/ -v # 80 checks: syntax + true-positive + false-positive python pipeline/compute_metrics.py # coverage metrics -> metrics.json ``` 接下来是 AI 分诊助手 —— 当未配置任何密钥时，它会优雅降级为确定性的、无 LLM 的报告，因此这在没有任何设置的情况下也能运行： ``` python -m pip install -r triage-assistant/requirements.txt cd triage-assistant && python -m app.main --alert sample_alerts/example_rdp_bruteforce_alert.json ``` 想看看*富信息*路径吗（真实的 VirusTotal/AbuseIPDB/OTX 查询以及由 LLM 编写的叙述，而不是确定性模板）？将 `.env.example` 复制到 `.env` 并填入你自己的免费层级密钥 —— 具体了解需要哪些密钥以及去哪里获取，请查看 [.env.example](.env.example)。本仓库中未提交任何真实密钥（参见 [局限性](#limitations--honest-trade-offs)，如果提交了真实密钥，Gitleaks CI 任务会使构建失败）。 完整的实况实验室启动指南（Wazuh + Sysmon 终端 + Atomic Red Team）： [docs/setup-guide.md](docs/setup-guide.md)。 ## 内容包含 | 目录 | 用途 | |-----------|---------| | [`rules/sigma/`](rules/sigma) | 13 个 Sigma 检测规则，包含完整元数据，映射至 ATT&CK | | [`pipeline/`](pipeline) | 内存级 Sigma 匹配器、转换、部署、atomic 编排、指标 | | [`tests/`](tests) | 3 个测试层级 + 捕获的攻击测试夹具 + 干净的基线 | | [`.github/workflows/`](.github/workflows) | 验证、测试并部署（失败即阻断）、密钥扫描 | | [`triage-assistant/`](triage-assistant) | 阶段 2 AI 分诊工具 | | [`mitre_attack/`](mitre_attack/coverage_map.md) | 覆盖范围映射图 + 单个规则的方法论 | | [`docs/`](docs) | 架构、设置、经验教训 | ## MITRE ATT&CK 覆盖范围 跨越 10 个战术的 13 项技术；**13/13** 个规则通过了真阳性和假阳性测试。完整表格及方法论： [mitre_attack/coverage_map.md](mitre_attack/coverage_map.md)。 | 技术 | 名称 | 战术 | 状态 | |-----------|------|--------|--------| | T1110.001 | RDP 暴力破解 | 凭证访问 | ✅ 测试通过 | | T1059.001 | 可疑的 PowerShell | 执行 | ✅ 测试通过 | | T1003.001 | LSASS 凭证转储 | 凭证访问 | ✅ 测试通过 | | T1547.001 | 注册表 Run 键持久化 | 持久化 | ✅ 测试通过 | | T1021.002 | SMB admin-share 横向移动 | 横向移动 | ✅ 测试通过 | | T1053.005 | 计划任务 | 持久化 | ✅ 测试通过 | | T1070.001 | 清除事件日志 | 防御规避 | ✅ 测试通过 | | T1078 | 有效账户滥用 | 初始访问 | ✅ 测试通过 | | T1071.001 | 可疑的 web UA (C2) | 命令与控制 | ✅ 测试通过 | | T1136.001 | 本地账户创建 | 持久化 | ✅ 测试通过 | | T1486 | 勒索软件文件影响 | 影响 | ✅ 测试通过 | | T1018 | 远程系统发现 | 发现 | ✅ 测试通过 | | T1055 | 进程注入 | 防御规避 | ✅ 测试通过 | ## 流水线如何保障质量 当你 `git push` 一个新增或修改的 Sigma 规则时： 1. **第 1 层（单元测试）** —— 每个规则都必须能被解析（结构化验证 + 真实的 pySigma），并携带所有必需的元数据，包括一个非空的 `falsepositives` 块。 2. **转换** —— Sigma 被编译为后端查询（Lucene / 原生 Wazuh XML）。 3. **第 2 层真阳性** —— 该规则将针对从匹配的 Atomic Red Team 测试中捕获的遥测数据进行重放；它**必须触发**。 4. **第 2 层假阳性** —— 该规则将针对正常活动的干净基线进行重放；它**绝对不能触发**。 5. **部署门禁** —— `deploy` 作业声明了 `needs: detection-tests` 和 `if: success()`。**任何未通过测试的检测规则都永远无法到达 SIEM。** 最后一行是整个项目的核心理念。评估过程通过内存级 Sigma 匹配器（`pipeline/sigma_matcher.py`）运行，因此整个测试套件在 CI 中不到一秒钟即可完成，且无需实况 SIEM —— 查看 [docs/architecture.md](docs/architecture.md) 了解原因，以及如何升级到实况的临时 SIEM（ephemeral-SIEM）测试。 ## 演示 *90秒录屏占位符*（拍摄清单见项目说明书第 9.3 节）：编辑规则 → 推送 → CI 运行变绿 → 触发 atomic → Wazuh 中触发告警 → 生成分诊报告。录好后将 GIF 添加到 `docs/images/demo.gif`。 ## 局限性与诚实的权衡 - **基于测试夹具的 CI，尚非实况 SIEM。** 测试使用内存级匹配器对捕获/规范化的遥测数据进行处理。这证明了*机制*的可行性；但它并未对时间窗口或跨事件序列的关联进行建模。升级到 CI 中的临时 OpenSearch 容器只需更改一个函数（见路线图）。 - **家庭实验室的假阳性率不能代表**企业环境的噪音水平。有几个规则需要针对真实流量进行调整。 - **部署受制品门禁控制，而非云端自动化。** GitHub 托管的 runner 无法连接到笔记本电脑实验室，因此 CI 会发布经过验证的制品，而部署是在本地/自托管 runner 上进行的。坦率地说，没有作假。 - **AI 报告需要人工审查**，且绝不会由其决定一个事件（阶段 2 是 Tier-1 的辅助增强）。 ## 路线图 实况临时 SIEM 的 CI 测试 · 用于自动部署的自托管 runner · Zeek/Suricata 网络检测 · 从覆盖范围映射图生成 ATT&CK Navigator 热力图 · 将 Ollama 作为默认的（空气隔离）LLM · Trivy 容器扫描 · 为目前不在范围内的有状态检测添加 Sigma 关联规则。 ## 简历要点与推介 请参阅 [docs/lessons-learned.md](docs/lessons-learned.md) 和项目说明书的第 10 节。30秒推介：*"我把检测规则当作软件来对待 —— 每个规则都经过版本控制，使用 Atomic Red Team 针对真实的模拟攻击进行自动化测试，并且只有在它能捕捉到攻击且对正常活动无误报时才会被部署。在此基础之上，我还构建了一个 AI 助手，它可以丰富任何告警的信息，构建时间线，并起草调查报告。"* ## 许可证 [MIT](LICENSE)。欢迎反馈和 PR。由 Eduardo Fernandes 作为蓝队 / DevSecOps 作品集项目构建。

标签：AI辅助分析, C2, SIEM告警分诊, 安全运营, 扫描框架, 检测即代码, 逆向工具