Skip to content

Merging a bunch of forks, cleanup, bug fixes #94

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 18 commits into
base: master
Choose a base branch
from
Open

Merging a bunch of forks, cleanup, bug fixes #94

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
907899f
Ran dos2unix on all files, converting CRLF->LF
Brayyy Sep 1, 2018
7defea1
Cleanup: Formatted and removed ending whitespace from html/
Brayyy Sep 1, 2018
69a03b2
Cleanup: Formatted code files
Brayyy Sep 1, 2018
69aa4e3
Adjusted BAUD_RATE 57200->57600
Brayyy Sep 1, 2018
3d2a86d
Changed OK from 0x99->0x06 (acknowledge)
Brayyy Sep 1, 2018
70ab436
Send lines one at a time. Wait for acknowledge. Fixed a lot of buffer…
Brayyy Sep 1, 2018
10acc4a
Store live code as a file in order to properly buffer
Brayyy Sep 1, 2018
0d64b5e
Added payload verification wrapper bytes
Brayyy Sep 1, 2018
17b2d57
Fixed REPLAY
Brayyy Sep 2, 2018
590c4d2
Added comments to commands
Brayyy Sep 2, 2018
714d3d0
Added command DEFAULT_DELAY, keys CONTROL, WINDOWS, ESCAPE, PAUSE, BR…
Brayyy Sep 2, 2018
f980f50
Split line into command and optional arguments early to reduce repeat…
Brayyy Sep 2, 2018
65c146b
Added mouse support
Brayyy Sep 2, 2018
984e901
Added commands ASCII and STRINGEN
Brayyy Sep 2, 2018
b631758
Updated README, adding credit
Brayyy Sep 2, 2018
c0f5cf6
Added a prefix to both Arduino and ESP debugging to tell them apart
Brayyy Sep 3, 2018
3d79114
Fixed issues with larger scripts and scripts with LF encoding
Brayyy Sep 3, 2018
348460f
Readme cleanup
Brayyy Sep 5, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
120 changes: 72 additions & 48 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@
Upload, save and run keystroke injections remotely with an ESP8266 + ATmega32u4

![image of my DIY Wi-Fi Duck](https://raw.githubusercontent.com/spacehuhn/wifi_ducky/master/images/my_wifi_duck.jpg)
**Support me and my projects on [Patreon!](https://www.patreon.com/spacehuhn)**
[<img width="200" alt="Support me on Patreon" src="https://raw.githubusercontent.com/spacehuhn/wifi_ducky/master/images/patreon.png">](https://www.patreon.com/spacehuhn)

**Support me and my projects on [Patreon!](https://www.patreon.com/spacehuhn)**
[<img width="200" alt="Support me on Patreon" src="https://raw.githubusercontent.com/spacehuhn/wifi_ducky/master/images/patreon.png">](https://www.patreon.com/spacehuhn)


## Contents
Expand All @@ -14,7 +14,7 @@ Upload, save and run keystroke injections remotely with an ESP8266 + ATmega32u4
- [The benefits of adding Wi-Fi](#the-benefits-of-adding-wi-fi)
- [Disclaimer](#disclaimer)
- [Installation](#installation)
- [Preparation](#preparation)
- [Preparation](#preparation)
- [ESP8266](#esp8266)
- [Arduino ATmega32u4](#arduino-atmega32u4)
- [Wire everything up](#wire-everything-up)
Expand All @@ -28,78 +28,78 @@ Upload, save and run keystroke injections remotely with an ESP8266 + ATmega32u4

### What it is

It's a Wi-Fi controlled BadUSB device to remotely execute Ducky Scripts.
It's a Wi-Fi controlled BadUSB device to remotely execute Ducky Scripts.

Using a USB device which act as a keyboard to inject keystrokes is well known these days.
Using a USB device which act as a keyboard to inject keystrokes is well known these days.
The [USB Rubber Ducky](https://hakshop.com/products/usb-rubber-ducky-deluxe) by [Hak5](https://www.hak5.org/) is THE hacker gadget for this kind of attack. It introduced a simple script language called *Ducky Script*, which this project uses too.

### How it works

The ESP8266 is a popular Wi-Fi chip used in a lot of projects. Because it's cheap, small and has its own file system ([SPIFFS](http://esp8266.github.io/Arduino/versions/2.0.0/doc/filesystem.html)), it's perfect for enabling an easy remote connection and holding Ducky Script payloads.

Although the ESP8266 is awesome, it doesn't have native USB, which means it can't act as a keyboard :(
([cnlohr](https://github.com/cnlohr) made a cool project on this and added a USB stack himself: https://github.com/cnlohr/espusb. The problem with that is, that it isn't compatible with the current SDK version, also I wanted to use Arduino to make it more user friendly.)
Although the ESP8266 is awesome, it doesn't have native USB, which means it can't act as a keyboard :(
([cnlohr](https://github.com/cnlohr) made a cool project on this and added a USB stack himself: https://github.com/cnlohr/espusb. The problem with that is, that it isn't compatible with the current SDK version, also I wanted to use Arduino to make it more user friendly.)

Here comes the ATmega32u4 into play!
It can act as keyboard and thanks to [Seytonic](http://youtube.com/seytonic) run Ducky Script ([link](https://github.com/Seytonic/Duckduino-microSD)).
Here comes the ATmega32u4 into play!
It can act as keyboard and thanks to [Seytonic](http://youtube.com/seytonic) run Ducky Script ([link](https://github.com/Seytonic/Duckduino-microSD)).
So what I did is connecting the ATmega to the ESP8266 via serial.

The ESP will open up a Wi-Fi access point and host a web interface from what you can upload and manage your scripts.
When you hit run, it will send the script to the ATmega, which then will execute it on the target machine.
The ESP will open up a Wi-Fi access point and host a web interface from what you can upload and manage your scripts.
When you hit run, it will send the script to the ATmega, which then will execute it on the target machine.

### The benefits of adding Wi-Fi

**But why add Wi-Fi** ...you might ask.
With Wi-Fi you can upload and run your Ducky Script payloads remotely.
You just need to plug the device in, connect to its Wi-Fi network and you have full control over the target machine.
**But why add Wi-Fi** ...you might ask.
With Wi-Fi you can upload and run your Ducky Script payloads remotely.
You just need to plug the device in, connect to its Wi-Fi network and you have full control over the target machine.

It also gives you one big advantage over other BadUSBs, you can test your scripts live! You don't need to copy them onto a micro-sd card or compile them. You can run them live over the web interface, which makes its super easy for testing and improving your scripts.

It also adds a lot of possibilities for different attacks.
It also adds a lot of possibilities for different attacks.
You could make the target download executables from the Wi-Fi chip, instead of the internet.
Or execute different attacks and send the results back to the Chip. Or open up a reverse shell on the ESP8266s Wi-Fi.
Or execute different attacks and send the results back to the Chip. Or open up a reverse shell on the ESP8266s Wi-Fi.
And so on... there are so much possibilities!

## Disclaimer

Use it only for testing purposes on your own devices!
I don't take any responsibility for what you do with this project.
Use it only for testing purposes on your own devices!
I don't take any responsibility for what you do with this project.

## Installation

### Short version:
Upload the `arduino_wifi_duck` sketch to your ATmega32u4 and upload the `esp8266_wifi_duck` sketch to your ESP8266.
Upload the `arduino_wifi_duck` sketch to your ATmega32u4 and upload the `esp8266_wifi_duck` sketch to your ESP8266.
Then connect the serial pins (RX and TX (Arduino) to TX and RX (ESP8266)) and GND.

---

### Preparation

What you will need:
- **ESP8266 Wi-Fi chip**
I recommend using an ESP-12. It's widely used, cheap, tiny and has 4MB of flash memory.
However if you're a beginner you should probably start with a developer board like the NodeMCU or a Wemos d1 mini.
- **ATmega32u4**
The Arduino Micro and Arduino Leonardo use an ATmega32u4 for example. You could also get a Arduino Pro Micro or other cheap Arduino clones which use the ATmega32u4. I will use an [ATmega32u4 CJMCU Beetle](https://www.google.de/search?q=Cjmcu-beetle&tbm=isch).
- **(a 3.3V regulator)**
I put that in brackets because you will only need this if your ATMega32u4 board doesn't provide 3.3V. The ESP8266 only works with 3.3V, so depending on your board you may need a regulator to get 3.3V out of the 5V.
- **Some skill, knowledge and common sense on this topic**
That's probably the most important part here. **This project is not noob friendly!** If you are a beginner, please start with other projects and get some knowledge about how Arduino and its code works, how to handle errors and how to work with the ESP8266. **I can't cover every little detail here. Please respect that.** Depending on your hardware choices you may need to add or change a bit of the Arduino code.

So make your hardware choices!
- **ESP8266 Wi-Fi chip**
I recommend using an ESP-12. It's widely used, cheap, tiny and has 4MB of flash memory.
However if you're a beginner you should probably start with a developer board like the NodeMCU or a Wemos d1 mini.
- **ATmega32u4**
The Arduino Micro and Arduino Leonardo use an ATmega32u4 for example. You could also get a Arduino Pro Micro or other cheap Arduino clones which use the ATmega32u4. I will use an [ATmega32u4 CJMCU Beetle](https://www.google.de/search?q=Cjmcu-beetle&tbm=isch).
- **(a 3.3V regulator)**
I put that in brackets because you will only need this if your ATMega32u4 board doesn't provide 3.3V. The ESP8266 only works with 3.3V, so depending on your board you may need a regulator to get 3.3V out of the 5V.
- **Some skill, knowledge and common sense on this topic**
That's probably the most important part here. **This project is not noob friendly!** If you are a beginner, please start with other projects and get some knowledge about how Arduino and its code works, how to handle errors and how to work with the ESP8266. **I can't cover every little detail here. Please respect that.** Depending on your hardware choices you may need to add or change a bit of the Arduino code.

So make your hardware choices!
Also I wouldn't go straight forward and solder everything together. Test it beforehand, otherwise debugging can be hard!

**For an easy start, better debugging, further development or if you just wanna test this project, I recommend using a Nodemcu + an Arduino Leonardo:**
![nodemcu with a leonardo as wifi duck](https://raw.githubusercontent.com/spacehuhn/wifi_ducky/master/images/leonardo_duck_1.jpg)
This is easy to setup, you don't need any soldering skills and you can still use both the NodeMCU and the Arduino for other cool projects.


But now let's get started!
But now let's get started!

### ESP8266

First you will need to flash your ESP8266.
You can either flash the bin file directly or compile it yourself using Arduino.
First you will need to flash your ESP8266.
You can either flash the bin file directly or compile it yourself using Arduino.

**Note:** You will only need to flash it once, every new update can then be done over the possibilities.

Expand All @@ -108,11 +108,11 @@ If don't use a USB dev board and don't know how to flash your plain ESP8266, I r
You could also use your Arduino to flash it: https://gist.github.com/spacehuhn/b2b7d897550bc07b26da8464fa7f4b36
(The connections are the same for this project, the only difference is that you need to set GPIO-0 to LOW to enabling a firmware update).

**Flash the .bin File**
Go to [releases](https://github.com/spacehuhn/wifi_ducky/releases) and download the right bin file for your ESP8266.
**Flash the .bin File**
Go to [releases](https://github.com/spacehuhn/wifi_ducky/releases) and download the right bin file for your ESP8266.
You can flash it with the [esptool](https://github.com/espressif/esptool) or the [nodemcu-flasher](https://github.com/nodemcu/nodemcu-flasher).

**Upload using Arduino**
**Upload using Arduino**
Open the `esp8266_wifi_duck` sketch with [Arduino](https://www.arduino.cc/en/Main/Software).
You need to install the following libraries:
- [the latest ESP8266 SDK](https://github.com/esp8266/Arduino)
Expand All @@ -123,11 +123,11 @@ Then compile and upload it to your ESP8266 (check if your settings are right).

### Arduino ATmega32u4

Open the `arduino_wifi_duck` sketch in Arduino and upload it to your Arduino.
Open the `arduino_wifi_duck` sketch in Arduino and upload it to your Arduino.

### Wire everything up

Ok so now you need to connect the ESP8266 with the Arduino.
Ok so now you need to connect the ESP8266 with the Arduino.
Connect these pins:

| Arduino | ESP82666 |
Expand All @@ -137,8 +137,8 @@ Connect these pins:
| GND | GND |
| VCC (3.3V) | VCC (3.3V) |

Like I mentioned before, you'll need a 3.3V regulator if your Arduino only provides 5V.
**Don't connect the ESP8266 to 5V!**
Like I mentioned before, you'll need a 3.3V regulator if your Arduino only provides 5V.
**Don't connect the ESP8266 to 5V!**

If you use a plain ESP-12 like me, you also have to set the enable pin and to HIGH and GPIO15 to LOW:

Expand All @@ -150,14 +150,14 @@ If you use a plain ESP-12 like me, you also have to set the enable pin and to HI

### Update ESP8266 over the Web interface

Once you flashed the software, you can update it over the web interface.
Go to `192.168.4.1/update` and upload the new .bin file.
(In Arduino go to `Sketch`->`Export compiled Binary` to compile your own .bin file)
Once you flashed the software, you can update it over the web interface.
Go to `192.168.4.1/update` and upload the new .bin file.
(In Arduino go to `Sketch`->`Export compiled Binary` to compile your own .bin file)

## How to use it

Plug your Wi-Fi Ducky in and connect to the new Wi-Fi network `WiFi Duck`. The password is `quackquack`.
Open your browser and go to `192.168.4.1`.
Plug your Wi-Fi Ducky in and connect to the new Wi-Fi network `WiFi Duck`. The password is `quackquack`.
Open your browser and go to `192.168.4.1`.

![screenshot of the webinterface](https://raw.githubusercontent.com/spacehuhn/wifi_ducky/master/images/wifiduck_screenshot_1.jpg)

Expand All @@ -175,9 +175,9 @@ Happy hacking :)
My wishlist:
- add support for Digispark (ATtiny85) as alternative for the ATmega32u4 Arduino
- change settings within the web interface (Wi-Fi SSID, password etc.)
- full support of all Ducky Script commands (DEFAULTDELAY is missing)
- ~~full support of all Ducky Script commands (DEFAULTDELAY is missing)~~
- auto execute scripts
- add mouse
- ~~add mouse~~
- control over the internet

## License
Expand All @@ -196,3 +196,27 @@ Seytonic: http://youtube.com/seytonic
Arduino Ducky Script interpreter: https://github.com/Seytonic/Duckduino-microSD

Cnlohrs ESP8266 USB Software Driver: https://github.com/cnlohr/espusb

## Additional credit
Some of the features/changes applied were sourced from various other forks of the project. Cherry-picking proved complicated, so I am giving credit here.

- @gloglas - https://github.com/gloglas/WifiDuckV2
- Did a rewrite/hard fork of the spacehuhn/wifi_ducky project
- Added mouse control
- Added ASCII characters
- Added OS Detection (unused here)
- ...and more.
- @mvojacek - https://github.com/mvojacek/wifi_ducky
- Ported changes made by @gloglas back into a fork of the original project
- @BlueArduino20 - https://github.com/BlueArduino20/super_wifi_ducky
- Partially fixed the payload corruption issue
- Added "STRING." command (here, renamed to STRINGER)
- Added various missing key string/ids, new HID keys
- @Brayyy - https://github.com/Brayyy/wifi_ducky
- Brought various forks together
- Fixed payload corruption issue, added payload verification bytes
- Fixed baud issues
- Improved payload speed
- Standardized project line-endings, indention, and formatting
- Fixed REPLAY command
- Other minor code refactoring
Loading