TapDucky - Injetor de Teclas HID USB para Android

Executor de DuckyScript de código aberto para Android rooteado com suporte a USB Gadget (ConfigFS)
TapDucky permite criar, personalizar, agendar e executar DuckyScript no Android emulando um teclado USB, mouse ou dispositivo HID composto para testes autorizados e automação. Inclui parametrização de payload, múltiplos gatilhos de agendamento, logs de execução e uma biblioteca de payloads baseada no GitHub com validação automática de DuckyScript e conversão opcional para Digispark .ino.

Visão Geral

• Perfis de dispositivo HID USB (sem necessidade de dongle USB externo em dispositivos com suporte/rooteados):
  • Perfis de Teclado, Mouse e Composto com VID/PID configuráveis, strings de fabricante/produto e consumo de energia.
• Pipeline DuckyScript:
  • Validação ao vivo com problemas/avisos legíveis por humanos, parâmetros de espaço reservado, multiplicador de atraso e jitter opcional para temporização mais natural.
• Gerenciamento de payloads:
  • Criar/editar payloads com nome/descrição/tags/parâmetros, compartilhamento/exportação rápida e modelos/assistente integrados.
• Loja de Payloads GitHub:
  • Adicionar fontes, navegar repositórios, visualizar arquivos com validação, importar scripts suportados; detecta automaticamente DuckyScript e converte sketches Digispark .ino quando possível.
• Agendador:
  • Única vez em data/hora, ao iniciar o app (cold start), ao abrir o app (foreground) ou quando a sessão HID é armada (device_connected), com janela de horário diária opcional.
• Execução e Logs:
  • Visualização de execução em abas, prompts de parâmetros, executar/cancelar, histórico de execução e logs estruturados com exportar/limpar e filtro por nível.
• Diagnóstico do dispositivo:
  • Instantâneo do dispositivo, status do kernel/gadget, informações de UDC, layouts de teclado; copiar para área de transferência; nota de detecção de emulador.

Nota: É necessário um dispositivo rooteado com suporte a Linux USB gadget (ConfigFS). Use um dispositivo físico, pois emuladores não podem validar o comportamento HID.

Recursos

• Editor de Payloads e Parâmetros

  • Criar payloads com nome/descrição/tags.
  • Adicionar parâmetros tipados com valores padrão, flags obrigatórias e substituições por execução.
  • Validador DuckyScript integrado com mapeamento linha/problema e contagem de comandos.
  • Compartilhar um único payload ou exportar um pacote.

• Loja de Payloads GitHub

  • Gerenciar múltiplas fontes GitHub (usuário/repo/branch/caminho).
  • Navegar por diretórios e visualizar arquivos com detecção de formato (DuckyScript, TapDucky JSON, script Digispark (.ino) convertido).
  • Importar scripts validados diretamente para sua biblioteca; validações falhas mostram visualizações com justificativa.

• Executar e Testar

  • Validar antes de executar; solicitar valores de parâmetros; executar ou cancelar com IDs de execução.
  • Testes HID rápidos: pressionamento de tecla, movimento do mouse e Ctrl+Alt+Del.
  • Estimativa de tempo de execução baseada no motor (corresponde ao modelo de temporização real).
  • Controle de wakelock para manter sessões ativas durante a execução.

• Agendador e Gatilhos

  • Gatilhos: one_time (única vez), app_cold_start (início do app), app_foreground (app em primeiro plano), device_connected (sessão armada).
  • Janela de horário diária opcional (HH:MM → HH:MM), incluindo atravessar meia-noite.
  • Ativar/desativar, editar e excluir agendamentos; última execução registrada.
  • Atalhos de discagem via códigos secretos (armar automaticamente + execução em segundo plano).
    • Códigos suportados: ##38250##, ##38251##, ##38252##, ##38253##
    • Chaves de vinculação por código: ativado, modo (último executado | payload selecionado), payload (quando modo = payload selecionado)

• Perfis de Dispositivo e HID

  • Ativar perfis de Teclado, Mouse ou Composto com IDs/strings/potência configuráveis.
  • Seleção de layout de teclado e resolução de código/ID.
  • Fluxo de status mostra ATIVO/OCIOSO, prontidão do escritor e solicitações de configuração do host.

• Logs e Histórico

  • Aba de logs com filtro por nível (todos/info/debug/warn/error), exportar para compartilhar, limpar todos.
  • Detalhes do histórico de execução com metadados e compartilhamento.

Para o usuário

• Painel com cartões de status rápidos, estatísticas de payload/biblioteca e resumo do agendador.
• Estados vazios claros e assistentes passo a passo para configuração/importação inicial.
• Tematização Material 3, esquemas de cores dinâmicos claro/escuro.

Técnico/arquitetural

• Canais de plataforma (Android):
  • Canal de Método: org.kaijinlab.tap_ducky/gadget
    • checkRoot, checkSupport, listUdcs, getStatus, getDiagnostics
    • getKeyboardLayouts, setKeyboardLayout, resolveKeyboardLayoutId, setKeyboardLayoutByCode
    • activateProfile, deactivate, panicStop, retryOpenHidWriters

Motor DuckyScript / Teclas

O TapDucky inclui um motor completo no estilo DuckyScript implementado nativamente no Android (Kotlin) com avaliação de expressões e fluxo de controle estruturado. Suporta teclado, mouse/ponteiro, temporização, variáveis/defines, funções e utilitários simples de aleatoriedade.

Famílias de comandos suportadas (alto nível):

• Texto e temporização: STRING, STRINGLN, STRING_DELAY, DELAY, DEFAULTDELAY/DEFAULT_DELAY, REM (e REM_BLOCK)
• Teclas e combinações: ENTER, TAB, ESC, SPACE, BACKSPACE, setas, teclas de navegação (HOME/END/PGUP/PGDN/INS/DEL), F1–F24, teclas de mídia, teclas do numpad
• Combinações com modificadores: GUI/WIN/COMMAND, CTRL/CONTROL, ALT/OPTION, SHIFT com tokens de tecla adicionais (ex.: GUI r, CTRL ALT DEL)
• Segurar/soltar e modificadores injetados: HOLD, RELEASE, INJECT_MOD (definir/limpar máscara de modificador que persiste em pressionamentos de tecla subsequentes)
• Ponteiro/mouse: MOUSE/POINTER CLICK, HOLD, DRAG, MOVE, SCROLL com botões LEFT/RIGHT/MIDDLE e dx/dy relativo e contagem de repetição
• Fluxo de controle: IF / ELSE IF / ELSE / END_IF, WHILE / END_WHILE
• Funções e chamadas: FUNCTION / END_FUNCTION, CALL_FUNCTION, RETURN
• Variáveis e constantes: VAR $nome = expr, DEFINE NOME valor; $?(código de saída) mantido como inteiro sem sinal de 16 bits
• Geradores aleatórios: RANDOM_LOWERCASE_LETTER, RANDOM_UPPERCASE_LETTER, RANDOM_LETTER, RANDOM_NUMBER, RANDOM_SPECIAL, RANDOM_CHAR
• Passagem de modo de ataque: ATTACKMODE (encaminhado para a camada do gerenciador de gadget quando aplicável)

Notas sobre comportamento:

• Atraso padrão: DEFAULTDELAY/DEFAULT_DELAY define um atraso base aplicado após cada comando executável (escalado pelo multiplicador de atraso de execução).
• Avaliador de expressão: aritmética, comparações e expressões lógicas são suportadas em IF/WHILE e atribuições VAR; diferente de zero é verdadeiro.
• Repetição: REPEAT N duplica o comando anterior N vezes durante o pré-processamento.
• Mapeamento de teclado: mapeamento completo de uso HID com seleção de layout; aliases comuns suportados (ESC/ESCAPE, BKSP/BACKSPACE, etc.).
• Fluxos de execução: eventos de passo/início/conclusão/erro são emitidos com progresso, para atualizações de UI em tempo real e logs.

Referência rápida de sintaxe 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]

Matriz de capacidades (selecionada):

Nota: O validador exibe erros de sintaxe, comandos desconhecidos e erros de estrutura antes da execução. Consulte o Editor de Payloads para resultados de validação na interface com números de linha.

Destaques de temporização de execução:

• Multiplicador de atraso de execução separado e fator de velocidade de digitação (com modo rápido arriscado opcional).
• Descarga periódica durante execuções longas de STRING para reduzir estouros de buffer de teclas do host.
• Retirada com conhecimento do host e janela de tolerância para desconexões HID transitórias.
• Calibração de estimativa ciente de hardware quando o micro-sleep não está disponível.

Suporte a teclas explícitas e aliases

Nota: Além dos aliases listados, o TapDucky aceita formas 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. Elas são normalizadas internamente.

• Modificadores (variantes esquerda/direita suportadas onde indicado):

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

• Teclas de sistema/navegação (aliases incluídos):

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

• Teclas de função:

  • F1–F24

• Teclas do numpad (aliases incluídos):

  • 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 de mídia (aliases incluídos):

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

• Atalhos alfanuméricos:

  • Caracteres únicos A–Z e dígitos 0–9 mapeiam para os códigos de uso HID correspondentes.

Exemplos

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

Gatilhos do Agendador (Detalhes)

• Única vez (One-time)
  • Executa uma vez em uma data/hora especificada, se dentro da janela de horário opcional.
• Início do App (Cold Start)
  • Executa uma vez quando o app inicia a partir de um cold start verdadeiro (não ao retomar do segundo plano).
• Abertura do App (Foreground)
  • Executa cada vez que o app fica em primeiro plano; pode executar muitas vezes.
• Sessão Armada (Session Armed)
  • Executa quando a sessão HID é armada (USB gadget se liga ao UDC) — tipicamente ao tocar em "Arm Session".

Gerenciamento de Payloads

• Criar/editar payloads com parâmetros e valores padrão.
• Validar scripts ao vivo; abrir a referência de sintaxe DuckyScript.
• Compartilhar payloads individuais ou exportar um pacote; importar da Loja GitHub.

Diagnóstico do Dispositivo

• Visualizar lista do kernel/UDC, prontidão dos escritores HID, estado do perfil ativo, contagem de solicitações de configuração do host e mais.
• Copiar valores para a área de transferência e atualizar instantâneo/diagnóstico independentemente.

Notas para Desenvolvedores

• Todas as ações HID privilegiadas exigem root e um kernel com suporte a ConfigFS gadget.
• No Android 8+, as notificações usam um canal dedicado; o serviço em primeiro plano mantém a sessão HID ativa.
• O app evita acoplar strings de UI de tempo de execução a recursos do Android na camada de serviço para reduzir o risco de mesclagem de recursos.

Requisitos

• Dispositivo Android rooteado com suporte a Linux USB Gadget (ConfigFS)
• Android 11+
• Dispositivo físico (emuladores não podem validar o comportamento do USB gadget)

Instalação

1. Baixe o APK mais recente das Releases:

2. Instale o aplicativo:

   • Habilite a instalação de fontes desconhecidas, se necessário.
   • Conceda root quando solicitado pelo seu gerenciador de root.

3. Inicie e Configure:

   • Abra o TapDucky.
   • Em Configurações Avançadas, escolha/ajuste o perfil HID (Teclado/Mouse/Composto), VID/PID e layout do teclado.
   • Arme uma sessão e execute um comando de teste em Executar.

Uso

Executando um Payload

1. Crie ou importe um payload (aba Payloads).
2. Valide-o e adicione parâmetros se necessário.
3. Vá para Executar, selecione o payload, preencha os parâmetros e execute.
4. Verifique os Logs e o Histórico de Execução para resultados.

Agendando um Payload

1. Abra o Agendador.
2. Crie um agendamento, escolha o gatilho (única vez, cold start, foreground, armado).
3. Opcionalmente, defina uma janela de horário diária e substituições de parâmetros.
4. Salve e certifique-se de que o agendamento está ativado.

Importar da Loja GitHub

1. Abra a Loja de Payloads.
2. Gerencie fontes (adicione owner/repo ou URL completa com branch/caminho).
3. Visualize arquivos; o TapDucky valida DuckyScript e pode converter sketches Digispark.
4. Importe arquivos suportados diretamente para seus payloads.

Capturas de Tela

Contribuindo

Contribuições são bem-vindas! Se você quiser ajudar a melhorar o TapDucky:

1. Faça um fork do repositório.
2. Crie um novo branch para sua funcionalidade ou correção de bug.
3. Envie um pull request com suas alterações propostas.

Licença

Este projeto está licenciado sob a Licença GNU GPLv3. Consulte LICENSE.

Suporte

Se você encontrar problemas ou tiver dúvidas, abra uma issue no repositório GitHub ou entre em contato com o mantenedor.

Mais Apps do KaijinLab!