Hugging Face's logo

Spaces:
devorbit
/
murshid
Paused

App Files Community
murshid
File size: 4,710 Bytes
26e1c2e
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
# 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).