g0dse11/detecttraceИнструмент с открытым исходным кодом для инженерии обнаружения, который отслеживает работу средств обнаружения угроз от начала до конца и выявляет первый сбойный этап.
Детект должен был сработать. Он не сработал. DetectTrace точно скажет вам, почему.
DetectTrace — это инструмент с открытым исходным кодом для инженерии детектов, предназначенный для сквозного тестирования security-детектов и локализации первой сбойной стадии.
Вместо тестирования только SIEM-запроса, DetectTrace рассматривает детект как конвейер:
test behaviour
-> telemetry
-> ingestion
-> normalization/schema
-> rule evaluation
-> rule execution
-> alert generation
DetectSpec декларирует, что должно произойти. DetectTrace собирает доказательства того, что произошло на самом деле, оценивает контракт, останавливает причинно-следственные рассуждения на первой доказанной ошибке и помечает зависимые нижестоящие стадии как BLOCKED.
Текущий живой бэкенд — Elastic Security. DetectTrace также включает детерминированный файловый режим для локальной разработки и регрессионного тестирования.
Сбои детектов часто диагностируются вручную:
DetectTrace превращает эти вопросы в исполняемые проверки и доказательства.
Пример сбоя:
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
Важно не только то, что детект не сработал. DetectTrace объясняет, где путь детекта впервые стал недействительным и почему.
detecttrace.run_iddetecttrace doctorDetectTrace — это не:
Выполнение атак/тестов может быть интегрировано позже. Задача DetectTrace — верифицировать путь детекта и диагностировать сбои на основе наблюдаемых доказательств.
CI-набор в настоящее время тестирует Python 3.10, 3.11, 3.12 и 3.13.
Клонируйте репозиторий, создайте виртуальное окружение и установите 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 .
Проверьте установку:
detecttrace --version
Создайте запускаемый стартовый проект:
detecttrace init demo
Затем:
cd demo
detecttrace validate detectspec.yaml
detecttrace test detectspec.yaml
Сгенерированный проект самодостаточен. Он не требует Elasticsearch, Kibana, Docker или доступа к сети.
Успешный запуск завершается:
Detection contract passed end-to-end.
Confidence: HIGH
Репозиторий включает PowerShell-фикстуру как с заведомо исправными, так и с намеренно сломанными доказательствами.
Исправный:
detecttrace test examples/powershell/detectspec.yaml --profile healthy
Сломанный:
detecttrace test examples/powershell/detectspec.yaml --profile broken
Сломанный профиль намеренно сохраняет исходную командную строку под process.args вместо требуемого process.command_line. DetectTrace локализует этот сбой на нормализацию и блокирует оценку правила/алерта.
DetectSpec — это декларативный контракт. DetectTrace — это движок, который оценивает этот контракт на основе доказательств.
DetectSpec может описывать:
Пример:
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"
JSON Schema находится в:
schemas/detectspec-v1.schema.json
Валидатор времени выполнения и JSON Schema намеренно строги к неизвестной структуре DetectSpec, чтобы опечатки выявлялись на раннем этапе.
Листовые предикаты используют:
field: process.name
op: equals
value: powershell.exe
Поддерживаемые операторы включают:
exists
equals
not_equals
contains
startswith
endswith
regex
in
gt
gte
lt
lte
Предикаты можно комбинировать с помощью all, any и not.
Пример:
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 следует простому правилу:
Доказательства прежде выводов. Побеждает первая сбойная стадия.
Если нормализация не удалась, DetectTrace не притворяется, что знает, сработало бы нижестоящее правило или алерт. Эти стадии помечаются как BLOCKED.
Если доказательства недоступны, а не опровергнуты, DetectTrace сообщает UNKNOWN вместо угадывания.
Стабильная машиночитаемая схема результата:
detecttrace.result/v1
Важные поля включают:
healthy
first_failed_stage
failure_code
confidence
root_cause
remediation
run_id
stages
Текущие коды ошибок включают такие категории, как: