LxveAce/headless-marauder-gui

# Headless Marauder **多合一的 ESP32 Marauder 控制器和多固件刷写工具。** 开源、跨平台、一键独立运行 exe —— 无需 Python，无需浏览器，无需云端。只需下载、运行并插上你的开发板。 **运行环境：** Linux (Kali, Debian, Ubuntu, Arch, Fedora), Windows 10/11, macOS, Raspberry Pi (ARM64) ## 特色亮点 大多数 Marauder UI 都是基于浏览器的，并依赖于 Web Serial API（仅限 Chromium）。在 Kali 上，这意味着 Firefox 根本无法工作，即使在 Chrome 中，功能集也受到限制。 Headless Marauder 则有所不同： - **多合一** —— 控制器和刷写工具集成于单个应用中。连接、扫描、攻击、刷写固件、刷写自杀版构建 —— 所有这些都无需切换工具。无需单独的 esptool 工作流，无需 Arduino IDE，也无需网页刷写器。 - **一键 exe** —— 适用于 Windows、Linux x64 和 Linux ARM64 的独立二进制文件。所有内容（Python、PyQt5 及所有依赖项）均已打包。下载，双击，即可运行。无需安装，无需配置，无需依赖。 - **开源** —— MIT 许可证，完全透明。阅读每一行代码，派生它，修改它，回馈社区。 - **自杀版构建支持** —— 唯一内置支持刷写反取证 Suicide-Marauder 包的 Marauder 控制器。一次配置，即可从应用中刷写并进行完整性验证。见[下文](#suicide-build)。 - **社区驱动** —— 由社区构建并为社区服务，未来将推出更多功能。欢迎提交 PR、想法和 Bug 报告。 ## 功能说明 ### 控制 - **四种前端，一个核心** —— PyQt5 桌面 GUI（推荐）、Tkinter GUI、适用于终端/SSH 的 Textual TUI，以及浏览器 UI（通过 Flask + WebSocket 运行在 localhost:5000）。所有界面均采用暗色主题。 - **每一个 Marauder 命令**（70+）按类别组织为按钮和树状条目，带有参数表单和原始命令输入框。以 115200 波特率自动连接，或指定 `--port` 和 `--baud`。 - **实时 AP/Station 表格** —— `scanap` 实时填充“接入点”选项卡；直接从串口流中解析并去重 AP 和 Station。在扫描期间，自动列表轮询每 3 秒进行一次，以保持表格最新。 - **目标选择器** —— 勾选你想要的网络、全选，或手动输入索引。根据 Marauder 的真实索引构建正确的 `select -a 0,2,5`。 - **悬停提示** —— 每个按钮、字段和复选框都有一个通俗易懂的提示，解释其功能。所有 UI 共享同一个词汇表。 ### 完整的命令覆盖 不仅是 WiFi 扫描和 deauth —— 涵盖 10 多个类别的完整 Marauder 命令集： | 类别 | 包含内容 | |----------|-------------| | **WiFi 扫描** | AP 扫描、Station 扫描、原始 PMKID 捕获、deauth + 嗅探、探测请求扫描、定向探测 | | **WiFi 嗅探** | Beacon、deauth、PMKID、probe、ESP 管理 frame 及原始数据包嗅探，支持 PCAP 存至 SD 卡 | | **WiFi 攻击** | Deauth（选定的/列表中的）、信标垃圾洪泛（随机/Rick Roll/列表）、探测垃圾洪泛、钓鱼门户、AP 克隆、Rick Roll AP | | **WiFi 网络** | 加入已扫描的 AP、ping 扫描局域网、TCP 端口扫描（包含全端口选项） | | **Bluetooth** | BLE 扫描、skimmer 检测 (`sniffskim`)、Pwnagotchi 检测 (`sniffpwn`)、AirTag/Flipper/Flock 追踪嗅探、BLE 垃圾洪泛 (SourApple, Swiftpair, Samsung, Google, AppJuice, Flipper, All) | | **GPS / Wardrive** | WiFi 战骑 (WiGLE CSV)、BT 战骑、GPS 字段查询（定位状态、经纬度、海拔、卫星、精度、原始 NMEA） | | **列表与目标** | 选择/清除 AP 和 Station、列出 AP/客户端、自动列表开关 | | **SSID** | 为信标垃圾洪泛列表添加/清除/生成随机 SSID | | **文件** | SD 卡文件列表、将 AP 和 SSID 列表保存/加载至 SD 卡 | | **系统** | 设置开关、LED 颜色/效果、重启、设备信息、OTA 更新（串口 + WiFi）、帮助 | ### 刷写工具 - **多固件刷写器** —— 刷写 [ESP32 Marauder](https://github.com/justcallmekoko/ESP32Marauder)、[ESP32-DIV](https://github.com/cifertech/esp32-div)、[Bruce](https://github.com/pr3y/Bruce) 或任何自定义的本地 `.bin` 文件。固件选择下拉菜单会动态切换配置文件和 UI。 - **自动芯片检测** —— 识别 ESP32、ESP32-S2、ESP32-S3、ESP32-C3、ESP32-C5 并自动选择正确的固件变体。 - **仅刷写 App 或全量刷写** —— 更新现有开发板（仅 App 镜像）或从零开始刷写全新开发板（bootloader + 分区表 + boot_app0 + App）。 - **擦除 Flash** —— 全片擦除，恢复纯净状态。 - **自杀版构建刷写** —— 一键刷写预配置的反取证 Marauder 包，并带有 SHA256 完整性验证。见[下文](#suicide-build)。 - **安全强化** —— 仅使用 HTTPS 获取固件并带有主机白名单、所有下载均受到路径遍历保护、防御 SSRF/重定向攻击。 ### 日志与数据导出 - **原始串口日志** —— 完整的串口数据流输出至 `serial-YYYYMMDD-HHMMSS.log`，对 `tail -f` 友好。 - **实时 JSON 快照** —— `latest.json` 每约 3.5 秒更新一次，包含 AP/Station 计数、完整数组、时间戳和会话元数据。采用原子写入，因此其他工具可以安全地进行轮询。 - **CSV 导出** —— `aps.csv` (SSID, 信道, RSSI, BSSID) 和 `stations.csv` (MAC, AP BSSID, RSSI)，适用于电子表格、脚本或导入其他工具。 ### 其他功能 - **`--mock` 模式** —— 在没有硬件的情况下运行完整 UI，适用于演示、开发或测试。 - **内置指南** —— 应用内的“指南”选项卡涵盖了攻击链以及如何将数据导入 Wireshark、hashcat、WiGLE、Kismet 等工具。 - **自我更新** —— 帮助 > 检查更新，会拉取最新代码并重新安装依赖项。 - **可安装** —— 添加到你的 PATH、应用菜单（Linux）或开始菜单。可从任何地方运行。 ## 自杀版构建 自杀版构建是一项**针对 ESP32 Marauder 的反取证固件选项** —— 这是一项防御性措施，用于在你自己的设备丢失、被盗或被查封时保护其中的数据。 ### 意义 “自杀版构建”是一个经过特殊配置的 Marauder 固件镜像，它为你的 ESP32 增加了硬件级别的保护： - **启动密码** —— 开发板需要密码才能引导进入 Marauder。没有密码，固件就不会运行。 - **两次失败擦除** —— 2 次密码尝试失败后，设备会自动擦除自身数据。Flash、NVS，所有东西 —— 统统消失。 - **GPIO 死人开关** —— 与 GPIO 引脚相连的硬件摧毁触发器。连接一个物理按钮或开关；拉低引脚，开发板就会立即擦除数据。可用作紧急按钮或防篡改检测触发器（例如赛博面板的“开盖检测”）。 这是在 bootloader 级别通过 eFuse 锁和 Flash 加密来强制执行的 —— 无法通过重新刷写或从外部读取芯片来绕过。一旦完成配置，这些保护措施就是永久性的，并由硬件强制执行。 ### 工作原理（两步流程） 自杀版构建采用 **双仓库工作流**： 1. **配置包**（独立仓库） —— 使用 **[Suicide-Marauder](https://github.com/LxveAce/Suicide-Marauder)** 配置工具构建固件包。该工具负责处理敏感部分：密码哈希、eFuse 配置、安全启动设置以及 Flash 加密。它会在 bundle 目录中输出一个 `bundle.json` 清单和 `.bin` 镜像文件。 2. **刷写包**（本应用） —— 在 Headless Marauder 刷写工具中： - 将 **固件** 选择器设置为 **ESP32 Marauder** - 勾选 **Suicide** 复选框 - 指向你的 bundle 目录（包含 `bundle.json` 和 `.bin` 文件的文件夹） - **检测芯片** → **FLASH** 就是这样。应用程序会读取 bundle 清单，根据配置工具记录的内容验证每个镜像文件的 SHA256 哈希值，将验证过的副本暂存到私有临时目录中（提供 TOCTOU 保护），并在单次 esptool 调用中写入所有内容。 ### 本应用的作用与限制 **本应用仅用于刷写已配置好的 bundle。** 它绝不会烧录 eFuse，绝不会对密码进行哈希处理，也绝不涉及安全启动或 Flash 加密配置 —— 所有这些操作都在 Suicide-Marauder 配置工具中完成，绝不在此处进行。 **在刷写任何内容之前都会强制进行完整性验证：** - bundle 中的每个文件都会根据清单进行 SHA256 验证 - 自杀版 bundle 上缺少或为空的哈希值被视为**严重错误** —— 没经验证绝不刷写 - 路径遍历保护会拒绝任何试图引用 bundle 目录之外文件的清单条目 - 验证过的文件会被暂存到私有临时目录中，并在刷写前重新进行哈希校验（防止文件在验证和刷写之间被掉包） **普通版 Marauder 始终是默认选项。** 不勾选 Suicide 复选框，刷写工具的工作方式就与普通的固件更新完全一样。自杀版路径完全是可选项。 ## 安装说明 ### 下载（最简单） 从 [Releases 页面](https://github.com/LxveAce/headless-marauder-gui/releases/latest) 获取预构建的二进制文件 —— 无需 Python 或 Git： | 平台 | 文件 | 说明 | |----------|------|-------| | Windows x64 | `headless-marauder-vX.X.X-windows-x64.exe` | 双击运行 | | Linux x64 | `headless-marauder-vX.X.X-linux-x64` | `chmod +x` 后运行 | | Linux ARM64 | `headless-marauder-vX.X.X-linux-arm64` | 适用于 Raspberry Pi (64位系统)、ARM 单板机 | 所有内容均已打包 —— Python、PyQt5 及所有依赖项。下载，运行，插上你的 ESP32 即可。 ### 从源码安装 #### Linux (Kali / Debian / Ubuntu) ``` git clone https://github.com/LxveAce/headless-marauder-gui.git cd headless-marauder-gui ./install.sh ``` 这将设置 venv，安装所有依赖，并在 `~/.local/bin` 中为你提供 `headless-marauder` (Qt GUI)、`headless-marauder-tui` (终端) 和 `headless-marauder-web` (浏览器) 命令，此外还会添加一个菜单项。 无需 sudo 即可进行串口访问（执行后请重新登录）： ``` sudo usermod -aG dialout $USER ``` #### Windows 你需要 [Python 3.9+](https://python.org)（勾选“Add Python to PATH”）和 [Git](https://git-scm.com/downloads)。 ``` git clone https://github.com/LxveAce/headless-marauder-gui.git cd headless-marauder-gui install.bat ``` 提供 `headless-marauder`、`headless-marauder-tk`、`headless-marauder-tui` 和 `headless-marauder-web` 命令，以及一个开始菜单快捷方式。 **CH340 驱动：** 如果 Windows 无法识别你的 ESP32，请下载 [CH340 驱动程序](https://www.wch-ic.com/downloads/CH341SER_EXE.html)。开发板会显示为一个 COM 端口（例如 `COM3`）。 #### macOS / 其他平台 ``` git clone https://github.com/LxveAce/headless-marauder-gui.git cd headless-marauder-gui python3 -m venv .venv source .venv/bin/activate pip install -r requirements.txt pip install PyQt5 ``` 然后运行： ``` source .venv/bin/activate python3 gui_qt/app.py # Qt GUI python3 gui/app.py # Tkinter python3 tui/app.py # Terminal ``` 添加 `--mock` 可在无硬件环境下尝试，添加 `--port /dev/tty.usbserial-xxxx` 可指定端口。 #### pip 安装 ``` pip install git+https://github.com/LxveAce/headless-marauder-gui.git[all] ``` 获取 `headless-marauder-tk` 和 `headless-marauder-tui`。Qt GUI 需要从克隆的仓库中运行（`python -m gui_qt.app`），因为 Qt 的入口点在使用 pip 时可能会出现问题。

手动 / 开发运行

``` # Linux sudo apt install -y python3-venv python3-tk python3-pyqt5 python3 -m venv --system-site-packages .venv source .venv/bin/activate pip install -r requirements.txt python3 gui_qt/app.py # Windows python -m venv .venv .venv\Scripts\activate pip install -r requirements.txt pip install PyQt5 python gui_qt\app.py ``` 参数：`--mock`（无硬件），`-- COM3` 或 `--port /dev/ttyUSB0`（跳过自动检测），`--baud 115200`（自定义波特率），`--no-autoconnect`（启动时不连接），`--log`（立即开始记录）。 对于浏览器 UI：`--host 0.0.0.0`（局域网访问），`--web-port 8080`（自定义端口）。

## 更新 在项目文件夹中执行 `git pull`。设置和日志不会受到影响。 最简单的方法是：在应用中点击 **Help > Check for Updates** —— 它会自动拉取并重新安装依赖。 从终端运行： ``` cd headless-marauder-gui git pull # Linux: 如果 deps 发生变化，请重新运行 ./install.sh # Windows: .venv\Scripts\pip.exe install -q -r requirements.txt ``` ## 卸载 **Linux:** ``` cd headless-marauder-gui ./uninstall.sh # removes launchers + menu entry rm -rf ../headless-marauder-gui ``` **Windows:** ``` cd headless-marauder-gui uninstall.bat # removes launchers + Start Menu shortcut ``` 然后删除 `headless-marauder-gui` 文件夹。 ## 使用说明 1. **连接** —— 自动检测开发板（115200 波特率）。顶部状态栏会变绿。 2. **扫描 AP** —— 开启自动列表（默认）后，接入点选项卡会在扫描时自动填充。 3. 看到足够数据后点击 **STOP**。 4. **选择 AP** —— 在选择器中勾选网络，它会发送 `select -a ...`。 5. 执行操作 —— 例如 Deauth（针对选定的 AP）。 ### 浏览器 UI 运行 `headless-marauder-web`（或 `python web/app.py`）并打开 **http://localhost:5000**。具有与桌面 GUI 相同的功能 —— 命令侧边栏、实时控制台、AP/Station 表格、参数表单、自动列表、日志记录、键盘快捷键（`Ctrl+L` 清除，`Ctrl+K` 命令框，`Ctrl+.` STOP）。原始输入支持方向键调用历史记录。 默认仅绑定到 localhost。传递 `--host 0.0.0.0` 可将其开放给局域网（无身份验证 —— 网络上的任何人都可以控制开发板）。 ### 键盘快捷键 (Qt GUI) | 快捷键 | 操作 | |----------|--------| | `Ctrl+L` | 清空控制台 | | `F5` | 刷新端口 | | `Ctrl+K` | 聚焦命令输入框 | | `Ctrl+.` | STOP | | `Ctrl+U` | 检查更新 | | `Ctrl+Q` | 退出 | | `F1` | 打开指南 | ### 刷写固件 1. 点击 **Flash Firmware** 2. 选择 **固件** —— ESP32 Marauder (默认)、ESP32-DIV、Bruce 或自定义 3. **检测芯片** —— 自动判断是经典版 ESP32、S3 等 4. **加载发布列表** —— 从该固件的官方 GitHub 拉取（或在“自定义”模式中选择你本地的 `.bin` 文件） 5. 选择一个变体（根据你的芯片自动选择） 6. **仅更新 App**（现有开发板）或 **全量刷写**（空白开发板） 7. **FLASH** —— 进度将实时显示 关于自杀版构建，请参阅上面的[自杀版构建](#suicide-build)章节。 ### 日志记录 在工具栏中切换 **Log**（或 File > Set Log Folder，或在启动时使用 `--log`）。默认路径：`~/marauder-logs`。 | 文件 | 包含内容 | |------|-------------| | `serial-YYYYMMDD-HHMMSS.log` | 原始串口数据流（对 `tail -f` 友好） | | `latest.json` | 实时快照（约 3.5 秒间隔）：AP/Station 计数、完整数组、时间戳。原子写入，因此其他工具可以安全轮询。 | | `aps.csv` | 解析出的 AP (SSID, 信道, RSSI, BSSID) | | `stations.csv` | 解析出的 Station (MAC, AP BSSID, RSSI) | 所有输出均专为导入其他工具而设计 —— Wireshark、hashcat、WiGLE、Kismet 及自定义脚本。有关链式操作示例，请参阅应用内指南。 ## 故障排除 **Linux:** - **找不到 `/dev/ttyUSB0`** —— The Gold 使用的是 CH340 芯片。在 Kali 上，`brltty` 喜欢抢占它：执行 `sudo apt remove brltty`，然后重新插拔。确保你处于 `dialout` 用户组中。 - **在虚拟机中** —— 透传 USB 设备（VirtualBox：设备 > USB；VMware：虚拟机 > 可移动设备）。 - **Qt GUI 无法启动** —— 缺少 PyQt5。执行 `sudo apt install -y python3-pyqt5`（venv 需要 `--system-site-packages`），或者直接使用 TUI。 **Windows:** - **没有 COM 端口** —— 安装 [CH340 驱动程序](https://www.wch-ic.com/downloads/CH341SER_EXE.html)。检查设备管理器 > 端口。 - **无法识别 `headless-marauder`** —— 打开一个新的终端（PATH 刚刚更新）。 - **COM 端口权限被拒绝** —— 关闭任何其他串口监视器（Arduino IDE、PuTTY 等）。 **常规：** - **开发板不断重启 / `scanap` 无反应** —— 检查控制台输出： - `invalid header: 0xffffffff` —— Flash 是空白的，请使用全量刷写。 - `Detected size(4096k) smaller than ... header(16384k)` —— Flash 大小头部错误。刷写工具会使用 `--flash_size detect` 修复此问题；请擦除并重新刷写。 - **Deauth“毫无反应”** —— Marauder 会打印一次开始消息，然后静默运行。如果设备没有掉线，通常是因为 802.11w/PMF（现代路由器会忽略 deauth）、目标是 5GHz 频段（经典版 ESP32 仅支持 2.4GHz），或者没有客户端连接。 ## 架构 ``` marauder_core/ controller.py parsing.py commands.py flasher.py capture.py updater.py uihelp.py gui_qt/app.py PyQt5 GUI (live tables, picker, flasher, logging) gui/app.py Tkinter GUI (simple, stdlib) tui/app.py Textual terminal UI web/app.py Browser UI (Flask + SocketIO at localhost:5000) build.py PyInstaller build script for standalone exes install.sh Linux installer (app menu + PATH + venv) install.bat Windows installer (Start Menu + PATH + venv) ``` 一个命令目录和一个解析器为所有四种前端提供支持。串口层同时将数据流传输到 UI、解析器和记录器。 ## 通用刷写工具 该工具可插拔的 `FirmwareProfile` 架构已扩展为 **[Universal Flasher](https://github.com/LxveAce/universal-flasher)** —— 这是一个多固件刷写器和设备管理器，支持跨 4 种刷写后端的 14 多种固件类型： | 刷写后端 | 设备 | |---------------|---------| | **esptool** | Marauder, GhostESP, Bruce, HaleHound, ESP32-DIV, Meshtastic, Flock-You, OUI-Spy, Sky-Spy, AirTag Scanner, CYT-NG | | **SD image writer** | Pwnagotchi, RaspyJack, Kali ARM | | **ADB** | RayHunter (Orbic RC400L) | | **qFlipper** | Flipper Zero (Momentum, Unleashed) | 还包括批量刷写、固件备份/恢复、设备自动检测、离线缓存、刷写历史记录、更新检查器、健康检查以及插件系统。**[github.com/LxveAce/universal-flasher](https://github.com/LxveAce/universal-flasher)** ## 法律声明 **仅供授权的安全测试使用。** 仅在你拥有或获得书面授权测试的网络和设备上使用。WiFi deauth、钓鱼门户、BLE 垃圾洪泛 —— 将这些技术用于他人的财产可能是非法的（如 CFAA、FCC 规定等）。你对如何使用此工具负有全部责任。 **ESP32-DIV** 和 **Bruce** 固件（可选的刷写目标）包含**在你的司法管辖区内可能是非法操作的 RF 功能**。本应用仅逐字节刷写官方镜像 —— 它不增加、启用或控制任何额外功能。固件刷写到开发板上后会执行什么操作，其责任由你自行承担。 **自杀版构建** 是一项仅供所有者使用的**防御性**措施，旨在保护你自己设备上的数据 —— 它不是攻击工具。仅在你拥有的硬件上进行配置和使用，并在启用前阅读 Suicide-Marauder 仓库的 **[SAFETY.md](https://github.com/LxveAce/Suicide-Marauder/blob/main/SAFETY.md)**。 按“原样”提供，无任何保证。完整声明请参见 [DISCLAIMER.md](DISCLAIMER.md)。 发现漏洞？请不要公开提交 issue —— 请参阅 [SECURITY.md](SECURITY.md)。 欢迎提交 PR 和 Bug 报告 —— 请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 ## 致谢 - 固件：由 justcallmekoko 开发的 [ESP32 Marauder](https://github.com/justcallmekoko/ESP32Marauder) (GPL) —— 本应用通过串口与其进行通信。 - 可选刷写目标：由 cifertech 开发的 [ESP32-DIV](https://github.com/cifertech/esp32-div)、由 pr3y 开发的 [Bruce](https://github.com/pr3y/Bruce) —— 本应用仅刷写官方镜像。 - 构建基于 [pyserial](https://pyserial.readthedocs.io/)、[PyQt5](https://www.riverbankcomputing.com/software/pyqt/)、[Textual](https://textual.textualize.io/)、[Flask](https://flask.palletsprojects.com/) 和 [esptool](https://github.com/espressif/esptool)。 [MIT 许可证](LICENSE) | [更新日志](CHANGELOG.md)

标签：ESP32, Marauder, PyQt5, WiFi审计, 动态调用, 固件烧录, 桌面应用, 逆向工具