murshid_backend/README.md

# Murshid Backend

REST API لمشروع "مرشد — من التنبيهات إلى التوجيه: ربط تقنيات MITRE ATT&CK لمحللي SOC"

## التقنيات

- **FastAPI** — REST API
- **MySQL** + **SQLAlchemy** — قاعدة البيانات
- **Alembic** — هجرة الجداول
- **Logistic Regression** — النموذج الأساسي في هذه المرحلة
- **SecureBERT+** — تضمينات نصية
- **Llama 3 8B** — تلخيص قواعد Wazuh

> المنطق مستخرج من `MurshidUIPipeline.ipynb` دون تعديله.

---

## هيكل المشروع

```
murshid_backend/
  app/
    main.py                    ← نقطة تشغيل FastAPI
    config.py
    api/routes/
      health.py                ← GET /health
      rules.py                 ← POST /rules/analyze + GET /results/{rule_id}
      queries.py               ← GET /queries/{technique_id} + Admin endpoints
    services/
      ml_service.py
      rule_service.py
      result_service.py
      template_service.py
    ml/
      sanitizer.py             ← تنظيف XML
      summarizer.py            ← تلخيص Llama
      embedder.py              ← SecureBERT+
      logistic_model.py        ← Logistic Regression inference
      pipeline.py              ← analyze_rule() الشامل
    models/                    ← SQLAlchemy ORM (6 جداول من ER Diagram)
    schemas/                   ← Pydantic schemas
    repositories/              ← DB access layer
    db/
      base.py
      session.py
  alembic/
    versions/0001_initial_schema.py
  requirements.txt
  .env.example
```

---

## جداول قاعدة البيانات (مستخرجة من ER Diagram §3.2.6)

| جدول | المصدر في التقرير |
|------|-------------------|
| `users` | User entity — username, email, password_hash, role |
| `mapping_jobs` | MappingJob entity — job_id, file_name, status, progress, timestamp |
| `rules` | Rule entity — rule_id, embedding_vector, job_id |
| `techniques` | Technique entity — technique_id, technique_name, tactic |
| `rule_technique_mappings` | RuleTechniqueMapping — rule_id, technique_id, confidence_score |
| `query_templates` | QueryTemplate — purpose, wql_query, note, is_active |

---

## الإعداد والتشغيل

### 1) متطلبات

- Python 3.10+
- MySQL 8+
- GPU موصى به لـ Llama 3 8B

### 2) تثبيت

```powershell
cd d:\GP\murshid_backend
python -m venv .venv
.\.venv\Scripts\activate
pip install -r requirements.txt
```

### 3) إعداد قاعدة البيانات

إنشاء قاعدة البيانات في MySQL:
```sql
CREATE DATABASE murshid_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
```

### 4) إعداد `.env`

```powershell
copy .env.example .env
```

عدّلي القيم:
```env
MURSHID_DB_URL=mysql+pymysql://root:YOUR_PASSWORD@localhost:3306/murshid_db
MURSHID_MODELS_DIR=d:/GP/Needed
HF_TOKEN=hf_xxxx
MURSHID_SKIP_LLM=false
```

### 5) تأكد من وجود ملفات النماذج في `d:\GP\Needed`

```
murshid_logreg_pipeline_manual_oof_pcatuned.joblib
murshid_logreg_thresholds_manual_oof_pcatuned.npy
murshid_label_columns.json
```

### 6) تشغيل Alembic (هجرة الجداول)

```powershell
alembic upgrade head
```

### 7) تشغيل الـ API

```powershell
uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
```

---

## الـ Endpoints

| Method | URL | الوصف |
|--------|-----|--------|
| `GET` | `/health` | فحص حالة النظام والنماذج |
| `POST` | `/rules/analyze` | تحليل قاعدة Wazuh XML وحفظ النتائج |
| `GET` | `/results/{rule_id}` | استرجاع التقنيات المخزنة لمعرف القاعدة |
| `GET` | `/queries/{technique_id}` | جلب قوالب WQL لتقنية معينة |
| `POST` | `/admin/templates` | إضافة قالب WQL جديد (Admin) |
| `PATCH` | `/admin/templates/{id}` | تعديل أو تعطيل قالب (Admin) |

### مثال — تحليل قاعدة

```bash
curl -X POST http://127.0.0.1:8000/rules/analyze \
  -H "Content-Type: application/json" \
  -d '{"rule_xml": "<rule id=\"597\" level=\"5\"><description>Registry Key Entry Deleted.</description></rule>"}'
```

### التوثيق التفاعلي

افتحي: **http://127.0.0.1:8000/docs**

---

## ملاحظات

- الملف الأصلي `MurshidUIPipeline.ipynb` **لم يُعدَّل** — المنطق منسوخ إلى طبقة `app/ml/`.
- النموذج المعتمد في هذه المرحلة: **Logistic Regression** فقط.
- لتشغيل بدون GPU للاختبار فقط: ضعي `MURSHID_SKIP_LLM=true` في `.env` (لكن `/rules/analyze` ستعيد 503).