TapDucky - Android USB HID 击键注入器

用于已 Root 安卓设备的开源 DuckyScript 执行器，支持 USB Gadget (ConfigFS)
TapDucky 允许您通过模拟 USB 键盘、鼠标或复合 HID 设备，在 Android 上创建、自定义、调度和运行 DuckyScript，用于授权测试和自动化。它包括有效载荷参数化、多个调度器触发器、执行日志以及一个由 GitHub 支持的有效载荷库，具有自动 DuckyScript 验证和可选的 Digispark .ino 转换功能。

概述

• USB HID 小工具配置文件（在支持/已 Root 设备上无需外部 USB 加密狗）：
  • 键盘、鼠标和复合配置文件，可配置 VID/PID、制造商/产品字符串和功耗。
• DuckyScript 流水线：
  • 实时验证，附带人类可读的问题/警告、占位符参数、延迟倍增器，以及用于模拟人类操作节奏的可选抖动。
• 有效载荷管理：
  • 使用名称/描述/标签/参数创建/编辑有效载荷，快速分享/导出，内置模板/向导。
• GitHub 有效载荷商店：
  • 添加来源，浏览仓库，预览带验证的文件，导入支持的脚本；自动检测 DuckyScript，并在可能时转换 Digispark .ino 草图。
• 调度器：
  • 一次性（日期/时间）、应用冷启动、应用前台或 HID 会话武装时（device_connected），可选的每日时间窗口。
• 执行与日志：
  • 带标签的执行视图、参数提示、运行/取消、执行历史记录，以及带导出/清除和级别过滤的结构化日志。
• 设备诊断：
  • 设备、内核/小工具状态、UDC 信息、键盘布局的快照；复制到剪贴板；模拟器检测提示。

注意：需要已 Root 且支持 Linux USB 小工具 (ConfigFS) 的设备。请使用物理设备，因为模拟器无法验证 HID 行为。

功能

• 有效载荷编辑器和参数

  • 使用名称/描述/标签创建有效载荷。
  • 添加带默认值、必需标记和每次执行覆盖的键入参数。
  • 内置 DuckyScript 验证器，带行号/问题映射和命令计数。
  • 分享单个有效载荷或导出包。

• GitHub 有效载荷商店

  • 管理多个 GitHub 来源（用户/仓库/分支/路径）。
  • 浏览目录并预览文件，格式检测（DuckyScript、TapDucky JSON、Digispark 脚本 (.ino) 转换）。
  • 直接将已验证脚本导入到您的库中；验证失败会显示带理由的预览。

• 执行与测试

  • 运行前验证；提示参数值；运行或取消，带执行 ID。
  • 快速 HID 测试：键盘按键、鼠标移动和 Ctrl+Alt+Del。
  • 基于引擎的运行时间估算（与实际时序模型匹配）。
  • 唤醒锁控制，在执行期间保持会话活动。

• 调度器与触发器

  • 触发器：一次性、应用冷启动、应用前台、设备连接（会话武装）。
  • 可选的每日时间窗口（HH:MM → HH:MM），包括跨午夜。
  • 启用/禁用、编辑和删除调度；追踪上次运行时间。
  • 通过秘密代码的拨号快捷绑定（自动武装 + 后台执行）。
    • 支持的代码：##38250##、##38251##、##38252##、##38253##
    • 每个代码的绑定键：启用、模式（最后执行 | 选定有效载荷）、有效载荷（当模式 = 选定有效载荷时）

• 设备和 HID 配置文件

  • 激活键盘、鼠标或复合配置文件，可配置 ID/字符串/功耗。
  • 键盘布局选择和代码/ID 解析。
  • 状态流显示 ACTIVE/IDLE、写入器就绪状态和主机配置请求。

• 日志与历史

  • 日志选项卡，带级别过滤（全部/信息/调试/警告/错误）、导出共享、清除全部。
  • 执行历史详情，带元数据和共享。

用户界面

• 仪表板，带快速状态卡片、有效载荷/库统计和调度器摘要。
• 清晰的空状态和首次设置/导入的分步向导。
• Material 3 主题，动态浅色/深色配色方案。

技术/架构

• 平台通道（Android）：
  • 方法通道：org.kaijinlab.tap_ducky/gadget
    • checkRoot、checkSupport、listUdcs、getStatus、getDiagnostics
    • getKeyboardLayouts、setKeyboardLayout、resolveKeyboardLayoutId、setKeyboardLayoutByCode
    • activateProfile、deactivate、panicStop、retryOpenHidWriters

DuckyScript / 击键引擎

TapDucky 包含一个完整的 DuckyScript 风格引擎，在 Android（Kotlin）上原生实现，支持表达式求值和结构化控制流。它支持键盘、鼠标/指针、时序、变量/定义、函数和简单的随机工具。

支持的命令系列（高级）：

• 文本和时序：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；$?（退出码）保持为无符号 16 位
• 随机生成器：RANDOM_LOWERCASE_LETTER、RANDOM_UPPERCASE_LETTER、RANDOM_LETTER、RANDOM_NUMBER、RANDOM_SPECIAL、RANDOM_CHAR
• 攻击模式透传：ATTACKMODE（在适用时代理到小工具管理器层）

行为说明：

• 默认延迟：DEFAULTDELAY/DEFAULT_DELAY 设置基本延迟，应用于每条可执行命令之后（按运行时延迟倍增器缩放）。
• 表达式求值器：IF/WHILE 和 VAR 赋值支持算术、比较和逻辑表达式；非零视为真。
• 重复：REPEAT N 在预处理期间将前一条命令复制 N 次。
• 键盘映射：完整的 HID 用法映射，带布局选择；支持常用别名（ESC/ESCAPE、BKSP/BACKSPACE 等）。
• 执行流：发出 step/start/done/error 事件，带进度，用于实时 UI 更新和日志。

鼠标/指针语法快速参考：

• 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]

能力矩阵（精选）：

注意：验证器会在执行前报告语法错误、未知命令和结构错误。请参阅有效载荷编辑器以查看带行号的 UI 内验证结果。

执行时序重点：

• 独立的执行延迟倍增器和打字速度因子（带有可选的风险快速模式）。
• 长 STRING 运行期间定期刷新，以减少主机键盘缓冲区溢出。
• 针对短暂 HID 断开的主机感知退避和宽限窗口。
• 当微睡眠不可用时的硬件感知估算校准。

显式键和别名支持

注意：除了列出的别名外，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 用法代码。

示例

• CTRL ALT DEL
• GUI r
• SHIFT TAB
• STRING_DELAY 15 Hello world
• MOUSE CLICK LEFT 2
• MOUSE MOVE 40 0 3

调度器触发器（详情）

• 一次性
  • 在指定的日期/时间运行一次，如果在可选时间窗口内。
• 应用启动（冷启动）
  • 应用从真正冷启动（而非从后台恢复）时运行一次。
• 应用打开（前台）
  • 每次应用进入前台时运行；可运行多次。
• 会话武装
  • HID 会话武装时（USB 小工具绑定到 UDC）运行——通常是在您点击“武装会话”时。

有效载荷管理

• 使用参数和默认值创建/编辑有效载荷。
• 实时验证脚本；打开 DuckyScript 语法参考。
• 分享单个有效载荷或导出包；从 GitHub 商店导入。

设备诊断

• 查看内核/UDC 列表、HID 写入器就绪状态、活动配置文件状态、主机配置请求计数等。
• 将值复制到剪贴板，并独立刷新快照/诊断。

开发者说明

• 所有特权 HID 操作都需要 Root 和支持 ConfigFS 小工具的内核。
• 在 Android 8+ 上，通知使用专用通道；前台服务使 HID 会话保持活动。
• 应用避免将运行时 UI 字符串耦合到服务层的 Android 资源，以减少资源合并风险。

要求

• 已 Root 且支持 Linux USB 小工具 (ConfigFS) 的 Android 设备
• Android 11+
• 物理设备（模拟器无法验证 USB 小工具行为）

安装

1. 从发行版下载最新 APK：

2. 安装应用程序：

   • 如有需要，启用从未知来源安装。
   • 当 Root 管理器提示时授予 Root 权限。

3. 启动并配置：

   • 打开 TapDucky。
   • 在高级设置中，选择/调整 HID 配置文件（键盘/鼠标/复合）、VID/PID 和键盘布局。
   • 武装会话并从“执行”运行测试命令。

用法

运行有效载荷

1. 创建或导入有效载荷（有效载荷标签页）。
2. 验证它，如有需要添加参数。
3. 前往“执行”，选择有效载荷，填写参数，然后运行。
4. 检查日志和执行历史以查看结果。

调度有效载荷

1. 打开调度器。
2. 创建调度，选择触发器（一次性、冷启动、前台、武装）。
3. 可选设置每日时间窗口和参数覆盖。
4. 保存并确保调度已启用。

从 GitHub 商店导入

1. 打开有效载荷商店。
2. 管理来源（添加 owner/repo 或包含分支/路径的完整 URL）。
3. 预览文件；TapDucky 验证 DuckyScript 并可转换 Digispark 草图。
4. 直接导入支持的文件到您的有效载荷。

屏幕截图

贡献

欢迎贡献！如果您想帮助改进 TapDucky：

1. Fork 此仓库。
2. 为您的功能或错误修复创建一个新分支。
3. 提交包含您拟议更改的拉取请求。

许可证

本项目采用 GNU GPLv3 许可证许可。请参阅 LICENSE。

支持

如果您遇到任何问题或有疑问，请在 GitHub 仓库上提出 issue 或联系维护者。

KaijinLab 的更多应用！