Eberth-sys/Deauth-Alert-WiFi-IoT-System

用于监控和检测 Wi-Fi 网络中取消认证攻击的 IoT 系统

使用 ESP32 节点、Raspberry Pi、实时警报和 Web 面板对 2.4 GHz Wi-Fi 频谱进行分布式监控。

▶️ 观看演示  ·  🎓 论文答辩 (UBA)  ·  📄 论文 (PDF)

## 概述 | ⚠️ **负责任且经授权的使用** | | :--- | | 本系统将 Wi-Fi 接口配置为混杂模式以检测 802.11 取消认证攻击。请仅在自有网络或获得明确授权的情况下使用。捕获第三方流量可能违反相关法律法规。作者不对任何不当使用承担责任。 | ## 目录 - [概述](#descripción-general) - [架构](#arquitectura) - [技术栈](#tecnologías) - [仓库结构](#estructura-del-repositorio) - [快速开始](#puesta-en-marcha) - [学术证据与公开资源](#evidencia-académica-y-recursos-públicos) - [项目状态](#estado-del-proyecto) - [当前范围](#alcance-actual) - [未来改进](#próximas-mejoras) - [支持项目](#apoye-el-proyecto) - [关于作者](#sobre-el-autor) - [许可证](#licencia) ## 概述 这是一个分布式 IoT 系统，可实时检测 802.11 取消认证攻击。这是一种拒绝服务 攻击，旨在强制断开 Wi-Fi 客户端的连接，并为更复杂的攻击（如伪造接入点 *Evil Twin*）提供便利。 **目标：** - 实时监控 2.4 GHz Wi-Fi 管理流量。 - 通过即时警报（Web 面板、Telegram 和云端）进行早期检测。 - 使用易获取的硬件（ESP32 + Raspberry Pi）实现低成本和可扩展性。 **背景（最新技术现状）：**诸如 *Aircrack-ng* 或 *Wireshark* 之类的工具在分析方面非常有效，但需要持续的人工监督，且无法自动做出响应；商业化的入侵检测解决方案（*WIDS/IPS*）虽然稳健，但价格昂贵且难以进行定制。本项目探索了一种基于 ESP32-WROOM-32U（运行于混杂模式）和 *Bluetooth Low Energy* (BLE) 的自主、低成本替代方案。 ## 架构 系统分为四层，涵盖了从捕获攻击到实时可视化的全过程。  **事件流（检测 → 警报）：** 1. 处于混杂模式的 ESP32 节点捕获 802.11 取消认证*帧*。 2. 节点比对目标 BSSID，如果匹配，则通过 BLE 发出警报。 3. Raspberry Pi 接收警报，将其持久化到 PostgreSQL 中，并发布到 AWS IoT 和 Telegram。 4. FastAPI 后端通过 REST 暴露警报，并通过 WebSocket 进行广播。 5. React 面板实时显示警报。   ## 技术栈 | 层级 | 技术手册 | 技术 | 角色 | | --- | --- | --- | --- | | 感知层 | [Arduino](perception-layer/esp32-nodes-ino/README.md) · [ESP-IDF](perception-layer/espidf-nodes/README.md) | ESP32-WROOM-32U · C/C++ (Arduino `.ino` 和 ESP-IDF `.c`) | 在混杂模式下捕获取消认证*帧*；通过 BLE 发送 | | 处理层 | [处理层](processing-layer/README.md) | Python (`bleak`, `paho-mqtt`, `psycopg2`) · Docker/PostgreSQL | BLE 摄取、持久化、发布 MQTT/AWS IoT 和 Telegram | | 后端 | [后端](backend/README.md) | FastAPI · SQLAlchemy · PostgreSQL · JWT | REST API + WebSocket + 身份验证 | | 前端 | [前端](frontend/README.md) | React · Vite · TypeScript · TailwindCSS | 实时面板 | ### 硬件组件 | 组件 | 系统角色 | | --- | --- | | **ESP32-WROOM-32U** | 感知层的传感器节点。在混杂模式下捕获 802.11 Wi-Fi 帧 (2.4 GHz) 并通过 BLE 发出警报。包含用于外接天线的 U.FL 连接器。 | | **Raspberry Pi 5 (8 GB RAM)** | 中央处理单元。接收 BLE 警报，将其持久化到 PostgreSQL，并发布到 AWS IoT 和 Telegram。 | ### 主要版本 取自 `requirements.txt`、`package.json`、Dockerfiles 和 `docker-compose.yml`。 | 组件 | 版本 | | --- | --- | | Python | 3.11 | | FastAPI · Uvicorn | 0.139 · 0.51 | | SQLAlchemy · Pydantic | 2.0 · 2.13 | | PostgreSQL | 16 | | React · Vite · TypeScript | 19 · 6 · 5.7 | | Node (构建) · nginx | 22 · 1.31 | ## 仓库结构 ``` Deauth-Alert-WiFi-IoT-System/ ├── perception-layer/ # Firmware ESP32 (Arduino .ino + ESP-IDF .c), modo promiscuo ├── processing-layer/ # Raspberry Pi: ingesta BLE, PostgreSQL (Docker), MQTT/AWS, Telegram ├── backend/ # API FastAPI + PostgreSQL + JWT + WebSocket (Dockerfile incluido) ├── frontend/ # Panel React + Vite + TypeScript (Dockerfile + nginx.conf) ├── docs/img/ # Diagramas y banner (SVG) usados en la documentación ├── docker-compose.yml # Conjunto de servicios web: postgres + backend + frontend (docker compose up) ├── .env.example # Plantilla de variables de entorno (los .env reales NO se versionan) ├── .gitignore └── README.md ``` ## 快速开始 **要求：**Docker（用于整套 Web 服务）。对于物理实验环境，还需要：Raspberry Pi (Raspberry Pi OS) · 4× ESP32-WROOM-32U · Python 3.11+ · Node.js 20+。 ``` git clone https://github.com/Eberth-sys/Deauth-Alert-WiFi-IoT-System.git cd Deauth-Alert-WiFi-IoT-System ``` ### 选项 A. 使用 Docker 运行 Web 服务套件（推荐，无需硬件） 只需一条命令即可启动 **postgres + backend + frontend**（通过环境变量进行配置；密钥在**运行时**从 `.env` 中获取，从不硬编码在镜像中）： ``` cp .env.example .env # completar: PG_*, JWT_SECRET_KEY (>=32), SERVICE_API_KEY, CORS_ORIGINS, VITE_* docker compose up --build ``` | 服务 | URL | | --- | --- | | 前端 (面板) | http://localhost:8080 | | 后端 (API + `/docs`) | http://localhost:8000 | | PostgreSQL | localhost:5432 | ### 无需硬件测试（ESP32 节点模拟器） 您还没有硬件，或者想在投资购买设备之前评估该项目？工具 [`tools/simulate_esp32.py`](tools/simulate_esp32.py) 允许您在不购买任何东西的情况下对 Deauth-Alert 进行端到端测试。它会生成与 ESP32 节点检测到攻击时产生的相同警报，并将它们插入到数据库中，且使用与处理层完全相同的列。这样，您就可以在搭建物理实验环境之前，看到面板、警报以及整个流程的运行情况。 在已启动 Web 服务套件（选项 A）的情况下，从仓库根目录运行： ``` # Linux / macOS: 连接变量（与 web-stack 的 .env 中的相同） export PG_HOST=localhost PG_PORT=5432 PG_DB=deauth_alerts \ PG_USER= PG_PASSWORD= pip install psycopg2-binary # solo la primera vez, si no está instalado python tools/simulate_esp32.py --count 10 --interval 2 ``` ``` # Windows PowerShell: 连接变量 $env:PG_HOST="localhost"; $env:PG_PORT="5432"; $env:PG_DB="deauth_alerts" $env:PG_USER=""; $env:PG_PASSWORD="" pip install psycopg2-binary python tools/simulate_esp32.py --count 10 --interval 2 ``` | 参数 | 描述 | 默认值 | | --- | --- | --- | | `--count` | 要发送的警报数量 | 6 | | `--interval` | 每次警报之间的间隔秒数 | 2.0 | 然后登录到面板 (`http://localhost:8080`)，您将看到警报实时出现。生成的 MAC 地址仅为示例（前缀为 `DE:AD:BE:EF` 和 `02:00:00`）；它们并不对应真实的硬件。 ### 选项 B. 手动执行与各层独立开发 **1. 数据库 (Docker 中的 PostgreSQL · 仅边缘层/RPi)** ``` cd processing-layer/docker cp .env.example .env # completar credenciales docker compose up -d # este compose (borde/RPi) levanta SOLO PostgreSQL; conjunto de servicios web completo: Opción A ``` **2. 后端，**使用 `uvicorn`（或在选项 A 的容器内）： ``` cd backend/src cp .env.example .env pip install -r requirements.txt uvicorn main:app --reload # http://localhost:8000 · documentación: /docs ``` **3. 前端** ``` cd frontend cp .env.example .env npm install npm run dev # http://localhost:5173 ``` **4. 处理层 (Raspberry Pi, BLE)** ``` cd processing-layer cp config/devices.yaml.example config/devices.yaml # MAC/UUID de los nodos pip install -r requirements.txt python main.py # requiere Bluetooth (BlueZ) y los ESP32 emparejados ``` **5. ESP32 固件。** 查看 [`perception-layer/`](perception-layer/) 以编译并烧录节点（从模板创建 `config.h`）。 ## 学术证据与公开资源 - 📄 **期末论文 (论文, PDF):** [LSE-FIUBA · CEIoT · 2025](https://lse-posgrados-files.fi.uba.ar/tesis/LSE-FIUBA-Trabajo-Final-CEIoT-Eberth-Gabriel-Alarcon-Gonzalez-2025.pdf) - 📊 **论文演示文稿 (PDF):** [答辩幻灯片](https://lse-posgrados-files.fi.uba.ar/tesis/LSE-FIUBA-Trabajo-Final-CEIoT-Eberth-Gabriel-Alarcon-Gonzalez-2025-Presentacion.pdf) - 🎓 **论文答辩 (UBA, 视频):** [在 YouTube 上观看](https://www.youtube.com/watch?v=JqII7Z1xTyE) - ▶️ **系统演示 (视频):** [在 YouTube 上观看](https://youtu.be/P1Kr70pG77Y) ### 如何引用 ``` @thesis{alarcon2025deauthalert, author = {Alarcón González, Eberth Gabriel}, title = {Sistema IoT para el monitoreo y detección de ataques de desautenticación en redes Wi-Fi}, school = {Universidad de Buenos Aires, Facultad de Ingeniería}, year = {2025}, type = {Trabajo Final de la Carrera de Especialización en Internet de las Cosas} } ``` ## 项目状态 Deauth-Alert 从一开始就设计了面向生产的架构：JWT 身份验证、基于环境变量的配置、可复现的 Docker 容器以及分层结构（感知、处理、后端、前端）。目前它是一个**功能正常的学术原型**，已在具有 ESP32 节点和 Raspberry Pi 的实验室环境中通过验证。有关向生产环境推进时的安全和部署注意事项，请参见 [`SECURITY.md`](SECURITY.md)。 ## 当前范围 - 实时检测 2.4 GHz 频段的 802.11 取消认证攻击。 - 通过 Web 面板、Telegram 和云端 (AWS IoT) 发出警报。 - 使用 Docker (`docker compose up`) 实现可复现的 PostgreSQL、后端和前端部署。 - 感知层 (ESP32 固件) 和处理层 (BLE, Raspberry Pi) 在专用硬件上运行。 ## 未来改进 - 使用带版本控制的 JSON 格式的 ESP32 → Raspberry Pi 通信契约。 - 边缘层的容器化以及使用 ESP-IDF 进行编译。 - 扩大测试覆盖率。 - *(探索性)* 引入 AI 和机器学习用于事件关联和异常检测。 ## 关于作者 **Esp. Ing. Eberth Gabriel Alarcón González** 电子工程师，电信方向 · IoT 专家 ### 👤 专业简介 毕业于 **Rafael Belloso Chacín 大学 (URBE, 2014)** 的电子工程专业（电信方向），并在 **布宜诺斯艾利斯大学 (UBA)** 获得 **IoT** 专家资格。他在信息技术领域拥有十多年的经验，在电信、网络和基础设施方面具有扎实的基础，其职业发展方向专注于网络安全。 目前，他担任 **网络安全工程师**，工作重点是应用于人工智能系统和语言模型 (**IA 和 LLM**) 的安全、**IoT** 环境安全、渗透测试、网络安全和事件响应。 **Deauth-Alert** 是他 IoT 专家资格的期末论文，代表了无线网络、互联设备和应用网络安全的融合。 ### 🎓 教育背景 * **IoT 专家** · 布宜诺斯艾利斯大学, 阿根廷 (**2025**) 期末论文: **Deauth-Alert** * **电子工程, 电信方向** · Rafael Belloso Chacín 大学, 委内瑞拉 (**2014**) ### 🛡️ 专业领域 - 网络安全与事件响应。 - AI 系统和语言模型安全 (IA 和 LLM)。 - IoT 设备和架构安全。 - 渗透测试和漏洞评估。 - 网络和端点安全。 - 电信与网络基础设施。 [](https://www.linkedin.com/in/eberthalarcon90) 工程学院 (FIUBA), 布宜诺斯艾利斯大学 · IoT 专家资格项目 ## 许可证 本仓库的代码和原创文档基于 Apache 2.0 许可证分发。有关使用条款，请参阅 [LICENSE](LICENSE)；有关归属、商标和排除的材料，请参阅 [NOTICE](NOTICE)。 © 2025-2026 Esp. Ing. Eberth Gabriel Alarcón González.

标签：AV绕过, ESP32, FastAPI, React, Syscalls, UML, Wi-Fi监控, 测试用例, 物联网, 网络安全, 自动化攻击, 请求拦截, 逆向工具, 隐私保护