├── .github ├── issue_template.md └── issues.md ├── .gitignore ├── LICENSE ├── README.md ├── esp8266_deauther ├── APScan.cpp ├── APScan.h ├── Attack.cpp ├── Attack.h ├── ClientScan.cpp ├── ClientScan.h ├── Mac.cpp ├── Mac.h ├── MacList.cpp ├── MacList.h ├── NameList.cpp ├── NameList.h ├── SSIDList.cpp ├── SSIDList.h ├── Settings.cpp ├── Settings.h ├── data.h └── esp8266_deauther.ino ├── screenshots ├── arduino_screenshot_1.JPG ├── arduino_screenshot_2.JPG ├── esp8266_with_oled.jpg ├── notepad_screenshot_1.JPG ├── smartphone_esp_1.jpg ├── smartphone_esp_2.jpg ├── web_screenshot_1.JPG ├── web_screenshot_2.JPG └── web_screenshot_3.JPG ├── sdk_fix ├── ESP8266WiFi.cpp ├── ESP8266WiFi.h ├── README.txt └── user_interface.h └── web_server ├── html ├── apscan.html ├── attack.html ├── error.html ├── index.html ├── info.html ├── js │ ├── apscan.js │ ├── attack.js │ ├── functions.js │ ├── settings.js │ └── stations.js ├── settings.html ├── stations.html └── style.css ├── jquery.js ├── minifier.html └── readme.md /.github/issue_template.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | Read [issues.md](https://github.com/spacehuhn/esp8266_deauther/blob/master/.github/issues.md) or your issue might be closed and labeled as invalid. 4 | 5 | --- 6 | -------------------------------------------------------------------------------- /.github/issues.md: -------------------------------------------------------------------------------- 1 | # General 2 | 3 | **Read the readme!!** 4 | Most issues can be solved just by reading the full readme file. 5 | Also make sure you have followed all the installation steps correctly. 6 | 7 | **Search for similar issues** 8 | Double posts will be closed, so make sure your issue doesn't exist yet (also look for closed ones). 9 | 10 | **Don't aswer via email** 11 | Just don't answer issues with your email, please... 12 | 13 | **Don't paste links to shops** 14 | It's odd that I have to say this, but don't just send your ebay or amazon links to show what hardware you're using. 15 | It's enough to say what model or version it is. 16 | 17 | **Apply some common sense** 18 | Also odd to mention this, but think about what you want to ask or answer and then post it. 19 | ***Use a clear, short headline with a good understandable description of your issue.*** 20 | Don't spam with issues, post or pictures! Be nice, understanding and help others. 21 | Also note that this is an open source project. No one must help you, so be thankfull for every help you get. 22 | 23 | # Bugs 24 | 25 | **Read the FAQ** 26 | Read the FAQ, which is a part of the readme. 27 | 28 | **Make sure it's related to this project** 29 | Make sure your issue is related to this project and doesn't occur when uploading other code to the device. 30 | 31 | **Post as much information as possible** 32 | What installation method, OS, browser and ESP8266 version are you useing? 33 | If your dealing with a bug in the webinterface, check if the browsers developer tools show you an error. 34 | 35 | **Send the serial log** 36 | Use the serial monitor in Arduino to look for possible erros and post it if necessary. 37 | If you have a very long error log use [pastebin](http://pastebin.com/). 38 | 39 | **Try out the testing branch** 40 | Can be found here: https://github.com/spacehuhn/esp8266_deauther/tree/testing 41 | You'll need to compile it with Arduino. 42 | 43 | # Feature Requests 44 | 45 | Just a few notes here: 46 | - Add an detailed description. 47 | - Research if it can be implemented (if it's possible using the hardware, software etc.) 48 | - Research if such a feature exists in an other project 49 | - Be sure it's really usefull for everyone (you'll need some common sense here!) 50 | - Try to implement it yourself! 51 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | # Object files 2 | *.o 3 | *.ko 4 | *.obj 5 | *.elf 6 | 7 | # Precompiled Headers 8 | *.gch 9 | *.pch 10 | 11 | # Libraries 12 | *.lib 13 | *.a 14 | *.la 15 | *.lo 16 | 17 | # Shared objects (inc. Windows DLLs) 18 | *.dll 19 | *.so 20 | *.so.* 21 | *.dylib 22 | 23 | # Executables 24 | *.exe 25 | *.out 26 | *.app 27 | *.i*86 28 | *.x86_64 29 | *.hex 30 | 31 | # Debug files 32 | *.dSYM/ 33 | *.su 34 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2017 Stefan Kremser 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | Any redistributing, advertising or selling of this project as "jammer" without clearly stating it as a pentesting device for testing purposes only, is prohibited! 16 | 17 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 18 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 19 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 20 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 21 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 22 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 23 | SOFTWARE. 24 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # ESP8266 Deauther 2 | Deauthentication attack and other hacks using an ESP8266. 3 | 4 | ![esp8266 deauther with a smartphone](/screenshots/smartphone_esp_1.jpg) 5 | 6 | [![Donate](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=RCHANSVSX9M8C) 7 | 8 | **Any redistributing, advertising or selling of this project as "jammer" without clearly stating it as a pentesting device for testing purposes only, is prohibited!** 9 | 10 | I disabled the issue section because of the flood of invalid questions, unrelated to this project. 11 | All necessary information is described below. Do not open issues about this project on any other of my projects, otherwise you will be blocked immediately! 12 | 13 | **This project is a proof of concept for testing and education.** 14 | Neither the ESP8266, nor the SDK was meant and build for such purposes. 15 | Bugs can occur! 16 | 17 | 18 | ## Contents 19 | - [Introduction](#introduction) 20 | - [What it is](#what-it-is) 21 | - [How it works](#how-it-works) 22 | - [What an ESP8266 is](#what-an-esp8266-is) 23 | - [How to protect against it](#how-to-protect-against-it) 24 | - [Disclaimer](#disclaimer) 25 | - [Videos](#videos) 26 | - [Installation](#installation) 27 | - [Uploading the bin files](#uploading-the-bin-files) 28 | - [Compiling the source with Arduino](#compiling-the-source-with-arduino) 29 | - [Adding OLED display](#adding-oled-display) 30 | - [How to use it](#how-to-use-it) 31 | - [Usage of fake captive portal](#captive-portal-usage) 32 | - [FAQ](#faq) 33 | - [License](#license) 34 | - [Sources and additional links](#sources-and-additional-links) 35 | 36 | ## Introduction ## 37 | 38 | ### What it is 39 | 40 | Basically it’s a device which performs a [deauth attack](https://en.wikipedia.org/wiki/Wi-Fi_deauthentication_attack). 41 | You select the clients you want to disconnect from their network and start the attack. As long as the attack is running, the 42 | selected devices are unable to connect to their network. 43 | Other attacks also have been implemented, such as beacon or probe request flooding. 44 | 45 | ### How it works 46 | 47 | 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 48 | network. 49 | 50 | 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. 51 | 52 | ### What an ESP8266 is 53 | 54 | The [ESP8266](https://en.wikipedia.org/wiki/ESP8266) is a cheap micro controller 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). 55 | 56 | You can buy these chips for under $2 from China! 57 | 58 | ### How to protect against it 59 | 60 | With [802.11w-2009](https://en.wikipedia.org/wiki/IEEE_802.11w-2009) Wi-Fi got an update to encrypt management frames. 61 | So make sure your router is up to date and has management frame protection enabled. But note that your client device needs to 62 | support it too, both ends need to have it enabled! 63 | 64 | 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. 65 | 66 | 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. 67 | 68 | ## Disclaimer 69 | 70 | Use it only for testing purposes on your own devices! 71 | I don't take any responsibility for what you do with this program. 72 | 73 | Please check the legal regulations in your country before using it. 74 | **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. 75 | 76 | Any redistributing, advertising or selling of this project as "jammer" without clearly stating it as a pentesting device for testing purposes only, is prohibited! 77 | 78 | My intention with this project is to draw more attention to this issue. 79 | This attack shows how vulnerable the 802.11 Wi-Fi standard is and that it has to be fixed. 80 | **A solution is already there, why don’t we use it?** 81 | 82 | ## Videos 83 | 84 | [![Cheap Wi-Fi 'Jammer' Device | NodeMCU](https://img.youtube.com/vi/oQQhBdCQOTM/0.jpg)](https://www.youtube.com/watch?v=oQQhBdCQOTM) 85 | 86 | [![Wifi 'Jammer' Device V1.1 | Setup Tutorial](https://img.youtube.com/vi/r5aoV5AolNo/0.jpg)](https://www.youtube.com/watch?v=r5aoV5AolNo) 87 | 88 | [![WiFi Jamming Tutorial "Deauthing Made Simple" ](https://img.youtube.com/vi/SswI-J-M2SE/0.jpg)](https://www.youtube.com/watch?v=SswI-J-M2SE) 89 | 90 | [![NodeMCU ESP8266 Tutorial 02: WiFi Hack with ESP8266 (NodeMCU WiFi Jammer)](https://img.youtube.com/vi/MOscKnm8IcY/0.jpg)](https://www.youtube.com/watch?v=MOscKnm8IcY) 91 | 92 | ## Installation 93 | 94 | The only thing you will need is a computer and an ESP8266. 95 | 96 | I recommend you to buy a USB breakout/developer board, because they have 4Mb flash and are very simple to use. 97 | It doesn’t matter which board you use, as long as it has an ESP8266 on it. 98 | 99 | You have 2 choices here. Uploading the bin files is easier but not as good for debugging, so keep that in mind in case you want to open an new issue. 100 | **YOU ONLY NEED TO DO ONE OF THE INSTALLATION METHODS!** 101 | 102 | ### Uploading the bin files 103 | 104 | **Note:** the 512kb version won't have the full MAC vendor list. 105 | The NodeMCU and every other board which uses the ESP-12 has 4mb flash on it. 106 | 107 | **0** Download the current release from [here](https://github.com/spacehuhn/esp8266_deauther/releases) 108 | 109 | **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. 110 | 111 | **That's all! :)** 112 | 113 | Make sure you select the right com-port, the right upload size of your ESP8266 and the right bin file. 114 | 115 | If flashing the bin files with a flash tool is not working, try flashing the esp8266 with the Arduino IDE as shown below. 116 | 117 | ### Compiling the source with Arduino 118 | 119 | **0** Download the source code of this project. 120 | 121 | **1** Install [Arduino](https://www.arduino.cc/en/Main/Software) and open it. 122 | 123 | **2** Go to `File` > `Preferences` 124 | 125 | **3** Add `http://arduino.esp8266.com/stable/package_esp8266com_index.json` to the Additional Boards Manager URLs. (source: https://github.com/esp8266/Arduino) 126 | 127 | **4** Go to `Tools` > `Board` > `Boards Manager` 128 | 129 | **5** Type in `esp8266` 130 | 131 | **6** Select version `2.0.0` and click on `Install` (**must be version 2.0.0!**) 132 | 133 | ![screenshot of arduino, selecting the right version](/screenshots/arduino_screenshot_1.JPG) 134 | 135 | **7** Go to `File` > `Preferences` 136 | 137 | **8** Open the folder path under `More preferences can be edited directly in the file` 138 | 139 | ![screenshot of arduino, opening folder path](/screenshots/arduino_screenshot_2.JPG) 140 | 141 | **9** Go to `packages` > `esp8266` > `hardware` > `esp8266` > `2.0.0` > `tools` > `sdk` > `include` 142 | 143 | **10** Open `user_interface.h` with a text editor 144 | 145 | **11** Scroll down and before `#endif` add following lines: 146 | 147 | `typedef void (*freedom_outside_cb_t)(uint8 status);` 148 | `int wifi_register_send_pkt_freedom_cb(freedom_outside_cb_t cb);` 149 | `void wifi_unregister_send_pkt_freedom_cb(void);` 150 | `int wifi_send_pkt_freedom(uint8 *buf, int len, bool sys_seq);` 151 | 152 | ![screenshot of notepad, copy paste the right code](/screenshots/notepad_screenshot_1.JPG) 153 | 154 | **don't forget to save!** 155 | 156 | **12** Go to the SDK_fix folder of this project 157 | 158 | **13** Copy ESP8266Wi-Fi.cpp and ESP8266Wi-Fi.h 159 | 160 | **14** Paste these files here `packages` > `esp8266` > `hardware` > `esp8266` > `2.0.0` > `libraries` > `ESP8266WiFi` > `src` 161 | 162 | **15** Open `esp8266_deauther` > `esp8266_deauther.ino` in Arduino 163 | 164 | **16** Select your ESP8266 board at `Tools` > `Board` and the right port at `Tools` > `Port` 165 | If no port shows up you may have to reinstall the drivers. 166 | 167 | **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 168 | 169 | **18** Upload! 170 | 171 | **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. 172 | 173 | **Your ESP8266 Deauther is now ready!** 174 | 175 | 176 | ### Adding OLED display 177 | 178 | ![image of the esp8266 deauther with an OLED and three buttons](/screenshots/esp8266_with_oled.jpg) 179 | 180 | **0** Follow the steps [above](#compiling-the-source-with-arduino) to get your Arduino environment ready. 181 | 182 | **1** Install this OLED driver library: https://github.com/squix78/esp8266-oled-ssd1306 183 | 184 | **2** Customize the code for your wiring. 185 | In `esp8266_deauther.ino` uncomment `#define USE_DISPLAY`. 186 | Then scroll down and customize these lines depending on your setup. 187 | I used a Wemos d1 mini with a SSD1306 128x64 OLED and 3 push buttons. 188 | 189 | //include the library you need 190 | #include "SSD1306.h" 191 | //#include "SH1106.h" 192 | 193 | //button pins 194 | #define upBtn D6 195 | #define downBtn D7 196 | #define selectBtn D5 197 | 198 | #define buttonDelay 180 //delay in ms 199 | 200 | //render settings 201 | #define fontSize 8 202 | #define rowsPerSite 8 203 | 204 | //create display(Adr, SDA-pin, SCL-pin) 205 | SSD1306 display(0x3c, D2, D1); 206 | //SH1106 display(0x3c, D2, D1); 207 | 208 | ## How to use it 209 | 210 | First start your ESP8266 by giving it power. 211 | 212 | You can use your smartphone if you have a USB OTG cable. 213 | ![esp8266 deauther with a smartphone](/screenshots/smartphone_esp_2.jpg) 214 | 215 | Scan for Wi-Fi networks and connect to `pwned`. The password is `deauther`. 216 | Once connected, you can open up your browser and go to `192.168.4.1`. 217 | 218 | You can now scan for networks... 219 | ![webinterface AP scanner](/screenshots/web_screenshot_1.JPG) 220 | 221 | scan for client devices... 222 | ![webinterface client scanner](/screenshots/web_screenshot_2.JPG) 223 | 224 | 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. 225 | 226 | ...and start different attacks. 227 | ![webinterface attack menu](/screenshots/web_screenshot_3.JPG) 228 | 229 | Happy hacking :) 230 | 231 | 232 | ### Captive Portal Usage 233 | You need to change the SSID and channel as same as victims Wi-Fi. 234 | For load the saved credentials type *any address*/readit 235 | For changing the captive portal page go to data.h and change value of fakePage. 236 | 237 | ## FAQ 238 | 239 | **Could it auto-deauth all APs in the range?** 240 | 241 | Yes, but I will not implement this 'feature' for ethical and legal reasons. 242 | 243 | **Can it sniff handshakes?** 244 | 245 | The ESP8266 has a promiscuous mode in which you can sniff packets, but handshake packets are dropped and there is no other way to get them with the functions provided by the SDK. 246 | Maybe someone will find a way around this barrier in the future. 247 | 248 | **espcomm_sync failed/espcomm_open when uploading** 249 | 250 | The ESP upload tool can't communicate with the chip, make sure the right port is selected! 251 | You can also try out different USB ports and cables. 252 | If this doesn't solve it, you may have to install USB drivers. 253 | Which drivers you need depends on the board, most boards use a cp2102 or ch340. 254 | 255 | **AP scan doesn't work** 256 | 257 | There is a reported issue on this: https://github.com/spacehuhn/esp8266_deauther/issues/5 258 | Try switching the browser or opening the website with another device. 259 | 260 | **Deauth attack won't work** 261 | 262 | If you see 0 pkts/s on the website, then you've made a mistake. Check that you have followed the installation steps correctly and that the right SDK is installed, it must be version 2.0.0! 263 | If it can send packets but your target doesn't loose its connection, then the Wi-Fi router either uses [802.11w](#how-to-protect-against-it) and it's protected against such attacks, or it communicates on the 5GHz band, which the ESP8266 doesn't support because of its 2.4GHz antenna. 264 | 265 | ### If you have other questions or problems with the ESP8266, you can also check out the official [community forum](http://www.esp8266.com/). 266 | 267 | ## License 268 | 269 | This project is licensed under the MIT License - see the [license file](LICENSE) for details. 270 | 271 | **The License file must be included in any redistributed version of this program!** 272 | Any redistributing, advertising or selling of this project as "jammer" without clearly stating it as a pentesting device for testing purposes only, is prohibited! 273 | 274 | ## Sources and additional links 275 | 276 | deauth attack: https://en.wikipedia.org/wiki/Wi-Fi_deauthentication_attack 277 | 278 | deauth frame: https://mrncciew.com/2014/10/11/802-11-mgmt-deauth-disassociation-frames/ 279 | 280 | ESP8266: 281 | * https://de.wikipedia.org/wiki/ESP8266 282 | * https://espressif.com/en/products/hardware/esp8266ex/overview 283 | 284 | packet injection with ESP8266: 285 | * http://hackaday.com/2016/01/14/inject-packets-with-an-esp8266/ 286 | * http://bbs.espressif.com/viewtopic.php?f=7&t=1357&p=10205&hilit=Wi-Fi_pkt_freedom#p10205 287 | * https://github.com/pulkin/esp8266-injection-example 288 | 289 | 802.11w-2009: https://en.wikipedia.org/wiki/IEEE_802.11w-2009 290 | 291 | Wi-Fi_send_pkt_freedom function limitations: http://esp32.com/viewtopic.php?f=13&t=586&p=2648&hilit=Wi-Fi_send_pkt_freedom#p2648 292 | -------------------------------------------------------------------------------- /esp8266_deauther/APScan.cpp: -------------------------------------------------------------------------------- 1 | #include "APScan.h" 2 | 3 | APScan::APScan() { 4 | 5 | } 6 | 7 | bool APScan::start() { 8 | if (debug) { 9 | Serial.println("starting AP scan..."); 10 | Serial.println("MAC - Ch - RSSI - Encrypt. - SSID - Hidden");// - Vendor"); 11 | } 12 | aps._clear(); 13 | for (int i = 0; i < maxAPScanResults; i++) selected[i] = false; 14 | results = WiFi.scanNetworks(false, settings.apScanHidden); // lets scanNetworks return hidden APs. (async = false & show_hidden = true) 15 | 16 | for (int i = 0; i < results && i < maxAPScanResults; i++) { 17 | Mac _ap; 18 | _ap.set(WiFi.BSSID(i)[0], WiFi.BSSID(i)[1], WiFi.BSSID(i)[2], WiFi.BSSID(i)[3], WiFi.BSSID(i)[4], WiFi.BSSID(i)[5]); 19 | aps.add(_ap); 20 | channels[i] = WiFi.channel(i); 21 | rssi[i] = WiFi.RSSI(i); 22 | encryption[i] = WiFi.encryptionType(i); 23 | hidden[i] = WiFi.isHidden(i); 24 | String _ssid = WiFi.SSID(i); 25 | _ssid.replace("\"", "\\\""); 26 | _ssid.toCharArray(names[i], 33); 27 | //data_getVendor(WiFi.BSSID(i)[0],WiFi.BSSID(i)[1],WiFi.BSSID(i)[2]).toCharArray(vendors[i],9); 28 | if (debug) { 29 | Serial.print((String)i); 30 | Serial.print(" - "); 31 | _ap._print(); 32 | Serial.print(" - "); 33 | Serial.print(channels[i]); 34 | Serial.print(" - "); 35 | Serial.print(rssi[i]); 36 | Serial.print(" - "); 37 | Serial.print(getEncryption(encryption[i])); 38 | Serial.print(" - "); 39 | Serial.print(names[i]); 40 | Serial.print(" - "); 41 | Serial.print(hidden[i]); 42 | //Serial.print(" - "); 43 | //Serial.print(vendors[i]); 44 | Serial.println(); 45 | } 46 | } 47 | 48 | //for debugging the APScan crash bug 49 | /* 50 | if(debug){ 51 | for(int i=results;i