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) تثبيت

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

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

إنشاء قاعدة البيانات في MySQL:

CREATE DATABASE murshid_db CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;

4) إعداد .env

copy .env.example .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 (هجرة الجداول)

alembic upgrade head

7) تشغيل الـ API

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)

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

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).