g0dse11/detecttrace보안 탐지를 처음부터 끝까지 추적하고 최초로 실패한 단계를 식별하는 오픈소스 탐지 엔지니어링 도구입니다.
탐지가 작동했어야 하는데, 작동하지 않았다. DetectTrace는 그 이유를 정확히 알려준다.
DetectTrace는 보안 탐지를 엔드투엔드로 테스트하고 최초 실패 단계를 특정하기 위한 오픈소스 탐지 엔지니어링 도구이다.
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_id를 사용한 상관된 Elastic Security 테스트detecttrace doctor 환경 검사DetectTrace는 다음이 아니다:
공격/테스트 실행은 나중에 통합될 수 있다. 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.command_line 대신 process.args 아래에 보존한다. 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 구조에 대해 의도적으로 엄격하여 오타가 조기에 실패하도록 한다.
리프 predicate는 다음을 사용한다:
field: process.name
op: equals
value: powershell.exe
지원되는 연산자는 다음과 같다:
exists
equals
not_equals
contains
startswith
endswith
regex
in
gt
gte
lt
lte
Predicate는 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
현재 실패 코드는 다음과 같은 범주를 포함한다:
INGESTION_FAILURE
TELEMETRY_MISSING
SCHEMA_DRIFT
REQUIRED_FIELD_MISSING
RULE_NOT_FOUND
RULE_DISABLED
RULE_LOGIC_MISMATCH
RULE_EXECUTION_ERROR
ALERT_TIMEOUT
UNKNOWN
재현 가능한 보안 랩이 다음 위치에 포함되어 있다:
lab/elastic
다음을 제공한다:
Elasticsearch 8.15.3 https://localhost:9201
Kibana 8.15.3 http://localhost:5602
Elasticsearch security enabled
Elasticsearch HTTP TLS enabled
Persistent Elasticsearch data
Persistent certificates
Kibana encryption keys
detecttrace-events index
전체 설정은 lab/elastic/README.md를 참조한다.
간단히 말하면:
cd lab\elastic
Copy-Item .env.example .env
docker compose up -d
서비스가 정상 상태가 되면 저장소 루트로 돌아가서 공개 CA를 내보낸다:
New-Item -ItemType Directory -Force .\certs | Out-Null
docker cp detecttrace-es:/usr/share/elasticsearch/config/certs/http_ca.crt .\certs\http_ca.crt
Copy-Item .detecttrace.example.yaml .detecttrace.yaml
그런 다음 환경을 확인한다:
detecttrace doctor
준비된 환경은 다음에 대해 PASS를 보고한다:
DetectTrace config
Elasticsearch CA
Elasticsearch
Telemetry index
Kibana
로컬 .env, .detecttrace.yaml, 내보낸 certs/ 자료는 환경별이며 커밋되지 않는다.
제공된 라이브 예시는 다음과 같다:
examples/elastic_live_detectspec.yaml
랩에서 사용하는 예시 Elastic Security 규칙은 다음과 같다:
Name:
DetectTrace - Encoded PowerShell
Index:
detecttrace-events
Query:
process.name : "powershell.exe" and process.command_line : "powershell.exe -enc AAA"
정상 상관 테스트를 실행한다:
detecttrace elastic test examples\elastic_live_detectspec.yaml `
--rule-name "DetectTrace - Encoded PowerShell" `
--case healthy
DetectTrace:
알림이 현재 run ID와 상관되어야 하므로 오래된 알림이 새 테스트를 통과시킬 수 없다.
의도적으로 손상된 케이스는 다음과 같다:
detecttrace elastic test examples\elastic_live_detectspec.yaml `
--rule-name "DetectTrace - Encoded PowerShell" `
--case broken
detecttrace doctor