franlrs/esp32-captive-poc
GitHub: franlrs/esp32-captive-poc
Stars: 1 | Forks: 0
# 📡 esp32-captive-poc — Educational PoC
-00599C?style=for-the-badge&logo=c%2B%2B)
A comprehensive Proof of Concept (PoC) demonstrating how **Captive Portals** (open WiFi networks that require authentication before allowing internet access) operate on ESP32 microcontrollers. This project emulates the behavior of public networks (such as those in hotels or airports) to study DNS routing, HTTP interception, and local session management.
"Understanding access control in local IoT networks"
### ⚠️ Legal Notice / Disclaimer
**This project was developed strictly for EDUCATIONAL purposes and technical research.**
The provided code is NOT a malicious hacking tool. It is a clone of the legitimate functionality found in captive portals. However, deploying WiFi access points that simulate existing networks without permission (Evil Twin attacks), or logging third-party data without explicit consent is **ILLEGAL**.
By cloning or using this repository, you agree that the author is not responsible for any misuse of the tool. Use it only in closed laboratory networks (e.g., your own home) and on devices you own.
### 📋 Table of Contents
- [Project Overview](#project-overview)
- [Key Features](#key-features)
- [Workflow Diagram](#workflow-diagram)
- [Installation and Deployment](#installation-and-deployment)
- [Admin Panel](#admin-panel)
- [License](#license)
### 🏷️ Project Overview
| Field | Details |
|---|---|
| **Platform** | ESP32, ESP32-S3 |
| **Framework** | Arduino IDE |
| **Dependencies** | `WiFi.h`, `DNSServer.h`, `WebServer.h`, `LittleFS.h` |
| **Default SSID** | Guest WiFi (Test) |
| **Portal IP** | `192.168.4.1` |
| **Core Concepts** | Local DNS Spoofing, HTTP Redirects, Flash File System (LittleFS) |
### ⚙️ Key Features
1. **Wildcard DNS (Local Spoofing):** Similar to commercial portals, the ESP32 runs a DNS server that resolves *any* requested domain to the microcontroller's local IP (`192.168.4.1`), forcing the client's browser to display the splash page.
2. **Automatic OS Detection:** Contains specific endpoint handlers (`/hotspot-detect.html`, `/generate_204`, etc.) to trigger native detection mechanisms in iOS, Android, and Windows, allowing the portal to pop up automatically (CNA - Captive Network Assistant).
3. **Session Management (IP Auth):** Once a user enters their name, their local IP is registered in memory. The web server verifies this IP on every subsequent request.
4. **Persistent Logging System:** Utilizes the flash memory (`LittleFS`) to store a `.csv` audit file containing all access records (Name, IP, parsed Device Type from the `User-Agent`).
### 🔗 Workflow Diagram
flowchart TD
A([📱 Client / Smartphone]) -->|WiFi Connection| B[📶 ESP32 AP\n'Guest WiFi']
B --> C{DNS Request\ne.g. captive.apple.com}
C -->|Resolves to 192.168.4.1| D[ESP32 Web Server]
D --> E{Is IP Authenticated?}
E -->|No| F[Redirect to /login\nRender HTML]
E -->|Yes| G[Return 204/Success code\nClose captive portal]
F --> H[User inputs their name]
H --> I[(💾 LittleFS logs.csv)]
H --> G
### 🚀 Installation and Deployment
1. **Clone the repository:**
git clone [https://github.com/franlrs/esp32-captive-poc.git](https://github.com/franlrs/esp32-captive-poc.git)
2. **Configure the environment:**
* Open `WIFI V1.0.ino` in the Arduino IDE.
* Go to `Tools` > `Partition Scheme` and select at least **"Default 4MB with spiffs/LittleFS"** (Required to store logs).
3. **Change credentials (MANDATORY):**
Locate the following line in the code and change the default administrator password:
const char* ADMIN_PASS = "CHANGE_THIS_PASS_123";
4. **Compile and Upload** to your ESP32.
5. **Connection:** Search for the "Guest WiFi (Test)" network on your mobile device or PC. The registration portal will open automatically.
### 🛡️ Admin Panel
The ESP32 hosts a hidden admin dashboard to visualize metrics and export access audits.
* **URL:** `http://192.168.4.1/admin-logs`
* **Features:**
* Secure cookie-based login.
* Statistics dashboard (Total records, current active devices, uptime).
* Full history view of the CSV file.
* Reset button to clear the audit logs.
* Local download button in `.csv` format.
### 📄 License
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
"Understanding access control in local IoT networks"