### إعداد البيئة

**هام:** يجب عليك تكوين متغيرات البيئة قبل بدء التطبيق. يتطلب التطبيق تعيين `NEO4J_PASSWORD`.

أنشئ ملف `.env` في جذر المشروع:```bash
# Copy the sample file
cp infra/env.sample .env

# Edit .env and set your actual passwords
nano .env

**ملاحظة:** سيفشل تشغيل التطبيق إذا لم يتم تعيين `NEO4J_PASSWORD`. راجع [إصلاح متغيرات البيئة](https://github.com/blevene/bandjacks/blob/HEAD/ENV_VARIABLES_FIX.md) لمزيد من التفاصيل.

### بدء الخدمات```bash
# Start the FastAPI backend server
uv run uvicorn bandjacks.services.api.main:app --reload --port 8000

# In another terminal, start the Next.js frontend
cd ui && npm run dev

# Access the applications
open http://localhost:8000/docs    # API documentation
open http://localhost:3000         # Frontend UI

> **ملاحظة:** تتطلب واجهة سطر الأوامر (CLI) تعيين متغيرات البيئة (NEO4J_PASSWORD، الخ). قم بتشغيلها من جذر المشروع حيث يوجد ملف `.env`.

### أوامر الاستعلام```bash
# Search for threat intelligence
uv run python -m bandjacks.cli.main query search "ransomware encryption techniques" --top-k 10

# Explore graph relationships
uv run python -m bandjacks.cli.main query graph "attack-pattern--abc123" --depth 2

### استخراج المستندات```bash
# Extract CTI from a document
uv run python -m bandjacks.cli.main extract document ./report.pdf --confidence-threshold 80 --show-evidence

### أوامر سير العمل```bash
# Process a directory of reports with analytics
uv run python -m bandjacks.cli.main workflow process-reports ./reports/ --workers 3 --analyze --export-dir ./results/

# Bulk export all analytics data
uv run python -m bandjacks.cli.main workflow bulk-export --export-dir ./analytics_export/

## واجهة المستخدم الأمامية

توفر واجهة Next.js الأمامية واجهة حديثة للعمل مع النظام.

### إدارة التقارير (`/reports`)
- **قائمة التقارير**: عرض جميع التقارير المستوردة مع الحالة وأعداد التقنيات
- **تقرير جديد** (`/reports/new`): رفع ملفات PDF/TXT أو لصق محتوى التقرير
- **تفاصيل التقرير** (`/reports/[id]`): عرض التقنيات المستخلصة والكيانات والأدلة
- **واجهة المراجعة** (`/reports/[id]/review`): سير عمل مراجعة مع إشراف بشري

### تحليلات التزامن (`/analytics/cooccurrence`)

> **ملاحظة:** تتطلب هذه الصفحات بيانات `AttackEpisode` في Neo4j. قم بمعالجة التقارير عبر خط أنابيب الاستخلاص أولاً، أو استخدم `POST /v1/flows/build` لتوليد الحلقات من بيانات مجموعة الاختراق.

- **الصفحة الرئيسية**: نظرة عامة مع عدد الحلقات/التقنيات/الفاعلين
- **أفضل الأزواج** (`/pairs`): أزواج التقنيات المتزامنة مع مقاييس NPMI/Lift
- **الاحتمال الشرطي** (`/conditional`): الاحتمالات الشرطية P(B|A)
- **الحزم** (`/bundles`): حزم التقنيات المتزامنة بشكل متكرر
- **الفاعلون** (`/actors`): أنماط تقنيات خاصة بفاعل معين
- **الجسر** (`/bridging`): التقنيات المستخدمة عبر عدة فاعلين

### صحة النظام (`/health`)
- حالة صحة جميع المكونات في الوقت الفعلي (Neo4j، OpenSearch، Redis)
- إحصائيات التخزين المؤقت واستخدام الذاكرة
- نقاط نهاية صحية متوافقة مع Kubernetes

### بدء تشغيل الواجهة الأمامية```bash
cd ui
npm run dev     # Development mode with hot reload
npm run build   # Production build
npm run start   # Start production server

# Ensure backend is running
# API_URL defaults to http://localhost:8000/v1

### 2. استخراج التقنيات من التقارير

استخرج تقنيات MITRE ATT&CK من تقارير استخبارات التهديدات:```python
import httpx
import time

# For small reports (<5KB) - synchronous processing
response = httpx.post(
    "http://localhost:8000/v1/reports/ingest",
    json={
        "content": "APT29 used spearphishing emails with malicious attachments...",
        "title": "APT29 Campaign Analysis",
        "config": {
            "use_optimized_extractor": True,
            "span_score_threshold": 0.7,
            "top_k": 5
        }
    }
)

result = response.json()
print(f"Extracted {len(result['extraction']['techniques'])} techniques")

# For large reports (>5KB) - asynchronous processing
response = httpx.post(
    "http://localhost:8000/v1/reports/ingest_async",
    json={
        "content": large_report_text,
        "title": "Large Report Analysis"
    }
)

job_id = response.json()["job_id"]

# Check job status
status = httpx.get(f"http://localhost:8000/v1/reports/jobs/{job_id}/status")
while status.json()["status"] == "processing":
    time.sleep(2)
    status = httpx.get(f"http://localhost:8000/v1/reports/jobs/{job_id}/status")

# Get results from completed job
result = status.json()["result"]
print(f"Extracted {result['techniques_count']} techniques in {result['elapsed_time']} seconds")

## معمارية خط أنابيب الاستخراج

يستخدم خط أنابيب استخراج Bandjacks معمارية متعددة الوكلاء لاستخراج الاستخبارات التهديدية المنظمة.

### مكونات خط الأنابيب

يستخدم خط أنابيب الاستخراج 9 وكلاء متخصصين بالتسلسل:

#### 1. **EntityExtractionAgent** - التعرف على الكيانات
- يستخرج ممثلي التهديدات والبرامج الضارة والأدوات والحملات
- يعمل أولاً لتوفير سياق لاستخراج التقنيات
- يستخدم التوجيه بقليل من الأمثلة مع التحقق من مخطط JSON
- يعالج المستندات المجزأة باستخراج نافذة تدريجي

#### 2. **SpanFinderAgent** - اكتشاف النص السلوكي
- يكتشف أجزاء النص التي تحتوي على سلوكيات تهديد باستخدام 14 نمط regex خاص بالتكتيكات
- يحدد معرفات التقنيات الصريحة (T1566.001) والأنماط السلوكية
- يُسجل الأجزاء حسب الثقة مع تعزيز فهرس الكلمات المفتاحية
- لا استدعاءات لـ LLM — مطابقة أنماط خالصة للسرعة

#### 3. **BatchRetrieverAgent** - استرداد المرشحين
- يستخدم البحث المتجهي KNN في OpenSearch للعثور على تقنيات مرشحة لكل جزء
- يزيل ازدواجية نصوص الأجزاء المتطابقة قبل الترميز لتجنب التضمينات الزائدة
- يعيد أفضل k مرشحًا مع درجات التشابه لكل جزء

#### 4. **Pre-filter** - تقليل الأجزاء
- يحدد الأجزاء إلى `max_spans_per_technique` (الافتراضي 2) لكل تقنية مرشحة
- يحتفظ بالأجزاء ذات الدرجات الأعلى لكل مرشح للحفاظ على جودة الأدلة
- يقلل استدعاءات LLM للمخطط بنحو ~46% مع خسارة تقنية ضئيلة

#### 5. **DiscoveryAgent** - اكتشاف LLM (شَرطي)
- يتم تشغيله عندما تكون ثقة المسترد منخفضة (متوسط <0.7)
- يستخدم LLM لاكتشاف التقنيات التي فاتها البحث المتجهي
- استدعاء دُفعي واحد لجميع الأجزاء منخفضة الثقة

#### 6. **BatchMapperAgent** - تعيين التقنيات (LLM)
- يعالج الأجزاء دُفعيًا في مجموعات تصل إلى 10 (`MAX_MAPPER_BATCH_SIZE`، تم خفض الافتراضي من 25 في 2026-05 للحد من اقتطاع LLM السحابي)
- يستخرج جميع التقنيات ذات الصلة لكل جزء مع درجات الثقة
- يستخدم التحقق من مخطط JSON للمخرجات المنظمة

#### 7. **EvidenceVerifierAgent** - التحقق من الأدلة
- التحقق القائم على الأنماط من الاقتباسات ومراجع الأسطر
- يُسجل جودة الأدلة على مقياس 40-100 نقطة
- لا استدعاءات لـ LLM — مطابقة regex والنص

#### 8. **ConsolidatorAgent** - دمج الأدلة
- يدمج التقنيات المكررة الموجودة عبر أجزاء متعددة
- يجمع الأدلة باستخدام تشابه جاكارد (عتبة >85%)
- ينتج قائمة التقنيات النهائية مع درجات الثقة المُجمعة

#### 9. **AttackFlowSynthesizer** - توليد التسلسل (LLM)
- يحلل العلامات الزمنية ("أولاً"، "ثم"، "بعد")
- يستنتج العلاقات السببية من السرد
- ينشئ كائنات STIX Attack Flow بحواف احتمالية
- يتراجع إلى نمذجة التزامن عندما يكون التسلسل غير واضح

### تحسينات الأداء

- **التجزئة الذكية**: المستندات مقسمة إلى أجزاء حجمها 2KB مع تداخل
- **المعالجة الدفعية**: يعالج المخطط ما يصل إلى 25 جزءًا لكل استدعاء LLM
- **المعالجة المتوازية**: تتم معالجة الأجزاء بشكل متزامن عبر خيوط العمال
- **تخزين الاستجابات مؤقتًا**: يتم تخزين استجابات LLM مؤقتًا لتجنب الاستدعاءات المكررة
- **الإنهاء المبكر**: عمليات الاستخراج عالية الثقة تتجاوز التحقق
- **TechniqueCache**: يتم تحميل جميع تقنيات ATT&CK عند بدء التشغيل لعملية بحث O(1)
- **المرشح المسبق**: يحدد الأجزاء لكل تقنية مرشحة قبل مخطط LLM (46% استدعاءات أقل)
- **التضمين الدفعي**: يتم إنشاء تضمينات التقنيات دفعة واحدة (أسرع بـ 2-5 مرات)
- **تجميع الاتصالات**: اتصالات Neo4j/OpenSearch مشتركة عبر الطلبات
- **دفعات UNWIND**: كتابات Neo4j مجمعة عبر UNWIND (30-40 استعلامًا → 6-7)
- **التهيئة المسبقة للنموذج**: يتم تحميل نموذج التضمين عند بدء التشغيل لتجنب زمن الوصول للبداية الباردة

### أوقات المعالجة

| حجم المستند | وقت المعالجة | التقنيات المستخرجة |
|--------------|-----------------|---------------------|
| صغير (<5 كيلوبايت) | 10-20 ثانية | 5-10 تقنيات |
| متوسط (5-15 كيلوبايت) | 20-40 ثانية | 10-15 تقنية |
| كبير (>15 كيلوبايت) | 30-60 ثانية | 15-25 تقنية |

## تحليلات التزامن

توفر Bandjacks تحليلات لفهم علاقات التقنيات. 

> **ملاحظة:** تتطلب التحليلات بيانات `AttackEpisode` و`AttackAction` في Neo4j. يتم إنشاء هذه عندما:
> - تتم معالجة التقارير عبر خط أنابيب الاستخراج
> - يتم بناء تدفقات الهجوم عبر `/v1/flows/build`
> - يتم استيعاب حزم STIX التي تحتوي على حلقات هجوم
>
> إذا لم توجد حلقات، فستعيد التحليلات نتائج فارغة.

### التزامن العالمي

احسب التقنيات التي تظهر معًا بشكل متكرر عبر جميع حلقات الهجوم:```python
# Via API
response = httpx.post(
    "http://localhost:8000/v1/analytics/cooccurrence/global",
    json={"min_support": 2, "min_episodes_per_pair": 2, "limit": 50}
)

for pair in response.json()["pairs"]:
    print(f"{pair['name_a']} + {pair['name_b']}: NPMI={pair['npmi']:.3f}")

### حزم التقنيات

تحديد حزم التقنيات المتكررة الحدوث معًا (3-5 تقنيات):```python
response = httpx.post(
    "http://localhost:8000/v1/analytics/cooccurrence/bundles",
    json={"min_support": 3, "min_size": 3, "max_size": 5}
)

## نظام المراجعة البشرية في الحلقة

يتضمن Bandjacks نظام مراجعة شامل للتحقق من المعلومات الاستخباراتية المستخرجة:

### واجهة مراجعة موحدة

يقدم نظام المراجعة جميع العناصر المستخرجة في واجهة واحدة:```typescript
// Review workflow
1. Upload/ingest report → Extraction pipeline runs
2. Navigate to /reports/{id}/review
3. Review extracted items across three tabs:
   - Entities (threat actors, malware, tools)
   - Techniques (ATT&CK mappings with evidence)
   - Attack Flow (sequenced steps)
4. Take actions on each item:
   - Approve: Accept as correct
   - Reject: Mark as incorrect
   - Edit: Modify details (name, confidence, etc.)
5. Submit all decisions atomically

### 4. البحث عن التقنيات

ابحث عن تقنيات ATT&CK باستخدام اللغة الطبيعية:```python
# Vector search for similar techniques
response = httpx.post(
    "http://localhost:8000/v1/search/ttx",
    json={
        "query": "ransomware that encrypts files and demands payment",
        "top_k": 5
    }
)

techniques = response.json()["results"]
for tech in techniques:
    print(f"{tech['external_id']}: {tech['name']} (score: {tech['score']:.2f})")

### ٦. إنشاء نماذج AttackFlow

إنشاء نماذج التواجد المشترك التي تظهر كيفية استخدام الجهات المهاجمة للتقنيات معًا:```python
# Generate flow for a specific intrusion set (e.g., APT29)
response = httpx.post(
    "http://localhost:8000/v1/flows/build",
    json={
        "intrusion_set_id": "intrusion-set--899ce53f-13a0-479b-a0e4-67d46e241542"
    }
)

flow = response.json()
print(f"Generated flow '{flow['name']}' with {len(flow['steps'])} techniques")
print(f"Co-occurrence edges: {len(flow['edges'])}")

نماذج AttackFlow تستخدم **الترافق (co-occurrence)** بدلاً من الترتيب التسلسلي لأن مجموعات التطفل لا تحتوي على معلومات تسلسلية متأصلة. يتم ربط التقنيات عن طريق:
- **حواف داخل التكتيك (Intra-tactic edges)**: بين التقنيات في نفس تكتيك قتل السلسلة (kill chain tactic)
- **حواف عبر التكتيكات (Cross-tactic edges)**: بين التقنيات عبر التكتيكات المتجاورة
- **أنماط مركز-فرع (Hub-spoke patterns)**: لمجموعات التقنيات الكبيرة لتجنب انفجار الحواف

راجع [دليل توليد AttackFlow](https://github.com/blevene/bandjacks/blob/HEAD/docs/ATTACKFLOW_GENERATION.md) للاستخدام المفصل.

## صيغ الإدخال المدعومة

تدعم سلسلة الاستخراج صيغ إدخال متعددة:

- **نص عادي (Plain Text)** - محتوى نصي مباشر
- **ماركداون (Markdown)** - مستندات ماركداون منسقة
- **PDF** - عبر استخراج pdfplumber
- **HTML** - عبر تحليل BeautifulSoup
- **JSON** - استخراج بيانات منظم

### الاستخراج من نص عادي```python
# Direct text extraction
plaintext_report = """
The threat actors used spearphishing emails with malicious attachments.
After gaining access, they deployed Mimikatz to harvest credentials and
used RDP for lateral movement across the network.
"""

result = asyncio.run(run_agentic_v2_async(plaintext_report, {
    "cache_llm_responses": True,
    "single_pass_threshold": 500
}))

### استخراج من PDF```python
import pdfplumber
from bandjacks.llm.extraction_pipeline import run_extraction_pipeline

# Read PDF with pdfplumber (recommended)
with pdfplumber.open("threat_report.pdf") as pdf:
    text = ""
    for page in pdf.pages:
        page_text = page.extract_text()
        if page_text:
            text += page_text + "\n"

# Extract techniques using extraction pipeline
result = run_extraction_pipeline(text, {
    "use_optimized_extractor": True,
    "span_score_threshold": 0.7,
    "chunk_size": 2000
}, source_id="threat_report")

print(f"Found {len(result['techniques'])} techniques")

results.append({
    "file": pdf_file.name,
    "techniques": list(result["techniques"].keys()),
    "count": len(result["techniques"])
})

### بناء تدفقات الهجوم```python
# Generate attack flow from extracted techniques
response = httpx.post(
    "http://localhost:8000/v1/flows/build",
    json={
        "source_id": "report-123",
        "technique_ids": ["T1566.001", "T1059.001", "T1003.001"]
    }
)

flow = response.json()
print(f"Generated flow with {len(flow['steps'])} steps")

## نقاط النهاية API

### نقاط النهاية الأساسية

- `POST /v1/stix/load/attack` - تحميل بيانات MITRE ATT&CK
- `POST /v1/reports/ingest` - إدخال تقارير متزامن (<5KB)
- `POST /v1/reports/ingest_async` - إدخال تقارير غير متزامن (>5KB)
- `POST /v1/reports/ingest/upload` - تحميل ملفات PDF/TXT
- `GET /v1/reports/jobs/{id}/status` - التحقق من حالة المهمة
- `POST /v1/reports/{id}/unified-review` - تقديم قرارات المراجعة
- `POST /v1/search/ttx` - البحث عن التقنيات
- `GET /v1/graph/technique/{id}` - الحصول على تفاصيل التقنية

### تدفقات الهجوم

- `POST /v1/flows/build` - إنشاء نماذج التواجد المشترك لتدفقات الهجوم
- `GET /v1/flows/{flow_id}` - استرجاع تفاصيل تدفق هجوم معين
- `POST /v1/flows/search` - البحث عن تدفقات هجوم مماثلة
- `GET /v1/flows/dump` - تصدير التدفقات بشكل مجمع مع التقسيم والتصفية

### التحليلات

- `GET /v1/analytics/cooccurrence/global` - مقاييس التواجد المشترك العالمية
- `GET /v1/analytics/cooccurrence/conditional` - الاحتمالات الشرطية
- `GET /v1/analytics/cooccurrence/bundles` - حزم التقنيات
- `GET /v1/analytics/cooccurrence/actor` - أنماط خاصة بالجهات الفاعلة
- `GET /v1/coverage/gaps` - فجوات تغطية التقنيات

### الدفاع والكشف

- `GET /v1/defense/technique/{id}` - الحصول على توصيات دفاعية
- `GET /v1/detections/technique/{id}` - استراتيجيات الكشف
- `POST /v1/sigma/validate` - التحقق من صحة قواعد Sigma

### المراقبة

- `GET /health` - فحص صحي أساسي
- `GET /health/live` - مسبار البقاء على قيد الحياة في Kubernetes
- `GET /health/ready` - مسبار الجاهزية في Kubernetes
- `GET /health/components/{component}` - صحة المكون الفردي
- `GET /v1/costs/stats` - تتبع تكلفة LLM (إجمالي يومي حسب النموذج)
- `GET /v1/cache/stats` - الحصول على إحصائيات ذاكرة التخزين المؤقت لـ LLM
- `POST /v1/cache/clear` - مسح ذاكرة التخزين المؤقت لـ LLM
- `GET /v1/compliance/report` - مقاييس الامتثال
- `GET /v1/drift/status` - حالة كشف الانجراف
- `GET /v1/ml-metrics/performance` - مقاييس نموذج التعلم الآلي

### الجهات الفاعلة والأصل

- `GET /v1/actors` - قائمة الجهات الفاعلة في التهديد
- `GET /v1/actors/{id}` - الحصول على تفاصيل الجهة الفاعلة
- `GET /v1/provenance/{object_id}` - أصل الكائن
- `GET /v1/provenance/{object_id}/lineage` - سلسلة النسب الكاملة
- `GET /v1/provenance/{object_id}/evidence` - مقتطفات الأدلة

### ميزات API فقط (بدون واجهة مستخدم أو سطر أوامر)

هذه النقاط النهائية تعمل بكامل وظائفها ولكن يتم الوصول إليها عبر REST API فقط (بدون صفحات أمامية أو أوامر CLI):

#### محاكاة مسار الهجوم
- `POST /v1/simulation/paths` - محاكاة مسارات الهجوم من تقنية/مجموعة بداية
- `POST /v1/simulation/predict` - التنبؤ بالتقنيات المحتملة التالية بالنظر إلى الحالة الحالية
- `POST /v1/simulation/whatif` - تحليل "ماذا لو" للسيناريوهات الدفاعية
- `POST /v1/simulation/scenario` - المحاكاة من مجموعات من المجموعات/البرامج/التقنيات
- `GET /v1/simulation/statistics/{technique_id}` - إحصائيات استخدام التقنية
- `GET /v1/simulation/groups/{group_id}/patterns` - أنماط هجوم المجموعة
- `POST /v1/simulation/compare` - مقارنة مسارات هجوم متعددة

#### سياسة MDP والتوزيع
- `POST /v1/simulate/rollout` - محاكاة توزيع PTG
- `POST /v1/simulate/mdp` - حساب سياسة الدفاع المثلى باستخدام MDP
- `GET /v1/simulate/models` - قائمة نماذج PTG المتاحة

#### كشف الانجراف والمراقبة
- `GET /v1/drift/status` - حالة الانجراف الحالية عبر جميع المقاييس
- `POST /v1/drift/analyze` - تشغيل تحليل الانجراف بعتبات مخصصة
- `GET /v1/drift/alerts` - الحصول على تنبيهات الانجراف النشطة
- `POST /v1/drift/alerts/{alert_id}/acknowledge` - تأكيد التنبيه
- `GET /v1/drift/metrics/{metric_name}` - الحصول على مقياس انجراف معين

#### تتبع مقاييس التعلم الآلي
- `POST /v1/ml-metrics/prediction` - تسجيل تنبؤ النموذج للتتبع
- `POST /v1/ml-metrics/review` - تسجيل مقاييس قرار المراجعة
- `POST /v1/ml-metrics/coverage-gap` - تسجيل فجوة التغطية
- `GET /v1/ml-metrics/performance` - الحصول على مقاييس أداء النموذج
- `GET /v1/ml-metrics/dashboard` - تصدير مقاييس لوحة المعلومات

#### الإشعارات
- `GET /v1/notifications/history` - الحصول على سجل الإشعارات
- `POST /v1/notifications/clear-history` - مسح سجل الإشعارات
- `GET /v1/notifications/config` - الحصول على تكوين الإشعارات
- `POST /v1/notifications/test` - إرسال إشعار اختبار

#### إدارة تحديث المتجهات
- `GET /v1/vectors/status` - حالة نظام تحديث المتجهات
- `GET /v1/vectors/metrics` - مقاييس تحديث المتجهات التفصيلية
- `POST /v1/vectors/update` - تشغيل تحديث المتجهات يدويًا
- `POST /v1/vectors/process-batch` - فرض معالجة الدفعة
- `DELETE /v1/vectors/queue` - مسح قائمة انتظار التحديثات المعلقة
- `GET /v1/vectors/health` - فحص صحة نظام المتجهات

#### قائمة التجاهل للكيانات
- `GET /v1/ignorelist` - الحصول على حالة قائمة التجاهل الحالية
- `POST /v1/ignorelist/add` - إضافة كيان إلى قائمة التجاهل
- `DELETE /v1/ignorelist/remove` - إزالة كيان من قائمة التجاهل
- `POST /v1/ignorelist/reload` - إعادة تحميل قائمة التجاهل من القرص

#### مراجعة الأنماط المرشحة
- `GET /v1/review/candidates` - قائمة أنماط الهجوم المرشحة
- `POST /v1/review/candidates` - إنشاء نمط مرشح
- `GET /v1/review/candidates/{id}` - الحصول على تفاصيل المرشح
- `POST /v1/review/candidates/{id}/approve` - الموافقة على المرشح
- `POST /v1/review/candidates/{id}/reject` - رفض المرشح
- `GET /v1/review/candidates/{id}/similar` - العثور على أنماط مماثلة
- `GET /v1/review/candidates/stats/summary` - إحصائيات المرشح

### توثيق API الكامل

الوصول إلى توثيق API الكامل على:
- Swagger UI: http://localhost:8000/docs
- ReDoc: http://localhost:8000/redoc
- OpenAPI JSON: http://localhost:8000/openapi.json

## الهندسة المعمارية

### هيكل المشروع```
bandjacks/
├── bandjacks/
│   ├── analysis/         # Graph analysis & interdiction
│   │   ├── graph_analyzer.py
│   │   └── interdiction.py
│   ├── analytics/        # Co-occurrence & clustering
│   │   ├── clustering.py
│   │   ├── cooccurrence.py
│   │   └── detection_bundles.py
│   ├── cli/              # Command-line interface
│   │   ├── main.py       # CLI entry point
│   │   ├── batch_extract.py
│   │   ├── formatters.py
│   │   └── workflows.py
│   ├── config/           # Configuration files
│   │   └── entity_ignorelist.yaml
│   ├── core/             # Core utilities
│   │   ├── cache.py      # Redis caching
│   │   ├── connection_pool.py
│   │   └── query_optimizer.py
│   ├── llm/              # Extraction pipeline
│   │   ├── extraction_pipeline.py
│   │   ├── agents_v2.py  # Core extraction agents
│   │   ├── chunked_extractor.py
│   │   ├── optimized_chunked_extractor.py
│   │   ├── entity_extractor.py
│   │   ├── flow_builder.py
│   │   ├── cache.py      # LLM response caching
│   │   └── experimental/ # Experimental features
│   ├── loaders/          # Data loading & indexing
│   │   ├── attack_catalog.py
│   │   ├── attack_upsert.py
│   │   ├── opensearch_index.py
│   │   ├── hybrid_search.py
│   │   └── sigma_loader.py
│   ├── monitoring/       # Metrics & monitoring
│   │   ├── compliance_metrics.py
│   │   ├── defense_metrics.py
│   │   ├── drift_detector.py
│   │   └── ml_metrics.py
│   ├── services/         # API & services
│   │   ├── api/          # FastAPI application
│   │   │   ├── main.py
│   │   │   ├── routes/   # API route handlers
│   │   │   └── middleware/
│   │   ├── technique_cache.py
│   │   └── actor_cache.py
│   ├── simulation/       # Attack simulation
│   │   ├── attack_simulator.py
│   │   ├── mdp_solver.py
│   │   └── ptg_rollout.py
│   └── store/            # Data stores
│       ├── report_store.py
│       ├── candidate_store.py
│       └── review_store.py
├── ui/                   # Next.js frontend
│   ├── app/              # App Router pages
│   │   ├── reports/      # Report management
│   │   ├── analytics/    # Analytics dashboards
│   │   └── health/       # Health monitoring
│   ├── components/       # React components
│   └── hooks/            # Custom React hooks
├── tests/                # Test suite
├── samples/              # Sample reports
├── scripts/              # Utility scripts
└── docs/                 # Documentation

**أولوية المزود:** واجهة API المحلية > Gemini > OpenAI > وكيل LiteLLM.
عند تكوين خادم محلي، تتم إضافة مزودي السحابة تلقائيًا كخيارات احتياطية.

#### أمثلة شائعة للخوادم المحلية

| الخادم | `LOCAL_LLM_API_BASE` | `LOCAL_LLM_MODEL` |
|--------|---------------------|-------------------|
| vLLM | `http://host:8000/v1` | `mistralai/Mistral-Nemo-Instruct-2407` |
| llama.cpp | `http://host:8080/v1` | `mistral-nemo` |
| Ollama | `http://host:11434/v1` | `mistral-nemo` |
| LM Studio | `http://host:1234/v1` | `mistral-nemo` |
| LocalAI | `http://host:8080/v1` | `mistral-nemo` |

### تكوين الاستخراج

يستخدم النظام خط أنابيب غير متزامن واحد عالي الأداء مع خيارات قابلة للتكوين:```python
{
    "cache_llm_responses": True,         # Enable LLM caching (default: True)
    "single_pass_threshold": 500,        # Max words for single-pass (default: 500)
    "early_termination_confidence": 90,  # Skip verification above this (default: 90)
    "disable_discovery": False,          # Disable LLM discovery agent
    "max_spans": 20,                     # Maximum spans to process
    "span_score_threshold": 0.7,         # Minimum span quality
    "top_k": 5,                          # Candidates per span

    # Cost optimization options
    "max_spans_per_technique": 2,        # Pre-filter: max spans per candidate technique (0=disable, default=2)
    "enable_span_dedup": False,          # Text-based span dedup before mapping (default=False)
}

### عتبات الثقة

التحكم في جودة الاستخراج:```python
{
    "confidence_threshold": 50.0,  # Minimum confidence (0-100)
    "auto_ingest": True            # Auto-add high-confidence results
}

### مثال استجابة الصحة```json
{
  "status": "healthy",
  "timestamp": "2025-01-28T17:43:30.184036Z",
  "version": "1.0.0",
  "components": {
    "neo4j": {
      "status": "healthy",
      "latency_ms": 5
    },
    "opensearch": {
      "status": "degraded",
      "cluster_status": "yellow",
      "indices": {
        "attack_nodes": false,
        "bandjacks_reports": true
      }
    },
    "redis": {
      "status": "healthy",
      "latency_ms": 2,
      "memory_mb": 1.69
    },
    "caches": {
      "status": "healthy",
      "technique_cache": {
        "count": 993,
        "loaded": true
      },
      "actor_cache": {
        "count": 145,
        "loaded": true
      }
    },
    "system": {
      "status": "healthy",
      "memory": {
        "available_gb": 8.84,
        "percent_used": 72.4
      },
      "disk": {
        "available_gb": 353.11,
        "percent_used": 2.9
      },
      "cpu": {
        "percent_used": 7.7
      }
    }
  }
}

## تحسين الأداء

### التخزين المؤقت

يتضمن النظام تخزينًا مؤقتًا تلقائيًا لاستجابات LLM لتحسين الأداء:```python
# Check cache statistics
response = httpx.get("http://localhost:8000/v1/cache/stats")
stats = response.json()
print(f"Cache hit rate: {stats['hit_rate']}")

# Clear cache if needed
httpx.post("http://localhost:8000/v1/cache/clear")

## الأمان

### التحقق من الإدخال

- **منع حقن Cypher**: جميع نقاط نهاية استعلام الرسم البياني تتحقق من معاملات `relationship_types` المقدمة من المستخدم مقابل قائمة مسموح بها من أنواع العلاقات المعروفة (USES, MITIGATES, HAS_TACTIC, إلخ) بالإضافة إلى نمط regex صارم (`^[A-Z][A-Z0-9_]*$`). يؤدي الإدخال غير الصالح إلى إرجاع 400 قبل بناء الاستعلام.
- **التحقق من مخطط JSON**: يتم التحقق من استجابات LLM مقابل مخططات JSON لمنع دخول البيانات المشوهة إلى خط الأنابيب.
- **التحقق من ADM**: يجب أن يمر جميع محتوى STIX بالتحقق من نموذج بيانات ATT&CK قبل الإدخال.

### المصادقة والتفويض

- **مصادقة JWT**: وسيط اختياري لمصادقة API (`JWTAuthMiddleware`)
- **تحديد المعدل**: تحديد المعدل لكل نقطة نهاية مع حدود قابلة للتكوين
- **CORS**: مشاركة الموارد عبر الأصول القابلة للتكوين

## الميزات المتقدمة

### تتبع المصدر

يتضمن كل كيان مستخرج مصدرًا كاملاً:```python
# Get provenance for an object
response = httpx.get(
    "http://localhost:8000/v1/provenance/attack-pattern--abc123"
)

### تحليلات التغطية

تحليل تغطية استخبارات التهديدات الخاصة بك:```python
# Get coverage analysis
response = httpx.get("http://localhost:8000/v1/analytics/coverage")
coverage = response.json()

print(f"Summary: {coverage['summary']}")
for tactic in coverage['tactics']:
    print(f"  {tactic['tactic']}: {tactic['coverage_percentage']}%")

## حالة الميزات

يوفر هذا القسم الشفافية حول حالة تنفيذ الميزات المختلفة:

### تعمل بكامل طاقتها ✅
- **خط أنابيب استخراج التقارير** - يعمل استخراج التقنيات القائم على LLM من البداية إلى النهاية
- **تحميل MITRE ATT&CK** - تحميل بيانات ATT&CK للمؤسسات/الأجهزة المحمولة/ICS إلى Neo4j
- **البحث المتجهي** - بحث دلالي قائم على OpenSearch للتقنيات
- **نظام المراجعة** - سير عمل مراجعة بوجود الإنسان في الحلقة عبر API وواجهة المستخدم
- **مراقبة الصحة** - فحوصات صحة المكونات ومقاييس Kubernetes
- **أوامر CLI للاستعلام/الإدارة** - البحث، التنقل في الرسم البياني، إدارة ذاكرة التخزين المؤقت
- **توليد تدفقات الهجوم** - بناء التدفق القائم على التزامن لمجموعات الاختراق
- **محاكاة الهجوم** - محاكاة المسار القائمة على MDP عبر `/simulation/*` و `/simulate/*`
- **تقارير التغطية** - تقارير JSON للرؤية التنفيذية والفنية والتكتيكية والتشغيلية

### تعمل مع تبعيات البيانات ⚠️
- **تحليلات التزامن** - يتطلب عقد `AttackEpisode` من معالجة التقارير
- **تحليلات الجهات الفاعلة** - يتطلب حلقات منسوبة إلى مجموعات الاختراق
- **حزم التقنيات** - يتطلب بيانات حلقات كافية لاستخراج الأنماط
- **أوامر CLI للتحليلات** - تعمل ولكنها ترجع فارغة إذا لم توجد حلقات

### عبر API فقط (بدون واجهة مستخدم أو CLI) 🔌
هذه ميزات منفذة بالكامل يمكن الوصول إليها فقط عبر REST API:
- **محاكاة مسار الهجوم** - مسارات `/simulation/*` للتنبؤ بالمسار وتحليل "ماذا لو"
- **حلال سياسة MDP** - `/simulate/mdp` لحساب سياسة الدفاع المثلى
- **كشف الانحراف** - مسارات `/drift/*` لمراقبة انحراف جودة البيانات
- **مقاييس التعلم الآلي** - مسارات `/ml-metrics/*` لتتبع أداء النموذج بمرور الوقت
- **إدارة المتجهات** - مسارات `/vectors/*` لإدارة تضمينات المتجهات
- **قائمة التجاهل للكيانات** - مسارات `/ignorelist/*` لتصفية الكيانات الإيجابية الخاطئة
- **الأنماط المرشحة** - مسارات `/review/candidates/*` لمرشحي التقنيات الجديدة
- **الإشعارات** - مسارات `/notifications/*` لتكوين التنبيهات وسجلها
- **السلالة** - مسارات `/provenance/*` لتتبع سلالة الاستخراج
- **الامتثال** - مسارات `/compliance/*` لتقارير مقاييس الامتثال

### تجريبية (في `llm/experimental/`) 🧪
- **PTG (الرسم البياني للتهديد الاحتمالي)** - المنطق الأساسي منفذ، اختبار محدود
- **تكامل Judge** - التحقق من التسلسل القائم على LLM
- **محاكي تدفق الهجوم** - محرك محاكاة قائم على التدفق
- **مستخرج التسلسل** - استخراج التسلسلات من التدفقات

### تمت إزالتها/تنظيفها 🗑️
تمت إزالة الميزات النمطية التالية من API:
- ~~تحليل تغطية المنصة~~ - كان يعيد بيانات نمطية ثابتة
- ~~تحليل الاتجاهات~~ - كان يعيد بيانات اصطناعية عشوائية
- ~~تصدير تقارير CSV/PDF~~ - كان يعيد 501؛ الآن JSON فقط
- ~~استدلال تسلسل Gemini~~ - كان نمط 501؛ استخدم `/sequence/propose` بدلاً من ذلك

### مصفوفة الاتصال

| منطقة الميزة | واجهة المستخدم الأمامية | CLI | REST API |
|--------------|-------------|-----|----------|
| إدارة التقارير | ✅ | ✅ | ✅ |
| سير عمل المراجعة | ✅ | ✅ | ✅ |
| البحث (TTX) | ✅ | ✅ | ✅ |
| تحليلات التزامن | ✅ | ✅ | ✅ |
| تحليلات التغطية | ✅ | - | ✅ |
| مراقبة الصحة | ✅ | - | ✅ |
| الكشف/Sigma | ✅ | - | ✅ |
| تدفقات الهجوم | ✅ | - | ✅ |
| تراكب الدفاع | ✅ | - | ✅ |
| التسلسلات/PTG | ✅ | - | ✅ |
| الجهات الفاعلة | ✅ | - | ✅ |
| محاكاة الهجوم | - | - | ✅ |
| كشف الانحراف | - | - | ✅ |
| مقاييس التعلم الآلي | - | - | ✅ |
| إدارة المتجهات | - | - | ✅ |
| قائمة التجاهل للكيانات | - | - | ✅ |
| الأنماط المرشحة | - | - | ✅ |
| الإشعارات | - | - | ✅ |
| السلالة | - | - | ✅ |
| الامتثال | - | - | ✅ |

### صفحات الواجهة الأمامية
| الصفحة | الحالة | ملاحظات |
|------|--------|-------|
| `/reports` | ✅ تعمل | قائمة، إنشاء، عرض التقارير |
| `/reports/[id]/review` | ✅ تعمل | سير عمل المراجعة بالكامل |
| `/analytics/cooccurrence` | ⚠️ تعتمد على البيانات | يعرض مؤشرات الأداء الرئيسية إذا وجدت حلقات |
| `/analytics/cooccurrence/pairs` | ⚠️ تعتمد على البيانات | يستدعي API حقيقي |
| `/analytics/cooccurrence/bundles` | ⚠️ تعتمد على البيانات | يستدعي API حقيقي |
| `/analytics/cooccurrence/actors` | ⚠️ تعتمد على البيانات | يستدعي API حقيقي |
| `/health` | ✅ تعمل | حالة الصحة في الوقت الفعلي |

## استكشاف الأخطاء وإصلاحها

### المشكلات الشائعة

1. **فشل اتصال OpenSearch**
   - تأكد من تشغيل OpenSearch: `curl http://localhost:9200`
   - تحقق من وجود الفهرس: `curl http://localhost:9200/bandjacks_attack_nodes-v1`

2. **فشل اتصال Neo4j**
   - تحقق من تشغيل Neo4j: `neo4j status`
   - تأكد من تعيين `NEO4J_PASSWORD` في ملف `.env`
   - تأكد من تطابق كلمة المرور مع مثيل Neo4j الخاص بك
   - إذا رأيت "NEO4J_PASSWORD environment variable is required"، فأنت بحاجة إلى تعيينه في ملف `.env`

3. **استدعاء استخراج منخفض**
   - تأكد من استخدام طريقة `agentic_v2`
   - تحقق من صحة مفتاح LLM API
   - تحقق من اسم النموذج (gemini-flash-latest)

4. **أخطاء المهلة**
   - زيادة إعدادات المهلة للمستندات الكبيرة
   - فكر في تقسيم التقارير الكبيرة جدًا

5. **عدم اتصال الواجهة الأمامية بـ API**
   - تأكد من تشغيل API على المنفذ 8000
   - تحقق من إعدادات CORS في تكوين API

### وضع التصحيح

تفعيل التسجيل المفصل:```python
import logging
logging.basicConfig(level=logging.DEBUG)

# Run extraction with debug output
result = run_agentic_v2(text, config)

### المساهمة

1. قم بعمل fork للمستودع
2. أنشئ فرع ميزة
3. قم بإجراء تغييراتك
4. قم بتشغيل الاختبارات: `uv run pytest`
5. قم بتشغيل التحليل النحوي: `uv run ruff check`
6. قدم طلب سحب

### جودة الكود```bash
# Format code
uv run ruff format

# Check linting
uv run ruff check

# Type checking
uv run mypy bandjacks