g0dse11/detecttraceOpen-Source-Tool für Detection Engineering, das Sicherheitsdetektionen durchgängig nachverfolgt und die erste fehlschlagende Stufe identifiziert.
Eine Erkennung hätte ausgelöst werden müssen. Sie wurde es nicht. DetectTrace sagt Ihnen genau, warum.
DetectTrace ist ein Open-Source-Tool für Detection Engineering, mit dem Sicherheitserkennungen Ende-zu-Ende getestet und die erste fehlschlagende Stufe lokalisiert werden kann.
Anstatt nur eine SIEM-Abfrage zu testen, behandelt DetectTrace eine Erkennung als Pipeline:
Testverhalten
-> Telemetrie
-> Ingestion
-> Normalisierung/Schema
-> Regelauswertung
-> Regelausführung
-> Alert-Generierung
Eine DetectSpec deklariert, was passieren soll. DetectTrace sammelt Belege dafür, was tatsächlich passiert ist, wertet den Vertrag aus, stoppt die kausale Schlussfolgerung bei dem ersten nachgewiesenen Fehler und markiert abhängige nachgelagerte Stufen als BLOCKED.
Das aktuell aktive Backend ist Elastic Security. DetectTrace enthält außerdem einen deterministischen, dateibasierten Modus für lokale Entwicklung und Regressionstests.
Erkennungsfehler werden oft manuell diagnostiziert:
DetectTrace verwandelt diese Fragen in ausführbare Prüfungen und Belege.
Beispielfehler:
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
Das Wichtige ist nicht nur, dass die Erkennung fehlgeschlagen ist. DetectTrace erklärt, wo der Erkennungspfad zuerst ungültig wurde und warum.
detecttrace.run_iddetecttrace doctor-UmgebungsprüfungenDetectTrace ist nicht:
Angriffs-/Testausführung kann später integriert werden. Die Aufgabe von DetectTrace ist es, den Erkennungspfad zu verifizieren und Fehler anhand beobachteter Belege zu diagnostizieren.
Die CI-Suite testet derzeit Python 3.10, 3.11, 3.12 und 3.13.
Klonen Sie das Repository, erstellen Sie eine virtuelle Umgebung und installieren Sie 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 .
Überprüfen Sie die Installation:
detecttrace --version
Erstellen Sie ein ausführbares Starterprojekt:
detecttrace init demo
Dann:
cd demo
detecttrace validate detectspec.yaml
detecttrace test detectspec.yaml
Das generierte Projekt ist eigenständig. Es benötigt weder Elasticsearch, Kibana, Docker noch Netzwerkzugriff.
Ein erfolgreicher Lauf endet mit:
Detection contract passed end-to-end.
Confidence: HIGH
Das Repository enthält ein PowerShell-Fixture mit sowohl bekannt-guten als auch absichtlich fehlerhaften Belegen.
Erfolgreich:
detecttrace test examples/powershell/detectspec.yaml --profile healthy
Fehlerhaft:
detecttrace test examples/powershell/detectspec.yaml --profile broken
Das fehlerhafte Profil bewahrt absichtlich die ursprüngliche Kommandozeile unter
process.args anstelle des erforderlichen process.command_line. DetectTrace
lokalisiert diesen Fehler in der Normalisierung und blockiert die Regel-/Alert-Auswertung.
DetectSpec ist der deklarative Vertrag. DetectTrace ist die Engine, die diesen Vertrag gegen Belege auswertet.
Eine DetectSpec kann beschreiben:
Beispiel:
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"
Das JSON-Schema befindet sich in:
schemas/detectspec-v1.schema.json
Der Laufzeit-Validator und das JSON-Schema sind absichtlich streng gegenüber unbekannter DetectSpec-Struktur, damit Tippfehler früh fehlschlagen.
Blattprädikate verwenden:
field: process.name
op: equals
value: powershell.exe
Unterstützte Operatoren umfassen:
exists
equals
not_equals
contains
startswith
endswith
regex
in
gt
gte
lt
lte
Prädikate können mit all, any und not zusammengesetzt werden.
Beispiel:
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 folgt einer einfachen Regel:
Belege vor Schlussfolgerung. Die erste fehlschlagende Stufe gewinnt.
Wenn die Normalisierung fehlschlägt, gibt DetectTrace nicht vor zu wissen, ob eine
nachgelagerte Regel oder ein Alert erfolgreich gewesen wäre. Diese Stufen werden als
BLOCKED gemeldet.
Wenn Belege nicht verfügbar statt widerlegt sind, meldet DetectTrace
UNKNOWN anstatt zu raten.
Das stabile maschinenlesbare Ergebnisschema ist:
detecttrace.result/v1
Wichtige Felder umfassen: