digtaalfathir/bayrecon

# BayRecon **适用于实验室的 ESP8266 WiFi 安全与侦察工具包。** 这是一款基于 **Wemos D1 Mini (ESP8266)** 的 WiFi **安全与侦察**工具包，用于在本地/实验室环境中进行研究、学习和测试网络安全。可以通过 **TFT 屏幕 + 3 个按钮**完全独立操作（无需笔记本电脑），也可以通过**串口 CLI** 进行控制。 功能：WiFi 扫描器与嗅探器、统计 station、beacon 泛洪、deauth 监测（防御性）、deauth、精准 deauth，以及带有 captive portal + 密码验证 + 自动 deauth 的 evil twin。 **版本：** 0.2.0 · **状态：** 7 个模块已激活并经过测试，完整的 TFT UI + 锁屏（照片）。  ## ⚠️ 负责任使用 / 免责声明 **仅限于你拥有所有权，或获得书面授权进行测试的网络。** - 用于在本地/实验室环境中进行网络安全**教育与研究**。 - **严禁**在未经许可的情况下访问、攻击或干扰他人的网络/设备。 - 用户**须自行全权负责**遵守所在地区的相关适用法律。 详情：[法律与道德声明](#catatan-legal--etis)。 ## 目录 - [硬件与接线](#hardware--wiring) - [环境配置与构建](#setup--build) - [两种控制方式：TFT 与 CLI](#dua-cara-kontrol-tft--cli) - [功能与使用说明](#fitur--cara-pakai) - [Evil Twin（详情）](#evil-twin-detail) - [代码架构](#arsitektur-kode) - [SDK 补丁 (deauth)](#sdk-patch-deauth) - [疑难解答](#troubleshooting) - [开发路线](#roadmap) - [技术栈](#tech-stack) - [License](#license) - [法律与道德声明](#catatan-legal--etis) ## 硬件与接线 | 组件 | 详情 | |---|---| | **MCU** | Wemos D1 Mini (ESP8266, 4MB flash) | | **显示屏** | TFT 240×280 **ST7789** (SPI, 如 1.69" IPS) | | **输入** | 3 个轻触按键 (UP / DOWN / OK) | | **电源** | USB micro-B / 充电宝 | ### TFT (硬件 SPI) | TFT | Wemos | GPIO | 说明 | |---|---|---|---| | VCC | 3V3 | — | 3.3V | | GND | GND | — | Ground | | SCL/SCK | D5 | 14 | SPI Clock (HSPI) | | SDA/MOSI | D7 | 13 | SPI MOSI (HSPI) | | RES/RST | D0 | 16 | Reset | | DC/A0 | D2 | 4 | Data/Command | | CS | D8 | 15 | Chip Select | | BLK/LED | 3V3 | — | Backlight (常亮) | | 按钮 | Wemos | GPIO | 备注 | |---|---|---|---| | **UP** | D1 | 5 | 空闲引脚 | | **DOWN** | D4 | 2 | 共用板载 LED (轻微闪烁，无害) | | **OK** | D3 | 0 | **开机/复位时切勿按住** (会进入 flash 模式) | ## 环境配置与构建 使用 **PlatformIO**（VSCode 扩展）。库与工具链会在首次构建时自动下载。 ``` # 串口权限 (Linux/Zorin) — 仅需一次 sudo usermod -aG dialout $USER # lalu logout/login ulang sudo apt remove brltty # fix bug CH340 "dibajak" brltty # Build + upload + monitor pio run -t upload && pio device monitor ``` TFT 配置与 SDK 补丁已在 [`platformio.ini`](platformio.ini) 中设置完毕 (build_flags TFT_eSPI + `extra_scripts = pre:patch_sdk.py`)。无需手动编辑库文件。 ## 两种控制方式：TFT 与 CLI 两者**并行**运行，并控制同一个核心引擎。 ### TFT + 按钮 (独立运行) - **UP/DOWN** = 导航 · **OK** = 选择/操作 · **长按 OK** = 返回/停止 - 开机 → **锁屏 (照片)** → 按下 **OK** 解锁 → 显示 8 个功能的菜单 · 在菜单中闲置 30 秒 → 自动返回锁屏 - 需要目标的功能 (统计/deauth/精准/evil) → 从扫描屏幕选择 AP → 显示实时操作界面 ### 串口 CLI (115200 baud) 输入 `help` 获取命令列表： | 命令 | 功能 | |---|---| | `help` / `info` | 帮助 / 设备状态 | | `scan` | 扫描活跃的 AP | | `sniff` / `sniff stop` | promiscuous 嗅探器 | | `channel <1-13>` / `hop [on\|off]` | 频道控制 | | `stats` | 帧计数器 | | `count` / `count stop` | 统计 station (选择 AP) | | `stations` / `stations clear` | 导出所有 AP→client | | `beacon` | beacon 泛洪菜单 | | `dmon` / `dmon stop` / `dmon test` | deauth 监测 | | `deauth` / `deauth stop` | 广播 deauth (选择 AP) | | `pdeauth` / `pdeauth stop` | 针对单一 client 的精准 deauth | | `evil` / `evil stop` | evil twin + portal | ## 功能与使用说明 ### 1. 嗅探器与扫描器 所有模块的基础。实现 802.11 帧的 promiscuous 捕获与频道跳变。 - **TFT → 扫描 AP**: AP 列表 (滚动查看，按 OK 重新扫描)。 - **TFT → 嗅探器**: 实时计数器 (总数/管理帧/数据帧/deauth)；UP/DOWN 切换频道，OK 切换跳频模式。 - **CLI**: `scan`, `sniff`, `channel`, `hop`, `stats`。 ### 2. 统计 Station 统计连接到 1 个目标 AP 的 client 数量。 - **流程**: 选择 AP → 显示实时的 **"N station"** 界面。 - 频道锁定至目标 AP (保证准确性)。MAC 随机化可能导致数值偏高。 - **CLI**: `count` → 选择编号 → `count stop`。 ### 3. Beacon 泛洪 广播大量伪造的 SSID (扫频 ch 1-13)。 - **TFT → Beacon 泛洪**: OK 开始/停止，UP 增加 5 个随机 SSID，DOWN 清除。 - **CLI**: `beacon` → 菜单 (手动/随机/开始)。 - 每帧设置 `delay(1)` 以防止 TX 缓冲区溢出。 ### 4. Deauth 监测 (防御性) 检测 deauth/disassoc 攻击，并在突发流量时触发警报。 - **TFT → Deauth 监测**: 显示 **安全/攻击** 横幅状态与速率；OK = 测试警报 (注入合成帧)。 - **CLI**: `dmon`, `dmon test`, `dmon stop`。默认阈值为 8 帧/秒 ([deauthmon.cpp](src/deauthmon.cpp) `DM_THRESHOLD`)。 ### 5. Deauth (广播) 将目标 AP 的所有 client 踢下线。 - **流程**: 选择 AP → 显示 **攻击中** 横幅与实时成功/失败状态。 - 帧：mgmt subtype 12 + 10，addr1=broadcast，addr2/3=BSSID 伪造。 - **CLI**: `deauth` → 选择编号 → `deauth stop`。 ### 6. 精准 Deauth (针对单一 client) 向特定 client 发送双向的 unicast deauth (更具针对性)。 - **流程**: 选择 AP → 实时收集 client → 选择 client 编号 (或 **">> 所有 client"**) → 发起攻击。 - **CLI**: `pdeauth` → 选择 AP → 输入 client 编号 / `a` 全选 / `r` 重置 / `q`。 ### 7. Evil Twin 请参阅下方专门的章节介绍。 ## Evil Twin (详情) 部署克隆 AP (SSID 相同，但为**开放网络**) + captive portal，以此捕获 Wi-Fi 密码并**向原始 AP 进行验证**。 ### 流程 ``` evil → pilih AP → twin nyala (Auto-deauth default OFF) → korban masuk twin → captive portal "Masuk ke Wi-Fi" (minta password) → SALAH : portal minta ulang → BENAR : halaman "menyelesaikan koneksi" (progress bar ~8s) → deauth auto-OFF → twin auto-bongkar (~9s) → korban auto-reconnect ke AP asli (mulus, tak curiga) ``` ### 自动 deauth (在 Evil Twin 界面按 OK 切换) | | OFF (默认) | ON | |---|---|---| | 原始 AP | 保持正常 | 持续受到 deauth 攻击 | | 受害者接入 twin | 自愿接入 (被诱骗) | 被迫切换 | | 检测情况 | 隐蔽 | 会被 `dmon` 检测到 | | 适用场景 | 公共 Wi-Fi / 新设备 | 强制将设备从活跃 Wi-Fi 踢出 | ### 核心技术说明 - 在运行 portal 期间采用**纯 AP 模式** (关闭 STA) → 保持 DHCP 稳定；STA 仅在验证密码时短暂开启。 - **使用 ESP 默认 MAC** (twin 的 BSSID ≠ 原始 AP) → 自动 deauth 不会将 twin 自身的 client 踢下线。*(克隆自定义 MAC 会导致 ESP8266 上的关联/DHCP 失败，因此避免使用。)* - **实时验证**: 通过 `WiFi.begin(ssid, pwd)` 连接原始 AP — 连接成功即表示密码正确。 - 密码验证成功后实现**自动拆除 (Auto-teardown)** → 网络恢复正常。 ### 局限性 已将原始 AP 保存为 **WPA2** 的设备有时会拒绝加入开放的 twin 网络 (操作系统的防降级保护机制)。Evil twin 对**公共/开放 Wi-Fi**或尚未保存目标网络的设备效果最好。 ## 代码架构 ``` src/ main.cpp entry: init semua modul + loop cli.h/.cpp control plane serial (command + mode input terpandu) buttons.h/.cpp 3 tombol (debounce + long-press = back) ui.h/.cpp UI TFT (menu + layar tiap fitur) sniffer.h/.cpp promiscuous engine (fondasi) + ring buffer + channel hop station.h/.cpp count station beacon.h/.cpp beacon spam deauthmon.h/.cpp deauth monitor (defensif) deauth.h/.cpp deauth broadcast pdeauth.h/.cpp precise deauth per-client evil.h/.cpp evil twin + captive portal + auto-deauth patch_sdk.py pre-build: buka blokir injection deauth di SDK platformio.ini config board + TFT_eSPI + SDK patch hook ``` **引擎→处理器模式**: 分析模块 (station/dmon/pdeauth) 通过 `sniffer_add_handler()` 将处理器挂载到嗅探器上。攻击与 UI 模块调用各个模块的**编程 API** (`*_attack`, `*_on`, `*_stats`) — 因此 CLI 和 TFT 就像是同一个引擎的两个“遥控器”，无需重复编写逻辑代码。 ## SDK 补丁 (deauth) ESP8266 库默认屏蔽了 deauth/disassoc 帧 (`ieee80211_freedom_output` 仅允许发送 data/beacon/probe)。[`patch_sdk.py`](patch_sdk.py) (预构建，自动运行) 会修改所有 NONOSDK 版本中 `libnet80211.a` 的 1 条指令，使得**所有管理帧**都能顺利发送： - 幂等操作 + 自动备份 `.orig` · 每次构建时自动重新应用 - **全局生效** (`~/.platformio/...`) → 会影响此设备上的其他 ESP8266 项目 - **还原**: 删除 `platformio.ini` 中的 `extra_scripts` 行，或通过 `libnet80211.a.orig` 恢复 / 重新安装平台环境 ## 疑难解答 **TFT 相关 (在 [platformio.ini](platformio.ini) / [ui.cpp](src/ui.cpp) 中调整):** | 症状 | 解决方法 | |---|---| | 空白/白屏 | 检查接线 DC=D2, CS=D8, RST=D0, VCC=3V3 | | 反色 | 设置 `-D TFT_INVERSION_OFF=1` | | 红蓝互换 | 设置 `-D TFT_RGB_ORDER=TFT_BGR` | | 画面偏移/反转 | 在 `ui_init()` 中修改 `tft.setRotation(0)` (尝试设为 2) | | 边缘被裁切 | 调大 ui.cpp 中的 `MX` (边距) | **其他:** - `/dev/ttyUSB0: Permission denied` → `dialout` 用户组未生效 (需重新登录)。 - 921600 上传失败 → 设置 `upload_speed = 115200`。 - Beacon/deauth `失败率`偏高 → 确认 SDK 补丁已应用 (查看构建日志 `[BayRecon] ... DIPATCH`)。 - 在网络密集区域嗅探器 `dropped` 数值升高 → 正常现象 (环形缓冲区为 24，回调函数刻意保持轻量化)。锁定 1 个频道可提高准确性。 - Evil twin: 手机无法获取 IP → 确保使用最新版本 (已移除 MAC 克隆功能)。已保存原始 WPA2 的设备 → 需先“忘记”网络才能进行测试。 ## 开发路线 待开发事项 (按优先级排序): 1. 持久化凭证记录 (SPIFFS) + `/log` 页面 2. 多 SSID evil twin 3.额外的 OLED 屏 / 状态指示灯 4. 持久化设置 (LittleFS) 5. PCAP 导出 (Wireshark)，事件记录器 6. OUI 查询 (MAC 厂商)，频道图表 ## 技术栈 | 层级 | 使用技术 | |---|---| | **MCU / 框架** | ESP8266 (Wemos D1 Mini) · Arduino · PlatformIO | | **显示驱动** | TFT_eSPI — ST7789 240×280 | | **WiFi** | ESP8266 NONOS SDK (promiscuous + `wifi_send_pkt_freedom`) | | **存储** | EEPROM (持久化设置) | | **语言与工具** | C/C++ · Python (SDK 补丁 + 图像→头文件转换) | ## License MIT © 2026 Rifky Andigta Al-Fathir — 详见 [LICENSE](LICENSE)。 ## 法律与道德声明 **仅限用于自有网络、受控实验室环境，或获得书面授权的渗透测试 (pentest)。** - ✅ **合法**: 测试自己的路由器、学习 802.11 协议、CTF、已获授权的红队演练。 - ❌ **非法**: 未经授权攻击他人网络、窃取凭证、对公共服务发起 DoS 攻击。 未经授权擅自使用部分功能 (deauth, evil twin, 密码捕获) 属于违法行为。请务必负责任地使用。 *BayRecon — 在 ESP8266 上进行 WiFi 安全探索。坚守道德底线，持续学习。* 🛡️

标签：ESP8266, UML, WiFi审计, 客户端加密, 插件系统, 物联网, 硬件工具, 逆向工具