Skip to content

Latest commit

 

History

History
215 lines (175 loc) · 11.5 KB

README.md

File metadata and controls

215 lines (175 loc) · 11.5 KB
Raw

About

This open-source project aims to provide a user-friendly tool to learn about keystroke injection attacks and 'BadUSBs'.

By emulating a USB keyboard, tools like this can gain full access to any computer with a USB port in a matter of seconds!
This is made possible by the fact that keyboards are trusted by computers. You can have full control over a computer with just a keyboard.
A BadUSB pretends to be a keyboard to the computer to send keystrokes. But unlike a human, it can type hundreds of characters per second. By using a simple scripting language, it's easy to make BadUSBs type whatever you want.

With the WiFi Duck, you can simply connect via WiFi to manage all scripts from within a web interface. This means that, unlike other BadUSBs, you don't need to install an app, log in, compile or copy scripts to an SD card.

Flash Software

  1. Download and install the Arduino IDE.
  2. Start the Arduino IDE, go to File > Preferences.
  3. At Additional Board Manager ULRs enter https://raw.githubusercontent.com/SpacehuhnTech/arduino/main/package_spacehuhn_index.json. You can add multiple URLs, separating them with commas.
  4. Go to Tools > Board > Board Manager, search for wifi duck and install WiFi Duck AVR Boards and WiFi Duck ESP8266 Boards.
  5. Download and extract this repository or git clone it.

Flash ESP8266

  1. Open esp_duck/esp_duck.ino with the Arduino IDE.
  2. Under Tools > Board in the WiFi Duck ESP8266 section, select your ESP8266
  3. Go to Tools > Disable Debug and choose I2C as connection
  4. In conf.h change the values to this

image

  1. Then under Sketch > export and compile bin (I'll include a precompiled bin in the future, so that you could skp this in the future)
  2. after that copy the path from your exported bin
  3. Download this tool https://github.com/nodemcu/nodemcu-flasher/blob/master/Win64/Release/ESP8266Flasher.exe
  4. Then open it and under settings paste your copied path in the fist entry
  5. then change your uploadrate to 9200
  6. reconnect your CJCMU3212 and select Arduino Leonardo in arduino
  7. Flash this https://github.com/robertio/DM-3212-Badusb/blob/master/step1.ino
  8. after that reconnect your CJMCU with the two metal bin on front connected with a cable etc
  9. Now you should flash your previously exported bin with the tool from step 7 (kepp the metal pins connected till end)
  10. remove the cable and reconnect your CJMCU3212
  11. Now your ESSP8266 is reeady now we have to flash the atmega

Flash Atmega32u4

  1. Open atmegaduck/atmega_duck.ino with the Arduino IDE.
  2. Connect your CJMCU3212
  3. Under Tools > Board select the normal arduino leonardo (not the wifi duck one)
  4. Press Upload.
  5. Finish

Soldering

  1. Grab a soldering Iron
  2. look at the table below
  3. solder the Esp8266 pins with a wire to the atmega pins
ESP8266 Atmega32u4
D1 alias GPIO 5 3 alias SCL
D2 alias GPIO 4 2 alias SDA
GND GND

How to Debug

To properly debug, you need to have both the Atmega32u4 and the ESP8266 connected via USB to your computer.

That can be tricky when you only have a all in one board, so it might be useful you built one yourself. You don't need to solder it, for example you can use an Arduino Leonardo and a NodeMCU and connect them with jumper cables.

Now open 2 instances of Arduino (so they run as separate processes!), select the COM port and open the serial monitor for each device. You might need to reset the Atmega32u4 to see serial output. If that causes problems with the i2c connection, try to reset the ESP8266 too.

Development

Edit Web Files

If you would like to modify the web interface, you can!
The web/ folder contains all .html, .css, .js files.
You can edit and test them locally as long as you're connected to the WiFi Duck network thanks to the websocket connection handled by JavaScript in the background.

To get the new files onto the ESP8266, run python3 webconverter.py in the repository folder.
It gzips all files inside web/, converts them into a hex array and saves it in esp_duck/webfiles.h.
Now you just need to flash the ESP8266 again.

Translate Keyboard Layout

Currently supported keyboard layouts:

All standard keys are defined in usb_hid_keys.h.
To translate a keyboard layout, you have to match each character on your keyboard to the one(s) of a US keyboard.
This stuff is hard to explain in writing and requires a lot of manual work and testing.

  1. Copy one of the existing layouts files, like locale_us.h.
    Preferably one that is close to your keyboard layout, it will save you time!
  2. Add #include "locale_xx.h" to the end of the locales.h file.
  3. Rename the file and its variables to your language code. For example:
    locale_xx.h -> locale_de.h,
    ascii_xx -> ascii_de,
    locale_xx -> locale_de,
    utf8_xx -> utf8_de.
    combinations_xx -> combinations_de,
  4. Modify the ASCII array.
    The ASCII array has a fixed size. Each row describes a key. First a modifier key like KEY_MOD_LSHIFT, then a character key. Some ASCII characters can't be typed or don't require a modifier, that's where you must place KEY_NONE. Check usb_hid_keys.h for the available keys.
    If multiple modifiers are required, you must use a bitwise OR to connect them: KEY_MOD_RALT | KEY_MOD_LSHIFT.
    For example, in locale_de.h Z is saved as KEY_MOD_LSHIFT, KEY_Y.
    This is because German keyboards use QWERTZ instead of the QWERTY layout and since the letter is uppercase, shift must be pressed as well.
    Thankfully you don't have to trial and error everything, the Hak5 Community translated a lot of layouts already here. It's just written in a different syntax. For example, ASCII_20 (20 in hexadecimal) is the 32th character in our ascii array.
  5. [deprecated] Modify or create the extended ASCII array.
    The extended ASCII array doesn't have a fixed size and is only as long as you make it. First the character code. For example, ä has the index 132, or 84 in hex. It doesn't use a modifier and sits where the apostrophe key is on a US keyboard: 0x84, KEY_NONE, KEY_APOSTROPHE, // ä.
  6. Modify or create the UTF-8 array.
    The UTF-8 array is variable in length, too.
    The first 4 bytes are the character code.
    For example, Ä has the hex code c384 or 0xc3 0x84. The other 2 bytes are not used so we set them to 0. Because the letter is uppercase, we need to press the shift key and like before, the letter is typed by pressing the same key as the apostrophe key of a US keyboard: 0xc3, 0x84, 0x00, 0x00, KEY_MOD_LSHIFT, KEY_APOSTROPHE, // Ä.
  7. Edit the hid_locale_t structure.
    If you renamed all variables accordingly, there's nothing left to do.
  8. Go to duckparser.cpp at // LOCALE (-> change keyboard layout) you can see a bunch of else if statements. You need to copy one for your layout.

Before adding GB layout:

if (compare(w->str, w->len, "US", CASE_SENSETIVE)) {
    keyboard::setLocale(&locale_us);
} else if (compare(w->str, w->len, "DE", CASE_SENSETIVE)) {
    keyboard::setLocale(&locale_de);
}

After adding GB layout:

if (compare(w->str, w->len, "US", CASE_SENSETIVE)) {
    keyboard::setLocale(&locale_us);
} else if (compare(w->str, w->len, "DE", CASE_SENSETIVE)) {
    keyboard::setLocale(&locale_de);
} else if (compare(w->str, w->len, "GB", CASE_SENSETIVE)) {
   keyboard::setLocale(&locale_gb);
}
  1. Test your layout with a Ducky Script that contains all characters of your keyboard. For example:
LOCALE DE
STRING !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_abcdefghijklmnopqrstuvwxyz{|}~²³äöüÄÖÜ߀°§`
ENTER
  1. Add a link to your layout to README, to web/index.html and please feel free to improve this tutorial to help future translators!
  2. Create a Pull Request

Disclaimer

This tool is intended to be used for testing, training, and educational purposes only.
Never use it to do harm or create damage!

The continuation of this project counts on you!

License

This software is licensed under the MIT License. See the license file for details.

Thanks and Credits to

https://github.com/SpacehuhnTech > For the Project https://github.com/todely > For the soldering solution https://github.com/robertio > For updating the ESP8266 Flashmode script https://github.com/nodemcu/nodemcu-flasher/blob/master/Win64/Release/ESP8266Flasher.exe > ESP8266 Flasher

Credits

Software libraries used in this project: