A professional-grade Network Security Research and Simulation Tool designed for the ESP8266 platform. This repository provides an all-in-one hardware and software simulation of the Evil Twin Attack—a classic phishing methodology used to demonstrate vulnerabilities in wireless clients and educate users on Wi-Fi security.
The ESP8266 Evil Twin demonstrates how rogue access points can impersonate legitimate networks to credential-harvest. Unlike basic captive portal scripts, this project features Real-time Password Verification by momentarily checking entered credentials against the target access point. If the credentials fail verification, the victim is prompted to re-enter them; if they succeed, they are persisted locally and the attack automatically stops.
This tool is designed for penetration testers, security educators, and students wanting to explore physical computing and cyber-security simulation on resource-constrained microcontrollers. It features both a physical control panel (OLED display + button controls) and a responsive web-based administration dashboard.
- Real-time Verification: Disconnects temporarily to test captured passwords against the actual target AP (
WL_CONNECTED), ensuring zero "garbage" credentials. - Physical Interface: Supports a 128x64 I2C OLED display and a 4-button tactile interface (Up, Down, Select, Back) for independent, PC-free field operations.
- Responsive Admin Panel: A clean web dashboard (
/menu) featuring dark/light modes, live connection stats, target scanning, and credential log management. - Persistent EEPROM Storage: Captured logs are stored securely in the ESP8266's EEPROM and persist across system power cycles.
- Smart Hardware Optimization: Uses asynchronous scanning and a 500ms button state debounce guard to keep the hardware responsive under CPU loads.
- Edge-Case Resilience: Automatically handles DNS redirection for any address requested by connected clients, forcing them to the validation portal page.
- Microcontroller Core: C++ / Arduino Framework (ESP8266 Arduino Core)
- Web UI & Captive Portal: Semantic HTML5, Vanilla CSS3 (Variables, Dark/Light theme support), and lightweight JavaScript
- Hardware Integration:
Adafruit_SSD1306&Adafruit_GFXlibraries (I2C) - Data Persistence: Internal EEPROM emulation
Note
Hardware schematics and physical interface references are available in the project directory.
| OLED Display (Physical UI) | Admin Dashboard (/menu) |
Captive Portal (Victim View) |
|---|---|---|
 |
 |
 |
To build the standalone hardware unit, wire the components according to the diagram below.
- Refer to esp8266 oled connection.png and esp8266 Buttons Connections.png inside the
ALL Connectionsdirectory for complete physical layouts.
| Component | Pin (ESP8266 / NodeMCU) | GPIO Mapping | Notes |
|---|---|---|---|
| OLED SDA | D1 | GPIO 5 | I2C Data Line |
| OLED SCL | D2 | GPIO 4 | I2C Clock Line |
| Button UP | D3 | GPIO 0 | Navigation Up (Internal Pullup) |
| Button DOWN | D6 | GPIO 12 | Navigation Down (Internal Pullup) |
| Button SELECT | D7 | GPIO 13 | Menu Confirmation (Internal Pullup) |
| Button BACK | D5 | GPIO 14 | Back / Cancel Option (Internal Pullup) |
- Navigate to the
Bin Filedirectory to locateEVIL_TWINS_ESP8266.ino.bin. - Connect your NodeMCU or generic ESP8266 to your computer via micro-USB.
- Open NodeMCU PyFlasher (or use
esptool.pyvia command line). - Configure the following flash parameters:
- Flash Mode:
DIO - Baud Rate:
115200 - Flash Frequency:
160MHz(Required for handling captive portal web traffic smoothly)
- Flash Mode:
- Select the bin file and click Flash.
- Prerequisites: Install Arduino IDE or VS Code with the PlatformIO Extension.
- Add ESP8266 board support via the Boards Manager:
http://arduino.esp8266.com/stable/package_esp8266com_index.json - Install the required libraries via Library Manager:
Adafruit SSD1306(for the OLED)Adafruit GFX Library
- Open the source sketch directory (
EVIL_TWINS_ESP8266.ino). - Select NodeMCU 1.0 (ESP-12E Module), choose your COM Port, compile, and upload.
- Booting up: Connect power via USB. The OLED display initializes and prints a splash screen.
- Scanning: Use the physical buttons (or the Web Dashboard) to select
Scan Networks. The system performs an asynchronous scan to record local SSIDs. - Cloning: Select your target network from the generated list and press the
SELECTbutton to launch the attack. - Baiting: The ESP8266 starts a SoftAP with the same SSID name and redirects any client attempting to access the internet to the local security portal (
192.168.4.1). - Admin Access: You can access the management panel at any time by connecting to the AP and navigating to
http://192.168.4.1/menuin your browser. - Capture: When a user enters a password, the ESP8266 pauses the AP, connects to the authentic AP, and tests the credentials. Correct credentials stop the simulation and save the password directly to the EEPROM logs.
This tool is strictly developed for educational and authorized network security testing purposes only. Unauthorized targeting, intercepting, or credential capturing on communication systems you do not own or lack written permission to audit is illegal. The author (@chetanngavali) and contributors assume no liability for misuse, damages, or violations of privacy laws resulting from using this software.
Contributions make the open-source community an amazing place to learn, inspire, and create. Please see our CONTRIBUTING.md for guidelines on code styling, PR submissions, and setup details.
This project is licensed under the MIT License. See the LICENSE file for the full license text.
Developed with 💎 by Chetan Gavali
- GitHub: @chetanngavali
- Issues: GitHub Issues Tracker