risinek/esp32-wifi-penetration-tool

Exploring possibilities of ESP32 platform to attack on nearby Wi-Fi networks.

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.

esp32-wifi-penetration-tool's Issues

Timeout issue

I know its normal for it to time out but when it does and i reconnect to the management AP it still says timeout without any infomation as if to say it didnt do anything. I do it on my home network and theres nothing in place to stop attacks

Hashcat no hashes loaded from capture.hccapx

─(kali㉿windows)-[~/Desktop]
└─$ hashcat -m 22000 capture.hccapx pass

hashcat (v6.2.5) starting

OpenCL API (OpenCL 2.0 pocl 1.8 Linux, None+Asserts, RELOC, LLVM 11.1.0, SLEEF, DISTRO, POCL_DEBUG) - Platform #1 [The pocl project]

• Device #1: pthread-Intel(R) Core(TM) i3-7020U CPU @ 2.30GHz, 708/1480 MB (256 MB allocatable), 4MCU

Minimum password length supported by kernel: 8
Maximum password length supported by kernel: 63

Hashfile 'capture.hccapx' on line 1 (HCPX): Separator unmatched
Hashfile 'capture.hccapx' on line 2 (): Separator unmatched
No hashes loaded.

Started: Thu Dec 7 08:20:45 2023
Stopped: Thu Dec 7 08:20:52 2023

192.168.4.1 not working on NodeMCU 32S

When I did ur project everything was good, I flashed everything into the NodeMCU 32S, And when I try to access 192.
168.4.1, The browser keeps on loading. I used ESP-IDF

Add support for MicroSD

It could be extremely useful to be able to store handshakes and PMKID's on an external MicroSD.

changing AP password

can you add options to control ap security(wpa,wep) , change AP password

Сap file problem

always cap file does not contain handshake( help!

Please Add WPS (Pixie Dust Attack)

Please add pixie dust attack

Provide guidance on how to use hashcat

Document step by step how to start password recovery using Hashcat from HCCAPX or PMKID (16800)

NOT an issue, More of an idea!

Big fan of this project! Wondering if there is the possibility of doing some html editing to make the UI more material design and dark mode? This would great when using on smartphones!!

CAP file does not contain ESSID and handshake.

After attacking the hccapx file is good. And in the "CAP" file there is no handshake.

How to edit web interface

I want to add CSS in web interface.

Tool not working with ESP32-S2-Mini-1

Hello,
When I try to flash the bin files to the ESP32, I am left with an error on the device saying, “Invalid chip id. Expected 2 read 0. Bootloader for wrong chip?” Does it work with an esp32 S2-mini-1 or do I need different files. It would help if there was some way to compile it for Arduino IDE and flash it from there. I am using ESP IDF version 5.0.

while building and flashing

\esp32-wifi-penetration-tool-master\build' doesn't seem to be a CMake build directory. Refusing to automatically delete files in this directory. Delete the directory manually to 'clean' it.

Move backlog from Gitlab to Github

This repo was originally in Gitlab so there is also a backlog of known issues, ideas for improvements, new approaches, refactors "ticket" etc.
It will be worth to move them here to make future plans more transparent.

But where is evil twin thought ?

does not turn on after loading the code

I uploaded 3 binaries based on the instructions into my nodeMCU, but after reboot, the AP does not appear.

the code you provided i am facing issue

the only attack i am able to perform is attack_type_handshake and attack method is deauth_rogue_ap rest all does literally nothing then one lat dos attack which combine all option again disconnect my device from router when started why is it happening and how to fix this?

Can be installed on CH340G controller or only CP2102 ?

Im nead to buy a cp2102 or i can buy ch340g, i can't find cp2102 in my country : (

fails to build - Error 2

[ 93%] Building C object esp-idf/hccapx_serializer/CMakeFiles/__idf_hccapx_serializer.dir/hccapx_serializer.c.obj
/Users/XXXX/Downloads/esp32-wifi-penetration-tool-master/components/hccapx_serializer/hccapx_serializer.c: In function 'save_eapol':
/Users/XXXX/Downloads/esp32-wifi-penetration-tool-master/components/hccapx_serializer/hccapx_serializer.c:102:49: error: implicit declaration of function 'ntoh' [-Werror=implicit-function-declaration]
     eapol_len = sizeof(eapol_packet_header_t) + ntohs(eapol_packet->header.packet_body_length);
                                                 ^~~~~
cc1: some warnings being treated as errors
make[3]: *** [esp-idf/hccapx_serializer/CMakeFiles/__idf_hccapx_serializer.dir/hccapx_serializer.c.obj] Error 1
make[2]: *** [esp-idf/hccapx_serializer/CMakeFiles/__idf_hccapx_serializer.dir/all] Error 2
make[2]: *** Waiting for unfinished jobs....

then a couple lines later...

make[1]: *** [CMakeFiles/flash.dir/rule] Error 2
make: *** [flash] Error 2
make failed with exit code 2

I'm on mac os 10.14.6

Issues with booting

I'm not 100% sure what esp32 board I have but when I flash it and boot it, it outputs this in PuTTY

Could somebody help please? I need this for a school project...

5G

该固件可以在ESP32-C5上运行吗？

Add Evil-twin attack (feature request)

bro plz add evil twin attack feature..

[BUG] frame_analyzer.h:12:10: fatal error: esp_event.h: No such file or directory

Hello Author,

I have a error message when i run idf.py build command. please help me check.

thank you.

In file included from E:/DEVLOP/esp32-wifi-penetration-tool/components/hccapx_serializer/hccapx_serializer.c:16:
E:/DEVLOP/esp32-wifi-penetration-tool/components/frame_analyzer/interface/frame_analyzer.h:12:10: fatal error: esp_event.h: No such file or directory
   12 | #include "esp_event.h"
      |          ^~~~~~~~~~~~~
compilation terminated.

adding new attacks

https://github.com/EParisot/ESP32_Network_Toolbox_App i found here an app which can literally do many things if we will connect our esp32 via usb or otg but the thing is it works only on the esp32 box this guy made can you add some codes or something so that normal esp32 can also connect to it because this app detects the esp32 but doesn't get connected

Mate

ninja failed with exit code 1 while trying to build

when building I get:

/home/${USER}/esp/esp32-wifi-penetration-tool/components/wifi_controller/interface/../ap_scanner.h:12:10: fatal error: esp_wifi_types.h: No such file or directory
   12 | #include "esp_wifi_types.h"
      |          ^~~~~~~~~~~~~~~~~~
compilation terminated.

I tried building on windows as well as Linux

working with wemos mini s2?

Hi, I am trying to flash a wemos s2 mini using the esp download tool

1. bootloader 0x1000
2. partitiontable 0x8000
3. esp wifi penetration tool 0x10000
   40 MHz
   DIO
   1152000
   and in my case com 10 (?)
   just got a esp32 first time today. Not sure what is wrong.
   It says sync but nothing happens. I tried resetting with 0 hold, reset hold , release 0
   Help is greatly appreciated

Please add hidden ssid support

esp82xx compatibility?

I think I checked all the documentation and information and didn't found a esp8266 (or esp8285) mentioned everywhere.

Is it possible (in theory) or are their unsolvable issues hardware or software wise to make this working on a esp82xx?

Is it possible to bypass channel hopping restriction?

I have managed to make it work in Arduino IDE. My method involves webserver to control deauthing process. But if the device is still connected to the SoftAP, deauth does not work. This behavior does not happen in ESP8266. Based on this documentation,

https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/network/esp_wifi.html#_CPPv420esp_wifi_set_channel7uint8_t18wifi_second_chan_t

ESP32 restrict esp_wifi_set_channel() so it returns "ESP_FAIL" if a device is connected to the SoftAP.
If i try to look at libnet80211.a, there is a function called "ieee80211_update_channel", my guess this is the function where it checks whether there is a station or not. Is it possible to force channel hopping?.

It may be an intended feature by Espressif to prevent stations from disconnecting, but if I do channel hopping quick enough, it still works normally.

i get error while the code is uploading

even though when i upload the code to my esp32 from arduino ide it works. the upload finishes but i don't see managmentAP ssid in wifi networks available here is the error in the brackets
(Uploading stub...
Running stub...
Stub running...
Changing baud rate to 115200
Changed.
Unable to perform XMC flash chip startup sequence (Cannot configure port, something went wrong. Original message: PermissionError(13, 'A device attached to the system is not functioning.', None, 31)).
FLASH_CRYPT_CNT 0
ABS_DONE_0 False
Compressed 24016 bytes to 14877...
Compressed 3072 bytes to 103...
Compressed 723248 bytes to 447613...

is stub and send flash finish)

Is it possible to use the wsl bypass with platformio?

I would like to build a similar project which will require the installation of ESP-IDF v4.1 and the use of the wsl bypass method shown in this repo?

Do you know if it is possible to accomplish this using Platformio? I have doing quite a bit of research and going down quite a few rabbit holes but have found no solution.

ManagementAP network disappears after attack start

After start attack ManagementAP network disappears, only reboot of ESP32 helps.

Flashing via Arduino and Hardware doubt

hello,
I am new to programming firmware to esp32 and can you tell the libraries and components we need to flash this and
will this work without the battery and only on a micro-USB connection like a pocket hacking machine.
there are 3 bin files and i have no idea which i need to flash and in which format please help
thank you @risinek @Dkbarrett

Attack timeout is limited to 255 seconds

uint8_t is used for timeout setting, which is not enough and allows just 255 seconds timeout.

Provide PMKID as a file

Instead of providing raw string, also include a downloadable file called e,g,test.16800
so that the user can directly run hashcat attack - e.g. ./hashcat -m 16800 test.16800 -a 3

Ref: https://hashcat.net/forum/thread-7717.html

The firmware is not compiled

I did everything according to the instructions. The compilation process fails (see photo). What did I do wrong? photo and log

I tried it with another ESP network, unfortunately it never works

I tried it with another ESP network, unfortunately it never works

Error "Separator unmatched" with hashcat

I have error "separator unmatched" when trying to use handshake hccapx with hashcat mode 22000
I generated the file using my own access point.

Output:

PS F:\hashcat-6.2.4> hashcat -m 22000 capture1.hccapx wordlist.txt
hashcat (v6.2.4) starting

Successfully initialized NVIDIA CUDA library.


* Device #1: CUDA SDK Toolkit not installed or incorrectly installed.
             CUDA SDK Toolkit required for proper device support and utilization.
             Falling back to OpenCL runtime.

* Device #1: WARNING! Kernel exec timeout is not disabled.
             This may cause "CL_OUT_OF_RESOURCES" or related errors.
             To disable the timeout, see: https://hashcat.net/q/timeoutpatch
nvmlDeviceGetFanSpeed(): Not Supported

OpenCL API (OpenCL 3.0 CUDA 11.4.125) - Platform #1 [NVIDIA Corporation]
========================================================================
* Device #1: NVIDIA GeForce GTX 1660 Ti, 5376/6144 MB (1536 MB allocatable), 24MCU

OpenCL API (OpenCL 2.1 ) - Platform #2 [Intel(R) Corporation]
=============================================================
* Device #2: Intel(R) UHD Graphics 630, 1568/3214 MB (803 MB allocatable), 24MCU

Minimum password length supported by kernel: 8
Maximum password length supported by kernel: 63

Hashfile 'capture1.hccapx' on line 1 (HCPX♦): Separator unmatched
Hashfile 'capture1.hccapx' on line 2 ("·↑úæF┬m▒∟#◄∟ å/╧èû∞$): Separator unmatched
Hashfile 'capture1.hccapx' on line 3 (): Separator unmatched
No hashes loaded.

Started: Mon Sep 06 12:42:23 2021
Stopped: Mon Sep 06 12:42:24 2021

capture.zip

PCAP file downloads fine but HCCAPX file not

As title says, I can download pcap file just fine but it is empty, but when download HCCAPX it just loads forever.

Wifi RSSI is too low (-93), could it be due to this or it might be that the handshake cannot be captured?

How does it work? "Add connectivity by Bluetooth. Add ability to reset via Bluetooth"

"Add connectivity by Bluetooth. Add ability to reset via Bluetooth"
How can i use the bluetooth to reset the esp32? thanks

not working with arduino as a component

I am currently working on a project that involves using an SSD1306 OLED with the U8g2 library. However, I have encountered some issues as many functions in the U8g2 library are exclusive to Arduino and do not work with the ESP IDF. To resolve this issue, I added an Arduino component(as described here) to my project and the code worked fine.

However, when I attempted to use your project with Arduino as a component, it failed to detect the component and displayed an error message stating that the directory doesn't exist. This error occurs when I use the Arduino config where you use setup() and loop() instead of app_main().
Heres the full error :

What do you think is causing this issue?

ESP32-S3 support

Hi, will there be a version of the precompiled binaries for the newer esp32s3 module? thanks!

Attacks do not appear to be working, ESP32 is not collecting any packet data.

No attacks appear to be working when testing against my home router. I let attacks run for up to 5 minutes and when the attack timer is over there is no packet data collected. No data appears on the screen. The PCAP file will download, but it is always empty and the same size (24 bytes). The HCCAPX file will not download, any attempt to download it results in a download that never downloads anything and never times out. When trying an active de-auth attack, nothing gets kicked off my router like it should, so nothing here seems to be working at all. Can someone please help me figure out if I am doing something wrong, or is this project just defunct? Thank you.

Ultra long range handshake transmission

Hi, kind of an interesting idea, the new LoRa devices, like the TTGO T-Beam, use eps32's and can communicate with other devices using LoRa, which can communicate miles. Any chance your project could be combined with the Meshtastic firmware to capture handshakes, then transmit them to another LoRa device?

Cannot download any file from the site

as in title, im unable to do so. i have an esp32 (not s2/c3) and im getting that sort of an error when following the demo vid

ManagementAP accesspoint is toooo slow

Allow deauth method combination for handshake capture

Similarly to DoS attack type that already have combination of two methods available

Incorrect path to Flash

the correct way would be esptool.py -p /dev/ttyUSB -b 115200 --after hard_reset write_flash --flash_mode dio --flash_freq 40m --flash_size detect 0x8000 partition_table/partition-table.bin 0x1000 bootloader/bootloader.bin 0x10000 esp32-wifi-penetration-tool.bin
the correct path to the 'partition-table.bin' file is:

partition_table/partition-table.bin

The plugin 2500 is deprecated and was replaced with plugin 22000.

Hello,

Please add support for the new format 22000 as hashcat returns this error and never tries to start cracking:

"The plugin 2500 is deprecated and was replaced with plugin 22000."

Otherwise - Awesome tool, thanks!!