g0dse11/detecttraceFerramenta open-source de engenharia de detecção que rastreia detecções de segurança de ponta a ponta e identifica o primeiro estágio com falha.
Uma detecção deveria ter disparado. Não disparou. O DetectTrace diz exatamente por quê.
DetectTrace é uma ferramenta open-source de engenharia de detecção para testar detecções de segurança de ponta a ponta e localizar o primeiro estágio com falha.
Em vez de testar apenas uma consulta SIEM, o DetectTrace trata uma detecção como um pipeline:
test behaviour
-> telemetry
-> ingestion
-> normalization/schema
-> rule evaluation
-> rule execution
-> alert generation
Um DetectSpec declara o que deveria acontecer. O DetectTrace reúne evidências do que realmente aconteceu, avalia o contrato, interrompe o raciocínio causal no primeiro estágio de falha comprovada e marca os estágios dependentes a jusante como BLOCKED.
O backend ativo atual é o Elastic Security. O DetectTrace também inclui um modo determinístico baseado em arquivos para desenvolvimento local e testes de regressão.
Falhas de detecção são frequentemente diagnosticadas manualmente:
O DetectTrace transforma essas perguntas em verificações executáveis e evidências.
Exemplo de falha:
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
A parte importante não é apenas que a detecção falhou. O DetectTrace explica onde o caminho de detecção se tornou inválido pela primeira vez e por quê.
detecttrace.run_id únicodetecttrace doctorO DetectTrace não é:
A execução de ataques/testes pode ser integrada posteriormente. O trabalho do DetectTrace é verificar o caminho de detecção e diagnosticar falhas a partir das evidências observadas.
A suíte de CI atualmente testa Python 3.10, 3.11, 3.12 e 3.13.
Clone o repositório, crie um ambiente virtual e instale o DetectTrace.
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
Verifique a instalação:
detecttrace --version
Crie um projeto inicial executável:
detecttrace init demo
Em seguida:
cd demo
detecttrace validate detectspec.yaml
detecttrace test detectspec.yaml
O projeto gerado é autocontido. Ele não requer Elasticsearch, Kibana, Docker ou acesso à rede.
Uma execução saudável termina com:
Detection contract passed end-to-end.
Confidence: HIGH
O repositório inclui um fixture PowerShell com evidências conhecidamente boas e deliberadamente quebradas.
Saudável:
detecttrace test examples/powershell/detectspec.yaml --profile healthy
Quebrado:
detecttrace test examples/powershell/detectspec.yaml --profile broken
O perfil quebrado preserva deliberadamente a linha de comando original em
process.args em vez do process.command_line exigido. O DetectTrace
localiza essa falha na normalização e bloqueia a avaliação de regra/alerta.
O DetectSpec é o contrato declarativo. O DetectTrace é o motor que avalia esse contrato em relação às evidências.
Um DetectSpec pode descrever:
Exemplo:
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"
O JSON Schema está em:
schemas/detectspec-v1.schema.json
O validador de runtime e o JSON Schema são intencionalmente estritos quanto a estrutura desconhecida do DetectSpec, para que erros de digitação falhem cedo.
Predicados folha usam:
field: process.name
op: equals
value: powershell.exe
Os operadores suportados incluem:
exists
equals
not_equals
contains
startswith
endswith
regex
in
gt
gte
lt
lte
Predicados podem ser compostos com all, any e not.
Exemplo:
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"
O DetectTrace segue uma regra simples:
Evidência antes de inferência. O primeiro estágio com falha vence.
Se a normalização falhar, o DetectTrace não finge saber se uma regra ou alerta
a jusante teria tido sucesso. Esses estágios são reportados como
BLOCKED.
Se a evidência estiver indisponível em vez de refutada, o DetectTrace reporta
UNKNOWN em vez de adivinhar.
O schema de resultado estável e legível por máquina é:
detecttrace.result/v1
Campos importantes incluem: