TapDucky - Injecteur de frappe clavier Android USB HID

Exécuteur open-source de DuckyScript pour Android rooté avec support USB Gadget (ConfigFS)
TapDucky vous permet de créer, personnaliser, planifier et exécuter du DuckyScript sur Android en émulant un clavier USB, une souris ou un périphérique HID composite pour des tests autorisés et de l'automatisation. Il inclut la paramétrisation des payloads, de multiples déclencheurs de planification, des journaux d'exécution et une bibliothèque de payloads hébergée sur GitHub avec validation automatique du DuckyScript et conversion optionnelle en Digispark .ino.

Aperçu

• Profils de gadget HID USB (aucun dongle USB externe requis sur les appareils supportés/rootés) :
  • Profils Clavier, Souris et Composite avec VID/PID configurables, chaînes fabricant/produit et consommation électrique.
• Pipeline DuckyScript :
  • Validation en direct avec problèmes/avertissements lisibles, paramètres de substitution, multiplicateur de délai et gigue optionnelle pour un timing proche du comportement humain.
• Gestion des payloads :
  • Créer/éditer des payloads avec nom/description/tags/paramètres, partage/exportation rapide et modèles/assistant intégrés.
• Magasin de payloads GitHub :
  • Ajouter des sources, parcourir des dépôts, prévisualiser des fichiers avec validation, importer les scripts supportés ; détection automatique du DuckyScript et conversion des esquisses Digispark .ino lorsque possible.
• Planificateur :
  • Exécution unique à date/heure, au démarrage à froid de l'application, au premier plan de l'application, ou lorsque la session HID est armée (device_connected), avec fenêtre horaire quotidienne optionnelle.
• Exécution et journaux :
  • Vue d'exécution à onglets, invitations de paramètres, exécution/annulation, historique d'exécution, et journaux structurés avec exportation/effacement et filtre par niveau.
• Diagnostique de l'appareil :
  • Instantané de l'appareil, état du noyau/gadget, informations UDC, dispositions clavier ; copie dans le presse-papiers ; note de détection d'émulateur.

Remarque : Un appareil rooté avec support du gadget USB Linux (ConfigFS) est requis. Utilisez un appareil physique car les émulateurs ne peuvent pas valider le comportement HID.

Fonctionnalités

• Éditeur de payload et paramètres

  • Créer des payloads avec nom/description/tags.
  • Ajouter des paramètres typés avec des valeurs par défaut, des indicateurs obligatoires et des surcharges par exécution.
  • Validateur DuckyScript intégré avec mappage ligne/problème et comptage de commandes.
  • Partager un seul payload ou exporter un pack.

• Magasin de payloads GitHub

  • Gérer plusieurs sources GitHub (utilisateur/dépôt/branche/chemin).
  • Parcourir les répertoires et prévisualiser les fichiers avec détection de format (DuckyScript, TapDucky JSON, script Digispark (.ino) converti).
  • Importer des scripts validés directement dans votre bibliothèque ; les validations échouées montrent des aperçus motivés.

• Exécuter et tester

  • Valider avant l'exécution ; inviter à saisir les valeurs des paramètres ; exécuter ou annuler avec des identifiants d'exécution.
  • Tests HID rapides : appui sur touche clavier, déplacement de souris et Ctrl+Alt+Suppr.
  • Estimation du temps d'exécution basée sur le moteur (correspond au modèle de timing réel).
  • Contrôle du wakelock pour maintenir les sessions actives pendant l'exécution.

• Planificateur et déclencheurs

  • Déclencheurs : one_time, app_cold_start, app_foreground, device_connected (session armée).
  • Fenêtre horaire quotidienne optionnelle (HH:MM → HH:MM), y compris le passage à minuit.
  • Activer/désactiver, éditer et supprimer les plannings ; dernière exécution suivie.
  • Raccourcis de numérotation via des codes secrets (armement automatique + exécution en arrière-plan).
    • Codes supportés : ##38250##, ##38251##, ##38252##, ##38253##
    • Clés de liaison par code : activé, mode (dernière exécution | payload sélectionné), payload (lorsque mode = payload sélectionné)

• Appareil et profils HID

  • Activer les profils Clavier, Souris ou Composite avec ID/chaînes/puissance configurables.
  • Sélection de la disposition du clavier et résolution du code/ID.
  • Flux de statut montrant ACTIF/INACTIF, état de préparation de l'écrivain et requêtes de configuration de l'hôte.

• Journaux et historique

  • Onglet Journaux avec filtre par niveau (tout/info/debug/warn/error), exportation vers le partage, tout effacer.
  • Détails de l'historique d'exécution avec métadonnées et partage.

Destiné à l'utilisateur

• Tableau de bord avec cartes de statut rapides, statistiques des payloads/bibliothèque et résumé du planificateur.
• États vides clairs et assistants pas à pas pour la configuration initiale/importations.
• Thème Material 3, schémas de couleurs dynamiques clair/foncé.

Technique/architectural

• Canaux de plateforme (Android) :
  • Canal de méthode : org.kaijinlab.tap_ducky/gadget
    • checkRoot, checkSupport, listUdcs, getStatus, getDiagnostics
    • getKeyboardLayouts, setKeyboardLayout, resolveKeyboardLayoutId, setKeyboardLayoutByCode
    • activateProfile, deactivate, panicStop, retryOpenHidWriters

Moteur DuckyScript / Frappe

TapDucky inclut un moteur complet de style DuckyScript implémenté nativement sur Android (Kotlin) avec évaluation d'expressions et flux de contrôle structuré. Il supporte les commandes clavier, souris/pointeur, de timing, de variables/définitions, de fonctions et des utilitaires de génération aléatoire simples.

Familles de commandes supportées (haut niveau) :

• Texte et timing : STRING, STRINGLN, STRING_DELAY, DELAY, DEFAULTDELAY/DEFAULT_DELAY, REM (et REM_BLOCK)
• Touches et combinaisons : ENTER, TAB, ESC, SPACE, BACKSPACE, flèches, touches de navigation (HOME/END/PGUP/PGDN/INS/DEL), F1–F24, touches multimédia, touches du pavé numérique
• Combinaisons de modificateurs : GUI/WIN/COMMAND, CTRL/CONTROL, ALT/OPTION, SHIFT avec des jetons de touches supplémentaires (ex. GUI r, CTRL ALT DEL)
• Maintien/relâchement et modificateurs injectés : HOLD, RELEASE, INJECT_MOD (définir/effacer un masque de modificateurs persistant sur les frappes suivantes)
• Pointeur/souris : MOUSE/POINTER CLICK, HOLD, DRAG, MOVE, SCROLL avec boutons LEFT/RIGHT/MIDDLE et dx/dy relatifs et nombre de répétitions
• Flux de contrôle : IF / ELSE IF / ELSE / END_IF, WHILE / END_WHILE
• Fonctions et appels : FUNCTION / END_FUNCTION, CALL_FUNCTION, RETURN
• Variables et constantes : VAR $nom = expr, DEFINE NOM valeur ; $?(code de sortie) conservé en non signé 16 bits
• Générateurs aléatoires : RANDOM_LOWERCASE_LETTER, RANDOM_UPPERCASE_LETTER, RANDOM_LETTER, RANDOM_NUMBER, RANDOM_SPECIAL, RANDOM_CHAR
• Passage en mode attaque : ATTACKMODE (proxysé vers la couche de gestion du gadget lorsque applicable)

Remarques sur le comportement :

• Délai par défaut : DEFAULTDELAY/DEFAULT_DELAY définit un délai de base appliqué après chaque commande exécutable (multiplié par le multiplicateur de délai d'exécution).
• Évaluateur d'expressions : arithmétique, comparaisons et expressions logiques sont supportées dans IF/WHILE et les affectations VAR ; non nul est vrai.
• Répétition : REPEAT N duplique la commande précédente N fois lors du pré-traitement.
• Mappage clavier : mappage complet des codes HID avec sélection de disposition ; alias courants supportés (ESC/ESCAPE, BKSP/BACKSPACE, etc.).
• Flux d'exécution : les événements step/start/done/error sont émis avec la progression, pour les mises à jour UI en temps réel et les journaux.

Référence rapide de la syntaxe souris/pointeur :

• 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 de capacités (sélection) :

Remarque : Le validateur signale les erreurs de syntaxe, les commandes inconnues et les erreurs de structure avant l'exécution. Consultez l'Éditeur de payload pour les résultats de validation dans l'interface utilisateur avec les numéros de ligne.

Points clés du timing d'exécution :

• Multiplicateur de délai d'exécution séparé et facteur de vitesse de frappe (avec mode rapide risqué optionnel).
• Vidage périodique lors des longues chaînes STRING pour réduire les débordements du tampon de touches de l'hôte.
• Repli et fenêtre de grâce adaptatifs pour les déconnexions HID transitoires.
• Calibration de l'estimation matérielle lorsque la micro-pause n'est pas disponible.

Prise en charge des touches explicites et des alias

Remarque : En plus des alias listés, TapDucky accepte les formes snake_case comme 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. Ceux-ci sont normalisés en interne.

• Modificateurs (variantes gauche/droite supportées là où indiqué) :

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

• Touches système/navigation (alias inclus) :

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

• Touches de fonction :

  • F1–F24

• Touches du pavé numérique (alias inclus) :

  • 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

• Touches multimédia (alias inclus) :

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

• Raccourcis alphanumériques :

  • Les caractères individuels A–Z et les chiffres 0–9 correspondent aux codes d'utilisation HID correspondants.

Exemples

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

Déclencheurs du planificateur (Détails)

• Unique
  • S'exécute une fois à une date/heure spécifiée, si dans la fenêtre horaire optionnelle.
• Démarrage de l'application (démarrage à froid)
  • S'exécute une fois lorsque l'application démarre d'un vrai démarrage à froid (pas lors de la reprise depuis l'arrière-plan).
• Ouverture de l'application (premier plan)
  • S'exécute chaque fois que l'application passe au premier plan ; peut s'exécuter plusieurs fois.
• Session armée
  • S'exécute lorsque la session HID est armée (le gadget USB se lie à UDC) — généralement lorsque vous appuyez sur « Armer la session ».

Gestion des payloads

• Créer/éditer des payloads avec paramètres et valeurs par défaut.
• Valider les scripts en direct ; ouvrir la référence de syntaxe DuckyScript.
• Partager des payloads individuels ou exporter un pack ; importer depuis le Magasin GitHub.

Diagnostique de l'appareil

• Voir la liste UDC/noyau, l'état de préparation des écrivains HID, l'état du profil actif, le nombre de requêtes de configuration de l'hôte, et plus.
• Copier les valeurs dans le presse-papiers et rafraîchir l'instantané/diagnostique indépendamment.

Notes aux développeurs

• Toutes les actions HID privilégiées nécessitent root et un noyau avec support ConfigFS gadget.
• Sur Android 8+, les notifications utilisent un canal dédié ; un service au premier plan maintient la session HID active.
• L'application évite de coupler les chaînes UI d'exécution aux ressources Android dans la couche service pour réduire le risque de fusion des ressources.

Prérequis

• Appareil Android rooté avec support Linux USB Gadget (ConfigFS)
• Android 11+
• Appareil physique (les émulateurs ne peuvent pas valider le comportement du gadget USB)

Installation

1. Téléchargez le dernier APK depuis les versions :

2. Installez l'application :

   • Activez l'installation depuis des sources inconnues si nécessaire.
   • Accordez root lorsque votre gestionnaire root le demande.

3. Lancez et configurez :

   • Ouvrez TapDucky.
   • Dans les Paramètres avancés, choisissez/ajustez le profil HID (Clavier/Souris/Composite), VID/PID et la disposition du clavier.
   • Armez une session et exécutez une commande de test depuis Exécuter.

Utilisation

Exécuter un payload

1. Créez ou importez un payload (onglet Payloads).
2. Validez-le et ajoutez des paramètres si nécessaire.
3. Allez dans Exécuter, sélectionnez le payload, remplissez les paramètres, et exécutez.
4. Consultez les Journaux et l'Historique d'exécution pour les résultats.

Planifier un payload

1. Ouvrez le Planificateur.
2. Créez un planning, choisissez un déclencheur (unique, démarrage à froid, premier plan, armé).
3. Définissez éventuellement une fenêtre horaire quotidienne et des surcharges de paramètres.
4. Sauvegardez et assurez-vous que le planning est activé.

Importer depuis le Magasin GitHub

1. Ouvrez le Magasin de payloads.
2. Gérez les sources (ajoutez propriétaire/dépôt ou une URL complète avec branche/chemin).
3. Prévisualisez les fichiers ; TapDucky valide le DuckyScript et peut convertir les esquisses Digispark.
4. Importez les fichiers supportés directement dans vos payloads.

Captures d'écran

Contribuer

Les contributions sont les bienvenues ! Si vous souhaitez aider à améliorer TapDucky :

1. Forkez le dépôt.
2. Créez une nouvelle branche pour votre fonctionnalité ou correction de bogue.
3. Soumettez une demande de tirage avec vos modifications proposées.

Licence

Ce projet est sous licence GNU GPLv3. Voir LICENSE.

Support

Si vous rencontrez des problèmes ou avez des questions, veuillez ouvrir un problème sur le dépôt GitHub ou contacter le mainteneur.

Plus d'applications de KaijinLab !