g0dse11/detecttraceHerramienta de ingeniería de detección de código abierto que rastrea las detecciones de seguridad de principio a fin e identifica la primera etapa que falla.
Una detección debería haberse activado. No lo hizo. DetectTrace te dice exactamente por qué.
DetectTrace es una herramienta de código abierto de ingeniería de detecciones para probar detecciones de seguridad de extremo a extremo y localizar la primera etapa que falla.
En lugar de probar solo una consulta de SIEM, DetectTrace trata una detección como un pipeline:
test behaviour
-> telemetry
-> ingestion
-> normalization/schema
-> rule evaluation
-> rule execution
-> alert generation
Un DetectSpec declara lo que debería ocurrir. DetectTrace recopila evidencia de lo que realmente ocurrió, evalúa el contrato, detiene el razonamiento causal en la primera falla comprobada y marca las etapas posteriores dependientes como BLOCKED.
El backend activo actual es Elastic Security. DetectTrace también incluye un modo determinista respaldado por archivos para desarrollo local y pruebas de regresión.
Las fallas de detección a menudo se diagnostican manualmente:
DetectTrace convierte esas preguntas en comprobaciones ejecutables y evidencia.
Ejemplo de falla:
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
Lo importante no es solo que la detección falló. DetectTrace explica dónde la ruta de detección se volvió inválida por primera vez y por qué.
detecttrace.run_id únicodetecttrace doctorDetectTrace no es:
La ejecución de ataques/pruebas puede integrarse más adelante. La función de DetectTrace es verificar la ruta de detección y diagnosticar fallas a partir de la evidencia observada.
La suite de CI actualmente prueba Python 3.10, 3.11, 3.12 y 3.13.
Clona el repositorio, crea un entorno virtual e instala 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 .
Comprueba la instalación:
detecttrace --version
Crea un proyecto inicial ejecutable:
detecttrace init demo
Luego:
cd demo
detecttrace validate detectspec.yaml
detecttrace test detectspec.yaml
El proyecto generado es autocontenido. No requiere Elasticsearch, Kibana, Docker ni acceso a la red.
Una ejecución saludable termina con:
Detection contract passed end-to-end.
Confidence: HIGH
El repositorio incluye un fixture de PowerShell con evidencia tanto correcta conocida como deliberadamente rota.
Saludable:
detecttrace test examples/powershell/detectspec.yaml --profile healthy
Roto:
detecttrace test examples/powershell/detectspec.yaml --profile broken
El perfil roto conserva deliberadamente la línea de comandos original bajo process.args en lugar del process.command_line requerido. DetectTrace localiza esa falla en la normalización y bloquea la evaluación de reglas/alertas.
DetectSpec es el contrato declarativo. DetectTrace es el motor que evalúa ese contrato contra la evidencia.
Un DetectSpec puede describir:
Ejemplo:
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"
El JSON Schema está en:
schemas/detectspec-v1.schema.json
El validador en tiempo de ejecución y el JSON Schema son intencionalmente estrictos con la estructura desconocida de DetectSpec para que los errores de escritura fallen temprano.
Los predicados hoja usan:
field: process.name
op: equals
value: powershell.exe
Los operadores admitidos incluyen:
exists
equals
not_equals
contains
startswith
endswith
regex
in
gt
gte
lt
lte
Los predicados pueden componerse con all, any y not.
Ejemplo:
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 sigue una regla simple:
Evidencia antes que inferencia. Gana la primera etapa que falla.
Si la normalización falla, DetectTrace no pretende saber si una regla o alerta posterior habría tenido éxito. Esas etapas se reportan como BLOCKED.
Si la evidencia no está disponible en lugar de estar refutada, DetectTrace reporta UNKNOWN en lugar de adivinar.
El esquema de resultado estable y legible por máquina es:
detecttrace.result/v1
Los campos importantes incluyen: