TapDucky - Iniettore di sequenze di tasti HID USB per Android

Eseguire script DuckyScript open-source per Android rooted con supporto USB Gadget (ConfigFS)
TapDucky ti permette di creare, personalizzare, programmare ed eseguire DuckyScript su Android emulando una tastiera USB, un mouse o un dispositivo HID composito per test autorizzati e automazione. Include parametrizzazione dei payload, molteplici trigger dello scheduler, log di esecuzione e una libreria di payload basata su GitHub con validazione automatica DuckyScript e conversione opzionale Digispark .ino.

Panoramica

• Profili gadget USB HID (nessun dongle USB esterno richiesto su dispositivi supportati/rooted):
  • Profili Tastiera, Mouse e Composito con VID/PID configurabili, stringhe produttore/prodotto e consumo energetico.
• Pipeline DuckyScript:
  • Validazione in tempo reale con problemi/avvisi leggibili, parametri segnaposto, moltiplicatore di ritardo e jitter opzionale per tempistiche umane.
• Gestione dei payload:
  • Crea/modifica payload con nome/descrizione/tag/parametri, condivisione/esportazione rapida e modelli/guida integrati.
• Negozio di Payload GitHub:
  • Aggiungi sorgenti, sfoglia repository, visualizza file con validazione, importa script supportati; rileva automaticamente DuckyScript e converte sketch Digispark .ino quando possibile.
• Scheduler:
  • Una tantum a data/ora, all'avvio a freddo dell'app, quando l'app è in primo piano o quando la sessione HID è armata (device_connected), con finestra temporale giornaliera opzionale.
• Esecuzione e Log:
  • Visualizzazione esecuzione a schede, richieste parametri, esecuzione/annullamento, cronologia esecuzioni e log strutturati con esportazione/cancellazione e filtro per livello.
• Diagnostica del dispositivo:
  • Istantanea del dispositivo, stato del kernel/gadget, informazioni UDC, layout tastiera; copia negli appunti; nota di rilevamento emulatore.

Nota: è richiesto un dispositivo rooted con supporto gadget USB Linux (ConfigFS). Utilizzare un dispositivo fisico poiché gli emulatori non possono validare il comportamento HID.

Funzionalità

• Editor Payload e Parametri

  • Crea payload con nome/descrizione/tag.
  • Aggiungi parametri tipizzati con valori predefiniti, flag obbligatori e override per esecuzione.
  • Validatore DuckyScript integrato con mappatura righe/problemi e conteggio comandi.
  • Condividi un singolo payload o esporta un pacchetto.

• Negozio Payload GitHub

  • Gestisci più sorgenti GitHub (utente/repo/branch/percorso).
  • Sfoglia directory e visualizza file con rilevamento del formato (DuckyScript, TapDucky JSON, script Digispark (.ino) convertito).
  • Importa script validati direttamente nella tua libreria; le validazioni fallite mostrano anteprime motivate.

• Esecuzione e Test

  • Valida prima dell'esecuzione; chiedi valori dei parametri; esegui o annulla con ID di esecuzione.
  • Test HID rapidi: pressione tasto tastiera, movimento mouse e Ctrl+Alt+Canc.
  • Stima del tempo di esecuzione basata sul motore (corrisponde al modello di temporizzazione reale).
  • Controllo wakelock per mantenere le sessioni attive durante l'esecuzione.

• Scheduler e Trigger

  • Trigger: one_time, app_cold_start, app_foreground, device_connected (sessione armata).
  • Finestra temporale giornaliera opzionale (HH:MM → HH:MM), inclusa la gestione del passaggio a mezzanotte.
  • Abilita/disabilita, modifica ed elimina pianificazioni; ultima esecuzione tracciata.
  • Collegamenti rapidi tramite codici segreti (armatura automatica + esecuzione in background).
    • Codici supportati: ##38250##, ##38251##, ##38252##, ##38253##
    • Tasti di associazione per codice: abilitato, modalità (ultimo eseguito | payload selezionato), payload (quando modalità = payload selezionato)

• Profili Dispositivo e HID

  • Attiva profili Tastiera, Mouse o Composito con ID/stringhe/potenza configurabili.
  • Selezione layout tastiera e risoluzione codice/ID.
  • Flusso di stato mostra ATTIVO/INATTIVO, prontezza scrittore e richieste di configurazione host.

• Log e Cronologia

  • Scheda log con filtro per livello (tutti/info/debug/avviso/errore), esportazione per condividere, cancella tutto.
  • Dettagli cronologia esecuzione con metadati e condivisione.

Aspetto utente

• Dashboard con schede di stato rapide, statistiche payload/libreria e riepilogo scheduler.
• Stati vuoti chiari e guide passo-passo per la configurazione/importazione iniziale.
• Tema Material 3, schemi colore dinamici chiaro/scuro.

Tecnico/architetturale

• Canali piattaforma (Android):
  • Canale metodo: org.kaijinlab.tap_ducky/gadget
    • checkRoot, checkSupport, listUdcs, getStatus, getDiagnostics
    • getKeyboardLayouts, setKeyboardLayout, resolveKeyboardLayoutId, setKeyboardLayoutByCode
    • activateProfile, deactivate, panicStop, retryOpenHidWriters

Motore DuckyScript / Tastiera

TapDucky include un motore completo in stile DuckyScript implementato nativamente su Android (Kotlin) con valutazione espressioni e flusso di controllo strutturato. Supporta tastiera, mouse/puntatore, temporizzazione, variabili/define, funzioni e utilità di casualità semplici.

Famiglie di comandi supportate (alto livello):

• Testo e temporizzazione: STRING, STRINGLN, STRING_DELAY, DELAY, DEFAULTDELAY/DEFAULT_DELAY, REM (e REM_BLOCK)
• Tasti e combinazioni: ENTER, TAB, ESC, SPACE, BACKSPACE, frecce, tasti di navigazione (HOME/END/PGUP/PGDN/INS/DEL), F1–F24, tasti multimediali, tasti tastierino numerico
• Combinazioni modificatori: GUI/WIN/COMMAND, CTRL/CONTROL, ALT/OPTION, SHIFT con tasti aggiuntivi (es. GUI r, CTRL ALT DEL)
• Hold/release e modificatori iniettati: HOLD, RELEASE, INJECT_MOD (imposta/cancella maschera modificatore persistente tra i successivi tasti premuti)
• Puntatore/mouse: MOUSE/POINTER CLICK, HOLD, DRAG, MOVE, SCROLL con pulsanti LEFT/RIGHT/MIDDLE e dx/dy relativi e numero di ripetizioni
• Flusso di controllo: IF / ELSE IF / ELSE / END_IF, WHILE / END_WHILE
• Funzioni e chiamate: FUNCTION / END_FUNCTION, CALL_FUNCTION, RETURN
• Variabili e costanti: VAR $nome = expr, DEFINE NOME valore; $?(codice di uscita) mantenuto come unsigned 16-bit
• Generatori casuali: RANDOM_LOWERCASE_LETTER, RANDOM_UPPERCASE_LETTER, RANDOM_LETTER, RANDOM_NUMBER, RANDOM_SPECIAL, RANDOM_CHAR
• Passaggio modalità attacco: ATTACKMODE (inviato al livello del gadget manager quando applicabile)

Note sul comportamento:

• Ritardo predefinito: DEFAULTDELAY/DEFAULT_DELAY imposta un ritardo base applicato dopo ogni comando eseguibile (scalato dal moltiplicatore di ritardo a runtime).
• Valutatore espressioni: supporta espressioni aritmetiche, di confronto e logiche in IF/WHILE e assegnazioni VAR; diverso da zero è vero.
• Ripetizione: REPEAT N duplica il comando precedente N volte durante la pre-elaborazione.
• Mappatura tastiera: mappatura completa degli usi HID con selezione layout; alias comuni supportati (ESC/ESCAPE, BKSP/BACKSPACE, ecc.).
• Flussi di esecuzione: vengono emessi eventi step/start/done/errore con progresso, per aggiornamenti UI in tempo reale e log.

Riferimento rapido sintassi mouse/puntatore:

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

Matrice di capacità (selezionate):

Nota: Il validatore solleva problemi di sintassi, comandi sconosciuti ed errori di struttura prima dell'esecuzione. Vedi l'Editor Payload per i risultati della validazione nell'interfaccia con numeri di riga.

Punti salienti della temporizzazione dell'esecuzione:

• Moltiplicatore di ritardo di esecuzione separato e fattore di velocità di digitazione (con modalità veloce rischiosa opzionale).
• Flush periodico durante esecuzioni STRING lunghe per ridurre sovraccarichi del keybuffer host.
• Backoff consapevole dell'host e finestra di grazia per disconnessioni HID temporanee.
• Calibrazione stima consapevole dell'hardware quando il micro-sleep non è disponibile.

Supporto tasti espliciti e alias

Nota: Oltre agli alias elencati, TapDucky accetta forme snake_case come down_arrow, up_arrow, left_arrow, right_arrow, page_up, page_down, print_screen, scroll_lock, num_lock, caps_lock, string_delay, default_delay, ecc. Questi vengono normalizzati internamente.

• Modificatori (varianti sinistra/destra supportate dove indicato):

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

• Tasti di sistema/navigazione (alias inclusi):

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

• Tasti funzione:

  • F1–F24

• Tasti tastierino numerico (alias inclusi):

  • 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

• Tasti multimediali (alias inclusi):

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

• Scorciatoie alfanumeriche:

  • Singoli caratteri A–Z e cifre 0–9 mappano ai corrispondenti codici di utilizzo HID.

Esempi

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

Trigger dello Scheduler (Dettagli)

• Una tantum
  • Viene eseguito una volta a una data/ora specificata, se all'interno della finestra temporale opzionale.
• Avvio App (Avvio a freddo)
  • Viene eseguito una volta quando l'app si avvia da un vero avvio a freddo (non quando riprende dallo sfondo).
• Apertura App (Primo piano)
  • Viene eseguito ogni volta che l'app passa in primo piano; può essere eseguito molte volte.
• Sessione Armata
  • Viene eseguito quando la sessione HID è armata (il gadget USB si lega a UDC) — tipicamente quando tocchi "Arma Sessione".

Gestione Payload

• Crea/modifica payload con parametri e valori predefiniti.
• Valida script in tempo reale; apri il riferimento sintassi DuckyScript.
• Condividi payload individuali o esporta un pacchetto; importa dal Negozio GitHub.

Diagnostica Dispositivo

• Visualizza elenco kernel/UDC, prontezza scrittori HID, stato profilo attivo, conteggio richieste configurazione host e altro.
• Copia valori negli appunti e aggiorna istantanea/diagnostica indipendentemente.

Note per Sviluppatori

• Tutte le azioni HID privilegiate richiedono root e un kernel con supporto gadget ConfigFS.
• Su Android 8+, le notifiche utilizzano un canale dedicato; il servizio in primo piano mantiene attiva la sessione HID.
• L'app evita di accoppiare le stringhe UI runtime alle risorse Android nel livello del servizio per ridurre il rischio di unione delle risorse.

Requisiti

• Dispositivo Android rooted con supporto USB Gadget Linux (ConfigFS)
• Android 11+
• Dispositivo fisico (gli emulatori non possono validare il comportamento del gadget USB)

Installazione

1. Scarica l'ultimo APK dai Rilasci:

   

2. Installa l'applicazione:

   • Abilita l'installazione da fonti sconosciute se necessario.
   • Concedi root quando richiesto dal tuo gestore root.

3. Avvia e configura:

   • Apri TapDucky.
   • In Impostazioni Avanzate, scegli/modifica il profilo HID (Tastiera/Mouse/Composito), VID/PID e layout tastiera.
   • Arma una sessione ed esegui un comando di test da Esecuzione.

Utilizzo

Esecuzione di un Payload

1. Crea o importa un payload (scheda Payload).
2. Validalo e aggiungi parametri se necessario.
3. Vai a Esecuzione, seleziona il payload, compila i parametri ed esegui.
4. Controlla Log e Cronologia Esecuzione per i risultati.

Pianificazione di un Payload

1. Apri Scheduler.
2. Crea una pianificazione, scegli il trigger (una tantum, avvio a freddo, primo piano, armato).
3. Imposta opzionalmente una finestra temporale giornaliera e override dei parametri.
4. Salva e assicurati che la pianificazione sia abilitata.

Importa dal Negozio GitHub

1. Apri Negozio Payload.
2. Gestisci sorgenti (aggiungi owner/repo o URL completo con branch/percorso).
3. Visualizza file; TapDucky valida DuckyScript e può convertire sketch Digispark.
4. Importa file supportati direttamente nei tuoi payload.

Screenshot

Contribuire

I contributi sono benvenuti! Se desideri aiutare a migliorare TapDucky:

1. Forka il repository.
2. Crea un nuovo branch per la tua funzionalità o correzione.
3. Invia una pull request con le modifiche proposte.

Licenza

Questo progetto è concesso in licenza secondo la GNU GPLv3. Vedi LICENSE.

Supporto

Se incontri problemi o hai domande, apri un issue sul repository GitHub o contatta il maintainer.

Altre App di KaijinLab!