Bandjacks

نظام نمذجة دفاع عالمي للتهديدات الإلكترونية

نظرة عامة

Bandjacks هو نظام شامل لاستخبارات التهديدات الإلكترونية (CTI) يقوم بـ:

• استخراج تقنيات MITRE ATT&CK من تقارير التهديدات في 12-40 ثانية
• بناء رسم بياني معرفي للجهات الفاعلة للتهديدات والتقنيات والدفاعات
• إنشاء حزم متوافقة مع STIX 2.1 مع تتبع كامل للمصدر
• دمج أنطولوجيا D3FEND للحصول على توصيات دفاعية
• توفير إمكانيات البحث المتجه وتحليلات الرسم البياني
• حساب تحليلات التكرار المشترك لتحديد أنماط التقنيات
• يتميز باستخراج أسرع بنسبة 94% مقارنة بالإصدارات السابقة مع تخزين مؤقت لاستجابات LLM
• يتضمن واجهة أمامية Next.js لمراجعة التقارير وعرض التحليلات

📚 الوثائق

الدليل	الوصف
البدء السريع	التشغيل في 5 دقائق
الإعداد الكامل	إعداد البيئة بالكامل
استخدام CLI	دليل واجهة سطر الأوامر
مرجع API	توثيق REST API
تحليلات التكرار المشترك	توثيق التحليلات
توليد تدفق الهجوم	دليل توليد التدفقات
نظام المراجعة	مراجعة بشرية في الحلقة

أبرز ميزات البنية

TechniqueCache

• ذاكرة تخزين مؤقت في الذاكرة لجميع تقنيات MITRE ATT&CK المحملة عند بدء التشغيل
• عمليات بحث O(1) بواسطة external_id (مثل T1557) لحل الأسماء الفوري
• 1376 تقنية مخزنة مؤقتًا مع البيانات الوصفية الكاملة (الاسم، الوصف، التكتيكات، المنصات)
• تسمية متسقة تضمن أن واجهة المراجعة تعرض دائمًا أسماء تقنيات قابلة للقراءة البشرية

ActorCache

• ذاكرة تخزين مؤقت في الذاكرة لجميع مجموعات الاختراق والجهات الفاعلة للتهديدات
• عمليات بحث سريعة لحل أسماء الجهات الفاعلة والبحث
• يدعم مطابقة الأسماء المستعارة والبحث التقريبي

بدء سريع

المتطلبات الأساسية

• Python 3.11+
• Neo4j 5.x (قاعدة بيانات رسوم بيانية)
• OpenSearch 2.x (مخزن متجهات)
• Redis (اختياري، للتخزين المؤقت)
• Node.js 18+ (لل واجهة الأمامية)
• الوصول إلى LLM: مفاتيح API سحابية (Gemini أو OpenAI) أو خادم محلي متوافق مع OpenAI

التثبيت```bash

Clone the repository

git clone https://github.com/yourusername/bandjacks.git cd bandjacks

Install Python dependencies with uv (recommended)

uv sync

Or with pip

pip install -e .

Install frontend dependencies

cd ui && npm install && cd ..

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

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

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

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

التكوين المطلوب في .env:```bash

Neo4j Configuration (REQUIRED)

NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=your-actual-neo4j-password # MUST BE SET - no default provided

OpenSearch Configuration

OPENSEARCH_URL=http://localhost:9200 OPENSEARCH_USER=admin OPENSEARCH_PASSWORD=your-opensearch-password # Optional if security is disabled

LLM Configuration — pick ONE of the options below:

Option A: Local OpenAI-compatible API (vLLM, llama.cpp, Ollama, LocalAI, LM Studio, etc.)

LOCAL_LLM_API_BASE=http://192.168.1.100:8080/v1 # Base URL of your local server LOCAL_LLM_MODEL=mistral-nemo # Model name as the server reports it LOCAL_LLM_API_KEY=no-key # Most local servers accept any value

Option B: Cloud LLM providers

PRIMARY_LLM=gemini GOOGLE_API_KEY=your-gemini-api-key

Optional: OpenAI as fallback (or primary if PRIMARY_LLM=openai)

OPENAI_API_KEY=your-openai-api-key

ATT&CK Configuration

ATTACK_INDEX_URL=https://raw.githubusercontent.com/mitre-attack/attack-stix-data/master/index.json ATTACK_COLLECTION=enterprise-attack ATTACK_VERSION=latest

Redis (optional, for caching)

REDIS_URL=redis://localhost:6379

**ملاحظة:** سيفشل تشغيل التطبيق إذا لم يتم تعيين `NEO4J_PASSWORD`. راجع [إصلاح متغيرات البيئة](https://github.com/blevene/bandjacks/blob/main/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)

تتضمن Bandjacks واجهة سطر أوامر شاملة لعمليات استخبارات التهديدات:```bash

Show all available commands

uv run python -m bandjacks.cli.main --help

> **ملاحظة:** تتطلب واجهة سطر الأوامر (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

Show review queue

uv run python -m bandjacks.cli.main review queue --status pending --limit 20

Approve a candidate

uv run python -m bandjacks.cli.main review approve "candidate-123" --reviewer analyst-1

Reject with reason

uv run python -m bandjacks.cli.main review reject "candidate-456" --reviewer analyst-1 --reason "False positive"

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

أوامر التحليلات

ملاحظة: تتطلب أوامر التحليلات بيانات AttackEpisode في Neo4j لإرجاع النتائج.```bash

Show top co-occurring technique pairs

uv run python -m bandjacks.cli.main analytics top-cooccurrence --limit 25 --min-episode-size 2

Compute conditional co-occurrence P(B|A) for a technique

uv run python -m bandjacks.cli.main analytics conditional "attack-pattern--abc123" --limit 25

Analyze a specific threat actor

uv run python -m bandjacks.cli.main analytics actor "intrusion-set--xyz789" --metric npmi

Extract technique bundles

uv run python -m bandjacks.cli.main analytics bundles --min-support 3 --min-size 3 --max-size 5 --format json --output bundles.json

Global co-occurrence metrics

uv run python -m bandjacks.cli.main analytics global --min-support 2 --limit 50 --format csv --output pairs.csv

### أوامر سير العمل```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/

أوامر المشرف```bash

Check system health

uv run python -m bandjacks.cli.main admin health

View cache statistics

uv run python -m bandjacks.cli.main admin cache-stats

Clear cache

uv run python -m bandjacks.cli.main admin cache-clear --pattern "search:*"

Optimize database

uv run python -m bandjacks.cli.main admin optimize

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

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

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

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

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