mirrors
/
esp8266_deauther
mirror of https://github.com/SpacehuhnTech/esp8266_deauther.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity

Rewritten Readme

This commit is contained in:
Stefan Kremser 2017-07-23 15:00:42 +02:00
parent 5abaefa5c2
commit 202a4849cb
1 changed files with 105 additions and 132 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

237
README.md
View File

@ -1,135 +1,113 @@
# ESP8266 Deauther
Deauthentication attack and other 'hacks' using an ESP8266.
Deauthentication attack and other exploits using an ESP8266!
![esp8266 deauther with a smartphone](https://raw.githubusercontent.com/spacehuhn/esp8266_deauther/master/screenshots/smartphone_esp_1.jpg)
<img width="100%" alt="esp8266 deauther with smartphone" src="https://raw.githubusercontent.com/spacehuhn/esp8266_deauther/master/smartphone_and_deauther.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/esp8266_deauther/master/screenshots/patreon.png">](https://www.patreon.com/spacehuhn)
I disabled the issue section because of the flood of invalid questions. All the information you need is described here. Don't open issues about this project on my other projects or you will be blocked immediately!
**New official [Supported Devices](#supported-devices) available!**
[<img height="350" alt="WiFi Deauther Board" src="https://raw.githubusercontent.com/spacehuhn/esp8266_deauther/master/screenshots/wifi_deauther_board.jpg">](#supported-devices)
<p align="center">
🐦 <a href="https://twitter.com/spacehuhn">Twitter</a>
| 📺 <a href="https://www.youtube.com/channel/UCFmjA6dnjv-phqrFACyI8tw">YouTube</a>
| 🌍 <a href="https://spacehuhn.de">spacehuhn.de</a><br/>
<br />
<b>Support me and my projects by purchasing one of the <a href="https://github.com/spacehuhn/esp8266_deauther/#supported-devices">official deauther boards</a>.<br/>Or become my patron on <a href="https://patreon.com/spacehuhn" target="_blank">patreon.com/spacehuhn</a>.</b>
</p>
## Contents
- [Introduction](#introduction)
- [What it is](#what-it-is)
- [How it works](#how-it-works)
- [What an ESP8266 is](#what-an-esp8266-is)
- [How to protect against it](#how-to-protect-against-it)
- [What it is and how it works](#what-it-is-and-how-it-works)
- [How to protect yourself against it](#how-to-protect-yourself-against-it)
- [Disclaimer](#disclaimer)
- [Supported Devices](#supported-devices)
- [Videos](#videos)
- [Installation](#installation)
- [Uploading the bin files](#uploading-the-bin-files)
- [Compiling the source with Arduino](#compiling-the-source-with-arduino)
- [Adding OLED display](#adding-oled-display)
- [Adding an OLED display](#adding-an-oled-display)
- [How to use it](#how-to-use-it)
- [How to reset it](#how-to-reset-it)
- [Alternative Designs](#alternative-designs)
- [FAQ](#faq)
- [FAQ](https://github.com/spacehuhn/esp8266_deauther/wiki/FAQ)
- [License](#license)
- [Sources and additional links](#sources-and-additional-links)
- [Contribute Code](#contribute-code)
- [Custom Design Versions](#custom-design-versions)
- [Videos](#videos)
- [Sources](#sources)
## Introduction ##
## Introduction
### What it is
### What it is and how it works
Basically it’s a device which performs a [deauth attack](https://en.wikipedia.org/wiki/Wi-Fi_deauthentication_attack).
You select the clients you want to disconnect from their network and start the attack. As long as the attack is running, the
selected devices are unable to connect to their network.
Other attacks also have been implemented, such as beacon or probe request flooding.
This software allows you to perform a [deauth attack](https://en.wikipedia.org/wiki/Wi-Fi_deauthentication_attack) with an ESP8266 against selected networks.
The [ESP8266](https://en.wikipedia.org/wiki/ESP8266) is a cheap and easy to use Wi-Fi SoC (System-on-a-Chip), programmable with the [Arduino IDE](https://www.arduino.cc/en/Main/Software).
With this software flashed onto it, you can select a target network and start different attacks.
### How it works
The deauth attack will, if the connection is vulnerable, disconnect the devices from the network. Because the attack is running constantly, the devices will be disconnected again and again. Depending on the network, that can either block a connection or slow it down.
The 802.11 Wi-Fi protocol contains a so called [deauthentication frame](https://mrncciew.com/2014/10/11/802-11-mgmt-deauth-disassociation-frames/). It is used to disconnect clients safely from a wireless
network.
Other attacks also have been implemented, such as beacon and probe request flooding.
Because these management packets are unencrypted, you just need the mac address of the Wi-Fi router and of the client device which you want to disconnect from the network. You don’t need to be in the network or know the password, it’s enough to be in its range.
The deauth attack works by exploiting an old and known vulnerability in the 802.11 Wi-Fi protocol.
Because these [deauthentication frames](https://mrncciew.com/2014/10/11/802-11-mgmt-deauth-disassociation-frames/), usally used to close a Wi-Fi connection safely, are are unencrypted, it's very easy to spoof them. You only need the mac address of the access point, which you can sniff easily.
If you don't want to attack all connected devices, you can also scan for connections and attack them specifictly.
### What an ESP8266 is
### How to protect yourself against it
The [ESP8266](https://en.wikipedia.org/wiki/ESP8266) is a cheap microcontroller with built-in Wi-Fi. It contains a powerful 160 MHz processor and it can be programmed using [Arduino](https://www.arduino.cc/en/Main/Software).
With [802.11w-2009](https://en.wikipedia.org/wiki/IEEE_802.11w-2009) the Wi-Fi protocol got encrypt management (and deauthentication) frames. This makes spoofing these packets way harder and the attack, in this form, ineffective.
So make sure your router is up to date and has management frame protection enabled. Your client device (e.g your phone, notebook etc.) needs to support that too. Both ends of the connection need to use it!
You can buy these chips for under $2 from China!
The problem with that is, most routers use unencrypted managment frames by default, don't provide any option to change that and don't provide any information about this issue.
I tested several networks and couldn't find one that wasn't vulnerable!
### How to protect against it
With [802.11w-2009](https://en.wikipedia.org/wiki/IEEE_802.11w-2009) Wi-Fi got an update to encrypt management frames.
So make sure your router is up to date and has management frame protection enabled. But note that your client device needs to
support it too, both ends need to have it enabled!
The only problem is that most devices don’t use it. I tested it with different Wi-Fi networks and devices, it worked every time! It seems that even newer devices which support frame protection don’t use it by default.
I made a [Deauth Detector](https://github.com/spacehuhn/DeauthDetector) using the same chip to indicate if such an attack is running against a nearby network. It doesn't protect you against it, but it can help you figure out if and when an attack is running.
I made a [Deauth Detector](https://github.com/spacehuhn/DeauthDetector) using the same ESP8266 to indicate high amounts of deauth frames. It can't protect you, but it can help you figure out if and when an attack is going on.
## Disclaimer
**This project is a proof of concept for testing and education only.**
Neither the ESP8266, nor the SDK was meant and build for such purposes.
**This project is a proof of concept for testing and educational purposes.**
Neither the ESP8266, nor its SDK was meant or build for such purposes.
Bugs can occur!
Use it only for testing purposes on your own devices!
Use it only against your own networks and devices!
I don't take any responsibility for what you do with this program.
Please check the legal regulations in your country before using it.
**It is not a frequency jammer as claimed falsely by many people.** Its attack, how it works and how to protect against it is described above. It uses valid Wi-Fi frames described in the official 802.11 standard and doesn't block or disrupt any other communications or frequencies.
Referring to this project as "jammer" is prohibited! Name the project by its correct name.
**It is not a frequency jammer as claimed falsely by many people.** Its attack, how it works and how to protect against it is described above. It uses valid Wi-Fi frames described in the official 802.11 standard and doesn't block or disrupt any frequencies.
My intention with this project is to draw more attention on this issue.
This attack shows how vulnerable the 802.11 Wi-Fi standard is and that it has to be fixed.
**A solution is already there, why don't we use it?**
Please don't refer to this project as "jammer", that totaly underminds the real purpose of this project!
## Supported Devices
You can flash the code to every ESP8266. Depending on the module or development board, there might be
differences in the stability and performance.
**You can flash this software yourself onto any ESP8266**, but if you would like to support me, you can get one of these cool boards that are made especially for this project and come with everything preinstalled!
**Officially supported devices:**
- WiFi Deauther (Pocket WiFi)
- [AliExpress](https://goo.gl/JAXhTg)
- [tindie](https://goo.gl/hv2MTj)
- WiFi Deauther OLED (Pocket WiFi)
- [AliExpress](https://goo.gl/P30vNz)
- [tindie](https://goo.gl/XsCoJ6)
## Videos
[![Cheap Wi-Fi 'Jammer' Device | NodeMCU](https://img.youtube.com/vi/oQQhBdCQOTM/0.jpg)](https://www.youtube.com/watch?v=oQQhBdCQOTM)
[![Wifi 'Jammer' Device V1.1 | Setup Tutorial](https://img.youtube.com/vi/r5aoV5AolNo/0.jpg)](https://www.youtube.com/watch?v=r5aoV5AolNo)
[![WiFi Tutorial "Deauthing Made Simple"](https://img.youtube.com/vi/SswI-J-M2SE/0.jpg)](https://www.youtube.com/watch?v=SswI-J-M2SE)
[![Seguridad Inalámbrica | Explicación de Wifi Deauther en Español](https://img.youtube.com/vi/YYsSDXRgD10/0.jpg)](https://www.youtube.com/watch?v=YYsSDXRgD10)
## Installation
The only things you will need are a computer and an ESP8266 board.
I recommend you to buy a USB breakout/developer board, because they have 4Mb flash and are very simple to use.
It doesn’t matter which board you use, as long as it has an ESP8266 on it.
You have 2 choices here. Uploading the bin files is easier but not as good for debugging.
**YOU ONLY NEED TO DO ONE OF THE INSTALLATION METHODS!**
You have 2 choices here. Uploading the .bin files is easier, but not as good for debugging.
**YOU ONLY NEED TO DO ONE OF THE INSTALLATION METHODS!**
### Uploading the bin files
**Note:** the 512kb version won't have the full MAC vendor list.
The NodeMCU and every other board use the ESP-12 which has 4mb flash on it.
**0** Download the current release from [releases](https://github.com/spacehuhn/esp8266_deauther/releases)
**0** Download the current release from [here](https://github.com/spacehuhn/esp8266_deauther/releases)
Always use the 1mb version, unless you're sure that your ESP8266 only has 512kb flash memory.
**Note:** the 512kb version won't have the full mac vendors list.
**1** Upload using the ESP8266 flash tool of your choice. I recommend using the [nodemcu-flasher](https://github.com/nodemcu/nodemcu-flasher). If this doesn't work you can also use the official [esptool](https://github.com/espressif/esptool) from espressif.
**1** Upload using the ESP8266 flash tool of your choice:
- [nodemcu-flasher](https://github.com/nodemcu/nodemcu-flasher) [Windows only]
- [esptool-gui](https://github.com/Rodmg/esptool-gui) [Windows, MacOS]
- [esptool](https://github.com/espressif/esptool) [Windows, MacOS, Linux]
**That's all! :)**
**That's all!**
Make sure you select the right com-port, the right upload size of your ESP8266 and the right bin file.
Make sure your settings are correct for your board. Most boards come with 4mb flash and sometimes you have to hold the flash button down while plugging it in and hold it until the flashing process started.
If flashing the bin files with a flash tool is not working, try flashing the esp8266 with the Arduino IDE as shown below.
Also make sure you select the right com-port, the right upload size (mostly 4mb) and the correct .bin file.
If it's not working, you can try using the Arduino as descriped below.
### Compiling the source with Arduino
@ -161,14 +139,16 @@ If flashing the bin files with a flash tool is not working, try flashing the esp
**11** Scroll down and before `#endif` add following lines:
`typedef void (*freedom_outside_cb_t)(uint8 status);`
`int wifi_register_send_pkt_freedom_cb(freedom_outside_cb_t cb);`
`void wifi_unregister_send_pkt_freedom_cb(void);`
`int wifi_send_pkt_freedom(uint8 *buf, int len, bool sys_seq);`
```
typedef void (*freedom_outside_cb_t)(uint8 status);
int wifi_register_send_pkt_freedom_cb(freedom_outside_cb_t cb);
void wifi_unregister_send_pkt_freedom_cb(void);
int wifi_send_pkt_freedom(uint8 *buf, int len, bool sys_seq);
```
![screenshot of notepad, copy paste the right code](https://raw.githubusercontent.com/spacehuhn/esp8266_deauther/master/screenshots/notepad_screenshot_1.JPG)
**don't forget to save!**
**don't forget to save!**
**12** Go to the SDK_fix folder of this project
@ -181,55 +161,57 @@ If flashing the bin files with a flash tool is not working, try flashing the esp
**16** Select your ESP8266 board at `Tools` > `Board` and the right port at `Tools` > `Port`
If no port shows up you may have to reinstall the drivers.
**17** Depending on your board you may have to adjust the `Tools` > `Board` > `Flash Frequency` and the `Tools` > `Board` > `Flash Size`. In my case i had to use a `80MHz` Flash Frequency, and a `4M (1M SPIFFS)` Flash Size
**17** Depending on your board you may have to adjust the `Tools` > `Board` > `Flash Frequency` and the `Tools` > `Board` > `Flash Size`. I use a `160MHz` flash frequency and a `4M (3M SPIFFS)` flash size.
**18** Upload!
**Note:** If you use a 512kb version of the ESP8266, you need to comment out a part of the mac vendor list in data.h.
**Note:** If you use a 512kb version of the ESP8266, you will need to comment out a part of the mac vendor list in data.h. Otherwise it will use too much memory to fit on 512kb.
**Your ESP8266 Deauther is now ready!**
### Adding OLED display
### Adding an OLED display
![image of the esp8266 deauther with an OLED and three buttons](https://raw.githubusercontent.com/spacehuhn/esp8266_deauther/master/screenshots/esp8266_with_oled.jpg)
**0** Follow the steps [above](#compiling-the-source-with-arduino) to get your Arduino environment ready.
I included 2 extra .bin files for the display version on the release page.
One for the 0.96" SSD1306 OLED and one for the 1.3" SH1106 OLED.
**1** Install this OLED driver library: https://github.com/squix78/esp8266-oled-ssd1306
| Display | ESP8266 |
| ------- | ------- |
| SDA | 5 |
| SCL | 4 |
| GND | GND |
| VCC | VCC (3.3V) |
**2** Customize the code for your wiring.
In `esp8266_deauther.ino` uncomment `#define USE_DISPLAY`.
Then scroll down and customize these lines depending on your setup.
I used a Wemos d1 mini with a SSD1306 128x64 OLED and 3 push buttons.
The buttons have to be between following pins and GND:
//include the library you need
#include "SSD1306.h"
//#include "SH1106.h"
| Button | ESP8266 |
| ------ | ------- |
| up | 12 (D6) |
| down | 13 (D7) |
| select | 14 (D5) |
//button pins
#define upBtn D6
#define downBtn D7
#define selectBtn D5
#define buttonDelay 180 //delay in ms
//render settings
#define fontSize 8
#define rowsPerSite 8
If you use Arduino, you have will need to install this library: https://github.com/squix78/esp8266-oled-ssd1306.
Then you only need to uncomment `//#define USE_DISPLAY` in the beginning of the sketch.
Below that, you can customize the settings:
//create display(Adr, SDA-pin, SCL-pin)
SSD1306 display(0x3c, D2, D1);
//SH1106 display(0x3c, D2, D1);
```
//create display(Adr, SDA-pin, SCL-pin)
SSD1306 display(0x3c, 5, 4); //GPIO 5 = D1, GPIO 4 = D2
//SH1106 display(0x3c, 5, 4);
//button pins
#define upBtn 12 //GPIO 12 = D6
#define downBtn 13 //GPIO 13 = D7
#define selectBtn 14 //GPIO 14 = D5
#define displayBtn 0 //GPIO 0 = FLASH BUTTON
```
## How to use it
First start your ESP8266 by plugging it in and giving it power.
You can use your smartphone if you have a USB OTG cable.
![esp8266 deauther with a smartphone](https://raw.githubusercontent.com/spacehuhn/esp8266_deauther/master/screenshots/smartphone_esp_2.jpg)
Scan for Wi-Fi networks and connect to `pwned`. The password is `deauther`.
Once connected, you can open up your browser and go to `192.168.4.1`.
@ -239,19 +221,20 @@ You can now scan for networks...
scan for client devices...
![webinterface client scanner](https://raw.githubusercontent.com/spacehuhn/esp8266_deauther/master/screenshots/web_screenshot_2.JPG)
Note: While scanning the ESP8266 will shut down its access point, so you may have to go to your settings and reconnect to the Wi-Fi network manually.
Note: While scanning the ESP8266 will shut down its access point, so you may have to go to your settings and reconnect to the Wi-Fi network manually!
...and start different attacks.
![webinterface attack menu](https://raw.githubusercontent.com/spacehuhn/esp8266_deauther/master/screenshots/web_screenshot_3.JPG)
For more information please read the [FAQ](https://github.com/spacehuhn/esp8266_deauther/wiki/FAQ).
## How to reset it
## License
Method 1: Connect pin 4 (D2 on the NodeMCU) to GND and plug the device in.
Method 2: Connect your device, open up the serial monitor in Arduino, set baudrate to 115200, type in "reset" and click send.
This software is licensed under the MIT License. See the [license file](LICENSE) for details.
## Sources and additional links
## Alternative Designs
### Custom Design Versions
![Screenshot of 'Wi-PWN'](https://raw.githubusercontent.com/samdenty99/Wi-PWN/master/pictures/secondary-banner.png)
[Wi-PWN](https://github.com/samdenty99/Wi-PWN) - By [@samdenty99](https://github.com/samdenty99)
@ -259,23 +242,17 @@ Method 2: Connect your device, open up the serial monitor in Arduino, set baudra
![Screenshot of 'Modern and Consistent'](https://raw.githubusercontent.com/Wandmalfarbe/esp8266_deauther/master/screenshots/web_screenshot_1.png)
[Modern and Consistent](https://github.com/Wandmalfarbe/esp8266_deauther) - By [@Wandmalfarbe](https://github.com/Wandmalfarbe)
![Screenshot of 'hax0r deauther skin'](https://camo.githubusercontent.com/38d6b29df9eab0ca5717260b6086e6da212ff126/68747470733a2f2f696d6167652e70726e747363722e636f6d2f696d6167652f56476379594c46465376755172695439443972565f672e706e67)
[hax0r deauther skin](https://github.com/EnigmaPROGRAMS/esp8266_deauther) - By [@EnigmaPROGRAMS](https://github.com/EnigmaPROGRAMS)
### Videos
[![Cheap Wi-Fi 'Jammer' Device | NodeMCU](https://img.youtube.com/vi/oQQhBdCQOTM/0.jpg)](https://www.youtube.com/watch?v=oQQhBdCQOTM)
[![Wifi 'Jammer' Device V1.1 | Setup Tutorial](https://img.youtube.com/vi/r5aoV5AolNo/0.jpg)](https://www.youtube.com/watch?v=r5aoV5AolNo)
[![WiFi Tutorial "Deauthing Made Simple"](https://img.youtube.com/vi/SswI-J-M2SE/0.jpg)](https://www.youtube.com/watch?v=SswI-J-M2SE)
## FAQ
[![Seguridad Inalámbrica | Explicación de Wifi Deauther en Español](https://img.youtube.com/vi/YYsSDXRgD10/0.jpg)](https://www.youtube.com/watch?v=YYsSDXRgD10)
The FAQ was moved over to the [Wiki](https://github.com/spacehuhn/esp8266_deauther/wiki/FAQ).
## License
This software is licensed under the MIT License. See the [license file](LICENSE) for details.
**Referring to this project as "jammer" is prohibited! Name the project by its correct name.**
## Sources and additional links
### Sources
deauth attack: https://en.wikipedia.org/wiki/Wi-Fi_deauthentication_attack
@ -293,7 +270,3 @@ packet injection with ESP8266:
802.11w-2009: https://en.wikipedia.org/wiki/IEEE_802.11w-2009
Wi-Fi_send_pkt_freedom function limitations: https://esp32.com/viewtopic.php?t=586
## Contribute Code
To contribute code, make pull requests in `testing` branch to avoid future code conflicts. The `testing` branch is merged with `master` on every release.