franlrs/esp32-captive-poc
GitHub: franlrs/esp32-captive-poc
在 ESP32 微控制器上实现强制门户的教学概念验证，用于演示和研究 IoT 本地网络中的 DNS 路由、HTTP 拦截与会话管理机制。
Stars: 1 | Forks: 0
# 📡 esp32-captive-poc — 教学概念验证
-00599C?style=for-the-badge&logo=c%2B%2B)
一个全面的概念验证，展示了**强制门户**（在允许访问互联网之前需要身份验证的开放 WiFi 网络）如何在 ESP32 微控制器上运行。该项目模拟了公共网络（例如酒店或机场中的网络）的行为，以研究 DNS 路由、HTTP 拦截和本地会话管理。
"Understanding access control in local IoT networks"
### ⚠️ 法律声明 / 免责声明
**本项目严格出于教学目的和技术研究而开发。**
提供的代码不是恶意的黑客工具。它是强制门户中合法功能的克隆。但是，未经许可部署模拟现有网络的 WiFi 接入点（Evil Twin 攻击），或未经明确同意记录第三方数据是**违法**的。
通过克隆或使用此代码库，您同意作者不对该工具的任何滥用行为负责。仅在封闭的实验室网络（例如您自己的家中）以及您拥有的设备上使用它。
### 📋 目录
- [项目概述](#project-overview)
- [核心功能](#key-features)
- [工作流程图](#workflow-diagram)
- [安装与部署](#installation-and-deployment)
- [管理面板](#admin-panel)
- [许可证](#license)
### 🏷️ 项目概述
| 字段 | 详情 |
|---|---|
| **平台** | ESP32, ESP32-S3 |
| **框架** | Arduino IDE |
| **依赖项** | `WiFi.h`, `DNSServer.h`, `WebServer.h`, `LittleFS.h` |
| **默认 SSID** | Guest WiFi (Test) |
| **门户 IP** | `192.168.4.1` |
| **核心概念** | 本地 DNS 欺骗, HTTP 重定向, 闪存文件系统 |
### ⚙️ 核心功能
1. **泛域名 DNS（本地欺骗）：** 与商业门户类似，ESP32 运行一个 DNS 服务器，将*任何*请求的域名解析为微控制器的本地 IP（`192.168.4.1`），从而强制客户端浏览器显示引导页面。
2. **自动操作系统检测：** 包含特定的端点处理器（`/hotspot-detect.html`, `/generate_204` 等），以触发 iOS、Android 和 Windows 中的原生检测机制，允许门户自动弹出（CNA - 强制网络助手）。
3. **会话管理（IP 认证）：** 用户输入其姓名后，其本地 IP 将被注册到内存中。Web 服务器会在后续的每个请求中验证此 IP。
4. **持久化日志系统：** 利用闪存（`LittleFS`）存储一个 `.csv` 审计文件，其中包含所有访问记录（姓名、IP、从 `User-Agent` 解析出的设备类型）。
### 🔗 工作流程图
```
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
```
### 🚀 安装与部署
**前置条件：** 已安装 Arduino IDE，已配置 ESP32 开发板支持。
1. **克隆代码库：**
```
git clone [https://github.com/franlrs/esp32-captive-poc.git](https://github.com/franlrs/esp32-captive-poc.git)
```
2. **配置环境：**
* 在 Arduino IDE 中打开 `WIFI V1.0.ino`。
* 转到 `Tools`（工具） > `Partition Scheme`（分区方案） 并至少选择 **"Default 4MB with spiffs/LittleFS"**（存储日志所需）。
3. **更改凭据（强制）：**
在代码中找到以下行并更改默认管理员密码：
```
const char* ADMIN_PASS = "CHANGE_THIS_PASS_123";
```
4. **编译并上传**到您的 ESP32。
5. **连接：** 在您的移动设备或 PC 上搜索 "Guest WiFi (Test)" 网络。注册门户将自动打开。
### 🛡️ 管理面板
ESP32 托管了一个隐藏的管理仪表板，用于可视化指标并导出访问审计。
* **URL：** `http://192.168.4.1/admin-logs`
* **功能：**
* 基于 cookie 的安全登录。
* 统计仪表板（总记录数、当前活动设备、正常运行时间）。
* CSV 文件的完整历史记录视图。
* 用于清除审计日志的重置按钮。
* `.csv` 格式的本地下载按钮。
### 📄 许可证
本项目基于 MIT 许可证授权 - 有关详细信息，请参阅 [LICENSE](LICENSE) 文件。
"Understanding access control in local IoT networks"
标签：C++, ESP32, 强制门户, 教育演示, 数据擦除, 物联网, 网络访问控制