cpt-ferna02/detection-engineering-cicd

# 检测工程 CI/CD 平台      ## Pipeline — 100% ATT&CK 覆盖率  ## 概述 大多数检测工程工作都在孤立的环境中进行——有人编写一条规则，部署它，并希望它能起作用。本项目通过构建一个**用于检测的 CI/CD pipeline** 来解决这个问题：每条规则都会针对真实的攻击模拟进行自动测试，并且必须通过测试才能被视为有效的覆盖。 这反映了成熟企业组织中的安全团队如何验证其检测内容——区别在于这是作为一个独立项目从零开始构建的。 ## 架构 ``` ┌─────────────────────────────────────────────────────────────────┐ │ ATTACK SIMULATION LAYER │ │ Atomic Red Team → Windows 11 Host (ATT&CK Techniques) │ └─────────────────────────┬───────────────────────────────────────┘ │ Sysmon Telemetry ▼ ┌─────────────────────────────────────────────────────────────────┐ │ DETECTION LAYER │ │ Sysmon → Wazuh Agent → Wazuh Manager → Custom Rules │ └─────────────────────────┬───────────────────────────────────────┘ │ Alerts + Rule Firing ▼ ┌─────────────────────────────────────────────────────────────────┐ │ VALIDATION LAYER │ │ Python Pipeline → Wazuh Indexer API → PASS/FAIL per Technique│ └─────────────────────────┬───────────────────────────────────────┘ │ Coverage Data ▼ ┌─────────────────────────────────────────────────────────────────┐ │ REPORTING LAYER │ │ HTML Dashboard + Claude AI SOC Incident Report │ └─────────────────────────────────────────────────────────────────┘ ``` ## ATT&CK 覆盖率结果 | 技术 | 名称 | 战术 | 自定义规则 | 状态 | |-----------|------|--------|-------------|--------| | T1057 | 进程发现 | 发现 | 100002 | ✅ 通过 | | T1059.001 | PowerShell 执行 | 执行 | 100004 | ✅ 通过 | | T1082 | 系统信息发现 | 发现 | 100006 | ✅ 通过 | | T1053.005 | 计划任务持久化 | 持久化 | 100003 | ✅ 通过 | | T1027 | Base64 防御规避 | 防御规避 | 100007 | ✅ 通过 | **检测到 5/5 项技术 — 100% 覆盖率** ## 功能 - 通过 Atomic Red Team 在活动的 Windows 11 端点上执行**自动化攻击模拟** - 通过 Sysmon 和 SwiftOnSecurity 配置提供**深度遥测** - 使用 Wazuh XML 编写的**自定义检测规则**，映射到 MITRE ATT&CK - **CI/CD 验证 pipeline**，查询 Wazuh indexer API 并为每条规则评分（通过/失败） - 包含 ATT&CK 技术细分和覆盖率环的 **HTML 覆盖率仪表板** - 通过 Claude API 生成 **AI SOC 事件报告** — 专业的 markdown 输出 - **单命令执行** — 使用 `bash pipeline/run_pipeline.sh` 运行整个 pipeline ## 截图 ### 实验环境 — Wazuh Agent 处于活动状态  *Windows 11 主机已连接到 Wazuh manager 且状态为活动 — 这是检测实验室的基础。* ### 攻击模拟 — Sysmon 遥测数据涌入  *在 ATT&CK 技术模拟期间捕获了 223+ 个 Sysmon 事件 — 发现活动、net.exe 账户枚举以及异常进程链均清晰可见。* ### 攻击模拟 — 高严重性检测  *触发等级 15（严重）警报 — 可执行文件被释放到恶意软件常见文件夹，并在注册表键中检测到类似 Base64 的模式（T1027 防御规避）。* ### 触发自定义检测规则  *触发自定义规则 ID 100004 和 100006 — 这些不是 Wazuh 内置规则。这些是专门为本项目编写的，映射到 MITRE ATT&CK T1059.001 和 T1082。* ### ATT&CK 覆盖率仪表板  *自动生成的 HTML 仪表板，显示 100% 的覆盖率环、5/5 项技术通过，并带有完整的 ATT&CK 技术细分。* ## 技术栈 | 组件 | 技术 | |-----------|-----------| | SIEM | Wazuh 4.7.5 (Docker) | | 端点遥测 | Sysmon + SwiftOnSecurity 配置 | | 攻击模拟 | Atomic Red Team (invoke-atomicredteam) | | 目标端点 | Windows 11 | | 检测规则 | 自定义 Wazuh XML 规则 | | Pipeline | Python 3 | | AI 报告 | Claude API (Anthropic) | | 版本控制 | Git + GitHub | ## 项目结构 ``` detection-engineering-cicd/ ├── pipeline/ │ ├── validate_detections.py # Core CI/CD validation engine │ ├── generate_dashboard.py # HTML ATT&CK coverage dashboard │ ├── generate_report.py # AI-powered SOC incident report │ └── run_pipeline.sh # Master pipeline runner ├── detection-rules/ │ └── local_rules.xml # Custom Wazuh detection rules ├── reports/ # Generated coverage reports (JSON/HTML/MD) ├── docs/ │ └── screenshots/ # Project screenshots └── attack-simulations/ # ATT&CK technique documentation ``` ## 用法 ``` # 设置你的 Anthropic API key export ANTHROPIC_API_KEY=your-key-here # 运行完整的 pipeline (validate + dashboard + AI report) bash pipeline/run_pipeline.sh # 或者运行单个组件 python3 pipeline/validate_detections.py # Validate all detection rules python3 pipeline/generate_dashboard.py # Generate HTML dashboard python3 pipeline/generate_report.py # Generate AI incident report ``` ### Pipeline 输出 ``` ============================================================ Detection Engineering CI/CD Pipeline Full Run - Thu Jun 4 06:58:08 PM CDT 2026 ============================================================ [1/3] Running detection validation... [+] Wazuh API authenticated successfully [*] Testing T1059.001 - PowerShell Execution [✓] PASS - Rule 100004 confirmed in alerts! [*] Testing T1082 - System Information Discovery [✓] PASS - Rule 100006 confirmed in alerts! [*] Testing T1057 - Process Discovery [✓] PASS - Rule 100002 confirmed in alerts! [*] Testing T1053.005 - Scheduled Task Persistence [✓] PASS - Rule 100003 confirmed in alerts! [*] Testing T1027 - Base64 Defense Evasion [✓] PASS - Rule 100007 confirmed in alerts! ============================================================ DETECTION COVERAGE REPORT Total: 5 | Passed: 5 | Failed: 0 | Coverage: 100.0% ============================================================ [2/3] Generating coverage dashboard... [+] Dashboard saved to reports/dashboard_20260604_185819.html [3/3] Generating AI incident report... [+] AI incident report saved to reports/incident_report_20260604_185831.md ============================================================ Pipeline complete! Check reports/ folder for all outputs ============================================================ ``` ## 挑战与问题解决 本节记录了在此构建过程中遇到的真实技术障碍及其解决方法。检测工程主要是调试——以下是其实际情况。 ### 挑战 1：Arch Linux 不支持 Wazuh **问题：** Wazuh 的官方安装脚本 (`wazuh-install.sh -a`) 立即退出并显示： ``` ERROR: Couldn't find type of system ``` Arch Linux 不在 Wazuh 支持的发行版列表中，并且该脚本没有后备方案。 **解决方案：** 使用官方的 `wazuh-docker` 单节点 compose stack 完全通过 Docker 部署 Wazuh。与本地安装相比，这实际上生成了一个更便携、更可复现的环境。 **经验教训：** 当工具不支持你的操作系统时，容器化通常是与安装程序抗争相比更简洁的解决方案。Docker 部署也更贴近实际——大多数企业级的 Wazuh 部署都是以容器方式运行的。 ### 挑战 2：项目中途磁盘空间耗尽 **问题：** 在安装 PowerShell 期间，根分区的容量达到了 100%： ``` Your Root partition is running out of disk space; 0 MiB remaining (0%) df -h showed: /dev/sda2 49G 47G 0 100% / ``` 来自之前多个安全项目的 Docker 镜像层消耗了几乎所有可用空间。 **解决方案：** 运行了 `docker system prune -a --volumes -f`，安全地移除了未使用的镜像和卷，恢复了 4.7GB 空间。还清理了 pacman 缓存和 journal 日志以恢复额外空间，使使用率降至 80%。 **经验教训：** 在实验室环境中，Docker 镜像膨胀是一个真实的运维问题。定期清理和磁盘监控应成为任何实验室维护规范的一部分。 ### 挑战 3：自定义检测规则未触发 (0% → 100%) **问题：** 在使用 `if_sid` 编写 6 条自定义 Wazuh 规则以从父规则（92027、92031、92034）进行链接后，验证 pipeline 显示 0% 的覆盖率——尽管父规则已正确触发并具有数百次命中，但没有一条自定义规则出现在警报中。 **诊断过程：** 1. 确认父规则正在触发——仪表板中可见数百次命中 2. 确认规则 XML 语法有效——重启时没有解析错误 3. 查询原始警报日志以查看 Sysmon 事件中的实际字段值 4. 发现 tasklist.exe 和 wmic.exe 事件触发了与预期不同的基础 Sysmon 事件 ID 5. 发现本身已经是子规则的规则（如 92041）上的 `if_sid` 需要改用 `if_matched_sid` **解决方案：** - 对于基于进程的规则，将基础 `if_sid` 引用更改为 `61603`（原始 Sysmon 进程创建事件） - 对于从 92041 链接的 T1027 Base64 注册表规则，将 `if_sid` 更改为 `if_matched_sid` - 通过迭代修复，覆盖率从 0% → 80% → 100% **经验教训：** 对于编写自定义规则的检测工程师来说，理解 Wazuh 规则链接模型中 `if_sid` 和 `if_matched_sid` 之间的区别至关重要。这一点并没有被很好地记录下来，需要直接从日志中阅读源代码行为。 ### 挑战 4：Wazuh API Endpoint 不匹配 **问题：** 最初的 pipeline 使用 `/siem/alerts` endpoint 查询已触发的规则。尽管在 Wazuh 仪表板中可以清楚地看到规则在触发，但所有 5 项技术均返回失败。该 endpoint 返回了 404。 **解决方案：** 切换为直接查询 Wazuh OpenSearch indexer，地址为： ``` https://localhost:9200/wazuh-alerts-*/_search ``` 使用 OpenSearch DSL 查询格式，并为规则 ID、agent ID 和时间戳范围设置 `bool/must` 过滤器。这提供了对警报索引的直接、准确的访问。 **经验教训：** 务必根据正在运行的特定版本验证 API endpoint。Wazuh API 和底层的 OpenSearch indexer API 是独立的接口——对于自定义工具，indexer 查询提供了更大的灵活性和可靠性。 ### 挑战 5：API 密钥在 Git 提交中暴露 **问题：** GitHub 的推送保护机制阻止了推送，提示： ``` remote: - GITHUB PUSH PROTECTION remote: Push cannot contain secrets remote: — Anthropic API Key — remote: locations: commit: fa580416 path: pipeline/generate_report.py:15 ``` Anthropic API 密钥被直接硬编码在源文件中，并在提交历史中被检测到。 **解决方案：** 1. 将硬编码的密钥替换为 `os.environ.get("ANTHROPIC_API_KEY")` 2. 创建 `.env` 文件用于本地存储密钥，并将其添加到 `.gitignore` 中 3. 使用 `git filter-branch` 重写历史记录，从所有提交中清除该密钥 4. 强制推送干净的历史记录 **经验教训：** 切勿在源文件中硬编码机密——从一开始就应使用环境变量。GitHub 的机密扫描是一项宝贵的最后防线，但正确的做法是首先不要提交机密。这是任何生产安全环境中的标准做法。 ## 面试的关键要点 **“这个项目最难的部分是什么？”** **“这与现实世界中的检测工程有什么联系？”** **“你为什么选择这个技术栈？”** ## 未来改进 - [ ] 添加 GitHub Actions 工作流，以便在每次规则更改时自动运行 pipeline - [ ] 扩展到涵盖更多战术的 20 多项 ATT&CK 技术 - [ ] 添加 Sigma 规则转换以支持多 SIEM（Splunk SPL、KQL） - [ ] 集成 Splunk 作为第二个 SIEM 验证目标 - [ ] 添加检测漂移警报——当以前通过的规则开始失败时发出通知 - [ ] 构建 ATT&CK Navigator 热力图 JSON 导出 - [ ] 为 Atomic Red Team 测试工件添加清理/回滚功能 ## 作者 **Fernando** — AAS 信息保障 专注于检测工程、SOC 自动化和 AI 辅助的安全运营。 GitHub: [@cpt-ferna02](https://github.com/cpt-ferna02)

标签：Atomic Red Team, Wazuh, 后端开发, 安全运营, 扫描框架, 数据泄露检测, 请求拦截, 逆向工具