VexilonHacker/OverQuack

✨ 功能 • 🖥️ 演示 • 🏁 快速开始 • ⚙️ 配置 • 🌐 无线 • 🖥️ IDE • 📜 语言 • 🗺️ 路线图

## 🤔 为什么选择 OverQuack？ **OverQuack** 专为希望获得一个紧凑、灵活且透明的脚本化 HID 自动化平台的用户而打造。 它集成了本地 payload 执行、无线管理、现代化的 Web IDE，以及易于检查和修改的可扩展代码库。 | OverQuack 提供的功能 | 典型的商业 USB payload 平台 | |-----------------------|------------------------------------------| | **经济实惠的硬件：** 运行在 Raspberry Pi Pico 开发板及其变体上 | 通常作为专用设备以更高的价格出售 | | **开源，GPLv2：** 完全可审计、可修改且由社区驱动 | 通常是闭源的或仅有部分文档 | | **完整的脚本语言：** 变量、函数、循环、数学运算、随机化等 | 功能集因平台和固件而异 | | **内置 Wi-Fi 远程控制：** 无线上传、执行和管理 payload | 无线控制可能需要额外硬件或额外设置 | | **基于 Web 的 IDE：** 实时错误检查、自动补全、模板、代码片段和 Vim 模式 | 一些平台提供编辑器或配套工具，但工作流通常较窄 | | **一键安装程序：** 跨平台的简化设置 | 安装可能更偏向手动且特定于设备 | | **USB 模式切换：** 无需重新插拔即可更改设备行为 | 支持程度因平台和固件而异 | | **多种键盘布局：** 随时切换布局 | 通常支持布局，但往往不够灵活 | | **鼠标和消费者控制：** 移动、点击、滚动和媒体键 | 通常受支持，尽管实现方式有所不同 | | **可 hack 且可扩展：** 易于检查、修改和在其基础上进行构建 | 可扩展性取决于平台是开放还是锁定 | | **专为教育和研究设计：** 行为清晰且代码透明 | 许多工具旨在进行测试，但提供的内部可见性较低 | ## ✨ 功能概览 - 🧠 **完整的 DuckyScript 扩展** 变量、条件语句、循环、函数、数学运算、随机化 - 📡 **无线控制** 内置 Wi-Fi 接入点和 TCP 服务器，可远程部署和触发 payload - 🔌 **即插即用 HID 注入** 键盘、鼠标、消费者控制（媒体键）。无需驱动程序 - 🖱 **完整的鼠标支持** 移动、点击、滚动、抖动以及后台鼠标抖动器 - 🔄 **USB 模式切换** 无需拔下即可切换至 HID、存储或 HID+存储模式 - 🖥️ **跨平台 payload** 适用于 Windows、macOS 和 Linux - ⚙️ **一键设置** 引导式跨平台安装程序 - 🛠️ **模块化且可 hack** 可通过新的 payload、布局和工具进行扩展；采用 GPLv2.0 许可 - ✅ **完全可配置** 所有设置均存在于 `config.json` 中 - 🌐 **功能丰富的桌面客户端** 具备自动补全、历史记录和进度条的交互式 shell - 🖥️ **基于 Web 的 IDE** 带有语法高亮、实时验证、模板和代码片段的 Monaco 编辑器 ## 🖥️ 跨平台演示

🪟 Windows	🍏 macOS
Windows 10: classic Notepad payload	macOS: Opening a Rick Roll in safari browser
🐧 Linux	📱 Android
Arch Linux (bspwm): >:^]	Android (OTG): Opening a Rick Roll in brave browser

## 🧠 支持的开发板 

OverQuack 可运行于整个 Raspberry Pi Pico 家族：
Pico · Pico W · Pico 2 · Pico 2 W

## 🧠 内存与性能 **OverQuack** 经过优化，适用于长时间运行的 payload、大型脚本以及可靠的远程操作。

Pico： 264 KB RAM andnbsp;|andnbsp; Pico W： 264 KB RAM andnbsp;|andnbsp; Pico 2： 520 KB RAM andnbsp;|andnbsp; Pico 2 W： 520 KB RAM

## 📦 组件 ``` Overquack/ ├── OverQauckInstaller.py # Cross-platform setup wizard ├── OverQuack_src/ # Pico firmware (runs on the board) │ ├── boot.py # USB config and ATTACKMODE switching │ ├── code.py # Startup and payload dispatcher │ ├── overquackify.py # DuckScript interpreter (the brain) │ ├── quackd.py # Wi-Fi TCP server │ ├── config.json # Device configuration │ ├── payload.oqs # Default payload (demo) │ ├── settings.toml # CircuitPython runtime settings │ └── lib/ # HID libraries, keycodes, layouts ├── OverQuack_Client/ # Desktop TCP client │   ├── overquack_client.py │   ├── pyproject.toml │   └── uv.lock ├── OverquackWebStudio/ # Browser IDE │   ├── oqws_static │   ├── oqws_template │   ├── OverquackWebStudio.py │   ├── pyproject.toml │   └── uv.lock ├── OverQuack_Cirpy_firmwaresen_10.2.1/ # Precompiled CircuitPython firmwares ├── assets/ └── README.md ``` ## 🏁 快速开始 ### 自动安装（推荐） 运行跨平台安装程序： ``` python OverQauckInstaller.py ``` 然后按照交互式向导操作。它将引导您完成开发板选择、固件刷写，并自动复制 OverQuack 源文件。  ### 手动安装 1. **下载仓库** 克隆或下载 [OverQuack 仓库](https://github.com/VexilonHacker/OverQuack)。 2. **进入 BOOTSEL 模式** - 断开 Pico 与 USB 的连接。 - 按住开发板上的 **BOOTSEL** 按钮。 - 在按住 BOOTSEL 的同时，将 Pico 插入您的计算机。 - 3 秒后，松开按钮。 - 将出现一个 USB 驱动器： - **Pico / Pico W**：名为 **`RPI-RP2`** 的驱动器 - **Pico 2 / Pico 2 W**：名为 **`RP2350`** 的驱动器 3. **清除闪存** *(擦除所有以前的数据 —— 这对于全新安装至关重要)* - 在仓库中打开 `OverQuack_Cirpy_firmwaresen_10.2.1/` 文件夹。 - 将文件 `flash_nuke_all_boards.uf2` 复制到 BOOTSEL 驱动器（`RPI-RP2` 或 `RP2350`）中。 - 开发板将自动弹出并重启**回到 BOOTSEL 模式**（相同的驱动器会再次出现）。 4. **刷入 CircuitPython** - 从相同的固件文件夹中，为您的开发板复制**匹配的 CircuitPython UF2** 文件。 | 开发板 | UF2 文件 | |-------------|----------| | Pico | `adafruit-circuitpython-raspberry_pi_pico-en_US-10.2.1.uf2` | | Pico W | `adafruit-circuitpython-raspberry_pi_pico_w-en_US-10.2.1.uf2` | | Pico 2 | `adafruit-circuitpython-raspberry_pi_pico2-en_US-10.2.1.uf2` | | Pico 2 W | `adafruit-circuitpython-raspberry_pi_pico2_w-en_US-10.2.1.uf2` | - 将正确的 UF2 文件拖到 BOOTSEL 驱动器中。开发板将再次重启，现在它将显示为 **`CIRCUITPY`**。 5. **安装 OverQuack** - 将 `OverQuack_src/` 目录中的**所有文件和文件夹**直接复制到 `CIRCUITPY` 驱动器的根目录。 - 该驱动器现在应该包含 `boot.py`、`code.py`、`overquackify.py`、`quackd.py`、`config.json`、`payload.oqs`、`settings.toml` 以及 `lib/` 文件夹。 6. **完成！** - 安全弹出 `CIRCUITPY` 驱动器，或者稍等片刻，开发板就会准备就绪。 - 您的 OverQuack 设备现已准备就绪。拨动开关并将其连接到目标机器，它将运行默认的 payload。  ## ⚙️ 配置 所有设备设置都位于 `CIRCUITPY/OVERQUACK` 驱动器上的 **`config.json`** 中。您可以在 Pico 处于存储模式时直接对其进行编辑。 ``` { "DEFAULT_PAYLOAD" : "payload.oqs", "DRIVE_LABEL": "OVERQUACK", "desc_DRIVE_LABEL": "Drive label will only change when you switch to attack mode", "ENABLE_SERIAL_DEBUG" : true, "desc_ENABLE_SERIAL_DEBUG": "Set to true for debug output on serial, false for silent operation", "BOARD" : { "controll_mode_pin": 5, "desc_controll_mode_pin" : "Setting GPIO pin that will change from keystroke mode to storage mode as example pin 2, 6, 10, 13...", "enable_auto_switch_mode" : true, "desc_enable_auto_switch_mode" : "switch attack mode without need to replug usb", "enable_auto_reload" : false, "desc_enable_auto_reload" : "when editing a file in PICO and saving it, it will auto reboot PICO" }, "AP" : { "ssid": "1984", "password": "OverQuackItBrother1984", "channel": "RANDOM", "desc_channel" : "You can set random channel value by using RANDOM or specify channel value as int in range [1,13]", "ip_address": "10.10.5.1", "ports": 1084, "desc_ports" : "TCP server port" }, "USB_IDENTIFICATION": { "manufacturer": "CHICONY", "product": "HP Basic USB Keyboard", "vid": "0x03F0", "pid": "0x0024" } } ``` ### 🔄 USB 模式：大容量存储 ⇄ HID 键盘 默认情况下，GPIO 引脚 **`controll_mode_pin`**（示例中为 GP5）决定了 USB 的行为模式： - **引脚连接到 GND** -> HID 攻击模式（键盘 + 鼠标，无驱动器） - **引脚悬空（断开）** -> 大容量存储模式（驱动器可见，用于编辑）

## 🌐 无线 TCP 控制（Pico W / Pico 2 W） **OverQuack** 会启动一个 Wi-Fi 接入点和端口为 `1084` 的 TCP 服务器。您可以使用 **OverQuack 客户端**远程控制该设备。 ### 启动客户端 ``` cd OverQuack_Client python -m venv .venv source .venv/bin/activate pip install uv uv sync python overquack_client.py --host 10.10.5.1 --port 1084 ``` #### 概览  ### 可用命令 | 命令 | 描述 | |--------------|-----------------------------------------------| | `ls` | 列出设备上的所有文件 | | `payloads` | 列出所有 `.oqs` 格式的 payload | | `read ` | 带语法高亮显示文件内容 | | `write ` | 上传 payload（本地文件、管道或内联输入）| | `delete ` | 删除文件 | | `run ` | 立即执行 payload | | `free_mem` | 检查可用的 RAM | | `wifi_scan` | 扫描附近的 Wi-Fi 网络 | | `get_config` | 下载设备配置 | | `reboot` | 重启进入正常 / UF2 / 安全模式 | | `format` | 擦除整个文件系统 | 该客户端还提供了一个交互式 shell，具备自动连接、历史记录以及远程 payload 的 Tab 补全功能。 ## 🖥️ Web Studio IDE 一个功能齐全的**基于浏览器的开发环境**，用于编写 OverQuack 脚本。  在本地启动它： ``` cd OverquackWebStudio python -m venv .venv source .venv/bin/activate pip install uv uv sync python OverquackWebStudio.py ``` 然后在浏览器中打开 `http://localhost:1084`。  ### IDE 亮点 - **Monaco 编辑器**，带有完整的 Ducky-Script 语言定义 - **语法高亮**和智能自动补全（命令、变量、系统变量、布局） - **实时错误检查：** 未知的 token、未闭合的代码块、未使用的变量/函数 - **代码片段库：** 100 多个即用型代码块（Windows、循环、鼠标、恶作剧...） - **模板：** 完整的 payload 蓝图（reverse shell、persistence、Wi-Fi dump...） - **Vim 模式**、minap、主题切换器 - **拖放：** 拖入 `.oqs`、`.txt`、`.dd`、`.duck` 文件即可打开它们 - **自动保存**到浏览器本地存储中 - 将 payload 作为 `.oqs` 文件**下载** ## 📜 OverQuack 脚本语言 (OQS) OverQuack 支持 **DuckyScript 的超集**，具备完整的编程能力、变量、函数、循环、鼠标控制、随机化等功能。 ## 🔧 高级主题 面向高级用户、开发者以及任何希望**确切**了解 OverQuack 底层工作原理的人：ATTACKMODE resume、TCP 通信协议、解释器内部机制、内存调优、添加布局以及已知的限制。请参阅专门的深度解析。 ## ❓ 常见问题与故障排除 有疑问或遇到问题？[FAQ.md](FAQ.md) 涵盖了最常见的（可能出现的）问题。从启动循环和 Wi-Fi 连接问题，到 ATTACKMODE resume 的怪异行为、NVM 清除、移动设备兼容性等等。 ## 🔍 串监视器 / 调试视图 您可以通过串口连接查看实时的调试输出（包括 `PRINT` 语句）。 ### Linux / MacOS ``` # 安装 picocom pkg x=0; while true; do [[ -e /dev/ttyACM0 ]] && picocom -b 9600 /dev/ttyACM0; ((++x)); printf '\n\033[1;37;41m[ %s | SESSION ENDED #%d ]\033[0m' "$(date '+%H:%M:%S')" "$x"; sleep 1; done ``` ### Windows 1. 通过 USB 连接 Pico。 2. 打开 **PuTTY**（或其他终端）。 3. 选择 **Serial**，输入 COM 端口（在设备管理器 -> 端口中查看），波特率设为 **9600**。 4. 启动会话。 所有的 `PRINT` 消息都进行了颜色编码，便于阅读。 ## 🗺️ 路线图 - [ ] **蓝牙 (BLE) 控制：** 适用于 Pico W 和 Pico 2 W - [ ] **加密的 TCP 协议：** 用于保障空中传输安全 - [ ] **设备上的 Payload 加密** - [ ] **在 FUNCTION 中添加参数支持** - [ ] **添加 OS 检测变量** - [ ] **通过 Caps Lock/Num Lock/Scroll Lock 反射进行文件窃取：** 适用于气隙系统 [最初的想法来源](https://shop.hak5.org/blogs/usb-rubber-ducky/keystroke-reflection) - [ ] **将 Pico 开发板作为键盘中间人：** 利用新的 circuitpython 10.2 CDC 支持，记录 USB 键盘与主机之间的击键 - [ ] **IDE 改进：** 更多验证规则、内置串口监视器，并将 OverquackWebStudio 与 OverQuack TCP 客户端绑定 ## 🤝 贡献 欢迎各种贡献！请提交 issue 或 pull request。请遵循本项目**教育和道德使用**的初衷。 ## 🫡 致谢 本项目是站在巨人的肩膀上完成的。 - **Dave Bailey (dbisu)** 创建了最初的 [pico-ducky](https://github.com/dbisu/pico-ducky)，这是 OverQuack 得以扩展并加入高级脚本编写、Wi‑Fi 远程控制、Web IDE 等更多功能的基础。 - **Adafruit 和 CircuitPython 社区** 提供了令人惊叹的生态系统，使 OverQuack 成为可能，从核心解释器和 HID 库，到 `asyncio` 模块以及支持我们所有键盘布局的布局生成器。 OverQuack 的存在离不开开源协作。 ## 📜 许可证 OverQuack 基于 **GNU General Public License v2.0** 发布。 ## ⚠️ 免责声明：请阅读否则后果自负 本工具仅供**教育和道德使用**。 **请勿**用于非法活动、未经授权的访问或任何有害目的。 作者对任何滥用、数据丢失、损坏或执法部门的来访**概不负责**。 请**明智地**使用它，并且仅在您**拥有**或获得**明确书面许可**进行测试的系统上使用。 ``` 💻 + 🧠 = ✅ 💻 + 🦆 + 😈 = 🚓 ``` **保持聪明。保持合法。负责任地进行 Hack。** 

标签：HID攻击, IoT安全, Raspberry Pi Pico, 并发处理, 硬件安全, 自定义脚本, 逆向工具