Note: If you are using other chips like ESP32S2, ESP32C2 any others chips:
- Just
idf.py buildthe project usingidf.py set-target <chip-type>and then build it to be flashed. - Flash any wrong chip type .bin image may cause error before and after flashing.
- Some chip types are prebuilded in this project to be more easily flashed without any enviroment build error
We have avaliable all the *.bin builded for:
- ESP32 [master] branch
- ESP32S2 [esp32s2] branch
- ... (We will update more builded distribution soon)
This project introduces an universal tool for ESP32 platform for implementing various Wi-Fi attacks. It provides some common functionality that is commonly used in Wi-Fi attacks and makes implementing new attacks a bit simpler. It also includes Wi-Fi attacks itself like capturing PMKIDs from handshakes, or handshakes themselves by different methods like starting rogue duplicated AP or sending deauthentication frames directly, etc...
Obviously cracking is not part of this project, as ESP32 is not sufficient to crack hashes in effective way. The rest can be done on this small, cheap, low-power SoC.
- PMKID capture
- WPA/WPA2 handshake capture and parsing
- Deauthentication attacks using various methods
- Denial of Service attacks
- Formatting captured traffic into PCAP format
- Parsing captured handshakes into HCCAPX file ready to be cracked by Hashcat
- Passive handshake sniffing
- Easily extensible framework for new attacks implementations
- Management AP for easy configuration on the go using smartphone for example
- And more...
-
Power ESP32
-
Management AP is started automatically after boot
-
Connect to this AP
By default: SSID:ManagementAPand password:mgmtadmin -
In browser open
192.168.4.1and you should see a web client to configure and control tool like this:
This project is currently developed using ESP-IDF 4.1 (commit 5ef1b390026270503634ac3ec9f1ec2e364e23b2). It may be broken on newer version.
Project can be built in the usual ESP-IDF way:
idf.py buildLegacy method using make is not supported by this project.
If you have setup ESP-IDF, the easiest way is to use idf.py flash.
In case you don't want to setup whole ESP-IDF, you can use pre-build binaries included in build/ and flash them using esptool.py (requires Python).
Example command (follow instructions in esptool repo):
esptool.py -p /dev/ttyS5 -b 115200 --after hard_reset write_flash --flash_mode dio --flash_freq 40m --flash_size detect 0x8000 build/partition_table/partition-table.bin 0x1000 build/bootloader/bootloader.bin 0x10000 build/esp32-wifi-penetration-tool.bin
On Windows you can use official Flash Download Tool.
Attacks implementations in this project are described in main component README. Theory behind these attacks is located in doc/ATTACKS_THEORY.md
This project uses Doxygen notation for documenting components API and implementation. Doxyfile is included so if you want to generate API reference, just run doxygen from root directory. It will generate HTML API reference into doc/api/html.
This project consists of multiple components, that can be reused in other projects. Each component has it's own README with detailed description. Here comes brief description of components:
- Main component is entry point for this project. All neccessary initialisation steps are done here. Management AP is started and the control is handed to webserver.
- Wifi Controller component wraps all Wi-Fi related operations. It's used to start AP, connect as STA, scan nearby APs etc.
- Webserver component provides web UI to configure attacks. It expects that AP is started and no additional security features like SSL encryption are enabled.
- Wi-Fi Stack Libraries Bypasser component bypasses Wi-Fi Stack Libraries restriction to send some types of arbitrary 802.11 frames.
- Frame Analyzer component processes captured frames and provides parsing functionality to other components.
- PCAP Serializer component serializes captured frames into PCAP binary format and provides it to other components (mostly for webserver/UI)
- HCCAPX Serializer component serializes captured frames into HCCAPX binary format and provides it to other components (mostly for webserver/UI)
This project was mostly build and tested on ESP32-DEVKITC-32E but there should not be any differences for any ESP32-WROOM-32 modules.
On the following pictures you can see a battery (Li-Pol accumulator) powered ESP32 DevKitC using following hardware:
- ESP32-DEVKITC-32E (cost 213 CZK/8.2 EUR/9.6 USD)
- 220mAh Li-Pol 3.7V accumulator (weights ±5g, cost 77 CZK/3 EUR/3.5 USD)
- MCP1702-3302ET step-down 3.3V voltage regulator (cost 11 CZK/0.42 EUR/0.50 USD)
- Czech 5-koruna coin for scale (weights 4.8g, diameter 23 mm, cost 0.19 EUR/0.23 USD)
Altogether (without coin) this setup weights around 17g. This can be further downsized by using smaller Li-Pol accumulator and using ESP32-WROOM-32 modul directly instead of whole dev board.
This setup cost me around 300 CZK (± 11.50 EUR/13.50 USD). Using the modul directly that costs around 80 CZK (± 3 EUR/3.5 USD) we can get to price of 160 CZK (± 6.5 EUR/7.5 USD) which makes this tool really cheap and available to almost everybody.
Based on experimental measurements, ESP32 consumes around 100mA during attack executions.
- GANESH-ICMC/esp32-deauther
- SpacehuhnTech/esp8266_deauther
- justcallmekoko/ESP32Marauder
- EParisot/esp32-network-toolbox
- Jeija/esp32free80211
Feel free to contribute. Don't hestitate to refactor current code base. Please stick to Doxygen notation when commenting new functions and files. This project is mainly build for educational and demonstration purposes, so verbose documentation is welcome.
This project demonstrates vulnerabilities of Wi-Fi networks and its underlaying 802.11 standard and how ESP32 platform can be utilised to attack on those vulnerable spots. Use responsibly against networks you have permission to attack on.
Even though this project is licensed under MIT license (see LICENSE file for details), don't be shy or greedy and share your work.