أداة استخراج TDO المستقلة

أداة سطر أوامر قوية ومستقلة لاستخراج معلومات التهديدات السيبرانية (CTI) من المستندات باستخدام نماذج اللغة الكبيرة مع إمكانيات مخرجات منظمة متقدمة.

🚀 المميزات

• دعم تنسيقات مستندات متعددة: PDF، DOCX، TXT، وملفات Markdown
• تكامل LLM متقدم: نماذج Google Gemini مع مخرجات منظمة وتحليل احتياطي تلقائي
• مخطط CTI شامل: 12 نوع كيان و24 نوع علاقة بخصائص غنية
• توليد فرص الكشف: إنشاء قواعد كشف تهديدات قابلة للتنفيذ مدعومة بالأدلة
• تجميع سير الهجوم: توليد مخططات تدفق MITRE ATT&CK قائمة على الأدلة
• موثوقية المخرجات المنظمة: مخططات Pydantic مع نسبة نجاح 100% في تحليل JSON
• معالجة متوازية: معالجة عدة ملفات في وقت واحد مع تتبع التقدم
• قابلية النقل والاستقلالية: تبعيات قليلة مع تهيئة تعتمد على البيئة

📋 بداية سريعة

1. التثبيت

# استنساخ أو تنزيل مجلد standalone-tdo
cd standalone-tdo

# إنشاء بيئة افتراضية (موصى به)
python -m venv .venv
source .venv/bin/activate  # على ويندوز: .venv\Scripts\activate

# تثبيت التبعيات
pip install -r requirements.txt

2. التهيئة

تستخدم الأداة متغيرات بيئة محملة من ملف .env للتهيئة:

# نسخ ملف التهيئة النموذجي
cp env.example .env

# تحرير ملف .env بإعداداتك
# المتغيرات المطلوبة:
GEMINI_API_KEY=your-google-ai-api-key-here
GEMINI_MODEL=gemini-2.5-flash

الحصول على مفتاح Gemini API:

1. زيارة Google AI Studio
2. إنشاء مفتاح API جديد
3. نسخ المفتاح إلى ملف .env

النماذج المتوفرة:

• gemini-2.5-flash-preview-05-20 (موصى به - سريع وفعّال من حيث التكلفة)
• gemini-2.5-pro-preview-06-05 (أكثر قوة، أبطأ)

3. الاستخدام الأساسي

# معالجة ملف واحد مع جميع الميزات
python tdo_bulk.py report.pdf --flow --opps

# معالجة عدة ملفات
python tdo_bulk.py file1.pdf file2.docx file3.txt

# معالجة جميع الملفات في مجلد مع عمال متوازيين
python tdo_bulk.py reports/ -j 4

# توليد تحليل شامل مع تقييم
python tdo_bulk.py report.pdf --flow --opps --eval-opps

🎯 مرجع سطر الأوامر

usage: tdo_bulk.py [options] FILE [FILE ...]

Positional Arguments:
  FILE                  ملف أو أكثر أو مجلدات للمعالجة

Core Options:
  -o, --output DIR      مجلد الإخراج (الافتراضي: ./extracted_data)
  --csv FILE            تصدير الملخص إلى ملف CSV
  -j, --jobs N          عدد العمال المتوازيين (الافتراضي: 1)
  --retries N           عدد محاولات LLM (الافتراضي: 2)
  --backoff SEC         أساس الإرجاع الأسي (الافتراضي: 1.5)

Analysis Features:
  --flow                توليد JSON لسير الهجوم
  --opps                توليد فرص كشف التهديدات
  --eval-opps           تقييم جودة فرص الكشف
  --debug-opps          إظهار معلومات التصحيح لتوليد الفرص

Output Control:
  -q, --quiet           إخراج وحدة التحكم محدود
  -v, --verbose         تسجيل مستوى التصحيح
  -h, --help            عرض رسالة المساعدة والخروج

أمثلة أوامر

# استخراج CTI أساسي
python tdo_bulk.py threat_report.pdf

# تحليل كامل مع جميع الميزات
python tdo_bulk.py apt_report.pdf --flow --opps --eval-opps

# معالجة دفعية مع عمال متوازيين
python tdo_bulk.py reports_folder/ -j 8 --flow --opps

# تصدير النتائج إلى CSV
python tdo_bulk.py *.pdf --csv results.csv

# وضع هادئ للأتمتة
python tdo_bulk.py reports/ -q -o /var/soc/cti --opps

📊 ملفات الإخراج

لكل ملف تمت معالجته، تولد الأداة:

المخرجات الأساسية

• {filename}_extracted.json: بيانات CTI منظمة بمخطط شامل
• {filename}_{timestamp}.md: تقرير Markdown قابل للقراءة البشرية مع كل التحليلات

المخرجات الاختيارية (مع العلامات)

• JSON لسير الهجوم: هيكل تدفق MITRE ATT&CK قائم على الأدلة (مع --flow)
• فرص الكشف: قواعد كشف قابلة للتنفيذ مع أدلة (مع --opps)

🔍 نظرة عامة على مخطط CTI

أنواع الكيانات (12 نوعًا)

Entity Type	Description	Key Properties
ThreatActor	مجموعات التهديدات السيبرانية	aliases, primary_motivation, first_seen
Tool	برامج مشروعة	family, capabilities, kill_chain_phases
Malware	برامج ضارة	family, capabilities, first_seen, last_seen
Technique	تقنيات MITRE ATT&CK	id (T1234), description, kill_chain_phases
Tactic	تكتيكات MITRE ATT&CK	id (TA0001), description
Infrastructure	عناوين IP، نطاقات، روابط	type, tags, first_seen, last_seen
Indicator	تجزئات ملفات، أنماط	value, pattern, valid_from, valid_until
Vulnerability	إدخالات CVE	id, cvss_score, affected_software
Campaign	حملات هجومية مسماة	objective, status, first_seen
Identity	مؤسسات مستهدفة	type, description
CourseOfAction	إجراءات تخفيف، تصحيحات	type, description
Source	مصدر المستند	filename, document_title, file_size_mb

أنواع العلاقات (24 نوعًا)

علاقات الإسناد والممثل:

• USES_TOOL, USES_TECHNIQUE, CONDUCTS, ATTRIBUTED_TO, TARGETS

علاقات فنية:

• TOOL_IMPLEMENTS_TECHNIQUE, HOSTS_ON, COMMUNICATES_WITH, VARIANT_OF
• DROPS, DOWNLOADS, INDICATES, OBSERVED_ON, EXPLOITS

علاقات متقدمة:

• MITIGATES, DETECTS, IS_SUBTECHNIQUE_OF, FLOW_CONTAINS_STEP
• FLOW_USED_BY_ACTOR, OBSERVES, SOURCED_FROM

جميع العلاقات تدعم خصائص مثل confidence, source, first_seen, last_seen.

💡 فرص الكشف

تولد الأداة فرص كشف قائمة على الأدلة مع:

الميزات الأساسية

• ربط التقنية: روابط لتقنيات MITRE ATT&CK محددة
• المصنوعات القابلة للملاحظة: مؤشرات محددة للكشف
• الأنماط السلوكية: متتاليات وأنماط للمراقبة
• الاستشهادات بالأدلة: اقتباسات مباشرة من تقارير المصدر
• درجات الثقة: تقييم الموثوقية (0.0-1.0)
• تقييم الجودة: تسجيل تلقائي مع تفصيل المعايير

مثال على الإخراج

{
  "id": "opp-001",
  "name": "كشف حقن عملية PowerShell",
  "technique_id": "T1055",
  "artefacts": ["powershell.exe مع استدعاءات WriteProcessMemory"],
  "behaviours": ["حقن العملية في العمليات المشروعة"],
  "rationale": "تستخدم مجموعات APT بشكل شائع PowerShell لحقن العملية",
  "confidence": 0.8,
  "source": "PowerShell المستخدمة لحقن العملية (T1055)",
  "evidence": [
    "• ينفذ PowerShell استدعاءات WriteProcessMemory (سطر 45)",
    "• العلاقة: ThreatActor USES_TECHNIQUE T1055"
  ]
}

🔗 تجميع سير الهجوم

توفر تدفقات الهجوم المحسّنة:

• ترتيب قائم على الأدلة: خطوات مدعومة بأدلة زمنية وسببية
• الإشارة إلى الكيانات: كل خطوة تشير إلى كيانات CTI المستخرجة
• الاستدلال الصريح: تبرير لترتيب الخطوات مع الاستشهادات
• تغطية شاملة: حتى 25 خطوة تغطي دورة حياة الهجوم الكاملة

مثال على سير الهجوم

{
  "flow": {
    "label": "AttackFlow",
    "pk": "attack-flow--uuid",
    "properties": {
      "name": "هجوم متعدد المراحل APT29",
      "description": "تدفق تصيد احتيالي متطور إلى تسرب البيانات"
    }
  },
  "steps": [
    {
      "order": 1,
      "entity": {"label": "Technique", "pk": "T1566.001"},
      "description": "تسليم مرفق التصيد الاحتيالي",
      "reason": "طريقة الوصول الأولي المذكورة في القسم 2.1 من التقرير"
    }
  ]
}

🏗️ نظرة عامة على البنية

المكونات الأساسية

🎯 واجهة CLI الرئيسية (tdo_bulk.py)

• نقطة دخول مع تحليل الوسائط والتحقق من البيئة
• تحميل تهيئة .env باستخدام python-dotenv
• تنسيق المعالجة المجمعة مع تتبع التقدم

⚙️ مشغل الدفعة (tdo_bulk_runner.py)

• إدارة المعالجة المتوازية مع ThreadPoolExecutor
• تنسيق مراحل خط أنابيب الاستخراج
• معالجة استدعاءات التقدم واسترداد الأخطاء

🧠 مستخرج CTI (tdo_core/extractors/report_processor.py)

• تحليل المستندات: دعم متعدد التنسيقات (PDF، DOCX، TXT، MD)
• تكامل LLM: Google Gemini مع مخرجات منظمة
• تحليل احتياطي: تحليل JSON يدوي عند فشل المخرجات المنظمة
• إدارة الرموز: تقسيم تلقائي للمستندات الكبيرة
• التحقق من المخططات: نماذج Pydantic تضمن اتساق البيانات

🔍 مولد TDO (tdo_core/detection/opportunity_generator.py)

• إنشاء فرص كشف قائمة على الأدلة
• ربط تقنيات MITRE ATT&CK
• تقييم الجودة مع معايير التسجيل
• وضع التصحيح للتحليل التفصيلي