g0dse11/detecttraceStrumento open-source di detection engineering che traccia le detection di sicurezza end to end e identifica il primo stage che fallisce.
Una detection avrebbe dovuto attivarsi. Non è successo. DetectTrace ti dice esattamente perché.
DetectTrace è uno strumento open-source di detection engineering per testare le detection di sicurezza end to end e localizzare il primo stadio fallito.
Invece di testare solo una query SIEM, DetectTrace tratta una detection come una pipeline:
test behaviour
-> telemetry
-> ingestion
-> normalization/schema
-> rule evaluation
-> rule execution
-> alert generation
Un DetectSpec dichiara cosa dovrebbe accadere. DetectTrace raccoglie le prove per ciò che è effettivamente accaduto, valuta il contratto, interrompe il ragionamento causale al primo fallimento dimostrato e contrassegna gli stadi downstream dipendenti come BLOCKED.
Il backend live attuale è Elastic Security. DetectTrace include anche una modalità deterministica basata su file per lo sviluppo locale e i test di regressione.
I fallimenti delle detection vengono spesso diagnosticati manualmente:
DetectTrace trasforma queste domande in controlli eseguibili e prove.
Esempio di fallimento:
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
La parte importante non è solo che la detection è fallita. DetectTrace spiega dove il percorso di detection è diventato invalido per la prima volta e perché.
detecttrace.run_id univocodetecttrace doctorDetectTrace non è:
L'esecuzione di attacchi/test può essere integrata in seguito. Il compito di DetectTrace è verificare il percorso di detection e diagnosticare i fallimenti dalle prove osservate.
La suite CI attualmente testa Python 3.10, 3.11, 3.12 e 3.13.
Clona il repository, crea un ambiente virtuale e installa 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 .
Verifica l'installazione:
detecttrace --version
Crea un progetto starter eseguibile:
detecttrace init demo
Poi:
cd demo
detecttrace validate detectspec.yaml
detecttrace test detectspec.yaml
Il progetto generato è autocontenuto. Non richiede Elasticsearch, Kibana, Docker o accesso alla rete.
Un'esecuzione sana termina con:
Detection contract passed end-to-end.
Confidence: HIGH
Il repository include una fixture PowerShell con prove sia note-buone che deliberatamente rotte.
Sano:
detecttrace test examples/powershell/detectspec.yaml --profile healthy
Rotto:
detecttrace test examples/powershell/detectspec.yaml --profile broken
Il profilo rotto preserva deliberatamente la command line originale sotto process.args invece del richiesto process.command_line. DetectTrace localizza quel fallimento nella normalizzazione e blocca la valutazione di regola/alert.
DetectSpec è il contratto dichiarativo. DetectTrace è il motore che valuta quel contratto rispetto alle prove.
Un DetectSpec può descrivere:
Esempio:
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"
Lo JSON Schema è in:
schemas/detectspec-v1.schema.json
Il validatore runtime e lo JSON Schema sono intenzionalmente severi riguardo a strutture DetectSpec sconosciute, così gli errori di battitura falliscono presto.
I predicati foglia usano:
field: process.name
op: equals
value: powershell.exe
Gli operatori supportati includono:
exists
equals
not_equals
contains
startswith
endswith
regex
in
gt
gte
lt
lte
I predicati possono essere composti con all, any e not.
Esempio:
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 segue una regola semplice:
Prove prima dell'inferenza. Il primo stadio fallito vince.
Se la normalizzazione fallisce, DetectTrace non finge di sapere se una regola o un alert downstream sarebbe riuscito. Quegli stadi vengono riportati come BLOCKED.
Se le prove non sono disponibili anziché smentite, DetectTrace riporta UNKNOWN invece di indovinare.
Lo schema di risultato stabile e machine-readable è:
detecttrace.result/v1
I campi importanti includono:
healthy
first_failed_stage
failure_code
confidence
root_cause
remediation
run_id
stages