USBCoercer: جهاز إكراه WPAD قائم على TinyUSB

يحوّل USBCoercer لوحة تطوير ESP32 المزودة بمنفذ USB-OTG أصلي إلى أداة Ethernet عبر USB قادرة على إكراه إعدادات الوكيل عبر WPAD. يعتمد على مثال نموذج التحكم في الشبكة (NCM) الخاص بـ TinyUSB ويضيف خادم DHCP مبسّطًا يحقن خيار DHCP 252 (WPAD/PAC)، بالإضافة إلى مسارات ثابتة غير مصنّفة (الخيار 121) لحجب بيانات تتبع EDR عند الحاجة.

المشروع مخصص لاختبارات الأمان والعروض التوضيحية في المختبرات. احرص دائمًا على الحصول على إذن صريح قبل استخدامه.

الميزات الرئيسية

• أداة Ethernet عبر USB NCM قائمة على TinyUSB
• خادم DHCP مدمج يوفّر مسارات ثابتة غير مصنّفة اختيارية (الخيار 121) وعنوان WPAD/PAC قابلًا للتكوين (الخيار 252).
• مؤشر LED للحالة يتحول إلى الأخضر بعد اكتمال تشغيل حزمة الشبكة على عتاد AtomS3U، وإلى الأصفر بعد مرحلة DHCP Discovery/Offer، وإلى الأزرق عند اكتمال DHCP Request/ACK.

المتطلبات

العتاد

• لوحة ESP32-S3 مزودة بمنفذ USB-OTG أصلي
• (في بعض الطرازات) كبل USB يربط منفذ OTG الخاص بـ SoC بالجهاز المستهدف.

البرمجيات

• إصدار Espressif ESP-IDF v5.5 (أو أحدث) مع تفعيل دعم TinyUSB.
• سلسلة أدوات ESP-IDF (toolchain) وبيئة Python مثبّتة عبر السكربتات القياسية install.sh/export.sh.
• مهم: تم تطوير هذا البرنامج الثابت باستخدام الفرع 1.x من espressif/esp_tinyusb ولم يُنقَل إلى الفرع 2.x. سيؤدي استخدام الفرع 2.x إلى أخطاء في التجميع. الحد الأقصى للإصدار المدعوم هو espressif/esp_tinyusb 1.6.0.

بدء سريع

1. إعداد ESP-IDF
   root@kitploit:~

   . $HOME/esp/esp-idf/export.sh
   

2. تكوين المشروع (اختياري)
   root@kitploit:~

   idf.py menuconfig
   

   راجع قائمة USBCoercer Configuration لتخصيص عنوان IP المحلي، وتجمع DHCP، وإعدادات WPAD، وغيرها.
3. البناء
   root@kitploit:~

   idf.py build
   

4. الحرق (Flash)
   root@kitploit:~

   idf.py flash
   

مرجع التكوين

يعرض المشروع قائمة مخصصة باسم USBCoercer Configuration داخل idf.py menuconfig:

• الواجهة – عيّن عنوان IPv4 المواجه لـ USB، وقناع الشبكة الفرعية، والبوابة بالإضافة إلى عنوان MAC المُدار محليًا والذي يُعلَن للمضيف.
• خادم DHCP – تحكم في بداية/نهاية تجمع التأجير، ومدة التأجير، وخادم DNS الاختياري، ولاحقة النطاق (الخيار 15).
• WPAD – بدّل الخيار 252 وحدد عنوان URL المُقدَّم للمضيفات المتصلة.
• المسارات الثابتة – فعّل الخيار 121 ووفّر قائمة مسارات مفصولة بفواصل منقوطة باستخدام صيغة destination/prefix,gateway (على سبيل المثال، 3.121.6.180/32,192.168.7.1). اترك القائمة فارغة لإغفال الخيار.

التكوين الافتراضي

يوفر sdkconfig.defaults إعدادًا ملائمًا للمختبرات:

• عنوان IP المحلي: 192.168.7.1/24 دون بوابة افتراضية.
• تجمع DHCP من ثلاثة عناوين (192.168.7.2 – 192.168.7.4).
• نطاق DHCP: badnet.
• WPAD مفعّل ويشير إلى http://192.168.7.1/wpad.dat. استضف ملف PAC على الأصل المُكوَّن أو عدّل عنوان URL حسب الحاجة.
• خيار DNS معطّل (تحتفظ المضيفات بخوادم DNS الخاصة بها).
• المسارات الثابتة معطّلة افتراضيًا (لا يُرسَل الخيار 121 إلا عند تكوينه).

عدّل sdkconfig.defaults أو استخدم menuconfig لتكييف البيئة مع اختباراتك. أعد بناء البرنامج الثابت (idf.py build) بعد تغيير أي معاملات.

سلوك الشبكة

• يعرض الجهاز نفسه كمهايئ Ethernet عبر USB NCM باستخدام عنوان MAC المُكوَّن.
• يجيب خادم DHCP المدمج على رسائل DISCOVER/REQUEST بالمعاملات المُكوَّنة.
• عند تفعيل المسارات غير المصنّفة، يُنشأ الخيار 121 ديناميكيًا.
• عند تفعيل WPAD مع توفير عنوان URL غير فارغ، يسترجع المضيف ملف PAC من الأصل المحدد ويطبّق إعدادات الوكيل.

استخدام آلية إكراه NTLM

حاليًا، يتطلب النشر خادمًا خارجيًا لتوفير الوكيل المُصادَق عبر NTLM وإكراه المصادقة. يُعد Responder مفيدًا لهذه المهمة. أما الخادم الخارجي لخدمة ملف WPAD.DAT فهو اختياري.

تحذيرات

• قد يؤدي التلاعب بـ WPAD أو المسارات الثابتة إلى إعادة توجيه حركة مرور الجهاز المتصل. استخدم هذا البرنامج الثابت فقط في بيئات خاضعة للتحكم وبناءً على موافقة مستنيرة.
• يستهدف المشروع سيناريوهات المختبرات؛ ولا يطبّق ضوابط أمان إضافية أو استمرارية للإعدادات.

الاختبار

تم اختبار هذا البرنامج الثابت على M5Stack AtomS3U وعمل بشكل صحيح.

شكر وتقدير

• مبني، بشكل أقرب أو أبعد، على أمثلة ESP-IDF TinyUSB NCM الرسمية.
• أُعيدت هيكلته وتحسينه باستخدام Codex.

اختراق سعيد (ومسؤول)!