TapDucky — Инжектор нажатий клавиш USB HID для Android

Средство выполнения DuckyScript с открытым исходным кодом для рутованных устройств Android с поддержкой USB Gadget (ConfigFS)
TapDucky позволяет создавать, настраивать, планировать и выполнять DuckyScript на Android путём эмуляции USB-клавиатуры, мыши или составного HID-устройства для разрешённого тестирования и автоматизации. Включает параметризацию полезных нагрузок, несколько триггеров планировщика, журналы выполнения и библиотеку полезных нагрузок на базе GitHub с автоматической проверкой DuckyScript и опциональным преобразованием Digispark .ino.

Обзор

• Профили USB HID-гаджетов (не требуется внешний USB-донгл на поддерживаемых/рутованных устройствах):
  • Профили клавиатуры, мыши и составные профили с настраиваемыми VID/PID, строками производителя/продукта и потребляемой мощностью.
• Конвейер DuckyScript:
  • Живая проверка с читаемыми проблемами/предупреждениями, параметрами-заполнителями, множителем задержки и опциональным джиттером для имитации человеческой скорости ввода.
• Управление полезными нагрузками:
  • Создание/редактирование полезных нагрузок с именем/описанием/тегами/параметрами, быстрый обмен/экспорт и встроенные шаблоны/мастер.
• Магазин полезных нагрузок GitHub:
  • Добавление источников, просмотр репозиториев, предпросмотр файлов с проверкой, импорт поддерживаемых скриптов; автоматическое обнаружение DuckyScript и преобразование скетчей Digispark .ino по возможности.
• Планировщик:
  • Одноразовый по дате/времени, при холодном старте приложения, при переходе в передний план или при вооружении HID-сессии (device_connected), с опциональным ежедневным временным окном.
• Выполнение и журналы:
  • Вкладка выполнения, запрос параметров, запуск/отмена, история выполнения и структурированные журналы с экспортом/очисткой и фильтром по уровню.
• Диагностика устройства:
  • Снимок состояния устройства, ядра/гаджета, информация UDC, раскладки клавиатуры; копирование в буфер обмена; примечание об обнаружении эмулятора.

Примечание: Требуется рутованное устройство с поддержкой Linux USB gadget (ConfigFS). Используйте физическое устройство, так как эмуляторы не могут проверить поведение HID.

Возможности

• Редактор полезных нагрузок и параметры

  • Создание полезных нагрузок с именем/описанием/тегами.
  • Добавление типизированных параметров со значениями по умолчанию, обязательными флагами и переопределениями для каждого выполнения.
  • Встроенный валидатор DuckyScript с сопоставлением строк/проблем и подсчётом команд.
  • Поделиться одной полезной нагрузкой или экспортировать набор.

• Магазин полезных нагрузок GitHub

  • Управление несколькими источниками GitHub (пользователь/репозиторий/ветка/путь).
  • Просмотр каталогов и предпросмотр файлов с определением формата (DuckyScript, TapDucky JSON, преобразованный скрипт Digispark (.ino)).
  • Импорт проверенных скриптов напрямую в вашу библиотеку; неудачные проверки показывают аргументированные предпросмотры.

• Выполнение и тестирование

  • Проверка перед запуском; запрос значений параметров; запуск или отмена с идентификаторами выполнения.
  • Быстрые HID-тесты: нажатие клавиш клавиатуры, движение мыши и Ctrl+Alt+Del.
  • Оценка времени выполнения на основе движка (соответствует реальной модели синхронизации).
  • Управление wakelock для поддержания активности сеансов во время выполнения.

• Планировщик и триггеры

  • Триггеры: one_time, app_cold_start, app_foreground, device_connected (сессия вооружена).
  • Опциональное ежедневное временное окно (ЧЧ:ММ → ЧЧ:ММ), включая переход через полночь.
  • Включение/отключение, редактирование и удаление расписаний; отслеживается последний запуск.
  • Привязки быстрого набора через секретные коды (авто-вооружение + фоновое выполнение).
    • Поддерживаемые коды: ##38250##, ##38251##, ##38252##, ##38253##
    • Ключи привязки для каждого кода: enabled, mode (last executed | selected payload), payload (when mode = selected payload)

• Устройство и HID-профили

  • Активация профилей клавиатуры, мыши или составного профиля с настраиваемыми ID/строками/питанием.
  • Выбор раскладки клавиатуры и разрешение кода/ID.
  • Поток состояния показывает ACTIVE/IDLE, готовность писателя и запросы конфигурации хоста.

• Журналы и история

  • Вкладка журналов с фильтром по уровню (all/info/debug/warn/error), экспорт для отправки, очистка всех.
  • Детали истории выполнения с метаданными и отправка.

Для пользователя

• Панель управления с карточками быстрого статуса, статистикой полезных нагрузок/библиотеки и сводкой планировщика.
• Чёткие пустые состояния и пошаговые мастера для первоначальной настройки/импорта.
• Тема Material 3, динамические светлые/тёмные цветовые схемы.

Технические/архитектурные

• Каналы платформы (Android):
  • Method Channel: 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, медиаклавиши, клавиши numpad
• Комбинации с модификаторами: 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 и т.д.).
• Потоки выполнения: события шага/начала/завершения/ошибки отправляются с прогрессом для обновления 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 (включая псевдонимы):

  • 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 в служебном слое, чтобы снизить риск слияния ресурсов.

Требования

• Рутованное устройство Android с поддержкой Linux USB Gadget (ConfigFS)
• Android 11+
• Физическое устройство (эмуляторы не могут проверить поведение USB-гаджета)

Установка

1. Загрузите последний APK из раздела Releases:

2. Установите приложение:

   • Включите установку из неизвестных источников, если необходимо.
   • Предоставьте root-доступ при запросе от вашего root-менеджера.

3. Запустите и настройте:

   • Откройте TapDucky.
   • В расширенных настройках выберите/настройте HID-профиль (Клавиатура/Мышь/Составной), VID/PID и раскладку клавиатуры.
   • Вооружите сессию и выполните тестовую команду из раздела «Выполнить».

Использование

Запуск полезной нагрузки

1. Создайте или импортируйте полезную нагрузку (вкладка «Полезные нагрузки»).
2. Проверьте её и при необходимости добавьте параметры.
3. Перейдите в «Выполнить», выберите полезную нагрузку, заполните параметры и нажмите «Запустить».
4. Проверьте результаты в журналах и истории выполнения.

Планирование полезной нагрузки

1. Откройте «Планировщик».
2. Создайте расписание, выберите триггер (одноразовый, холодный старт, передний план, вооружение).
3. При необходимости установите ежедневное временное окно и переопределения параметров.
4. Сохраните и убедитесь, что расписание включено.

Импорт из магазина GitHub

1. Откройте «Магазин полезных нагрузок».
2. Управляйте источниками (добавьте владелец/репозиторий или полный URL с веткой/путью).
3. Просматривайте файлы; TapDucky проверяет DuckyScript и может преобразовывать скетчи Digispark.
4. Импортируйте поддерживаемые файлы напрямую в свои полезные нагрузки.

Скриншоты

Вклад

Вклад приветствуется! Если вы хотите помочь улучшить TapDucky:

1. Сделайте форк репозитория.
2. Создайте новую ветку для вашей функции или исправления ошибки.
3. Отправьте pull request с вашими предложенными изменениями.

Лицензия

Этот проект лицензирован под лицензией GNU GPLv3. См. LICENSE.

Поддержка

Если вы столкнулись с какими-либо проблемами или у вас есть вопросы, пожалуйста, откройте issue в репозитории GitHub или свяжитесь с сопровождающим.

Другие приложения от KaijinLab!