zero1byte/FrameHunter32

# ESP32 WPA2 握手抓包器 一个裸机 ESP-IDF 固件，用于在 ESP32 上被动捕获 Wi-Fi 上的 WPA2 4 路 EAPOL 握手，并以可通过 `aircrack-ng` 进行离线密码分析的格式输出结果。 ## 功能 - **交互式 UART shell** — 通过波特率为 115200 的串口监视器输入命令 - **AP 扫描器** — 主动扫描并列出 SSID、BSSID、信道、安全类型和 RSSI - **Beacon 嗅探器** — 通用混杂模式捕获 802.11 beacon 帧 - **握手捕获** — 双阶段引擎，先搜寻目标 beacon，然后捕获完整的 WPA2 4 路 EAPOL 交换 - **Deauthentication** — 注入原始的 802.11 deauth 帧，强制客户端重新关联（从而触发握手） - **text2pcap 输出** — 以可直接转换为 `.pcap` 格式的 hex dump 输出，供 Wireshark 和 aircrack-ng 使用 - **Ctrl+C 中断** — 随时按 `Ctrl+C` 可取消正在运行的捕获并返回提示符 ## 硬件要求 - ESP32 开发板（任何带有 Wi-Fi 的型号） - 通过 USB 串口连接到运行 `idf.py monitor` 的主机 ## 软件要求 | 工具 | 版本 | |---|---| | ESP-IDF | v5.x（也兼容 v4.4+） | | Python | 3.8+（IDF 依赖项） | | text2pcap | Wireshark 的一部分 — `sudo apt install wireshark-common` | | aircrack-ng | `sudo apt install aircrack-ng` | ## 项目结构 ``` . ├── main.c # app_main: UART init, NVS init, spawns CLI task ├── cli.c / .h # Interactive UART shell, argument parser, Ctrl+C abort ├── sniffer.c / .h # Generic promiscuous beacon capture engine ├── handshake.c / .h# Two-phase beacon + EAPOL capture engine ├── deauth.c / .h # Raw 802.11 deauth frame injection ├── wifi_mgr.c / .h # Wi-Fi driver lifecycle (idempotent init/start/stop) └── CMakeLists.txt # IDF component registration ``` ## 构建与烧录 ``` # 设置 IDF 环境（根据您的 IDF 安装路径进行调整） . $IDF_PATH/export.sh # 配置目标 idf.py set-target esp32 # 构建 idf.py build # 烧录并打开串口监视器（根据需要调整端口） idf.py -p /dev/ttyUSB0 flash monitor ``` ## Shell 命令 监视器打开后，您将看到 `esp32>` 提示符。 ### `help` 打印命令参考。 ### `scan` 运行主动 802.11 扫描，列出附近所有接入点的 SSID、BSSID、信道、安全类型和 RSSI。适用于在运行 `handshake` 之前查找目标 AP 的信道和 BSSID。 ``` esp32> scan ``` ### `config` 显示当前持久化设置（信道、SSID、BSSID、STA MAC）。 ``` esp32> config ``` ### `sniffer [选项]` 在已配置的信道上启动针对 beacon 帧的通用混杂模式捕获。在捕获到请求的帧数（默认为 10）后停止，并以 text2pcap 格式输出。 ``` esp32> sniffer --channel 6 --ssid MyNetwork esp32> sniffer --channel 6 --ssid "My Home Network" --count 20 esp32> sniffer --count 5 ``` **选项** | 选项 | 默认值 | 描述 | |---|---|---| | `--ssid <名称>` | （任意） | 按 SSID 过滤。如果 SSID 包含空格，请使用引号。 | | `--channel <1-13>` | 6 | 要监听的 802.11 信道。 | | `--bssid ` | （任意） | 按 AP MAC 地址过滤。 | | `--count <1-50>` | 10 | 在停止前要捕获的 beacon 帧数量。 | ### `handshake [选项]` 双阶段阻塞式捕获： - **阶段 1** — 在指定信道上搜寻匹配 `--ssid` / `--bssid` 的 beacon - **阶段 2** — 切换到 DATA 帧捕获，并收集 4 路 EAPOL 交换（M1–M4） ``` esp32> handshake --channel 1 --ssid MyNetwork esp32> handshake --channel 6 --ssid "JioFiber Home" --bssid AA:BB:CC:DD:EE:FF esp32> handshake --channel 6 --bssid AA:BB:CC:DD:EE:FF ``` 选项是**持久化**的 — 设置一次后，它们将应用于随后的每条命令，直到被更改： ``` esp32> handshake --channel 6 esp32> handshake --ssid JioFiber-A6ceM # channel 6 still applies ``` **包含空格的 SSID** 必须用双引号或单引号括起来： ``` esp32> handshake --ssid "My Home Network" esp32> sniffer --ssid 'Office WiFi 5G' --count 15 ``` ### `deauth --bssid --sta-mac <客户端>` 注入针对特定客户端的原始 802.11 deauthentication 帧。强制客户端重新关联，从而触发 `handshake` 可以捕获的新的 WPA2 握手。 ``` esp32> deauth --bssid AA:BB:CC:DD:EE:FF --sta-mac 11:22:33:44:55:66 ``` ### Ctrl+C 在任何阻塞命令（`scan`、`sniffer`、`handshake`）执行期间按 **Ctrl+C** 可干净地中止捕获并返回 `esp32>` 提示符。返回前会优雅地断开 Wi-Fi。 ## 捕获工作流 ### 步骤 1 — 寻找目标 ``` esp32> scan ``` 记下目标 AP 的 SSID、BSSID 和信道。 ### 步骤 2 — （可选）对客户端进行 Deauth 以强制握手 ``` esp32> deauth --bssid AA:BB:CC:DD:EE:FF --sta-mac 11:22:33:44:55:66 ``` ### 步骤 3 — 捕获握手 ``` esp32> handshake --channel 6 --ssid MyNetwork ``` Shell 将打印： ``` [Phase 1] Hunting beacon on channel 6 for SSID "MyNetwork" ... [Phase 1] Beacon captured! BSSID : AA:BB:CC:DD:EE:FF [Phase 2] Capturing EAPOL 4-way handshake (need 4 frames)... [Phase 2] EAPOL frames: 1 / 4 [Phase 2] EAPOL frames: 2 / 4 [Phase 2] EAPOL frames: 3 / 4 [Phase 2] EAPOL frames: 4 / 4 -- done. ``` 随后是 text2pcap 格式的 hex dump。 ### 步骤 4 — 转换为 pcap 将串口监视器输出中的 hex dump 复制到 `capture.txt` 文件中，然后执行： ``` text2pcap -F pcap -l 105 capture.txt out.pcap ``` `-l 105` 标志将链路层类型设置为 IEEE 802.11（原始帧，无 radiotap header，无 FCS）。 ### 步骤 5 — 破解密码 ``` aircrack-ng out.pcap -w /usr/share/wordlists/rockyou.txt ``` ## 架构说明 ### 为什么需要两个阶段？ ESP32 的混杂模式过滤器一次只能高效地通过一种帧类型。阶段 1 使用 `WIFI_PROMIS_FILTER_MASK_MGMT` 快速找到目标 beacon 并获取其 BSSID。阶段 2 切换到 `WIFI_PROMIS_FILTER_MASK_DATA` 以接收 EAPOL DATA 帧。过滤器切换发生在 CLI 任务中（而不是在回调内部），因为不能在 Wi-Fi 任务上下文中调用 ESP-IDF 驱动 API。 ### 为什么在回调上使用 IRAM_ATTR？ 混杂模式回调运行在 Wi-Fi 驱动任务内部。将它们放在 IRAM 中可以避免高帧率捕获期间的 flash 指令缓存停顿，否则会导致帧丢失。 ### 密码错误 resilience EAPOL 状态机处理了 AP 在密码尝试失败后（例如在重连期间）重传 Message 1 的情况。当检测到序列违规时，`eapol_sequence_reset()` 会将帧缓冲区指针回滚到 beacon 之后，这样旧帧就会被覆盖，而不是累积并填满缓冲区。如果不进行此修复，缓冲区将在失败的尝试中被填满，并且 `store_frame()` 会静默丢弃随后正确握手中的每一帧。 ## 已知限制 - ESP32 的 2.4 GHz 无线电仅支持 1-13 信道。无法扫描到 5 GHz 网络。 - `deauth` 使用的 `esp_wifi_80211_tx` 是非官方的 IDF API。它在当前的 IDF 版本上可以正常工作，但不属于公开的稳定 API。 - UART shell 每次读取一个字符；除了退格之外，没有命令历史记录或行编辑功能。 - 捕获的帧存储在 RAM 中。缓冲区对于嗅探器最多可容纳 10 个帧，对于握手引擎最多可容纳 5 个帧（1 个 beacon + 4 个 EAPOL）。如果在超过可用 DRAM 的情况下增加 `MAX_SNIFF_PACKETS` 或 `MAX_FRAME_SIZE`，将导致启动时的断言失败。 ## 法律声明 本工具仅供**授权的安全测试和教育目的**使用。在您不拥有或未获得明确书面测试许可的网络上捕获网络流量或注入 deauthentication 帧可能在您的司法管辖区属于违法行为。作者对任何滥用行为不承担责任。

标签：客户端加密