Vitaliy598/detection-as-code

# Detection-as-Code 作品集  这是我的 Detection Engineering 作品集项目。 我构建这个项目是为了展示我如何以结构化和可重复的方式设计、验证、记录和审查检测逻辑。 该项目侧重于 SOC 调查逻辑、基于行为的检测、多信号关联、规范化遥测、告警质量、误报调优以及 Detection-as-Code 实践。 主要检测包不再依赖简单的关键字匹配，而是使用规范化的合成遥测和行为条件。每个规则都包含测试数据、预期输出、元数据、验证检查、覆盖范围说明和已记录的局限性。 目标是使检测工作流易于审查： - 正在检测什么行为； - 需要什么遥测； - 使用了哪些字段； - 告警是如何产生的； - 规则是如何测试的； - 哪些正常活动不应触发告警； - 哪里可能出现误报； - 存在哪些假设和局限性。 本仓库被设计为一个公开的作品集展示物。它使用合成遥测和轻量级验证工具来展示检测开发背后的工程工作流。 ## 本项目展示的内容 本项目演示了围绕 SOC 和 Detection Engineering 场景的完整 Detection-as-Code 工作流： - 行为和多信号关联； - 规范化的遥测字段； - 结构化的告警输出； - 机器可读的规则元数据； - schema 与语义验证； - 恶意、良性、近似阈值、窗口外以及仅包含关键字的测试用例； - 带有特定范围异常处理的误报调优； - 覆盖范围与遥测缺口追踪； - 面向 KQL、SPL 和 Sigma 的检测表示形式； - SOC 分诊和升级文档； - 基于 CI 的验证与可重复检查。 核心理念很简单：检测不仅应发现可疑活动，它还应当是可解释、可测试、可调优和可审查的。 ## 主要检测包 当前主要的检测包使用规范化遥测模型和标准告警契约。 | 规则 ID | 检测场景 | 状态 | 证据 | |---|---|---|---| | `DET-LINUX-002` | SSH 暴力破解后成功登录、sudo 活动及 cron 持久化 | `validation` | 阳性、良性、阈值近似以及窗口外案例 | | `DET-WIN-001` | 可疑 PowerShell 执行后伴随远程下载行为 | `validation` | 阳性、良性以及不相关的窗口外活动 | | `DET-NET-001` | 下载活动后伴随重复的出站回调行为 | `validation` | 阳性、良性、阈值近似以及窗口外案例 | | `DET-CLOUD-001` | 涉及登录、MFA 和转发信号的云身份滥用 | `validation` | 阳性、良性、评分近似以及白名单安全案例 | `validation` 表示该规则通过了仓库内设定的检查：遥测格式、告警 schema、元数据引用、预期输出以及回归测试。 只有经过针对特定环境的审查（真实遥测映射、基线分析、预期告警量、抑制策略、性能测试、责任归属以及部署监控）后，规则才能脱离此状态。 ## 历史回归包 `DET-LINUX-001` 作为历史回归包被保留。 它代表了仓库转向当前规范化遥测模型之前，早期使用的一种 Linux 无文件执行和身份验证验证方法。 它留在仓库中是为了： - 进行历史比较； - 向后兼容的回归验证； - 展示项目是如何演进的。 它独立于四个主要的规范化关联包。 标准元数据： ``` metadata/DET-LINUX-001.json ``` 历史快照： ``` metadata/legacy/ ``` 文档： ``` docs/legacy-det-linux-001.md ``` ## 仓库结构 ``` .github/ GitHub Actions workflow and PR checklist capstone/ End-to-end investigation artifact config/ Trusted change and allowlist configuration conversions/ KQL, SPL, Sigma, and field mapping examples coverage/ Coverage matrix and telemetry gaps data/ Synthetic telemetry fixtures docs/ Architecture, lifecycle, testing, tuning, and review notes metadata/ Canonical rule manifests playbooks/ SOC investigation and escalation guidance reviews/ Detection review evidence rules/ Detection and correlation logic schemas/ Alert, manifest, and tuning contracts scripts/ Validation utilities tests/ Expected outputs and regression checks tuning/ Scoped tuning exception records run_ci.sh Main validation entry point ``` 该仓库有意保持轻量化。重点在于检测推理、验证、文档记录和可审查性，而不是复杂的基础设施。 ## 检测工作流 本项目使用的工作流如下： ``` telemetry fixture ↓ normalization checks ↓ behavior-based rule logic ↓ canonical alert output ↓ expected output validation ↓ metadata and schema validation ↓ coverage and tuning checks ↓ CI result ``` 每个检测包都围绕相同的审查问题进行构建： 1. 什么行为是可疑的？ 2. 需要什么遥测？ 3. 哪些字段是必填的？ 4. 预期的告警输出是什么？ 5. 哪些正常活动不应触发告警？ 6. 应该测试哪些边缘情况？ 7. 可能出现哪些误报？ 8. 应该记录哪些局限性？ ## 规范化遥测模型 主要的 fixture 使用规范化的遥测字段，例如： ``` event_time case_id event_type host user source_ip destination_ip process_name parent_process_name command_line url domain action result auth_method rule_context ``` 这将检测行为与实验室环境特定的字符串分离开来。 例如，主要规则不应仅仅因为命令行、URL 或日志信息中出现可疑词就触发告警。它们应该因为存在预期的字段、动作、实体和时序关系序列而触发告警。 这使得逻辑更容易审查，并且更贴近 SOC 和 SIEM 环境中评估检测思路的方式。 ## 标准告警契约 可操作的告警使用管道符分隔的 `key=value` 字段。 必填字段包括： ``` schema_version alert_id rule_id rule_version lifecycle_state severity risk_score event_start event_end correlation_window_seconds case_id host user source_ip destination_ip observed_signals reason recommended_action ``` 严重性标准化取值为： ``` low medium high critical ``` 规则不会将 `NO_ALERT` 记录作为告警输出。如果预期某案例不产生告警，测试工具会验证该案例是否确实未产生告警。 `case_id` 字段用于 fixture 的可追溯性。在 SIEM 部署中，它将被特定平台的告警、事件、事件单或关联标识符所取代。 ## 验证工作流 运行与 GitHub Actions 相同的验证入口： ``` ./run_ci.sh ``` CI 工作流验证内容： 1. 仓库元数据； 2. 规范化遥测格式； 3. 告警 schema 和必填字段； 4. 规则清单和引用； 5. 验证器失败路径； 6. 覆盖率记录； 7. 主要检测场景； 8. 历史回归行为； 9. 转换示例； 10. 审查和最终交付物； 11. Python 语法； 12. 格式化问题。 预期输出使用共享格式： ``` CaseID|ExpectedSeverity ``` 共享验证逻辑实现于： ``` tests/validate_detection_output.py ``` 这避免了每个规则都有自己脆弱的输出解析器。 ## 测试策略 项目包含多种类型的测试用例： | 测试类型 | 目的 | |---|---| | Positive (阳性) | 确认恶意行为会产生预期告警 | | Benign (良性) | 确认正常活动不会触发告警 | | Near-miss (近似阈值) | 确认接近阈值的活动不会过早触发告警 | | Out-of-window (窗口外) | 确认关联窗口之外的事件不会被错误地关联 | | Keyword-only (仅含关键字) | 确认仅凭可疑词汇不会触发告警 | | Keyword-independent (关键字无关) | 确认即使没有旧的特定实验关键字，行为也能触发告警 | | Allowlist safety (白名单安全性) | 确信任信的异常处理不会抑制其他不相关的可疑链条 | | Regression (回归) | 确认历史行为保持稳定 | 最重要的部分是，测试必须证明规则是因为正确的原因触发告警，而不仅仅是因为 fixture 中存在某个合成的关键字。 ## 检测生命周期 规则会经历已记录的生命周期状态： ``` idea development experimental validation production_candidate tuning_required deprecated ``` 在本仓库中，主要规则保持在 `validation` 阶段。 这意味着它们通过了仓库的验证门，但在实际部署前仍需进行针对特定环境的审查。 只有在审查以下内容后，规则才应向 `production_candidate` 推进： - 遥测源质量； - 字段映射可靠性； - 基线行为； - 预期告警量； - 误报风险； - 抑制和调优策略； - 响应归属； - 性能影响； - 针对部署环境的局限性。 ## 误报调优 调优记录被视为受控的异常处理，而非宽泛的白名单。 一个调优异常应当具备： - 明确的所有者； - 特定的作用范围； - 正当理由； - 过期日期； - 回滚条件； - 回归测试覆盖率。 本项目展示了一个重要原则：如果其他信号仍然提示存在风险，信任某一个信号不应自动抑制整个可疑链条。 这在云身份和转发规则场景中尤为重要，因为过于宽泛的白名单可能会掩盖账户被盗用的特征。 ## 覆盖范围和遥测缺口 覆盖范围跨越多个维度进行追踪： - ATT&CK 映射； - 检测覆盖率； - 遥测可用性； - 字段可用性； - 测试覆盖率； - 已知的盲点。 覆盖率为： ``` full partial indirect not_covered ``` 覆盖率仅适用于本仓库中可用的证据。不应将其理解为宣称相同的检测在每个环境中都能不加修改地有效运行。 已知的缺口包括： - 生产环境时间戳语义； - 时区和摄入延迟处理； - 进程父进程质量； - payload 哈希和签名； - 设备合规性上下文； - IP 和域名信誉； - TLS 可见性； - 基线量； - 目标 SIEM 性能； - 部署后监控。 这些局限性是有意记录下来的。当假设和盲点清晰可见时，检测逻辑会更为严谨。 ## 面向 SIEM 的表示形式 仓库包含以下示例： - KQL 风格逻辑； - Splunk SPL 风格逻辑； - 面向 Sigma 的表示形式； - 字段映射。 包含这些内容是为了展示如何在面向 SIEM 的格式之间转换相同的检测思路，同时仍能记录假设和局限性。 本地验证工具证明了本仓库内的检测行为。而真实部署将需要原生 SIEM 实现、针对特定环境的字段映射、查询测试、性能审查和运营调优。 ## ATT&CK 映射策略 ATT&CK 映射包括： - 技术 ID； - 战术； - 置信度； - 针对规则的说明； - 直接观察到的行为； - 推断出的行为； - 歧义或局限性。 本项目避免将每一个可疑事件都视为完整 ATT&CK 技术的证明。 例如，反复的出站 HTTP 回调可能支持命令与控制（C2）的假设，但它们本身并不能证明存在命令与控制的意图。这种区别在 SOC 调查和升级过程中至关重要。 ## 审查工作流 仓库包含一个针对检测变更的审查工作流。 审查过程检查： - 规则目的； - 所需遥测； - 字段映射； - 检测逻辑； - 告警输出； - 测试覆盖率； - 误报假设； - 调优范围； - ATT&CK 理由； - 已知局限性； - 响应指导。 在这个作品集中，审查清单是一种自我审查控制机制。它展示了我如何构建检测审查流程，但并不意味着这是一个需要多人参与的批准过程。 ## 最终交付物 `capstone/` 目录将项目整合为一个调查工作流。 它连接了： ``` telemetry → detection → alert → evidence → review → triage explanation ``` 其目的是展示检测不仅在于如何编写，还在于如何以一种支持 SOC 调查和升级的方式进行解释。 ## 如何审查本仓库 要进行快速的技术审查，请从这里开始： 1. `README.md` — 项目概述和范围。 2. `run_ci.sh` — 验证入口。 3. `rules/` — 检测和关联逻辑。 4. `data/` — 规范化遥测 fixture。 5. `tests/` — 预期输出和回归检查。 6. `metadata/` — 标准规则清单。 7. `schemas/` — 告警和元数据契约。 8. `coverage/` — 覆盖率和已知缺口。 9. `docs/testing-strategy.md` — 测试模型。 10. `docs/reviewer-workflow.md` — 审查方法。 11. `capstone/` — 端到端调查工件。 该项目最有力之处不在于某一条单一的规则。最有力之处在于围绕规则的完整工作流：验证、文档记录、调优、覆盖率以及可审查性。 ## 范围 本仓库专注于检测逻辑、验证、文档记录和可审查性。 某些领域被特意留给了针对特定环境的部署工作： - 实时 SIEM 部署； - 生产环境遥测摄入； - 性能基准测试； - 真实的客户或公司数据； - 实测的生产环境误报率； - 端点响应自动化； - SOAR playbook 执行； - 长期告警监控； - 特定于环境的抑制策略； - 完整的 ATT&CK 覆盖。 这些领域不在公开作品集仓库的范围内，它们需要真实的部署环境、生产环境的遥测、运营责任归属以及部署后监控。 ## 作品集定位 我使用这个项目来展示我如何处理 Detection Engineering 工作：规则逻辑、遥测要求、告警质量、验证、调优、文档记录和可审查性。 该仓库展示了以可重复的方式构建和测试检测逻辑的结构化工作流。它不是作为一个已部署的检测平台来展示的，而是作为一个专注于 SOC 调查和面向 SIEM 的检测工程的实际作品集项目。 我的重点是 SOC 调查、行为关联、误报分析、面向 SIEM 的检测逻辑以及 Detection-as-Code 实践。

标签：SIEM规则, 代码化检测, 安全运营, 扫描框架, 逆向工具