ESP32 Wi-Fi Penetration Tool

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.

Features

• 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...

Demo video

Usage

1. Build and flash project onto ESP32 (DevKit or module)

2. Power ESP32

3. Management AP is started automatically after boot

4. Connect to this AP
   By default: SSID: ManagementAP and password: mgmtadmin

5. In browser open 192.168.4.1 and you should see a web client to configure and control tool like this:

   

Build

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 build

Legacy method using make is not supported by this project.

Flash

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.

Documentation

Wi-Fi attacks

Attacks implementations in this project are described in main component README. Theory behind these attacks is located in doc/ATTACKS_THEORY.md

API reference

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.

Components

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)

Further reading

• Academic paper about this project (PDF)

Hardware

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.

Power consumption

Based on experimental measurements, ESP32 consumes around 100mA during attack executions.

Similar projects

• GANESH-ICMC/esp32-deauther
• SpacehuhnTech/esp8266_deauther
• justcallmekoko/ESP32Marauder
• EParisot/esp32-network-toolbox
• Jeija/esp32free80211

Contributing

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.

Disclaimer

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.

License

Even though this project is licensed under MIT license (see LICENSE file for details), don't be shy or greedy and share your work.