g0dse11/detecttraceOutil d'ingénierie de détection open source qui trace les détections de sécurité de bout en bout et identifie la première étape défaillante.
Une détection aurait dû se déclencher. Elle ne l'a pas fait. DetectTrace vous dit exactement pourquoi.
DetectTrace est un outil d'ingénierie de détection open source pour tester les détections de sécurité de bout en bout et localiser la première étape en échec.
Au lieu de tester uniquement une requête SIEM, DetectTrace traite une détection comme un pipeline :
test behaviour
-> telemetry
-> ingestion
-> normalization/schema
-> rule evaluation
-> rule execution
-> alert generation
Un DetectSpec déclare ce qui devrait se produire. DetectTrace rassemble les preuves de ce qui s'est réellement produit, évalue le contrat, arrête le raisonnement causal à la première défaillance prouvée, et marque les étapes dépendantes en aval comme BLOCKED.
Le backend actif actuel est Elastic Security. DetectTrace inclut également un mode déterministe basé sur des fichiers pour le développement local et les tests de régression.
Les échecs de détection sont souvent diagnostiqués manuellement :
DetectTrace transforme ces questions en vérifications exécutables et en preuves.
Exemple d'échec :
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
L'important n'est pas seulement que la détection a échoué. DetectTrace explique où le chemin de détection est devenu invalide pour la première fois et pourquoi.
detecttrace.run_id uniquedetecttrace doctorDetectTrace n'est pas :
L'exécution d'attaques/tests peut être intégrée ultérieurement. Le rôle de DetectTrace est de vérifier le chemin de détection et de diagnostiquer les échecs à partir des preuves observées.
La suite CI teste actuellement Python 3.10, 3.11, 3.12 et 3.13.
Clonez le dépôt, créez un environnement virtuel et installez 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 .
Vérifiez l'installation :
detecttrace --version
Créez un projet de démarrage exécutable :
detecttrace init demo
Puis :
cd demo
detecttrace validate detectspec.yaml
detecttrace test detectspec.yaml
Le projet généré est autonome. Il ne nécessite ni Elasticsearch, ni Kibana, ni Docker, ni accès réseau.
Une exécution saine se termine par :
Detection contract passed end-to-end.
Confidence: HIGH
Le dépôt inclut un fixture PowerShell avec à la fois des preuves valides connues et des preuves délibérément défaillantes.
Sain :
detecttrace test examples/powershell/detectspec.yaml --profile healthy
Défaillant :
detecttrace test examples/powershell/detectspec.yaml --profile broken
Le profil défaillant préserve délibérément la ligne de commande d'origine sous
process.args au lieu du process.command_line requis. DetectTrace
localise cet échec au niveau de la normalisation et bloque l'évaluation de la règle/de l'alerte.
DetectSpec est le contrat déclaratif. DetectTrace est le moteur qui évalue ce contrat par rapport aux preuves.
Un DetectSpec peut décrire :
Exemple :
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"
Le JSON Schema se trouve dans :
schemas/detectspec-v1.schema.json
Le validateur d'exécution et le JSON Schema sont intentionnellement stricts concernant les structures DetectSpec inconnues afin que les fautes d'orthographe échouent tôt.
Les prédicats feuilles utilisent :
field: process.name
op: equals
value: powershell.exe
Les opérateurs pris en charge incluent :
exists
equals
not_equals
contains
startswith
endswith
regex
in
gt
gte
lt
lte
Les prédicats peuvent être composés avec all, any et not.
Exemple :
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 suit une règle simple :
Preuves avant inférence. La première étape en échec l'emporte.
Si la normalisation échoue, DetectTrace ne prétend pas savoir si une
règle ou une alerte en aval aurait réussi. Ces étapes sont signalées comme
BLOCKED.