A powerful, cross-platform Python toolkit for Wi-Fi deauthentication testing using only an ESP32 board and a data cable. With a simple command-line interface and interactive menus, you can easily erase and flash your ESP32, scan for Wi-Fi networks, and launch a variety of wireless attacks—all from your terminal. The tool also provides seamless WiFi reconnection to the ESP32's ManagementAP WiFi network (SSID: ManagementAP
, password: mgmtadmin
) on Windows, Linux, and macOS.
Supports continuous or unlimited attack looping—run attacks in a loop for as long as needed (e.g., for stress testing or research).
> **If you like this project, please consider giving it a star ⭐️ on GitHub. Your support motivates me to keep improving it!
To use the ESP32 Deauthentication Tool, you will need:
-
ESP32 Board:
Any ESP32 development board (e.g., ESP32-WROOM-32) is supported.The tool is designed for use with standard ESP32 boards and has been tested with models such as the ESP32-WROOM-32.
-
USB Data Cable:
A USB cable with data lines (not just charging) to connect the ESP32 to your computer for flashing and serial communication. -
Computer:
A Windows, Linux, or macOS machine with Python 3.7+ installed.
No additional Wi-Fi adapters or special hardware are required—just a standard ESP32 board and a USB cable.
-
One-Command Flashing:
Effortlessly erase and flash your ESP32 with the included firmware (bootloader.bin
,partition-table.bin
,esp32-wifi-penetration-tool.bin
) using simple CLI commands. -
Interactive Attack Console:
Scan for nearby Wi-Fi networks, select targets, and launch attacks via an intuitive interactive menu. -
Automated WiFi Reconnection:
Automatically reconnect your computer to the ESP32's ManagementAP WiFi network (password:mgmtadmin
) using native tools:
• Windows:netsh
• Linux:nmcli
• macOS:networksetup
-
Flexible Attack Modes:
Supports multiple attack types, including deauthentication (DoS), handshake capture, and PMKID collection. -
Unlimited/Looping Attacks:
Supports continuous or unlimited attack looping—run attacks in a loop for as long as needed (e.g., for stress testing or research). -
Cross-Platform Support:
Works on Windows, Linux, and macOS—no manual driver or interface setup required. -
Easy Installation:
Install directly from PyPI with all dependencies and firmware included. -
Educational & Research Focused:
Designed for cybersecurity students, researchers, and professionals to learn about Wi-Fi security in a controlled environment.
- Python 3.7 or newer
- ESP32 board (e.g., ESP32-WROOM-32)
- USB cable with data wires
- Windows 10/11, Linux (e.g., Ubuntu with
nmcli
), or macOS for WiFi operations sudo
privileges for Linux/macOS WiFi reconnection- Firmware files (included in the package)
To avoid dependency conflicts, create and activate a Python virtual environment:
python -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
Install esp32-deauth
via pip:
pip install esp32-deauth
Erase the ESP32's flash memory to ensure a clean slate before flashing:
esp32-deauth erase --port COM3
--port
: Serial port (e.g.,COM3
on Windows,/dev/ttyUSB0
on Linux/macOS).--baud
: Baud rate (default: 115200).
Example (Linux/macOS):
esp32-deauth erase --port /dev/ttyUSB0 --baud 115200
Flash the ESP32 with the included firmware files:
esp32-deauth flash --port COM3
--port
: Serial port.--baud
: Baud rate (default: 115200).
Example (Linux/macOS):
esp32-deauth flash --port /dev/ttyUSB0 --baud 115200
This command uses esptool
to write:
bootloader.bin
at0x1000
partition-table.bin
at0x8000
esp32-wifi-penetration-tool.bin
at0x10000
Launch the interactive Wi-Fi attack tool to scan networks, select targets, and perform attacks:
sudo esp32-deauth run
- Note:
sudo
is required on Linux/macOS for WiFi reconnection (nmcli
ornetworksetup
). - Connect to the ESP32's
ManagementAP
WiFi network before running. - The interactive menu offers:
- Scan WiFi Networks
- Attack Single Network
- Attack Multiple Selected Networks
- Attack All Networks
- Exit
Example Output:
=== ESP32 WiFi Attack Tool ===
1. Scan WiFi Networks
2. Attack Single Network
3. Attack Multiple Selected Networks
4. Attack All Networks
5. Exit
Select option:
Scan for available Wi-Fi networks and display their details (SSID, BSSID, RSSI):
sudo esp32-deauth scan
Example Output:
+----+----------+-------------------+-------+
| ID | SSID | BSSID | RSSI |
+----+----------+-------------------+-------+
| 0 | Network1 | 00:11:22:33:44:55 | -50 |
| 1 | Network2 | 66:77:88:99:AA:BB | -60 |
+----+----------+-------------------+-------+
Perform a deauthentication attack on a specific access point:
sudo esp32-deauth attack --ap-id 0 --attack-type DOS --attack-method DEAUTH_BROADCAST --timeout 225 --continuous
--ap-id
: ID of the target AP (fromscan
output).--attack-type
: Attack type (PASSIVE
,HANDSHAKE
,PMKID
,DOS
; default:DOS
).--attack-method
: Method (e.g.,DEAUTH_BROADCAST
,DEAUTH_ROGUE_AP
; default:DEAUTH_BROADCAST
).--timeout
: Attack duration in seconds (default: 225).--continuous
: Run attack in a continuous/unlimited loop (optional).
When--continuous
is set, the attack will loop indefinitely until manually stopped (Ctrl+C).
Example: Attack AP with ID 0 in continuous DOS mode:
sudo esp32-deauth attack --ap-id 0 --attack-type DOS --attack-method DEAUTH_BROADCAST --timeout 225 --continuous
You can run attacks in an unlimited loop for as long as you want by using the --continuous
flag. This is useful for stress testing or long-term research scenarios. The attack will repeat automatically until you interrupt it (Ctrl+C).
- Port Not Found: Ensure the ESP32 is connected and the port is correct (e.g.,
ls /dev/tty*
on Linux/macOS, Device Manager on Windows). - WiFi Reconnection Fails:
- Windows: Ensure
netsh
can seeManagementAP
(netsh wlan show networks
). - Linux: Verify
nmcli
is installed (sudo apt install network-manager
) and the WiFi interface is detected. - macOS: Ensure
sudo
is used andnetworksetup
can access the WiFi interface.
- Windows: Ensure
- Server Unreachable: Confirm the ESP32 is flashed with the correct firmware and connected to
ManagementAP
. - Permission Errors: Use
sudo
for Linux/macOS commands requiring WiFi or serial port access.
The ESP32 Deauthentication Tool supports several Wi-Fi attack types, each implemented in the deauth.py module and selectable via the CLI or interactive menu. Here’s a brief explanation of each:
- Description:
Performs passive monitoring of Wi-Fi traffic. No active attack is launched; instead, the ESP32 listens for packets, which can be useful for reconnaissance or gathering information about nearby networks. - Reference:
Seeattack_types = {'PASSIVE': 0, ...}
indeauth.py
.
- Description:
Captures WPA/WPA2 4-way handshakes by deauthenticating clients from the target AP, forcing them to reconnect. The handshake can then be used for offline password cracking. - How it works:
The ESP32 sends deauthentication frames to clients, then listens for the handshake packets as clients reconnect. - Reference:
Seeattack_types = {'HANDSHAKE': 1, ...}
andformat_handshake()
indeauth.py
.
- Description:
Attempts to capture the PMKID (Pairwise Master Key Identifier) from the target AP. PMKID can sometimes be obtained without client interaction and is used for faster WPA2 password cracking. - How it works:
The ESP32 requests the PMKID from the AP and saves it if available. - Reference:
Seeattack_types = {'PMKID': 2, ...}
andformat_pmkid()
indeauth.py
.
- Description:
Performs a denial-of-service attack by sending continuous deauthentication frames to disconnect clients from the target AP. - Attack Methods:
DEAUTH_ROGUE_AP
: Imitates a rogue AP to confuse clients.DEAUTH_BROADCAST
: Sends broadcast deauth frames to all clients.DEAUTH_COMBINE_ALL
: Uses multiple deauth techniques together.
- Reference:
Seeattack_types = {'DOS': 3, ...}
andattack_methods
indeauth.py
.
Each attack type and method is selectable in the interactive menu or via CLI options. For implementation details, see the esp32_deauth/deauth.py source file.
esp32-deauth/
├── esp32_deauth/
│ ├── __init__.py
│ ├── cli.py
│ ├── deauth.py
│ ├── firmware/
│ │ ├── esp32-wifi-penetration-tool.bin
│ │ ├── partition-table.bin
│ │ ├── bootloader.bin
├── README.md
├── setup.py
├── LICENSE
- Clone or download the repository:
git clone https://github.com/Ishanoshada/Esp32-Deauth.git cd Esp32-Deauth
- Create a virtual environment:
python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
- Install dependencies:
pip install -r requirements.txt
- Install the package locally:
pip install -e .
- Run tests:
python -m unittest discover tests
Contributions are welcome! Please:
- Fork the repository.
- Create a feature branch (
git checkout -b feature/your-feature
). - Commit changes (
git commit -m "Add your feature"
). - Push to the branch (
git push origin feature/your-feature
). - Open a pull request.
Contact: ishan.kodithuwakku.officals@gmail.com
GNU General Public License v2.0 (see LICENSE
file).
- Inspired by the need for educational tools in cybersecurity research.
- Firmware is based on esp32-wifi-penetration-tool by risinek.
- Thanks to the Python,
esptool
, and Flask communities for their excellent libraries. - Built with contributions from the open-source community.