Raspberry Pi Zero 2 W BadUSB HID टूलकिट

Raspberry Pi Zero 2 W पर निर्मित एक प्रोग्रामेबल BadUSB / HID आक्रमण प्लेटफ़ॉर्म। यह Pi एक USB कम्पोज़िट डिवाइस (कीबोर्ड प्लस एक वैकल्पिक रीड-ओनली मास-स्टोरेज वॉल्यूम) के रूप में एन्यूमरेट होता है और Ducky-Script-शैली के पेलोड उस होस्ट पर निष्पादित करता है जिससे यह जुड़ा होता है। यह अधिकृत रेड-टीम अभियानों, पेनेट्रेशन परीक्षणों और CTF के लिए डिज़ाइन किया गया है।

⚠️ कानूनी सूचना। केवल उन्हीं सिस्टम पर उपयोग करें जिनके आप स्वामी हैं या जिनके परीक्षण की स्पष्ट लिखित अनुमति आपके पास है। अधिकांश क्षेत्राधिकारों में अनधिकृत पहुँच अवैध है, और यह दिखावा करना कि आपको पता नहीं था, काम नहीं आएगा।

विषय-सूची

1. विशेषताएँ
2. यह कैसे काम करता है
3. हार्डवेयर
4. इंस्टॉल
5. दैनिक संचालन
6. पेलोड लिखना
7. कॉन्फ़िगरेशन संदर्भ
8. आर्किटेक्चर नोट्स
9. परीक्षण
10. समस्या निवारण
11. रिपॉजिटरी संरचना
12. श्रेय

विशेषताएँ

• प्रोग्रामेबल कीस्ट्रोक पेलोड एक Ducky-Script-संगत डायलेक्ट में।
• विश्वसनीय होस्ट-अटैच डिटेक्शन UDC configured अवस्था के माध्यम से — बूट पर कोई फ़र्ज़ी पेलोड फायर नहीं होता।
• "Reset between attacks" जो Pi Zero 2 W हार्डवेयर पर वास्तव में काम करता है। अनप्लग करें, दोबारा प्लग करें, फिर से फायर करें — कोई पावर-साइकिल नहीं।
• कॉन्फ़िगर करने योग्य सुरक्षा उपाय रनअवे लूप्स के विरुद्ध यदि डिवाइस प्लग्ड रह जाए: प्रति-फायर न्यूनतम अंतराल और फायर-प्रति-मिनट दर सीमा, दोनों env-var द्वारा ओवरराइड करने योग्य।
• वैकल्पिक कम्पोज़िट मास-स्टोरेज गैजेट जो एक फ्लैट इमेज फ़ाइल द्वारा समर्थित है (डिफ़ॉल्ट रूप से रीड-ओनली — आपके लाइव SD कार्ड को एक्सपोज़ करना पुराना, डीबग करने में कठिन FS-भ्रष्टाचार फ़ुट-गन था)।
• US और UK कीबोर्ड लेआउट LAYOUT के साथ प्रति-पेलोड चयन योग्य।
• चर, IF / ELSE, WHILE, HOLD / RELEASE, INJECT_MOD, RANDOM_* जनरेटर, STRING_BLOCK / STRINGLN_BLOCK, DEFINE।
• systemd एकीकरण ExecStop के साथ जो गैजेट को सफाई से टियर-डाउन करता है। कोई बचा हुआ configfs स्टेट नहीं, रीस्टार्ट बिना रीबूट के काम करता है।
• udev-प्रबंधित अनुमतियाँ /dev/hidg0 के लिए — कोई वर्ल्ड-राइटेबल डिवाइस नोड नहीं।
• 34-परीक्षण pytest सुइट Ducky पार्सर के लिए, बिना Pi जुड़े किसी भी होस्ट पर चलाने योग्य।
• प्रत्येक पेलोड रन के बाद ACT LED स्थिति संकेतक।

यह कैसे काम करता है

+----------------+        USB cable        +-------------+
|  Raspberry Pi  | ===================>>>  |  Host PC    |
|  Zero 2 W      |   (Pi emulates HID +    |  (target)   |
|  (this device) |    optional drive)      |             |
+----------------+                         +-------------+
        |
        |  /home/pi/pi-badusb/
        |
        +-- badusb.service ----> monitor_and_run.py
                                   |
                                   |  on `state == configured`:
                                   v
                                 run_payload.py
                                   |
                                   v
                                 /dev/hidg0  (USB HID gadget)

1. बूट पर, badusb.service systemd यूनिट gadget_setup.sh चलाता है, जो configfs/libcomposite का उपयोग करके एक HID कीबोर्ड फ़ंक्शन और (वैकल्पिक रूप से) /var/badusb/storage.img पर एक फ्लैट इमेज फ़ाइल द्वारा समर्थित मास-स्टोरेज LUN के साथ एक USB गैजेट कम्पोज़ करता है।
2. यूनिट फिर monitor_and_run.py चलाती है। यह /sys/class/udc/<udc>/state को पोल करती है और configured की प्रतीक्षा करती है — USB-विनिर्देश अवस्था जिसका अर्थ है कि एक होस्ट ने गैजेट को सफलतापूर्वक एन्यूमरेट कर लिया है। (हम /dev/hidg0 के अस्तित्व को संकेत के रूप में नहीं उपयोग करते: वह उसी क्षण सत्य होता है जब गैजेट बूट पर UDC से बाइंड होता है, चाहे कुछ भी प्लग्ड हो।)
3. जब होस्ट अटैच होता है, लिसनर run_payload.py निष्पादित करता है, जो payload.txt को पार्स करता है और HID रिपोर्टें /dev/hidg0 पर लिखता है।
4. जब पेलोड समाप्त होता है, लिसनर गैजेट को UDC से सक्रिय रूप से अनबाइंड करता है (Pi Zero 2 W सॉफ़्टवेयर के माध्यम से भौतिक डिस्कनेक्ट का पता नहीं लगा सकता — देखें), एक कूलडाउन के लिए सोता है, और रीबाइंड करता है। फिर डिवाइस अगले संक्रमण की प्रतीक्षा करता है।

हार्डवेयर

Pi Zero 2 W में दो micro-USB पोर्ट हैं:

• PWR IN — केवल पावर, dwc2 OTG ब्लॉक को USB डेटा लाइनें एक्सपोज़ नहीं करता।
• USB — OTG डेटा पोर्ट; यही वह जगह है जहाँ आप टारगेट में प्लग करते हैं।

सॉफ़्टवेयर

इंस्टॉल

रिपो को 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 (पुराना) का पता लगाता है।
• सुनिश्चित करता है कि config.txt में [all] ब्लॉक के अंतर्गत dtoverlay=dwc2,dr_mode=otg सक्रिय है। Raspberry Pi Imager डिफ़ॉल्ट इस पंक्ति को [cm5] फ़िल्टर के अंदर रखते हैं जो Pi Zero 2 W पर लागू नहीं होता; इंस्टॉलर एक सेंटिनल-चिह्नित ओवरराइड जोड़ता है ताकि दोबारा चलाने पर यह डुप्लिकेट न हो।
• सुनिश्चित करता है कि modules-load=dwc2 cmdline.txt में है।
• चेतावनी देता है यदि g_ether अभी भी cmdline.txt में मौजूद है (यह libcomposite से UDC चुरा लेता है और गैजेट मोड को तोड़ देता है)।
• systemd यूनिट को /etc/systemd/system/badusb.service पर इंस्टॉल करता है।
• udev नियम को /etc/udev/rules.d/99-badusb-hidg.rules पर इंस्टॉल करता है ताकि द्वारा ग्रुप-राइटेबल हो।

दैनिक संचालन

# Start / stop / restart
sudo systemctl start badusb
sudo systemctl stop badusb
sudo systemctl restart badusb              # safe to do while plugged in

# Watch live
journalctl -u badusb -f

# Disable autostart on boot
sudo systemctl disable badusb

# Tune timings (creates an override drop-in)
sudo systemctl edit badusb
# (paste an [Service] block with Environment="BADUSB_REARM_COOLDOWN_S=8" etc)
sudo systemctl restart badusb

सेवा sys-kernel-config.mount और एक UDC की उपस्थिति पर निर्भर करती है, इसलिए गैजेट वास्तव में तैयार होने से पहले यह पेलोड फायर नहीं कर सकती।

पेलोड संपादित करने के लिए रीस्टार्ट की आवश्यकता नहीं होती — payload.txt हर प्लग-इन पर ताज़ा पढ़ा जाता है।

पेलोड लिखना

payload.txt इंस्टॉल निर्देशिका में रहता है। पूर्ण कमांड संदर्भ payload_commands.md में है।

न्यूनतम उदाहरण

REM Open Run dialog and type a greeting via Notepad
LAYOUT US
GUI r
DELAY 1500
STRING notepad
ENTER
DELAY 2500
STRINGLN Hello from the Pi Zero 2 W

चर, शर्तें, लूप्स

VAR $USER="alice"
VAR $COUNT=0
WHILE $COUNT < 3
  STRINGLN Hello $USER (iteration $COUNT)
  VAR $COUNT = $COUNT + 1
END_WHILE

IF $USER == "alice"
  STRINGLN matched
ELSE
  STRINGLN missed
END_IF

VAR में गणितीय व्यंजक एक ast-वॉकर सुरक्षित मूल्यांकनकर्ता से गुजरते हैं — कोई नाम नहीं, कोई कॉल नहीं, कोई एट्रिब्यूट एक्सेस नहीं, केवल संख्यात्मक लिटरल और + - * / // % **।

मॉडिफ़ायर होल्ड करना

HOLD SHIFT
STRINGLN this line is in capitals
RELEASE SHIFT

मनमाने मॉडिफ़ायर संयोजन भेजना

REM Hold Ctrl+Shift (0x01 + 0x02) and tap A
INJECT_MOD 0x03
STRING a
REM Release all modifiers
INJECT_MOD 0x00

यादृच्छिकता

RANDOM_LETTER 12      # 12 random mixed-case letters
RANDOM_NUMBER 6       # 6 random digits
RANDOM_SPECIAL 4      # 4 random ASCII symbols

कीबोर्ड लेआउट

LAYOUT UK             # switch to UK ISO mappings for subsequent STRING/STRINGLN
STRING @ " # ~ £ \ |  # types correctly on a UK-locale host

keymaps/ में एक और फ़ाइल डालें (us.py और uk.py के साथ) और LAYOUT <name> निर्देश इसे importlib के माध्यम से उठा लेगा।

कॉन्फ़िगरेशन संदर्भ

मास-स्टोरेज गैजेट (gadget_setup.sh का शीर्ष)

इन्हें प्रति-इनवोकेशन ओवरराइड किया जा सकता है, gadget_setup.sh को मैन्युअल रूप से चलाते समय पर्यावरण में सेट करके, या वैश्विक रूप से यूनिट के Environment= निर्देशों के माध्यम से।

लिसनर ट्यूनेबल्स (monitor_and_run.py)

इस प्रकार ओवरराइड करें:

sudo systemctl edit badusb
# In the editor:
# [Service]
# Environment="BADUSB_REARM_COOLDOWN_S=8"
# Environment="BADUSB_MIN_INTER_FIRE_S=20"
sudo systemctl restart badusb

आर्किटेक्चर नोट्स

लिसनर UDC state का उपयोग क्यों करता है, /dev/hidg0 का नहीं

पिछला कार्यान्वयन /dev/hidg0 के अस्तित्व + लिखने-योग्यता को "host attached" संकेत के रूप में परीक्षण करता था। वह डिवाइस नोड उसी क्षण बन जाता है जब गैजेट बूट पर UDC से बाइंड होता है — किसी होस्ट द्वारा वास्तव में एन्यूमरेट किए जाने से बहुत पहले। इसलिए पेलोड पावर-अप पर तुरंत फायर हो जाते थे, चाहे Pi कहीं भी प्लग्ड हो।

विश्वसनीय संकेत /sys/class/udc/<udc>/state है, जो USB-विनिर्देश डिवाइस अवस्था रिपोर्ट करता है। केवल configured का अर्थ है कि होस्ट ने SetConfiguration(1) जारी किया है — डिवाइस अब HID रिपोर्ट भेजने के योग्य है।

हम प्रत्येक पेलोड के बाद फोर्स-अनबाइंड क्यों करते हैं

Pi Zero 2 W पर भौतिक डिस्कनेक्ट का पता लगाना सॉफ़्टवेयर से असंभव है: बोर्ड VBUS सेंस को SoC के dwc2 OTG ब्लॉक से नहीं जोड़ता। भौतिक अनप्लग के बाद:

• /sys/class/udc/<udc>/state configured पर बना रहता है।
• current_speed high-speed पर बना रहता है।
• dwc2 GOTGCTL रजिस्टर 0x000d0000 पर बना रहता है (BSesVld बिट सेट)।
• कोई udev इवेंट फायर नहीं होते।

इसलिए ऐसे संकेत की प्रतीक्षा करने के बजाय जो कभी नहीं आएगा, लिसनर सक्रिय रूप से डिस्कनेक्ट का कारण बनता है: प्रत्येक पेलोड के बाद, यह गैजेट की UDC configfs फ़ाइल में "" लिखता है (जिसे कर्नेल अनबाइंड के रूप में व्याख्या करता है), BADUSB_REARM_COOLDOWN_S के लिए सोता है, फिर रीबाइंड करने के लिए UDC नाम वापस लिखता है। अगला होस्ट प्लग-इन एक स्वच्छ configured संक्रमण उत्पन्न करता है जिसे लिसनर पहचान सकता है।

यदि ऑपरेटर पेलोड के बाद Pi को प्लग्ड छोड़ देता है, तो रीबाइंड होस्ट को गैजेट को फिर से एन्यूमरेट करने का कारण बनता है। रनअवे फायर लूप को रोकने के लिए, दो सुरक्षा उपाय सक्रिय होते हैं:

1. BADUSB_MIN_INTER_FIRE_S — यदि पिछले फायर के इस विंडो के भीतर कोई configured संक्रमण होता है, तो उसे दबाएँ और फिर से अनबाइंड करें। गैजेट पृष्ठभूमि में चुपचाप चक्र करता रहता है।
2. BADUSB_MAX_FIRES_PER_MINUTE — स्लाइडिंग-विंडो कठोर सीमा। सीमा से अधिक पर, लिसनर BADUSB_RATELIMIT_PAUSE_S के लिए रुकता है और एक चेतावनी लॉग करता है।

हम configfs पर rm -rf कभी उपयोग क्यों नहीं करते

configfs की कर्नेल-प्रबंधित एट्रिब्यूट फ़ाइलें (bcdUSB, idVendor, webusb/*, os_desc/*, …) को rm(2) द्वारा हटाया नहीं जा सकता — कर्नेल EPERM लौटाता है। वे केवल तब जारी होती हैं जब उनकी पैरेंट निर्देशिका rmdir की जाती है। gadget_setup.sh और teardown_gadget.sh दोनों configfs ट्री को विहित libcomposite क्रम में चलते हैं — केवल rmdir, एट्रिब्यूट फ़ाइलों पर कभी rm नहीं — और कर्नेल बाकी को स्वचालित रूप से साफ कर देता है।

Python हेल्पर्स os.write का उपयोग क्यों करते हैं, file.write का नहीं

open(path, "w").write("") के माध्यम से एक खाली स्ट्रिंग लिखना शून्य बाइट्स के साथ write(2) को नहीं बुलाता — CPython का TextIOWrapper इसे हटा देता है। configfs अनबाइंड के लिए (जिसे कर्नेल न्यूलाइन-स्ट्रिप के बाद शून्य-लंबाई वाली राइट से व्याख्या करता है), हम सीधे os.write(fd, b"\n") का उपयोग करते हैं ताकि syscall हमेशा कम से कम एक बाइट के साथ जारी हो।

परीक्षण

Ducky पार्सर के पास एक 34-परीक्षण pytest सुइट है जो MockHIDEngine (वास्तविक HID राइटर के लिए इन-मेमोरी ड्रॉप-इन) के विरुद्ध चलता है, इसलिए इसे किसी Pi और किसी USB हार्डवेयर की आवश्यकता नहीं होती।

cd /home/pi/pi-badusb
python3 -m pytest tests/

कवरेज में शामिल हैं:

• safe_eval_math अंकगणित स्वीकार करता है, नाम / कॉल / एट्रिब्यूट एक्सेस / स्ट्रिंग कॉन्स्टेंट अस्वीकार करता है।
• evaluate_condition संख्यात्मक और केस-संवेदी स्ट्रिंग तुलनाओं के लिए।
• VAR =, +=, -=, *=, /= के साथ।
• IF / ELSE / END_IF सही शाखा लेता है।
• WHILE / END_WHILE पुनरावृत्ति गणनाएँ < और <= के लिए।

समस्या निवारण

"प्लग इन करने पर पेलोड कभी फायर नहीं होता"

1. cat /sys/class/udc/*/state — होस्ट एन्यूमरेट करने पर configured तक पहुँचना चाहिए। यदि यह not attached पर बना रहता है, होस्ट संवाद नहीं कर रहा: एक अलग केबल आज़माएँ (कुछ केवल-चार्ज होती हैं) या एक अलग होस्ट पोर्ट।
2. lsmod | grep dwc2 — लोड होना चाहिए। यदि केवल dwc_otg है, तो dtoverlay=dwc2,dr_mode=otg लागू नहीं हो रहा; install.sh दोबारा चलाएँ और रीबूट करें।
3. प्लग इन करते समय journalctl -u badusb -f — होस्ट एन्यूमरेशन के ~2s के भीतर Host attached. Running payload. दिखाना चाहिए।

"पेलोड LED ब्लिंक करते हुए लूप में फायर होता है, अनप्लग्ड होने पर भी"

यह एक वास्तविक बग था जो अब ठीक कर दिया गया है। यदि ऐसा होता है, तो आप pre-os.write बिल्ड पर लौट गए हैं। सुनिश्चित करें कि monitor_and_run.py वर्तमान main ब्रांच से मेल खाता है (os.write(fd, payload) खोजें)।

"सेवा रीस्टार्ट नहीं होगी — Operation not permitted"

फिक्स से पहले gadget_setup.sh configfs पर rm -rf का उपयोग करता था। वर्तमान संस्करण teardown_gadget() का उपयोग करता है — यदि आप वे त्रुटियाँ देखते हैं, तो आपके पास एक पुरानी कॉपी है। Main से पुनः डिप्लॉय करें।

"/dev/hidg0 पर अनुमति अस्वीकृत"

udev नियम को लागू होने के लिए हॉट-प्लग की आवश्यकता होती है, या sudo udevadm trigger और एक पुनः-लॉगिन ताकि pi उपयोगकर्ता plugdev समूह उठा सके।

"इंस्टॉल के दौरान g_ether चेतावनी"

cmdline.txt से g_ether हटाएँ; यह libcomposite के बाइंड होने से पहले UDC पर दावा कर लेता है।

"होस्ट एक USB ड्राइव दिखाता है लेकिन यह उस आकार का नहीं है जिसकी मैंने अपेक्षा की थी"

मास-स्टोरेज आकार BACKING_SIZE_MB द्वारा सेट होता है और केवल पहले रन पर प्रभावी होता है जब बैकिंग इमेज बनाई जाती है। आकार बदलने के लिए:

sudo systemctl stop badusb
sudo rm /var/badusb/storage.img
sudo BACKING_SIZE_MB=256 /home/pi/pi-badusb/gadget_setup.sh
sudo systemctl start badusb

"मैं Pi को प्लग्ड छोड़ना चाहता हूँ बिना यह होस्ट को स्पैम करे"

इसी के लिए BADUSB_MIN_INTER_FIRE_S और BADUSB_MAX_FIRES_PER_MINUTE हैं। उन्हें systemctl edit badusb के माध्यम से अधिक सेट करें। डिफ़ॉल्ट के साथ, प्लग्ड छोड़ा गया Pi पहले मिनट के लिए हर ~15s में फिर से फायर करता है, फिर 60s के लिए रुकता है, फिर जारी रखता है।

रिपॉजिटरी संरचना

.
├── README.md                   This file
├── LICENSE                     MIT
├── install.sh                  Idempotent installer (firmware config, systemd, udev, plugdev)
├── gadget_setup.sh             Composes the USB gadget via configfs/libcomposite
├── teardown_gadget.sh          Canonical configfs teardown (wired as ExecStop)
├── reload_gadget.sh            Manual UDC unbind/rebind helper
├── autorun.sh                  Legacy manual-launch wrapper (systemd is preferred)
├── monitor_and_run.py          Listener: waits for host attach, runs payload, forces re-arm
├── run_payload.py              Ducky-Script-style interpreter
├── payload.txt                 Your payload — edit freely; re-read on each plug-in
├── payload_commands.md         Full command reference
├── etc/
│   ├── badusb.service          systemd unit
│   └── 99-badusb-hidg.rules    udev rule for /dev/hidg0 ownership
├── keymaps/
│   ├── __init__.py             Dynamic layout loader
│   ├── us.py                   US ANSI (default)
│   └── uk.py                   UK ISO
└── tests/
    ├── __init__.py
    ├── conftest.py             pytest path setup
    └── test_parser.py          34 parser tests against a MockHIDEngine

श्रेय

• मूल प्रोजेक्ट स्क्रिप्ट और प्रेरणा: Psycostea।
• USB गैजेट अनुसंधान: USB Rubber Ducky, Hak5, libcomposite दस्तावेज़ीकरण, dwc2 कर्नेल ड्राइवर।
• 2026-05 शुद्धता पास: होस्ट-अटैच डिटेक्शन को फिर से लिखा, मास स्टोरेज को सुरक्षित बनाया, कई पार्सर बग ठीक किए, एक कीमैप एब्स्ट्रैक्शन जोड़ा, स्टार्टअप को systemd में माइग्रेट किया, यूनिट-टेस्ट हार्नेस जोड़ा, और Pi Zero 2 W की भौतिक डिस्कनेक्ट का पता लगाने में हार्डवेयर-स्तरीय असमर्थता का समाधान किया।

लाइसेंस

MIT — देखें LICENSE।