BadRat-in/wifikit

# wifikit **一个终端 UI + CLI，用于驱动运行 [ESP32 Marauder][marauder] 固件的 ESP32 —— 专用于授权的 WiFi 安全测试与学习。** [](LICENSE) [](https://www.python.org/) [](https://github.com/BadRat-in/wifikit/actions/workflows/ci.yml) [](https://github.com/astral-sh/ruff) [](https://github.com/Textualize/textual) [](CONTRIBUTING.md) `wifikit` 将原始的 Marauder 串口命令行转换为一个单屏的、 面向目标的仪表板。无需死记硬背命令，也无需在多个终端中繁琐地切换 aircrack-ng 工作流（这里开 airodump，那里开 aireplay，第三个窗口跑 aircrack），你可以直接**扫描**，**从实时表格中选择目标**，并通过菜单或快捷键对其进行操作 —— 然后在同一个 UI 中执行主机端的破解。

## ⚠️ 法律与授权使用须知 这是一个**仅限授权安全测试和教育**使用的工具。攻击 非本人所有或未经**明确书面授权**测试的网络， 在大多数司法管辖区都是非法的。 - 仅对你**自己拥有**的/设备或你有合同授权评估的网络/设备使用 `wifikit`。 - Deauth（取消认证）和握手抓包会影响网络上的真实用户——切勿 对第三方执行这些操作。 - 作者对滥用行为**不承担任何责任**。使用本软件即表示 你同意自行负责遵守所有适用的法律。 `wifikit` 是一个*前端*：它驱动已开源的 ESP32 Marauder 固件以及 `hashcat`/`aircrack-ng` 等标准工具。它不包含任何新的 攻击代码。 ## 功能 - 🖥️ **Textual TUI**（默认）：实时 AP 表格、选项卡式布局、支持鼠标 + 键盘。 - 🎯 **面向目标**：选择一个 AP，然后执行 Deauth / 抓取 PMKID / 抓取 握手包 / 设置信道 —— 通过操作菜单（Enter 键或右键单击）或快捷键。 - 👥 **Stations（工作站）选项卡**：按 AP 分组的客户端（通过 Marauder 的 `list -c` 实现），在 扫描期间实时填充；选择一个工作站可直接对其进行 deauth。 - 📥 **免 SD 卡抓包**：`wifikit --capture --channel N` 通过 USB（使用 Marauder 的 `-serial`）将 pcap 数据流传输到 `captures/` 目录 —— 无需 microSD 卡。 - 🔌 **自动检测** ESP32 的串口（通过 USB-UART 芯片识别），自动忽略 蓝牙/调试端口。 - ⌨️ **优秀的 REPL**（`--cli`）：支持本地回显、历史记录和 Tab 补全 —— 完美替代由于 Marauder 的无回显 CLI 而变得极其难用的 `screen`。 - 🤖 **可脚本化**的一次性执行模式（`--exec "scanall"`）。 - 🧨 **集成破解功能**：在 Crack 选项卡中运行 `hashcat`/`aircrack-ng` 并实时 输出流 —— 在一个地方完成 扫描 → deauth → 抓包 → 破解。 - ⚡ **一键刷入**正确的经典 ESP32 构建版本（`wifikit-flash`）。 ``` ● /dev/cu.usbserial-…. | SCANNING | APs: 4 | [s]can [x]stop [r]efresh ┌ Targets ─┬ Console ─┬ Crack ─────────────────────────────────────────────────┐ │ Idx CH ESSID / BSSID RSSI │ │ 0 3 rb_alderson -72 ← cursor; press Enter for Actions │ │ 1 3 8e:86:dd:a0:8b:68 -73 │ │ 2 3 rb_alderson -84 │ └──────────────────────────────────────────────────────────────────────────────┘ s Scan x Stop r Refresh a Actions d Deauth p PMKID ^r Reconnect q Quit ``` ## 文档 完整指南位于 [`docs/`](docs/index.md) 目录中： - [概述与心智模型](docs/index.md) — wifikit 是什么以及如何导航操作。 - [架构](docs/architecture.md) — 模块、数据流、线程。 - [使用说明](docs/usage.md) — 刷写固件、TUI、CLI/REPL、快捷键。 - [抓包 → 破解](docs/capture-to-crack.md) — 免 SD 卡的 `-serial` 工作流。 - [性能与 GPU](docs/performance.md) — 实测破解速率，`--benchmark`。 - [固件](docs/firmware.md) — Marauder 构建版本、`-serial`、未来计划。 - [故障排除](docs/troubleshooting.md) — 端口、波特率、抓包问题等。 ## 硬件 - 一块 **ESP32** 开发板（在经典的 **ESP32-WROOM-32** DevKit 上开发并测试通过），需刷入 **ESP32 Marauder**。 - **microSD 模块** (SPI) 为**可选** —— 抓包可通过 Marauder 的 `-serial` 经由 USB 流传输， 因此只有在进行*脱机*抓包（脱离主机运行开发板）时才需要 SD 卡。 ## 安装 要求 Python 3.10+。使用 [uv][uv]（推荐）： ``` uv tool install wifikit # once published to PyPI # 或者从 clone 运行： uv venv && uv pip install -e . ``` 使用 pipx： ``` pipx install wifikit ``` ## 刷写 ESP32 `wifikit-flash` 会下载**正确的经典 ESP32 构建版本**（`old_hardware` app 以及匹配的 bootloader/partition table）并将其写入。它**不会** 捆绑 Marauder 的二进制文件 —— 这些文件会从官方发布版本中获取。 ``` wifikit-flash # auto-detect port, flash at a safe 115200 baud wifikit-flash --erase # wipe flash first ``` ## 使用说明 ``` wifikit # launch the TUI (auto-detect the board) wifikit --cli # line-based REPL instead of the TUI wifikit --exec "scanall" --timeout 15 # one-shot, print output, exit wifikit --capture --channel 3 # stream a pcap over USB into captures/ (no SD) wifikit --list-ports # show candidate serial ports wifikit --demo # try the TUI with sample data (no board needed) wifikit --benchmark # measure this GPU's WPA crack rate + time table ``` `--capture` 还支持 `--seconds S`、`--mode pmkid|handshake` 和 `--out PATH`。它会启用 Marauder 的 `SavePCAP`，使用 `-serial` 进行嗅探，并在 主机上重组传输流中的 `.pcap`。 **TUI 快捷键：** `s` 扫描 · `x` 停止 · `r` 刷新列表 · `a`/Enter 操作 · `d` 对选定目标进行 deauth · `p` 对选定目标抓取 PMKID · `Ctrl-R` 重连 · `q` 退出。 **Stations** 选项卡会列出按 AP 分组的客户端，并在扫描期间实时填充。 ### 抓包 → 破解循环（仅限*你自己的*网络） 无需 SD 卡 —— 抓包数据通过 USB 直接传输到你的 Mac。 1. 按 `s` 扫描，按 `x` 停止 —— 表格会根据 Marauder 的 `list -a` 实时填充。 2. 高亮选中你的 AP，按 **Enter** → **Capture (stream to Mac)**，或者在 CLI 中运行 `wifikit --capture --channel N`（可附加 `--seconds S`、`--mode pmkid|handshake`、`--out PATH`）。 3. 简短地执行 **Deauth** 以强制客户端重连（从而产生握手包）。 4. `wifikit` 会启用 Marauder 的 `SavePCAP`，使用 `-serial` 运行嗅探，并 **将传输流中的 `.pcap` 重组到 `captures/` 目录中** —— 然后通过 `hcxpcapngtool` 将其转换为 `hc22000` 格式。 5. 在 **Crack** 选项卡中，运行例如 `hashcat -m 22000 capture.hc22000 wordlist.txt` —— 输出结果将实时显示。 ## 工作原理 ``` ┌────────────── wifikit (Python) ──────────────┐ ESP32 <──USB serial──> session.py ──> tui.py / cli.py Marauder (threaded I/O) (UI + parsing) │ marauder.py (command set + `list` parser) │ flash.py (esptool + firmware fetch) ``` - `session.py` — 串口自动检测 + 多线程串口读取器/写入器。 - `marauder.py` — 固件的命令集和 `list` 解析器（AP + 工作站）。 - `capture.py` — 将 Marauder 的 `-serial` pcap 流解复用为 `.pcap` 并 （可选）通过 `hcxpcapngool` 转换为 `hc22000`。 - `cli.py` / `tui.py` — 两个前端界面（REPL 和 Textual 仪表板）。 - `flash.py` — 通过 `esptool` 实现一键刷写。 ## 开发 ``` uv sync # create venv + install deps (incl. dev group) uv run ruff check . # lint uv run ruff format . # format uv run pytest # tests (parser/port logic run without hardware) ``` 请阅读 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [行为准则](CODE_OF_CONDUCT.md)。安全报告：请参阅 [SECURITY.md](SECURITY.md)。 ## 许可证 [MIT](LICENSE) © 2026 Ravindra Singh。ESP32 Marauder 固件归 其各自的作者所有，并受其自身的许可证约束。

标签：DOS头擦除, ESP32, Python, WiFi安全测试, 密码破解, 无后门, 终端UI, 逆向工具, 防御绕过