iodn/tap-ducky
GitHub: iodn/tap-ducky
利用 Root 权限将 Android 设备转化为 USB Rubber Ducky，支持完整的 DuckyScript 语法、HID 设备模拟及任务调度功能。
Stars: 31 | Forks: 5
# TapDucky - Android USB HID 击键注入器
2. 安装应用程序：
- 如有需要，启用从未知来源安装。
- 当 root 管理器提示时，授予 root 权限。
3. 启动并配置：
- 打开 TapDucky。
- 在 Advanced Settings 中，选择/调整 HID 配置（Keyboard/Mouse/Composite）、VID/PID 和键盘布局。
- 激活（Arm）一个 session 并从 Execute 运行测试命令。
## Usage
### 运行 Payload
1. 创建或导入一个 Payload（Payloads 标签页）。
2. 验证它并根据需要添加参数。
3. 进入 Execute，选择 Payload，填写参数，然后 Run。
4. 检查 Logs 和 Execution History 以查看结果。
### 调度 Payload
1. 打开 Scheduler。
2. 创建一个计划，选择触发器（一次性、冷启动、前台、armed）。
3. 可选地设置每日时间窗口和参数覆盖。
4. 保存并确保计划已启用。
### 从 GitHub Store 导入
1. 打开 Payloads Store。
2. 管理源（添加 `owner/repo` 或带有 branch/path 的完整 URL）。
3. 预览文件；TapDucky 验证 DuckyScript 并可以转换 Digispark sketches。
4. 将支持的文件直接导入到你的 Payloads。
## 截图
## License
本项目采用 GNU GPLv3 许可证授权。详见 [LICENSE](LICENSE)。
## Support
如果你遇到任何问题或有疑问，请在 GitHub 仓库提交 issue 或联系维护者。
## KaijinLab 的更多应用！
| App | What it does |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **[IR Blaster](https://github.com/iodn/android-ir-blaster)** | Control and test infrared functionality for compatible devices. |
| **[USBDevInfo](https://github.com/iodn/android-usb-device-info)** | Inspect USB device details and behavior to understand what's connected. |
| **[GadgetFS](https://github.com/iodn/gadgetfs)** | Experiment with USB gadget functionality (hardware‑adjacent, low‑level). |
| **[TapDucky](https://github.com/iodn/tap-ducky)** | A security/testing tool for controlled keystroke injection workflows. |
| **[HIDWiggle](https://github.com/iodn/hid-wiggle)** | A mouse jiggler built with USB gadget functionalities. |
| **[AKTune](https://github.com/iodn/android-kernel-tweaker)** | Adaptive Android kernel auto‑tuner for CPU/GPU/scheduler/memory/I/O. |
TapDucky - Android USB HID Keystroke Injector
Open-source DuckyScript runner for rooted Android with USB Gadget (ConfigFS) support
TapDucky lets you create, customize, schedule, and run DuckyScript on Android by emulating a USB keyboard, mouse, or composite HID device for authorized testing and automation. It includes payload parameterization, multiple scheduler triggers, execution logs, and a GitHub-backed payload library with automatic DuckyScript validation and optional Digispark .ino conversion.
[](LICENSE)
[](https://github.com/iodn/tap-ducky/issues)
[](https://github.com/iodn/tap-ducky/pulls)
[](https://www.android.com)
[](#)
## 概述
- USB HID gadget 配置文件（在受支持/已 root 的设备上无需外部 USB dongle）：
- Keyboard（键盘）、Mouse（鼠标）和 Composite（复合）配置文件，支持可配置的 VID/PID、制造商/产品字符串以及功耗。
- DuckyScript 管道：
- 实时验证，包含人性化的错误/警告提示、占位符参数、延迟倍增器，以及可选的用于模拟人类输入节奏的抖动（jitter）。
- Payload（载荷）管理：
- 创建/编辑 Payload，包含名称/描述/标签/参数，快速分享/导出，以及内置模板/向导。
- GitHub Payload Store：
- 添加源，浏览仓库，预览文件并验证，导入支持的脚本；自动检测 DuckyScript 并在可能的情况下转换 Digispark `.ino` 草图。
- Scheduler（调度器）：
- 支持一次性（指定日期/时间）、App 冷启动、App 前台运行，或 HID session 激活（device_connected）时触发，并可选每日时间窗口。
- Execution & Logs（执行与日志）：
- 分页式执行视图，参数提示，运行/取消，执行历史，以及支持导出/清除和级别过滤的结构化日志。
- Device diagnostics（设备诊断）：
- 设备快照、内核/gadget 状态、UDC 信息、键盘布局；复制到剪贴板；模拟器检测提示。
注意：需要具有 Linux USB gadget (ConfigFS) 支持的已 root 设备。请使用真机，因为模拟器无法验证 HID 行为。
## 功能特性
- Payload 编辑器与参数
- 创建包含名称/描述/标签的 Payload。
- 添加带类型的参数，支持默认值、必填标志和每次执行时的覆盖。
- 内置 DuckyScript 验证器，包含行号/问题映射和命令计数。
- 分享单个 Payload 或导出为包。
- GitHub Payload Store
- 管理多个 GitHub 源（user/repo/branch/path）。
- 浏览目录并预览文件，支持格式检测（DuckyScript、TapDucky JSON、转换后的 Digispark 脚本 (.ino)）。
- 将验证通过的脚本直接导入到你的库中；验证失败的文件会显示原因预览。
- Execute & Test（执行与测试）
- 运行前验证；提示输入参数值；运行或取消（带执行 ID）。
- 快速 HID 测试：键盘按键、鼠标移动和 Ctrl+Alt+Del。
- 基于引擎的运行时间估算（与实际计时模型匹配）。
- Wakelock 控制，在执行期间保持 session 活跃。
- Scheduler & Triggers（调度器与触发器）
- 触发器：one_time（一次性）、app_cold_start（冷启动）、app_foreground（前台）、device_connected（session armed/连接）。
- 可选的每日时间窗口（HH:MM → HH:MM），支持跨午夜循环。
- 启用/禁用、编辑和删除计划；跟踪上次运行时间。
- 通过密钥（secret codes）绑定拨号快捷方式（自动 arm + 后台执行）。
- 支持的代码：`*#*#38250#*#*`, `*#*#38251#*#*`, `*#*#38252#*#*`, `*#*#38253#*#*`
- 每个代码的绑定键：enabled（启用）、mode（模式：上次执行 | 选定 payload）、payload（当 mode = 选定 payload 时）
- Device & HID Profiles（设备与 HID 配置）
- 激活 Keyboard、Mouse 或 Composite 配置文件，包含可配置的 ID/字符串/功率。
- 键盘布局选择和代码/ID 解析。
- 状态流显示 ACTIVE/IDLE、writer 就绪状态以及主机配置请求。
- Logs & History（日志与历史）
- 日志标签页，支持级别过滤（all/info/debug/warn/error），导出分享，清除所有。
- 执行历史详情，包含元数据和分享功能。
### 用户界面
- 仪表板，包含快速状态卡片、Payload/库统计和调度摘要。
- 清晰的空状态和分步向导，用于首次设置/导入。
- Material 3 主题，动态浅色/深色配色方案。
### 技术/架构
- Platform channels (Android)：
- Method Channel：`org.kaijinlab.tap_ducky/gadget`
- `checkRoot`、`checkSupport`、`listUdcs`、`getStatus`、`getDiagnostics`
- `getKeyboardLayouts`、`setKeyboardLayout`、`resolveKeyboardLayoutId`、`setKeyboardLayoutByCode`
- `activateProfile`、`deactivate`、`panicStop`、`retryOpenHidWriters`
- `executeDuckyScript(script, delayMultiplier, executionId?)`、`cancelExecution(executionId)`
- 测试辅助：`testKeyboardKey(label)`、`testMouseMove(dx,dy,wheel,buttons)`、`testCtrlAltDel()`
- Event Channels：
- `org.kaijinlab.tap_ducky/gadget_logs`
- `org.kaijinlab.tap_ducky/gadget_status`
- `org.kaijinlab.tap_ducky/gadget_exec`
- HID Profiles 模型：keyboard/mouse/composite，包含 VID/PID、strings、serial、power。
- DuckyScript：
- 解析为步骤；支持 DELAY/STRING/keys/raw 命令；占位符解析；基础按键延迟；jitter（抖动）。
- 验证器返回带有严重程度和行映射的问题；用于编辑器/Store/执行流程。
- TRY/CATCH/END_TRY、WAIT_FOR、SLEEP_UNTIL、FUNCTION 参数和作用域变量。
- Unicode 回退模式（warn+skip / skip / ASCII transliteration）。
- 执行流中的结构化错误代码。
- Scheduling engine（调度引擎）：
- 触发器（冷启动、前台、armed、一次性），每日时间窗口规则，持久化于 SharedPreferences。
- 状态管理：Riverpod 3，go_router 导航，清晰的 repository/services/controllers 分离。
## DuckyScript / Keystroke 引擎
TapDucky 包含一个在 Android (Kotlin) 上原生实现的完整 DuckyScript 风格引擎，支持表达式求值和结构化控制流。它支持键盘、鼠标/指针、计时、变量/定义、函数和简单的随机工具。
支持的命令系列（高级）：
- 文本与计时：STRING, STRINGLN, STRING_DELAY, DELAY, DEFAULTDELAY/DEFAULT_DELAY, REM (以及 REM_BLOCK)
- 按键与组合：ENTER, TAB, ESC, SPACE, BACKSPACE, 方向键, 导航键 (HOME/END/PGUP/PGDN/INS/DEL), F1–F24, 媒体键, 小键盘键
- 修饰键组合：GUI/WIN/COMMAND, CTRL/CONTROL, ALT/OPTION, SHIFT 配合额外的按键标记（例如 GUI r, CTRL ALT DEL）
- 按住/释放与注入修饰键：HOLD, RELEASE, INJECT_MOD (设置/清除跨后续按键持续的修饰键掩码)
- 指针/鼠标：MOUSE/POINTER CLICK, HOLD, DRAG, MOVE, SCROLL，支持 LEFT/RIGHT/MIDDLE 按键以及相对 dx/dy 和重复次数
- 控制流：IF / ELSE IF / ELSE / END_IF, WHILE / END_WHILE
- 函数与调用：FUNCTION / END_FUNCTION, CALL_FUNCTION, RETURN
- 变量与常量：VAR $name = expr, DEFINE NAME value; $?(exit code) 保持为无符号 16 位
- 随机生成器：RANDOM_LOWERCASE_LETTER, RANDOM_UPPERCASE_LETTER, RANDOM_LETTER, RANDOM_NUMBER, RANDOM_SPECIAL, RANDOM_CHAR
- 攻击模式透传：ATTACKMODE（在适用时代理到 gadget 管理层）
行为说明：
- 默认延迟：DEFAULTDELAY/DEFAULT_DELAY 设置一个基础延迟，在每个可执行命令后应用（按运行时延迟倍增器缩放）。
- 表达式求值器：在 IF/WHILE 和 VAR 赋值中支持算术、比较和逻辑表达式；非零为真。
- 重复：REPEAT N 在预处理期间将前一个命令复制 N 次。
- 键盘映射：完整的 HID usage 映射，支持布局选择；支持常见别名（ESC/ESCAPE, BKSP/BACKSPACE 等）。
- 执行流：发出 step/start/done/error 事件并附带进度，用于实时 UI 更新和日志。
Mouse/Pointer 语法快速参考：
- MOUSE CLICK [LEFT|RIGHT|MIDDLE] [num]
- MOUSE HOLD [LEFT|RIGHT|MIDDLE] [dx] [dy] [num]
- MOUSE DRAG [LEFT|RIGHT|MIDDLE] [dx] [dy] [num]
- MOUSE MOVE [dx] [dy] [num]
- MOUSE SCROLL [UP|DOWN] [num]
能力矩阵（精选）：
| Feature group | Sub-feature | Supported | Notes |
|---|---|:---:|---|
| Text/timing | STRING / STRINGLN / STRING_DELAY | ✅ | STRING_DELAY 的每字符计时；通过 DEFAULTDELAY 设置全局延迟 |
| Text blocks | STRING/STRINGLN blocks | ✅ | 以 END_STRING / END_STRINGLN 结尾的多行块 |
| Timing | DELAY, DEFAULTDELAY/DEFAULT_DELAY | ✅ | DEFAULT 在每个可执行步骤后应用 |
| Repeat | REPEAT N | ✅ | 将前一个命令复制 N 次 |
| Comments | REM, REM_BLOCK/END_REM | ✅ | 不可执行 |
| Modifiers | GUI/WIN, CTRL, ALT, SHIFT combos | ✅ | 解析为单个组合步骤 |
| Key commands | Explicit key names | ✅ | “Explicit key and alias support”中列出的所有按键/别名 |
| Hold/release | HOLD, RELEASE | ✅ | 跟踪按住的按键集；与 INJECT_MOD 配对 |
| Explicit key state | KEYDOWN, KEYUP | ✅ | 直接控制按键按下/弹起，用于组合键和按住键 |
| Injected modifiers | INJECT_MOD | ✅ | 持续保持修饰键掩码直到清除 |
| Mouse/pointer | MOUSE/POINTER CLICK/HOLD/DRAG/MOVE/SCROLL | ✅ | 带重复计数的相对运动 |
| Control flow | IF/ELSE IF/ELSE/END_IF | ✅ | 支持嵌套链 |
| Loops | WHILE/END_WHILE | ✅ | 条件由表达式引擎求值 |
| Functions | FUNCTION/END_FUNCTION, CALL/CALL_FUNCTION, RETURN | ✅ | 支持参数；RETURN 设置 $? |
| Variables | VAR $name = expr | ✅ | 整数，存储范围 0..65535；$? 为 exit code；作用域局部变量 |
| Defines | DEFINE NAME value | ✅ | 解析前的简单文本替换 |
| Error handling | TRY/CATCH/END_TRY | ✅ | 可恢复的失败，不中止脚本 |
| Waits | WAIT_FOR, SLEEP_UNTIL | ✅ | 主机/UDC/键盘就绪 + 定时等待 |
| Random | RANDOM_* generators | ✅ | lower/upper/letter/number/special/char |
| Attack modes | ATTACKMODE | ⚠️ | 已解析，但尚未实现后端处理程序 |
注意：验证器会在执行前显示语法问题、未知命令和结构错误。请参阅 Payload Editor 以获取带有行号的 UI 内验证结果。
执行计时要点：
- 独立的执行延迟倍增器和打字速度因子（可选的高风险快速模式）。
- 在长时间 STRING 运行期间定期刷新，以减少主机键缓冲区溢出。
- 主机感知退避和针对瞬时 HID 断开的宽限窗口。
- 当微睡眠不可用时的硬件感知估算校准。
### 显式 Key 和 Alias 支持
注意：除了列出的别名外，TapDucky 还接受 snake_case 形式，如 down_arrow, up_arrow, left_arrow, right_arrow, page_up, page_down, print_screen, scroll_lock, num_lock, caps_lock, string_delay, default_delay 等。这些在内部会进行规范化。
- 修饰键（在注明处支持左/右变体）：
- 左：CTRL/CONTROL, SHIFT, ALT/OPTION, GUI/WINDOWS/COMMAND/WIN
- 右：RCTRL/RCONTROL, RSHIFT, RALT, RGUI/RWINDOWS/RCOMMAND
- 系统/导航键（包含别名）：
- ENTER
- ESC/ESCAPE
- BACKSPACE/BKSP
- TAB
- SPACE
- DELETE/DEL
- INSERT/INS
- HOME, END- PAGEUP, PAGEDOWN
- 方向键：UP/UPARROW, DOWN/DOWNARROW, LEFT/LEFTARROW, RIGHT/RIGHTARROW
- 锁定键：CAPSLOCK, NUMLOCK, SCROLLLOCK
- PRINTSCREEN/PRINTSCRN/PRTSCN
- PAUSE/BREAK
- MENU/APP
- 功能键：
- F1–F24
- 小键盘键（包含别名）：
- NUMPAD_0/KP0, NUMPAD_1/KP1, NUMPAD_2/KP2, NUMPAD_3/KP3, NUMPAD_4/KP4,
NUMPAD_5/KP5, NUMPAD_6/KP6, NUMPAD_7/KP7, NUMPAD_8/KP8, NUMPAD_9/KP9
- NUMPAD_PLUS/KPPLUS, NUMPAD_MINUS/KPMINUS, NUMPAD_MULTIPLY/KPASTERISK,
NUMPAD_DIVIDE/KPSLASH, NUMPAD_ENTER/KPENTER, NUMPAD_PERIOD/KPDOT
- 媒体键（包含别名）：
- MEDIA_PLAYPAUSE/PLAYPAUSE
- MEDIA_STOP/STOPCD
- MEDIA_PREV/PREVIOUSSONG
- MEDIA_NEXT/NEXTSONG
- MEDIA_VOLUMEUP/VOLUMEUP
- MEDIA_VOLUMEDOWN/VOLUMEDOWN
- MEDIA_MUTE/MUTE
- 字母数字快捷键：
- 单个字符 A–Z 和数字 0–9 映射到相应的 HID usage codes。
### 示例
- CTRL ALT DEL
- GUI r
- SHIFT TAB
- STRING_DELAY 15 Hello world
- MOUSE CLICK LEFT 2
- MOUSE MOVE 40 0 3
## Scheduler 触发器（详情）
- One‑time（一次性）
- 在指定的日期/时间运行一次，如果在可选的时间窗口内。
- App Start (Cold Start)（App 冷启动）
- 当 App 从真正的冷启动启动时运行一次（不是从后台恢复时）。
- App Open (Foreground)（App 前台打开）
- 每次 App 进入前台时运行；可以运行多次。
- Session Armed（Session 激活）
- 当 HID session 被激活（USB gadget 绑定到 UDC）时运行 —— 通常在你点击 "Arm Session" 时。
## Payloads 管理
- 创建/编辑带参数和默认值的 Payload。
- 实时验证脚本；打开 DuckyScript 语法参考。
- 分享单个 Payload 或导出为包；从 GitHub Store 导入。
## 设备诊断
- 查看内核/UDC 列表、HID writers 就绪状态、活动配置文件状态、主机配置请求计数等。
- 复制值到剪贴板并独立刷新快照/诊断。
## 开发者笔记
- 所有特权 HID 操作都需要 root 和支持 ConfigFS gadget 的内核。
- 在 Android 8+ 上，通知使用专用通道；前台服务保持 HID session 活跃。
- App 避免将运行时 UI 字符串与 Service 层中的 Android 资源耦合，以减少资源合并风险。
## Requirements
- 具有 Linux USB Gadget (ConfigFS) 支持的已 root Android 设备
- Android 11+
- 物理设备（模拟器无法验证 USB gadget 行为）
## Installation
1. 从 Releases 下载最新的 APK：
2. 安装应用程序：
- 如有需要，启用从未知来源安装。
- 当 root 管理器提示时，授予 root 权限。
3. 启动并配置：
- 打开 TapDucky。
- 在 Advanced Settings 中，选择/调整 HID 配置（Keyboard/Mouse/Composite）、VID/PID 和键盘布局。
- 激活（Arm）一个 session 并从 Execute 运行测试命令。
## Usage
### 运行 Payload
1. 创建或导入一个 Payload（Payloads 标签页）。
2. 验证它并根据需要添加参数。
3. 进入 Execute，选择 Payload，填写参数，然后 Run。
4. 检查 Logs 和 Execution History 以查看结果。
### 调度 Payload
1. 打开 Scheduler。
2. 创建一个计划，选择触发器（一次性、冷启动、前台、armed）。
3. 可选地设置每日时间窗口和参数覆盖。
4. 保存并确保计划已启用。
### 从 GitHub Store 导入
1. 打开 Payloads Store。
2. 管理源（添加 `owner/repo` 或带有 branch/path 的完整 URL）。
3. 预览文件；TapDucky 验证 DuckyScript 并可以转换 Digispark sketches。
4. 将支持的文件直接导入到你的 Payloads。
## 截图
## License
本项目采用 GNU GPLv3 许可证授权。详见 [LICENSE](LICENSE)。
## Support
如果你遇到任何问题或有疑问，请在 GitHub 仓库提交 issue 或联系维护者。
## KaijinLab 的更多应用！
| App | What it does |
| ----------------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **[IR Blaster](https://github.com/iodn/android-ir-blaster)** | Control and test infrared functionality for compatible devices. |
| **[USBDevInfo](https://github.com/iodn/android-usb-device-info)** | Inspect USB device details and behavior to understand what's connected. |
| **[GadgetFS](https://github.com/iodn/gadgetfs)** | Experiment with USB gadget functionality (hardware‑adjacent, low‑level). |
| **[TapDucky](https://github.com/iodn/tap-ducky)** | A security/testing tool for controlled keystroke injection workflows. |
| **[HIDWiggle](https://github.com/iodn/hid-wiggle)** | A mouse jiggler built with USB gadget functionalities. |
| **[AKTune](https://github.com/iodn/android-kernel-tweaker)** | Adaptive Android kernel auto‑tuner for CPU/GPU/scheduler/memory/I/O. |标签：Android安全, BadUSB, ConfigFS, CTF工具, DNS 反向解析, DuckyScript, Gadget驱动, HID模拟, Root工具, USB HID攻击, USB Rubber Ducky, 安全测试, 安卓攻防, 按键注入, 攻击性安全, 数字取证, 模拟键盘, 漏洞搜索, 物理层攻击, 目录枚举, 移动安全, 自动化脚本, 鼠标模拟