blevene/standalone_tdoيستخرج معلومات استخباراتية عن التهديدات السيبرانية المنظمة (CTI) من مستندات PDF و DOCX و TXT باستخدام نماذج اللغة الكبيرة (LLMs). يولّد تدفقات هجوم MITRE ATT&CK، وفرص الكشف، ورسومات بيانية شاملة للعلاقات بين الكيانات.
أداة سطر أوامر قوية ومستقلة لاستخراج معلومات التهديدات السيبرانية (CTI) من المستندات باستخدام نماذج اللغة الكبيرة مع إمكانيات مخرجات منظمة متقدمة.
# استنساخ أو تنزيل مجلد standalone-tdo
cd standalone-tdo
# إنشاء بيئة افتراضية (موصى به)
python -m venv .venv
source .venv/bin/activate # على ويندوز: .venv\Scripts\activate
# تثبيت التبعيات
pip install -r requirements.txt
تستخدم الأداة متغيرات بيئة محملة من ملف .env للتهيئة:
# نسخ ملف التهيئة النموذجي
cp env.example .env
# تحرير ملف .env بإعداداتك
# المتغيرات المطلوبة:
GEMINI_API_KEY=your-google-ai-api-key-here
GEMINI_MODEL=gemini-2.5-flash
الحصول على مفتاح Gemini API:
.envالنماذج المتوفرة:
gemini-2.5-flash-preview-05-20 (موصى به - سريع وفعّال من حيث التكلفة)gemini-2.5-pro-preview-06-05 (أكثر قوة، أبطأ)# معالجة ملف واحد مع جميع الميزات
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 قابل للقراءة البشرية مع كل التحليلات--flow)--opps)| 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, |
علاقات الإسناد والممثل:
USES_TOOL, USES_TECHNIQUE, CONDUCTS, ATTRIBUTED_TO, TARGETSعلاقات فنية:
TOOL_IMPLEMENTS_TECHNIQUE, HOSTS_ON, COMMUNICATES_WITH, VARIANT_OFDROPS, DOWNLOADS, INDICATES, OBSERVED_ON, EXPLOITSعلاقات متقدمة:
MITIGATES, DETECTS, IS_SUBTECHNIQUE_OF, FLOW_CONTAINS_STEPFLOW_USED_BY_ACTOR, OBSERVES, SOURCED_FROMجميع العلاقات تدعم خصائص مثل confidence, source, first_seen, last_seen.
تولد الأداة فرص كشف قائمة على الأدلة مع:
{
"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"
]
}
توفر تدفقات الهجوم المحسّنة:
{
"flow": {
"label": "AttackFlow",
"pk": "attack-flow--uuid",
"properties": {
"name": "هجوم متعدد المراحل APT29",
"description": "تدفق تصيد احتيالي متطور إلى تسرب البيانات"
}
},
"steps": [
{
"order": 1,
"entity": {"label": "Technique", "pk": "T1566.001"},
"description": "تسليم مرفق التصيد الاحتيالي",
"reason": "طريقة الوصول الأولي المذكورة في القسم 2.1 من التقرير"
}
]
}
tdo_bulk.py).env باستخدام python-dotenvtdo_bulk_runner.py)tdo_core/extractors/report_processor.py)tdo_core/detection/opportunity_generator.py)tdo_core/flows/attack_flow_synthesizer.py)tdo_core/report/md_export.py)tdo_core/llm/prompts.py)إدخال المستند → استخراج النص → معالجة LLM → إخراج منظم
↓ ↓ ↓ ↓
PDF/DOCX نص نظيف API Gemini JSON + احتياطي
↓ ↓ ↓ ↓
متعدد التنسيقات معالجة مسبقة مخطط Pydantic تحقق من الصحة
↓ ↓ ↓ ↓
دعم الملفات تنقية النص بيانات منظمة رسم بياني CTI
↓
معالجة لاحقة
↓ ↓
تدفقات الهجوم فرص الكشف
↓ ↓
تصدير تقرير Markdown
| Variable | Required | Description | Example |
|---|---|---|---|
GEMINI_API_KEY | ✅ | مفتاح Google AI API | AIza... |
GEMINI_MODEL | ✅ | نموذج Gemini للاستخدام | gemini-2.5-flash-preview-05-20 |
| Model | Speed | Quality | Cost | Use Case |
|---|---|---|---|---|
gemini-2.5-flash-preview-05-20 | ⚡ سريع | 🎯 جيد | 💰 منخفض | إنتاج، معالجة مجمعة |
gemini-2.5-pro-preview-06-05 | 🐌 بطيء | 🏆 ممتاز | 💸 مرتفع | تحليل معقد، بحث |
خطأ: متغيرات البيئة المطلوبة مفقودة: GEMINI_API_KEY, GEMINI_MODEL
الحل: إنشاء ملف .env مع كلا المتغيرين المطلوبين
تخطي ملف غير مدعوم: document.rtf
الحل: التحويل إلى تنسيق PDF، DOCX، TXT، أو MD
خطأ في Gemini API المنظم: ...
الحلول:
--verbose للحصول على سجلات أخطاء مفصلةتتعامل الأداة تلقائياً مع مشاكل تحليل JSON باستخدام:
-j لملفات متعددة-q لنصوص الأتمتة# تفعيل التسجيل المفصل
python tdo_bulk.py report.pdf -v
# تصحيح فرص الكشف
python tdo_bulk.py report.pdf --opps --debug-opps
# تصدير سجلات مفصلة
python tdo_bulk.py report.pdf -v > processing.log 2>&1
تتطلب الأداة Python 3.9+ وهذه الحزم الرئيسية:
google-generativeai: عميل Google AI (Gemini) API مع إخراج منظمPyMuPDF: استخراج نصوص PDF عالي الأداءpython-docx: معالجة مستندات Microsoft Wordpandas: معالجة البيانات وتصدير CSVpydantic: التحقق من المخططات والإخراج المنظمpython-dotenv: إدارة متغيرات البيئةcleantext: أدوات معالجة النص الأوليةهذا الإصدار المستقل:
ومع ذلك، فإنه يتضمن جميع قدرات استخراج وتحليل CTI الأساسية اللازمة لمعظم حالات الاستخدام.
.env باستخدام dotenv.env الخاص بك - فهو مستبعد بواسطة .gitignoreGEMINI_API_KEY بأمان باستخدام متغيرات البيئةقد تحتوي ملفات JSON وMarkdown المستخرجة على:
قم دائماً بمراجعة المخرجات قبل المشاركة العامة.
يرجى الإبلاغ عن الثغرات الأمنية بشكل مسؤول. راجع SECURITY.md للتفاصيل.
هذا المشروع مرخص بموجب رخصة MIT - راجع LICENSE للتفاصيل.
المساهمات مرحب بها! يرجى قراءة CONTRIBUTING.md للإرشادات.
هل تحتاج إلى مساعدة؟ قم بتشغيل python tdo_bulk.py --help للمرجع السريع أو راجع قسم استكشاف الأخطاء وإصلاحها أعلاه.
file_size_mb