مجموعة أدوات BadUSB HID لـ Raspberry Pi Zero 2 W

منصة هجوم BadUSB / HID قابلة للبرمجة مبنية على Raspberry Pi Zero 2 W. يتعرف Pi على أنه جهاز USB مركب (لوحة مفاتيح بالإضافة إلى وحدة تخزين كبيرة للقراءة فقط اختيارية) وينفذ حمولات على غرار Ducky-Script ضد المضيف الذي يتم توصيله به. مصممة لاستخدامات الفريق الأحمر المصرح بها، واختبارات الاختراق، ومسابقات CTF.

⚠️ إشعار قانوني. استخدم فقط على الأنظمة التي تمتلكها أو لديك إذن كتابي صريح لاختبارها. الوصول غير المصرح به غير قانوني في معظم الدول، والتظاهر بعدم المعرفة لن يفيد.

الميزات

حمولات ضغطات مفاتيح قابلة للبرمجة بلهجة متوافقة مع Ducky-Script.
كشف موثوق لتوصيل المضيف عبر حالة configured لـ UDC — لا يتم إطلاق حمولات خاطئة عند الإقلاع.
"إعادة ضبط بين الهجمات" تعمل فعليًا على أجهزة Pi Zero 2 W. افصل، أعد التوصيل، أطلق مرة أخرى — لا حاجة لدورة طاقة.
ضمانات قابلة للتكوين ضد الحلقات الجامحة إذا بقي الجهاز موصولاً: حد أدنى للفاصل الزمني بين عمليات الإطلاق، وحد أقصى لعدد الإطلاقات في الدقيقة، وكلاهما قابل للتجاوز عبر متغيرات البيئة.
أداة تخزين كبيرة مركبة اختيارية مدعومة بملف صورة مسطح (للقراءة فقط افتراضيًا — كان عرض بطاقة SD الحية هو السبب القديم الصعب التصحيح لفساد نظام الملفات).
تخطيط لوحة مفاتيح أمريكي وبريطاني قابل للاختيار لكل حمولة باستخدام LAYOUT.
المتغيرات، IF / ELSE، WHILE، HOLD / RELEASE، INJECT_MOD، مولدات RANDOM_*، STRING_BLOCK / STRINGLN_BLOCK، DEFINE.
تكامل systemd مع ExecStop الذي يفك الأداة بشكل نظيف. لا توجد حالة متبقية من configfs، وإعادة التشغيل تعمل دون إعادة إقلاع.
صلاحيات مدارة عبر udev لـ /dev/hidg0 — لا توجد عُقد جهاز قابلة للكتابة للجميع.
مجموعة اختبارات pytest مكونة من 34 اختبارًا لمحلل Ducky، قابلة للتشغيل على أي مضيف بدون توصيل Pi.
مؤشر حالة LED ACT بعد كل تشغيل حمولة.

كيف يعمل

+----------------+        كابل USB          +-------------+
|  Raspberry Pi  | ===================>>>  |  المضيف     |
|  Zero 2 W      |   (Pi يحاكي HID +       |  (الهدف)    |
|  (هذا الجهاز)   |    محرك اختياري)        |             |
+----------------+                         +-------------+
        |
        |  /home/pi/pi-badusb/
        |
        +-- badusb.service ----> monitor_and_run.py
                                   |
                                   |  عند `state == configured`:
                                   v
                                 run_payload.py
                                   |
                                   v
                                 /dev/hidg0  (أداة USB HID)

عند الإقلاع، يقوم وحدة النظام badusb.service بتشغيل gadget_setup.sh، الذي يستخدم configfs/libcomposite لتكوين أداة USB مع وظيفة لوحة مفاتيح HID و (اختياريًا) LUN تخزين كبير مدعوم بملف صورة مسطح في /var/badusb/storage.img.
ثم تقوم الوحدة بتشغيل monitor_and_run.py. يستطلع حالة /sys/class/udc/<udc>/state وينتظر configured — حالة USB-Spec التي تعني أن المضيف قد عدّد الأداة بنجاح. (نحن لا نستخدم وجود /dev/hidg0 كإشارة: هذا صحيح منذ اللحظة التي ترتبط فيها الأداة بـ UDC عند الإقلاع، بغض النظر عما إذا كان أي شيء موصولاً.)
عند توصيل المضيف، يقوم المستمع بتنفيذ run_payload.py، الذي يوزع payload.txt ويكتب تقارير HID إلى /dev/hidg0.
عند انتهاء الحمولة، يقوم المستمع بإلغاء ربط الأداة من UDC بشكل نشط (لا يستطيع Pi Zero 2 W اكتشاف الانفصال الفعلي عبر البرنامج — انظر ملاحظات معمارية)، ينام لفترة تبريد، ويعيد الربط. ينتظر الجهاز بعد ذلك الانتقال التالي إلى configured.

الأجهزة

المكون	ملاحظة
Raspberry Pi Zero 2 W	تم اختباره على مراجعة الأجهزة 2026-05. يعمل Pi Zero W الأقدم مع برنامج تشغيل BCM2835 dwc_otg من حيث المبدأ أيضًا، لكن هذا README يفترض 2 W مع dwc2.
كابل micro-USB إلى USB-A	أو محول على شكل "محرك أقراص USB" يسمح للPi بالتوصيل مباشرة بمنفذ مضيف.
اختياري: شاحن منفصل	إذا كنت ترغب في تشغيل Pi من مصدر غير المضيف حتى يتمكن المستمع من الإقلاع قبل توصيله بهدف (وإلا فإن منفذ المضيف يوفر الطاقة).

يحتوي Pi Zero 2 W على منفذي micro-USB:

PWR IN — الطاقة فقط، لا يعرض خطوط بيانات USB لكتلة dwc2 OTG.
USB — منفذ بيانات OTG؛ هذا هو المكان الذي توصل به إلى الهدف.

البرامج

المتطلب	لماذا
Raspberry Pi OS (Debian Bookworm أو Trixie، 64 بت Lite موصى به)	يكتب البرنامج النصي للتثبيت `/boot/firmware/...` على Bookworm+ ويعود إلى `/boot/...` على الصور الأقدم.
Python 3	يأتي مع Pi OS.
`mkfs.vfat`	لتهيئة صورة التخزين الكبير الخلفية في التشغيل الأول. قم بتعطيله إذا ألغيت التخزين الكبير.
وصول root للإعداد	يلمس systemd و udev و `/boot/firmware/config.txt`.

التثبيت

انسخ المستودع أو استنسخه إلى Pi، ثم قم بتشغيل المثبِّت:

git clone http://your-gitea/admin/Pi-Zero-2W-Bad-USB.git /home/pi/pi-badusb
cd /home/pi/pi-badusb
sudo ./install.sh
sudo reboot

بعد إعادة الإقلاع، قم بتمكين الخدمة وتشغيلها:

sudo systemctl enable --now badusb.service
journalctl -u badusb -f

install.sh غير مؤثرة — أعد تشغيلها كلما غيرت ملفات المشروع. تقوم بـ:

كشف /boot/firmware (Bookworm+) مقابل /boot (الأقدم).
التأكد من أن dtoverlay=dwc2,dr_mode=otg نشط تحت كتلة [all] في config.txt. الإعدادات الافتراضية لـ Raspberry Pi Imager تضع هذا السطر داخل مرشح [cm5] الذي لا ينطبق على Pi Zero 2 W؛ يضيف المثبِّت تجاوزًا مُوسومًا بحيث لا تكرره عمليات إعادة التشغيل.
التأكد من أن modules-load=dwc2 موجود في cmdline.txt.
تحذير إذا كان g_ether لا يزال موجودًا في cmdline.txt (يسرق UDC من libcomposite ويكسر وضع الأداة).
تثبيت وحدة النظام في /etc/systemd/system/badusb.service.
تثبيت قاعدة udev في /etc/udev/rules.d/99-badusb-hidg.rules بحيث يكون /dev/hidg0 قابلًا للكتابة للمجموعة بواسطة plugdev.
إضافة المستخدم pi إلى plugdev.
إنشاء /var/badusb/ لصورة التخزين الكبير الخلفية.

الاستخدام اليومي

# بدء / إيقاف / إعادة تشغيل
sudo systemctl start badusb
sudo systemctl stop badusb
sudo systemctl restart badusb              # آمن أثناء التوصيل

# مراقبة مباشرة
journalctl -u badusb -f

# تعطيل التشغيل التلقائي عند الإقلاع
sudo systemctl disable badusb

# ضبط التوقيتات (ينشئ إدراج تجاوز)
sudo systemctl edit badusb
# (الصق كتلة [Service] مع Environment="BADUSB_REARM_COOLDOWN_S=8" إلخ)
sudo systemctl restart badusb

تعتمد الخدمة على sys-kernel-config.mount ووجود UDC، لذا لا يمكنها إطلاق الحمولات قبل أن تكون الأداة جاهزة فعليًا.

تحرير الحمولة لا يتطلب إعادة تشغيل — تتم قراءة payload.txt من جديد عند كل توصيل.

كتابة الحمولات

payload.txt موجود في دليل التثبيت. مرجع الأوامر الكامل موجود في payload_commands.md.

مثال بسيط

REM افتح مربع حوار التشغيل واكتب تحية عبر Notepad
LAYOUT US
GUI r
DELAY 1500
STRING notepad
ENTER
DELAY 2500
STRINGLN مرحبًا من Pi Zero 2 W

المتغيرات، الشروط، الحلقات

VAR $USER="alice"
VAR $COUNT=0
WHILE $COUNT < 3
  STRINGLN مرحبًا $USER (التكرار $COUNT)
  VAR $COUNT = $COUNT + 1
END_WHILE

IF $USER == "alice"
  STRINGLN تم المطابقة
ELSE
  STRINGLN لم يتم المطابقة
END_IF

تمر التعبيرات الرياضية في VAR عبر مقيم آمن يعمل على ast — لا أسماء، لا استدعاءات، لا وصول إلى سمات، فقط القيم الرقمية و + - * / // % **.

الاحتفاظ بالمعدِّلات

HOLD SHIFT
STRINGLN هذا السطر مكتوب بأحرف كبيرة
RELEASE SHIFT

إرسال تركيبات معدِّلات عشوائية

REM أمسك Ctrl+Shift (0x01 + 0x02) واضغط A
INJECT_MOD 0x03
STRING a
REM تحرير جميع المعدِّلات
INJECT_MOD 0x00

Pi-Zero-2W-Bad-USB

الأكثر شعبية