TapDucky - Inyector de pulsaciones de teclado USB HID para Android

Ejecutor de DuckyScript de código abierto para Android rooteado con soporte de USB Gadget (ConfigFS)
TapDucky te permite crear, personalizar, programar y ejecutar DuckyScript en Android emulando un teclado USB, un ratón o un dispositivo HID compuesto para pruebas autorizadas y automatización. Incluye parametrización de payloads, múltiples disparadores de programación, registros de ejecución y una biblioteca de payloads respaldada por GitHub con validación automática de DuckyScript y conversión opcional de .ino de Digispark.

Resumen

• Perfiles de gadget HID USB (no requiere dongle USB externo en dispositivos compatibles/rooteados):
  • Perfiles de Teclado, Ratón y Compuesto con VID/PID configurables, cadenas de fabricante/producto y consumo de energía.
• Pipeline de DuckyScript:
  • Validación en vivo con problemas/advertencias legibles, parámetros de marcador de posición, multiplicador de retardo y jitter opcional para un tiempo similar al humano.
• Gestión de payloads:
  • Crear/editar payloads con nombre/descripción/etiquetas/parámetros, compartir/exportar rápido, y plantillas/asistente integrados.
• Tienda de payloads de GitHub:
  • Agregar fuentes, navegar repositorios, previsualizar archivos con validación, importar scripts compatibles; detecta automáticamente DuckyScript y convierte bocetos .ino de Digispark cuando sea posible.
• Programador:
  • Única vez en fecha/hora, al inicio en frío de la app, al primer plano de la app, o cuando la sesión HID está armada (device_connected), con ventana de tiempo diaria opcional.
• Ejecución y Registros:
  • Vista de ejecución con pestañas, indicaciones de parámetros, ejecutar/cancelar, historial de ejecución y registros estructurados con exportar/limpiar y filtro de nivel.
• Diagnósticos del dispositivo:
  • Instantánea del dispositivo, estado del kernel/gadget, información UDC, diseños de teclado; copiar al portapapeles; nota de detección de emulador.

Nota: Se requiere un dispositivo rooteado con soporte de gadget USB de Linux (ConfigFS). Use un dispositivo físico, ya que los emuladores no pueden validar el comportamiento HID.

Características

• Editor de Payloads y Parámetros

  • Crear payloads con nombre/descripción/etiquetas.
  • Agregar parámetros tipados con valores predeterminados, banderas obligatorias y anulaciones por ejecución.
  • Validador de DuckyScript integrado con mapeo de línea/problema y conteo de comandos.
  • Compartir un solo payload o exportar un paquete.

• Tienda de Payloads de GitHub

  • Gestionar múltiples fuentes de GitHub (usuario/repo/rama/ruta).
  • Navegar directorios y previsualizar archivos con detección de formato (DuckyScript, TapDucky JSON, script de Digispark (.ino) convertido).
  • Importar scripts validados directamente a tu biblioteca; las validaciones fallidas muestran vistas previas razonadas.

• Ejecutar y Probar

  • Validar antes de ejecutar; solicitar valores de parámetros; ejecutar o cancelar con IDs de ejecución.
  • Pruebas HID rápidas: pulsación de tecla de teclado, movimiento del ratón y Ctrl+Alt+Del.
  • Estimación de tiempo de ejecución basada en el motor (coincide con el modelo de temporización real).
  • Control de wakelock para mantener las sesiones activas durante la ejecución.

• Programador y Disparadores

  • Disparadores: one_time, app_cold_start, app_foreground, device_connected (sesión armada).
  • Ventana de tiempo diaria opcional (HH:MM → HH:MM), incluyendo envolvente a medianoche.
  • Habilitar/deshabilitar, editar y eliminar horarios; último seguimiento de ejecución.
  • Enlaces directos de marcación a través de códigos secretos (armado automático + ejecución en segundo plano).
    • Códigos soportados: *#*#38250#*#*, *#*#38251#*#*, *#*#38252#*#*, *#*#38253#*#*
    • Claves de enlace por código: habilitado, modo (último ejecutado | payload seleccionado), payload (cuando modo = payload seleccionado)

• Dispositivo y Perfiles HID

  • Activar perfiles de Teclado, Ratón o Compuesto con IDs/cadenas/consumo de energía configurables.

Orientado al usuario

• Panel con tarjetas de estado rápido, estadísticas de payload/biblioteca y resumen del programador.
• Estados vacíos claros y asistentes paso a paso para configuración/importaciones por primera vez.
• Tema Material 3, esquemas de color dinámicos claro/oscuro.

Técnico/arquitectónico

• Canales de plataforma (Android):
  • Method Channel: org.kaijinlab.tap_ducky/gadget
    • checkRoot, checkSupport, listUdcs, getStatus, getDiagnostics
    • getKeyboardLayouts, setKeyboardLayout, resolveKeyboardLayoutId, setKeyboardLayoutByCode
    • activateProfile, deactivate, panicStop, retryOpenHidWriters

Motor de DuckyScript / Pulsaciones

TapDucky incluye un motor completo al estilo DuckyScript implementado de forma nativa en Android (Kotlin) con evaluación de expresiones y flujo de control estructurado. Soporta teclado, ratón/puntero, temporización, variables/defines, funciones y utilidades simples de aleatoriedad.

Familias de comandos compatibles (alto nivel):

• Texto y temporización: STRING, STRINGLN, STRING_DELAY, DELAY, DEFAULTDELAY/DEFAULT_DELAY, REM (y REM_BLOCK)
• Teclas y combinaciones: ENTER, TAB, ESC, SPACE, BACKSPACE, flechas, teclas de navegación (HOME/END/PGUP/PGDN/INS/DEL), F1–F24, teclas multimedia, teclas del teclado numérico
• Combinaciones de modificadores: GUI/WIN/COMMAND, CTRL/CONTROL, ALT/OPTION, SHIFT con tokens de tecla adicionales (por ejemplo, GUI r, CTRL ALT DEL)
• Mantener/soltar y modificadores inyectados: HOLD, RELEASE, INJECT_MOD (establecer/limpiar máscara de modificador que persiste en pulsaciones de tecla posteriores)
• Puntero/ratón: MOUSE/POINTER CLICK, HOLD, DRAG, MOVE, SCROLL con botones LEFT/RIGHT/MIDDLE y dx/dy relativo y conteo de repetición
• Flujo de control: IF / ELSE IF / ELSE / END_IF, WHILE / END_WHILE
• Funciones y llamadas: FUNCTION / END_FUNCTION, CALL_FUNCTION, RETURN
• Variables y constantes: VAR $nombre = expr, DEFINE NOMBRE valor; $?(código de salida) mantenido como unsigned de 16 bits
• Generadores aleatorios: RANDOM_LOWERCASE_LETTER, RANDOM_UPPERCASE_LETTER, RANDOM_LETTER, RANDOM_NUMBER, RANDOM_SPECIAL, RANDOM_CHAR
• Paso a través del modo de ataque: ATTACKMODE (proxy a la capa del gestor de gadget cuando sea aplicable)

Notas sobre el comportamiento:

• Retardo predeterminado: DEFAULTDELAY/DEFAULT_DELAY establece un retardo base aplicado después de cada comando ejecutable (escalado por el multiplicador de retardo en tiempo de ejecución).
• Evaluador de expresiones: se admiten expresiones aritméticas, de comparación y lógicas en IF/WHILE y asignaciones VAR; distinto de cero es verdadero.
• Repetición: REPEAT N duplica el comando anterior N veces durante el preprocesamiento.
• Mapeo de teclado: mapeo completo de usos HID con selección de diseño; se admiten alias comunes (ESC/ESCAPE, BKSP/BACKSPACE, etc.).
• Flujos de ejecución: se emiten eventos de paso/inicio/terminado/error con progreso, para actualizaciones en tiempo real de la interfaz de usuario y registros.

Referencia rápida de sintaxis de ratón/puntero:

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

Matriz de capacidades (seleccionada):

Nota: El validador muestra problemas de sintaxis, comandos desconocidos y errores de estructura antes de la ejecución. Consulte el Editor de Payloads para ver los resultados de validación en la interfaz de usuario con números de línea.

Destacados de temporización de ejecución:

• Multiplicador de retardo de ejecución separado y factor de velocidad de escritura (con modo rápido riesgoso opcional).
• Vaciado periódico durante ejecuciones largas de STRING para reducir desbordamientos del búfer de teclas del host.
• Retroceso consciente del host y ventana de gracia para desconexiones HID transitorias.
• Calibración de estimación consciente del hardware cuando el microsueño no está disponible.

Soporte de tecla explícita y alias

Nota: Además de los alias enumerados, TapDucky acepta formas en snake_case como down_arrow, up_arrow, left_arrow, right_arrow, page_up, page_down, print_screen, scroll_lock, num_lock, caps_lock, string_delay, default_delay, etc. Estos se normalizan internamente.

• Modificadores (variantes izquierda/derecha admitidas cuando se indica):

  • Izquierda: CTRL/CONTROL, SHIFT, ALT/OPTION, GUI/WINDOWS/COMMAND/WIN
  • Derecha: RCTRL/RCONTROL, RSHIFT, RALT, RGUI/RWINDOWS/RCOMMAND

• Teclas del sistema/navegación (alias incluidos):

  • ENTER
  • ESC/ESCAPE
  • BACKSPACE/BKSP
  • TAB
  • SPACE
  • DELETE/DEL
  • INSERT/INS
  • HOME, END
  • PAGEUP, PAGEDOWN
  • Flechas: UP/UPARROW, DOWN/DOWNARROW, LEFT/LEFTARROW, RIGHT/RIGHTARROW
  • BLOQUEOS: CAPSLOCK, NUMLOCK, SCROLLLOCK
  • PRINTSCREEN/PRINTSCRN/PRTSCN
  • PAUSE/BREAK
  • MENU/APP

• Teclas de función:

  • F1–F24

• Teclas del teclado numérico (alias incluidos):

  • 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

• Teclas multimedia (alias incluidos):

  • MEDIA_PLAYPAUSE/PLAYPAUSE
  • MEDIA_STOP/STOPCD
  • MEDIA_PREV/PREVIOUSSONG
  • MEDIA_NEXT/NEXTSONG
  • MEDIA_VOLUMEUP/VOLUMEUP
  • MEDIA_VOLUMEDOWN/VOLUMEDOWN
  • MEDIA_MUTE/MUTE

• Atajos alfanuméricos:

  • Los caracteres individuales A–Z y los dígitos 0–9 se asignan a los códigos de uso HID correspondientes.

Ejemplos

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

Disparadores del Programador (Detalles)

• Única vez
  • Se ejecuta una vez en una fecha/hora especificada, si está dentro de la ventana de tiempo opcional.
• Inicio de App (Inicio en frío)
  • Se ejecuta una vez cuando la app se inicia desde un inicio en frío real (no al reanudar desde segundo plano).
• Apertura de App (Primer plano)
  • Se ejecuta cada vez que la app pasa a primer plano; puede ejecutarse muchas veces.
• Sesión Armada
  • Se ejecuta cuando la sesión HID está armada (el gadget USB se vincula a UDC) — generalmente cuando tocas "Armar Sesión".

Gestión de Payloads

• Crear/editar payloads con parámetros y valores predeterminados.
• Validar scripts en vivo; abrir la referencia de sintaxis de DuckyScript.
• Compartir payloads individuales o exportar un paquete; importar desde la Tienda de GitHub.

Diagnósticos del Dispositivo

• Ver lista de kernel/UDC, preparación de los escritores HID, estado del perfil activo, conteo de solicitudes de configuración del host, y más.
• Copiar valores al portapapeles y actualizar instantánea/diagnósticos de forma independiente.

Notas para Desarrolladores

• Todas las acciones HID privilegiadas requieren root y un kernel con soporte de Gadget ConfigFS.
• En Android 8+, las notificaciones usan un canal dedicado; el servicio en primer plano mantiene activa la sesión HID.
• La app evita acoplar cadenas de la interfaz de usuario en tiempo de ejecución a recursos de Android en la capa de servicio para reducir el riesgo de fusión de recursos.

Requisitos

• Dispositivo Android rooteado con soporte de Gadget USB de Linux (ConfigFS)
• Android 11+
• Dispositivo físico (los emuladores no pueden validar el comportamiento del gadget USB)

Instalación

1. Descarga el APK más reciente desde Releases:

2. Instala la aplicación:

   • Habilita la instalación desde fuentes desconocidas si es necesario.
   • Concede root cuando lo solicite tu gestor de root.

3. Inicia y Configura:

   • Abre TapDucky.
   • En Configuración Avanzada, elige/ajusta el perfil HID (Teclado/Ratón/Compuesto), VID/PID y diseño de teclado.
   • Arma una sesión y ejecuta un comando de prueba desde Ejecutar.

Uso

Ejecutar un Payload

1. Crea o importa un payload (pestaña Payloads).
2. Valídalo y agrega parámetros si es necesario.
3. Ve a Ejecutar, selecciona el payload, completa los parámetros y pulsa Ejecutar.
4. Revisa los Registros y el Historial de Ejecución para ver los resultados.

Programar un Payload

1. Abre el Programador.
2. Crea un horario, elige el disparador (única vez, inicio en frío, primer plano, armado).
3. Opcionalmente, establece una ventana de tiempo diaria y anulaciones de parámetros.
4. Guarda y asegúrate de que el horario esté habilitado.

Importar desde la Tienda de GitHub

1. Abre la Tienda de Payloads.
2. Gestiona fuentes (agrega owner/repo o URL completa con rama/ruta).
3. Previsualiza archivos; TapDucky valida DuckyScript y puede convertir bocetos de Digispark.
4. Importa archivos compatibles directamente a tus payloads.

Capturas de Pantalla

Contribuciones

¡Las contribuciones son bienvenidas! Si deseas ayudar a mejorar TapDucky:

1. Haz un fork del repositorio.
2. Crea una nueva rama para tu característica o corrección de errores.
3. Envía una solicitud de extracción con tus cambios propuestos.

Licencia

Este proyecto está licenciado bajo la Licencia GNU GPLv3. Ver LICENSE.

Soporte

Si encuentras algún problema o tienes preguntas, por favor abre un issue en el repositorio de GitHub o contacta al mantenedor.

Más Apps de KaijinLab!