esp-idf-injection-ng

حقن إطارات 802.11 الخام على ESP-IDF v5.x / v6.x. تصحيح عكسي بأمر واحد يعيد تفعيل المجموعة الكاملة من أنواع إطارات 802.11 (Authentication، Deauth، Assoc، Reassoc، Disassoc، RTS/CTS/ACK، …) للإرسال عبر esp_wifi_80211_tx()، والتي تقيّدها مكتبة libnet80211.a المُوزَّعة من Espressif بقائمة بيضاء قصيرة (Beacon، Probe Req/Resp، Action، Data غير QoS).

يتضمن:

• التصحيح نفسه (patch/patch_libnet80211.sh) — objcopy --weaken-symbol على رمز واحد، مع نسخة احتياطية و--revert.
• برنامج تجريبي بسيط (example/) يحقن خمسة أشكال من الإطارات ويبلّغ عن النتائج عبر المنفذ التسلسلي.
• أدلة من Pcap وسجل Hostapd والسجل التسلسلي تُثبت أن التصحيح يفعّل حقن SAE Commit (Authentication subtype 11) على ESP32 — وهو حالة الاستخدام الدافعة لهذا العمل.
• التوثيق الهندسي الكامل على شكل ورقة بحثية (docs/esp32_raw_tx_report.pdf).

لماذا يوجد هذا؟

اعتمدت مشاريع المجتمع السابقة (wsl_bypasser، esp32-wifi-penetration-tool، Atomic-SAQuery، …) على تجاوز رمز C قوي لدالة الـ blob ieee80211_raw_frame_sanity_check. توقفت تلك التقنية عن العمل بصمت حوالي ESP-IDF v5: تغيّر ارتباط رمز الـ blob من WEAK إلى STRONG، لذا يفشل التجاوز الآن عند الربط بخطأ تعريف متعدد.

كذلك يفشل البديل الواضح (-Wl,--wrap=ieee80211_raw_frame_sanity_check) بصمت: إذ يعيد GNU ld --wrap كتابة المراجع غير المعرّفة بين الكائنات فقط، لكن الاستدعاء المهم — esp_wifi_80211_tx → sanity_check — داخلي الكائن داخل ieee80211_output.o، وغير مرئي لـ --wrap.

يوثّق هذا المستودع التغيير الكاسر ويقدّم بديلاً عاملاً: إعادة قلب رمز الـ blob إلى WEAK باستخدام objcopy --weaken-symbol، ثم توفير التجاوز في كود التطبيق. إعادة الربط عبر قاعدة تفوّق القوي على الضعيف عالميًا تعيد ربط كل مرجع، بما في ذلك المرجع داخلي الكائن.

راجع docs/esp32_raw_tx_report.pdf للحصول على التتبع الهندسي الكامل بما في ذلك تفكيك القائمة البيضاء لأنواع الإطارات، وثلاث محاولات فاشلة، وأدلة التحقق من البداية إلى النهاية.

البدء السريع

1. تصحيح أرشيف IDF

# Assumes IDF is at $IDF_PATH. Override with LIBNET80211=... if needed.
bash patch/patch_libnet80211.sh

# Verify (should print "W" after; "T" means not patched)
xtensa-esp32-elf-nm $IDF_PATH/components/esp_wifi/lib/esp32/libnet80211.a \
    | grep ieee80211_raw_frame_sanity_check
#   0000005c W ieee80211_raw_frame_sanity_check    ← correct

التصحيح عديم الأثر التكراري (idempotent)؛ إعادة تشغيله لا تُحدث أي تغيير. للتراجع:

bash patch/patch_libnet80211.sh --revert

يتم حفظ نسخة احتياطية من الأرشيف الأصلي باسم libnet80211.a.bak عند أول تشغيل.

2. بناء العرض التجريبي وحرقه

cd example
idf.py set-target esp32
idf.py build flash monitor

يجب أن يتنقل الإخراج التسلسلي عبر خمسة متغيرات كل 4 ثوانٍ، مع الإبلاغ عن esp_wifi_80211_tx() -> ESP_OK في كل مرة:

I (xxxxx) INJ-DEMO: >>> Sending V0 Deauth (control)            esp_wifi_80211_tx() -> ESP_OK
I (xxxxx) INJ-DEMO: >>> Sending V1 Open-Auth (baseline)        esp_wifi_80211_tx() -> ESP_OK
I (xxxxx) INJ-DEMO: >>> Sending V2 SAE-Commit bare             esp_wifi_80211_tx() -> ESP_OK
I (xxxxx) INJ-DEMO: >>> Sending V3 SAE-Commit full (malformed) esp_wifi_80211_tx() -> ESP_OK
I (xxxxx) INJ-DEMO: >>> Sending V4 SAE-Commit valid (scalar=2,E=G)
                                                               esp_wifi_80211_tx() -> ESP_OK

إذا رأيت بدلاً من ذلك E (xxxxx) wifi:unsupport frame type: 0b0 في كل دورة، فإن التصحيح لم يُطبَّق؛ أعد تشغيل patch_libnet80211.sh و idf.py fullclean build flash.

3. (اختياري) الالتقاط عبر الأثير

وجّه محول Wi-Fi آخر في وضع المراقبة على القناة نفسها وشغّل tcpdump / Wireshark. راجع evidence/ للحصول على مثال على عملية التقاط.

ما الذي تم تمكينه

جدول من الورقة البحثية (الجدول 1):

نوع الإطار	الأنواع الفرعية المسموح بها في النسخة الأصلية	الأنواع الفرعية المرفوضة في النسخة الأصلية، والمُمكَّنة بواسطة هذا التصحيح
MGMT (0)	4 (ProbeReq)، 5 (ProbeResp)، 6 (TimingAd)، 7، 8 (Beacon)، 13 (Action)	0 Assoc، 1 AssocResp، 2 Reassoc، 3 ReassocResp، 9 ATIM، 10 Disassoc، 11 Auth، 12 Deauth
CTRL (1)	(لا شيء)	الكل (RTS، CTS، ACK، BlockAck، …)
DATA (2)	0–7 (غير QoS)	8–15 (متغيرات QoS)

تحذيرات

• لا تزال القيود في المسار السفلي سارية. التصحيح يزيل فقط بوابة sanity_check. لا تزال أجهزة MAC وآلة حالة MLME ومجدول TX تطبّق قيودها الخاصة. عملياً، هذا يعني أن أطر الإدارة (mgmt) تُحقن بشكل موثوق؛ أما أطر التحكم (RTS/CTS/ACK) فتُرسَل لكنها قد تكون متأخرة جداً في مساحة المستخدم بالنسبة لتوقيت IEEE 802.11 الصحيح (موعد SIFS النهائي). بالنسبة لتشويش المحتوى (fuzzing)، لا يهم التوقيت؛ أما بالنسبة للتفاعلات المتوافقة مع البروتوكول، فإنه يهم.
• هذا يعدّل تثبيت ESP-IDF عالمياً. كل مشروع تبنيه مقابل ذلك IDF سيُربط بالأرشيف المُصحَّح. patch_libnet80211.sh --revert يستعيد الملف الأصلي من النسخة الاحتياطية.
• تجاوز TX فقط. هذا لا يفعل شيئاً لـ RX — الالتقاط المختلط في وضع المراقبة يعمل جاهزاً في ESP-IDF.
• تم الاختبار على ESP-IDF v6.1-dev مقابل ESP32 (الكلاسيكي). يجب أن يعمل على v5.x والأهداف الأخرى (ESP32-S2/S3/سلسلة C) إذا كان ربط الرمز هو T — تحقق باستخدام nm أولاً، راجع خطوة "التحقق" أعلاه.

الاستخدام الأخلاقي

تُمكّن التقنيات هنا من إرسال أطر 802.11 الخام، وهو ما له استخدامات بحثية/دفاعية (التشويش، اختبار PMF، قياس القنوات الجانبية — حالة الاستخدام الدافعة) واستخدامات عدائية (عواصف deauth ضد شبكات لا تملكها). لا تعمل إلا ضد شبكات وأجهزة Wi-Fi تملكها أو لديك تفويض كتابي صريح لاختبارها. التشغيل غير المصرح به ضد بنية تحتية تابعة لطرف ثالث غير قانوني في معظم الولايات القضائية.

يستخدم المؤلف هذا التصحيح داخل بيئة مختبر معزولة في NHSM، الجزائر، لأطروحة ماجستير حول تحليل القنوات الجانبية لـ WPA3-SAE.

هيكل المستودع

.
├── README.md                            — this file
├── LICENSE                              — MIT
├── patch/
│   └── patch_libnet80211.sh             — the patch script
├── example/                             — minimal demo IDF project
│   ├── CMakeLists.txt
│   └── main/
│       ├── CMakeLists.txt
│       └── main.c
├── docs/
│   └── esp32_raw_tx_report.pdf          — full engineering writeup
└── evidence/
    ├── README.md                        — what each file proves
    ├── sae_injection_first_capture.pcap — monitor-mode OTA capture
    ├── tshark_injected_frames.txt       — decoded frame list
    ├── hostapd_v4_roundtrip.log         — Hostapd parse + response
    └── serial_log_post_bypass.txt       — ESP32 serial, no reject log

أعمال ذات صلة

• risinek/wsl_bypasser — نهج تجاوز الاسم نفسه الأصلي. يعمل على IDF ≤ v4.x؛ ويتعطّل بصمت على v5+ كما هو موثّق هنا.
• risinek/esp32-wifi-penetration-tool — يعتمد على wsl_bypasser؛ القيد نفسه.
• Matheus-Garbelini/esp32_esp8266_attacks — إثباتات مفهوم أكاديمية لثغرات CVE، مقتصرة على حقن الإطارات الإعلانية (beacon) فقط.
• Vanhoef & Ronen، Dragonblood: Analyzing the Dragonfly Handshake of WPA3 and EAP-pwd، IEEE S&P 2020 — القناة الجانبية SAE PWE التي تحفّز هذا المشروع.

الاستشهاد

إذا استخدمت هذا التصحيح أو التقرير في عمل أكاديمي، فيرجى الاستشهاد بـ:

Mehdi Mansour. "Enabling Raw 802.11 Management Frame Injection on
ESP-IDF v6: A Linker-Level Analysis of ieee80211_raw_frame_sanity_check
and a Reproducible Bypass." Technical report, École Nationale
Supérieure de Mathématiques (NHSM), Algiers, October 2026.

المؤلف

مهدي منصور — قسم التشفير والترميز والأمن، NHSM الجزائر العاصمة. للتواصل: [email protected] · LinkedIn

الترخيص

MIT. راجع LICENSE.