DetectTrace

检测本应触发。它却没有。DetectTrace 会准确告诉你原因。

DetectTrace 是一个开源检测工程工具，用于端到端测试安全检测，并定位第一个失败的阶段。

DetectTrace 不是只测试 SIEM 查询，而是将检测视为一条流水线：

test behaviour
    -> telemetry
    -> ingestion
    -> normalization/schema
    -> rule evaluation
    -> rule execution
    -> alert generation

DetectSpec 声明应该发生什么。DetectTrace 收集实际发生情况的证据，评估契约，在第一个被证实的失败处停止因果推理，并将依赖的下游阶段标记为 BLOCKED。

当前实时后端是 Elastic Security。DetectTrace 还包含一个确定性的基于文件的模式，用于本地开发和回归测试。

为什么存在 DetectTrace

检测失败通常需要手动诊断：

• 测试实际运行了吗？
• 遥测生成了吗？
• 它到达后端了吗？
• 某个字段被重命名或丢弃了吗？
• 规则仍然匹配吗？
• 规则被禁用或不健康吗？
• 告警出现了吗，而且它属于这次确切的测试运行吗？

DetectTrace 将这些问题转化为可执行的检查和证据。

失败示例：

Test event                 PASS
Backend connection         PASS
Telemetry index            PASS
Telemetry located          PASS
Normalization              FAIL
Rule                       BLOCKED
Elastic rule exists        BLOCKED
Elastic rule enabled       BLOCKED
Rule execution             BLOCKED
Elastic alert              BLOCKED

RESULT
------------------------------------------------------------------------
Required field 'process.command_line' is absent, but the value from
'winlog.event_data.CommandLine' survived at 'process.args'.
Probable schema/mapping drift.

Confidence: HIGH
First failing stage: NORMALIZATION
Failure code: SCHEMA_DRIFT

重要的不只是检测失败了。DetectTrace 会解释检测路径在哪里首次失效，以及为什么。

DetectTrace 当前支持的功能

• DetectSpec v1 验证
• 基于 JSON/JSONL 证据的确定性离线追踪
• 安全的声明式谓词 DSL；不执行任意 Python 或 shell
• 嵌套字段检查
• 用于可能的 schema/mapping 漂移的字段血缘提示
• PASS / FAIL / BLOCKED / UNKNOWN / SKIPPED 阶段语义
• 首个失败阶段诊断
• 稳定的失败代码和修复文本
• 使用唯一 detecttrace.run_id 的相关 Elastic Security 测试
• 真实的 Elastic 规则存在/启用/执行检查
• 相关的 Elastic 告警验证
• 告警延迟测量
• 使用已配置 CA 的安全 Elasticsearch TLS
• detecttrace doctor 环境检查
• 文本、JSON 和 JUnit 兼容输出
• 回归测试和 GitHub Actions CI
• 可复现的本地 Elasticsearch + Kibana 实验环境

DetectTrace 不是什么

DetectTrace 不是：

• 攻击模拟平台
• BAS 替代品
• SIEM 规则编辑器
• 通用漏洞扫描器
• 猜测检测是否生效的 AI 系统

攻击/测试执行可以在以后集成。DetectTrace 的工作是根据观察到的证据验证检测路径并诊断失败。

要求

• Python 3.10+
• 仅当你想要运行提供的 Elastic 实验环境时，才需要带 Compose v2 的 Docker

CI 套件当前测试 Python 3.10、3.11、3.12 和 3.13。

五分钟离线快速开始

克隆仓库，创建虚拟环境，并安装 DetectTrace。

Windows PowerShell

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

Linux/macOS

python -m venv .venv
source .venv/bin/activate
python -m pip install -e .

检查安装：

detecttrace --version

创建一个可运行的入门项目：

detecttrace init demo

然后：

cd demo
detecttrace validate detectspec.yaml
detecttrace test detectspec.yaml

生成的项目是自包含的。它不需要 Elasticsearch、Kibana、Docker 或网络访问。

一次健康的运行会以如下内容结束：

Detection contract passed end-to-end.
Confidence: HIGH

离线健康与损坏示例

仓库包含一个 PowerShell fixture，其中既有已知良好的证据，也有故意损坏的证据。

健康：

detecttrace test examples/powershell/detectspec.yaml --profile healthy

损坏：

detecttrace test examples/powershell/detectspec.yaml --profile broken

损坏的 profile 故意将原始命令行保留在 process.args 下，而不是所需的 process.command_line。DetectTrace 将该失败定位到 normalization，并阻止 rule/alert 评估。

DetectSpec

DetectSpec 是声明式契约。DetectTrace 是根据证据评估该契约的引擎。

一个 DetectSpec 可以描述：

1. 执行证据
2. 源遥测
3. 收集证据
4. 规范化要求
5. 规则语义
6. 告警预期和时序
7. 相关的实时测试用例

示例：

spec_version: detectspec/v1
id: DET-PS-LIVE-001
title: Live Encoded PowerShell

inputs:
  profiles:
    live: {}

test:
  cases:
    healthy:
      event:
        event:
          code: 1
        process:
          name: powershell.exe
          command_line: powershell.exe -enc AAA

    broken:
      event:
        event:
          code: 1
        winlog:
          event_data:
            CommandLine: powershell.exe -enc AAA
        process:
          name: powershell.exe
          args: powershell.exe -enc AAA

checkpoints:
  normalization:
    require_event:
      all:
        - field: process.name
          op: endswith
          value: powershell.exe
    required_fields:
      - field: process.command_line
        from: winlog.event_data.CommandLine

  rule:
    match:
      all:
        - field: process.name
          op: endswith
          value: powershell.exe
        - field: process.command_line
          op: regex
          value: "(?i)(?:\\s|^)-(?:enc|encodedcommand)\\b"

JSON Schema 位于：

schemas/detectspec-v1.schema.json

运行时验证器和 JSON Schema 有意对未知的 DetectSpec 结构保持严格，以便拼写错误尽早失败。

谓词 DSL

叶子谓词使用：

field: process.name
op: equals
value: powershell.exe

支持的运算符包括：

exists
equals
not_equals
contains
startswith
endswith
regex
in
gt
gte
lt
lte

谓词可以用 all、any 和 not 组合。

示例：

all:
  - field: process.name
    op: endswith
    value: powershell.exe
  - any:
      - field: process.command_line
        op: contains
        value: "-enc"
      - field: process.command_line
        op: contains
        value: "-EncodedCommand"

首个失败阶段语义

DetectTrace 遵循一条简单规则：

先证据，后推断。首个失败阶段优先。

如果 normalization 失败，DetectTrace 不会假装知道下游规则或告警是否本会成功。这些阶段会报告为 BLOCKED。

如果证据不可用而不是被证伪，DetectTrace 会报告 UNKNOWN，而不是猜测。

稳定的机器可读结果 schema 是：

detecttrace.result/v1

重要字段包括：

healthy
first_failed_stage
failure_code
confidence
root_cause
remediation
run_id
stages

当前失败代码包括以下类别：

INGESTION_FAILURE
TELEMETRY_MISSING
SCHEMA_DRIFT
REQUIRED_FIELD_MISSING
RULE_NOT_FOUND
RULE_DISABLED
RULE_LOGIC_MISMATCH
RULE_EXECUTION_ERROR
ALERT_TIMEOUT
UNKNOWN

本地 Elastic Security 实验环境

一个可复现的安全实验环境包含在：

lab/elastic

它提供：

Elasticsearch 8.15.3   https://localhost:9201
Kibana 8.15.3          http://localhost:5602
Elasticsearch security enabled
Elasticsearch HTTP TLS enabled
Persistent Elasticsearch data
Persistent certificates
Kibana encryption keys
detecttrace-events index

完整设置请参见 lab/elastic/README.md。

简版是：

cd lab\elastic
Copy-Item .env.example .env
docker compose up -d

服务健康后，返回仓库根目录并导出公共 CA：

New-Item -ItemType Directory -Force .\certs | Out-Null
docker cp detecttrace-es:/usr/share/elasticsearch/config/certs/http_ca.crt .\certs\http_ca.crt
Copy-Item .detecttrace.example.yaml .detecttrace.yaml

然后验证环境：

detecttrace doctor

就绪的环境会为以下项报告 PASS：

DetectTrace config
Elasticsearch CA
Elasticsearch
Telemetry index
Kibana

本地 .env、.detecttrace.yaml 和导出的 certs/ 材料是特定于环境的，不会被提交。

Elastic 端到端测试

提供的实时示例是：

examples/elastic_live_detectspec.yaml

实验环境使用的示例 Elastic Security 规则是：

Name:
DetectTrace - Encoded PowerShell

Index:
detecttrace-events

Query:
process.name : "powershell.exe" and process.command_line : "powershell.exe -enc AAA"

运行健康的相关测试：

detecttrace elastic test examples\elastic_live_detectspec.yaml `
  --rule-name "DetectTrace - Encoded PowerShell" `
  --case healthy

DetectTrace：

1. 生成唯一 run ID
2. 注入确切的测试事件
3. 检索该 run ID 的遥测
4. 评估 normalization
5. 评估 DetectSpec 规则谓词
6. 验证 Elastic 规则存在
7. 验证 Elastic 规则已启用
8. 检查规则执行证据
9. 轮询携带相同 run ID 的 Elastic Security 告警
10. 报告近似告警延迟

旧告警无法让新测试通过，因为告警必须与当前 run ID 相关联。

故意损坏的用例是：

detecttrace elastic test examples\elastic_live_detectspec.yaml `
  --rule-name "DetectTrace - Encoded PowerShell" `
  --case broken

detecttrace doctor

在运行实时 Elastic 测试之前：

detecttrace doctor

doctor 执行只读检查：

• DetectTrace 配置
• Elasticsearch CA 配置
• Elasticsearch TLS/身份验证/连接性
• 遥测索引可用性
• Kibana 可用性

退出代码：

0  environment ready
2  configuration/environment problem

密码不会存储在 .detecttrace.yaml 中。通过交互式提示或 DETECTTRACE_ELASTIC_PASSWORD 提供 Elastic 密码。

配置

示例：

config_version: detecttrace/config-v1

elastic:
  url: https://localhost:9201
  kibana_url: http://localhost:5602
  username: elastic
  index: detecttrace-events
  ca_cert: certs/http_ca.crt

配置优先级是：

CLI argument > environment variable > .detecttrace.yaml > default

DetectTrace 会拒绝其 YAML 配置中的 password/token/API-key 字段。

--insecure 用于临时故障排除，但使用 CA 证书的已验证 TLS 是正常路径。

机器可读输出

JSON

Elastic 端到端测试：