DetectTrace

كان يجب أن ينطلق اكتشاف. لم يحدث ذلك. يخبرك DetectTrace بالسبب الدقيق.

DetectTrace هو أداة هندسة اكتشاف مفتوحة المصدر لاختبار اكتشافات الأمان من البداية إلى النهاية وتحديد موقع أول مرحلة فاشلة.

بدلاً من اختبار استعلام SIEM فقط، يتعامل DetectTrace مع الاكتشاف كخط معالجة:

test behaviour
    -> telemetry
    -> ingestion
    -> normalization/schema
    -> rule evaluation
    -> rule execution
    -> alert generation

يعلن DetectSpec عما يجب أن يحدث. يجمع DetectTrace الأدلة على ما حدث فعلاً، ويقيّم العقد، ويوقف الاستدلال السببي عند أول فشل مُثبت، ويضع علامة BLOCKED على المراحل اللاحقة التابعة.

الواجهة الخلفية الحية الحالية هي Elastic Security. يتضمن DetectTrace أيضاً وضعاً حتمياً مدعوماً بالملفات للتطوير المحلي واختبار الانحدار.

لماذا يوجد 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 حالياً

• التحقق من DetectSpec v1
• آثار حتمية دون اتصال من أدلة JSON/JSONL
• DSL محمول آمن تصريحي؛ لا تنفيذ عشوائي لـ Python أو shell
• فحوصات الحقول المتداخلة
• تلميحات نسب الحقول لاحتمال انحراف المخطط/التعيين
• دلالات المراحل PASS / FAIL / BLOCKED / UNKNOWN / SKIPPED
• تشخيصات أول مرحلة فاشلة
• رموز فشل مستقرة ونص معالجة
• اختبارات Elastic Security مترابطة باستخدام detecttrace.run_id فريد
• فحوصات حقيقية لوجود/تمكين/تنفيذ قواعد Elastic
• التحقق من تنبيهات Elastic المترابطة
• قياس زمن استجابة التنبيه
• TLS آمن لـ Elasticsearch مع CA مُهيأ
• فحوصات بيئة detecttrace doctor
• مخرجات نصية وJSON ومتوافقة مع JUnit
• اختبارات الانحدار وGitHub Actions CI
• مختبر محلي قابل لإعادة الإنتاج لـ Elasticsearch + Kibana

ما ليس DetectTrace

DetectTrace ليس:

• منصة محاكاة هجوم
• بديل BAS
• محرر قواعد SIEM
• ماسح ثغرات عام
• نظام ذكاء اصطناعي يخمّن ما إذا كان الاكتشاف قد نجح

يمكن دمج تنفيذ الهجوم/الاختبار لاحقاً. مهمة DetectTrace هي التحقق من مسار الاكتشاف وتشخيص الإخفاقات من الأدلة المرصودة.

المتطلبات

• Python 3.10+
• Docker مع Compose v2 فقط إذا كنت تريد تشغيل مختبر Elastic المرفق

تختبر مجموعة CI حالياً Python 3.10 و3.11 و3.12 و3.13.

بداية سريعة دون اتصال في خمس دقائق

استنسخ المستودع، أنشئ بيئة افتراضية، وثبّت DetectTrace.

Windows PowerShell

python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e .

Linux/macOS

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

DetectSpec هو العقد التصريحي. DetectTrace هو المحرك الذي يقيّم ذلك العقد مقابل الأدلة.

يمكن لـ DetectSpec وصف:

1. أدلة التنفيذ
2. تليمتري المصدر
3. أدلة الجمع
4. متطلبات التطبيع
5. دلالات القاعدة
6. توقعات التنبيه وتوقيته
7. حالات اختبار حية مترابطة

مثال:

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 موجود في:

schemas/detectspec-v1.schema.json

المدقق وقت التشغيل ومخطط JSON صارمان عمداً بشأن بنية DetectSpec غير المعروفة حتى تفشل الأخطاء الإملائية مبكراً.

DSL المحمول

تستخدم المحمولات الورقية:

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

مختبر Elastic Security المحلي

مختبر آمن قابل لإعادة الإنتاج مضمّن في:

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