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 構造に対して意図的に厳格です。
リーフ述語は次を使用します:
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
現在の失敗コードには、次のようなカテゴリが含まれます:
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 に相関している必要があるため、古いアラートが新しいテストを合格させることはできません。
意図的に破損させたケースは次のとおりです: