TapDucky – Android USB HID Keystroke Injector

Open-Source-DuckyScript-Ausführer für gerootetes Android mit USB-Gadget- (ConfigFS) Unterstützung
TapDucky ermöglicht es Dir, DuckyScripts zu erstellen, anzupassen, zu planen und auf Android auszuführen, indem es eine USB-Tastatur, -Maus oder ein zusammengesetztes HID-Gerät für autorisiertes Testen und Automatisierung emuliert. Es enthält Payload-Parametrisierung, mehrere Scheduler-Trigger, Ausführungsprotokolle und eine GitHub-gestützte Payload-Bibliothek mit automatischer DuckyScript-Validierung und optionaler Digispark .ino-Konvertierung.

Übersicht

• USB‑HID‑Gadget‑Profile (kein externer USB‑Dongle auf unterstützten/gerooteten Geräten erforderlich):
  • Tastatur‑, Maus‑ und zusammengesetzte Profile mit konfigurierbarer VID/PID, Hersteller/Produkt-Strings und Leistungsaufnahme.
• DuckyScript‑Pipeline:
  • Live‑Validierung mit lesbaren Problemen/Warnungen, Platzhalter-Parametern, Verzögerungsmultiplikator und optionalem Jitter für menschliches Timing.
• Payload‑Verwaltung:
  • Erstellen/Bearbeiten von Payloads mit Name/Beschreibung/Tags/Parametern, Schnellfreigabe/Export und integrierten Vorlagen/Assistenten.
• GitHub‑Payload‑Store:
  • Quellen hinzufügen, Repositories durchsuchen, Dateien mit Validierung in der Vorschau anzeigen, unterstützte Skripte importieren; erkennt automatisch DuckyScript und konvertiert Digispark .ino-Skizzen, wenn möglich.
• Scheduler:
  • Einmalig zu einem Datum/einer Uhrzeit, bei kaltem App‑Start, bei App‑Vordergrund oder wenn die HID‑Sitzung aktiv (device_connected) ist, mit optionalem täglichem Zeitfenster.
• Ausführung & Protokolle:
  • Registerkartenansicht für die Ausführung, Parameterabfragen, Start/Abbruch, Ausführungsverlauf und strukturierte Protokolle mit Export/Löschen und Level‑Filter.
• Gerätediagnose:
  • Schnappschuss von Gerät, Kernel/Gadget‑Status, UDC‑Informationen, Tastaturlayouts; in die Zwischenablage kopieren; Emulator-Erkennungshinweis.

Hinweis: Ein gerootetes Gerät mit Linux‑USB‑Gadget‑ (ConfigFS) Unterstützung ist erforderlich. Verwende ein physisches Gerät, da Emulatoren das HID‑Verhalten nicht validieren können.

Funktionen

• Payload‑Editor & Parameter

  • Erstelle Payloads mit Name/Beschreibung/Tags.
  • Füge typisierte Parameter mit Standardwerten, erforderlichen Flags und Überschreibungen pro Ausführung hinzu.
  • Integrierter DuckyScript‑Validator mit Zeilen‑/Problemzuordnung und Befehlszählung.
  • Einzelnen Payload teilen oder ein Paket exportieren.

• GitHub‑Payload‑Store

  • Verwalte mehrere GitHub‑Quellen (Benutzer/Repo/Branch/Pfad).
  • Durchsuche Verzeichnisse und zeige Dateien mit Formaterkennung in der Vorschau an (DuckyScript, TapDucky JSON, Digispark‑Skript (.ino) konvertiert).
  • Importiere validierte Skripte direkt in Deine Bibliothek; fehlgeschlagene Validierungen zeigen begründete Vorschauen.

• Ausführen & Testen

  • Vor dem Start validieren; nach Parameterwerten fragen; mit Ausführungs‑IDs starten oder abbrechen.
  • Schnelle HID‑Tests: Tastendruck, Mausbewegung und Strg+Alt+Entf.
  • Motor‑basierte Laufzeitschätzung (entspricht dem tatsächlichen Zeitmodell).
  • Wakelock‑Steuerung, um Sitzungen während der Ausführung aktiv zu halten.

• Scheduler & Trigger

  • Trigger: one_time, app_cold_start, app_foreground, device_connected (Sitzung aktiv).
  • Optionales tägliches Zeitfenster (HH:MM → HH:MM), einschließlich Mitternachtsüberlauf.
  • Zeitpläne aktivieren/deaktivieren, bearbeiten und löschen; letzte Ausführung wird nachverfolgt.
  • Kurzwahl‑Verknüpfungen über geheime Codes (Auto‑Arm + Hintergrundausführung).
    • Unterstützte Codes: ##38250##, ##38251##, ##38252##, ##38253##
    • Bindungstasten pro Code: aktiviert, Modus (zuletzt ausgeführt | ausgewählter Payload), Payload (wenn Modus = ausgewählter Payload)

• Gerät & HID‑Profile

  • Tastatur‑, Maus‑ oder zusammengesetzte Profile mit konfigurierbaren IDs/Strings/Leistung aktivieren.
  • Tastaturlayout‑Auswahl und Code/ID‑Auflösung.
  • Status‑Stream zeigt AKTIV/INAKTIV, Schreibbereitschaft und Host‑Konfigurationsanforderungen an.

• Protokolle & Verlauf

  • Registerkarte „Protokolle“ mit Level‑Filter (alle/Info/Debug/Warn/Fehler), Export zum Teilen, alle löschen.
  • Ausführungsverlaufsdetails mit Metadaten und Teilen.

Benutzerorientiert

• Dashboard mit Schnellstatuskarten, Payload‑/Bibliotheksstatistiken und Scheduler‑Zusammenfassung.
• Klare leere Zustände und Schritt‑für‑Schritt‑Assistenten für die Ersteinrichtung/Importe.
• Material 3‑Design, dynamische helle/dunkle Farbschemata.

Technisch/architektonisch

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

DuckyScript / Tastaturanschlag‑Engine

TapDucky enthält eine vollständige DuckyScript‑Engine, die nativ auf Android (Kotlin) implementiert ist, mit Ausdrucksauswertung und strukturiertem Kontrollfluss. Sie unterstützt Tastatur, Maus/Zeiger, Timing, Variablen/Defines, Funktionen und einfache Zufallsdienstprogramme.

Unterstützte Befehlsklassen (allgemein):

• Text und Timing: STRING, STRINGLN, STRING_DELAY, DELAY, DEFAULTDELAY/DEFAULT_DELAY, REM (und REM_BLOCK)
• Tasten und Kombos: ENTER, TAB, ESC, SPACE, BACKSPACE, Pfeile, Navigationstasten (HOME/END/PGUP/PGDN/INS/DEL), F1–F24, Medientasten, Numpad‑Tasten
• Modifikatorkombos: GUI/WIN/COMMAND, CTRL/CONTROL, ALT/OPTION, SHIFT mit zusätzlichen Tastentoken (z. B. GUI r, CTRL ALT DEL)
• Halten/Loslassen und injizierte Modifikatoren: HOLD, RELEASE, INJECT_MOD (setze/lösche Modifikatormaske, die über nachfolgende Tastendrücke erhalten bleibt)
• Zeiger/Maus: MOUSE/POINTER CLICK, HOLD, DRAG, MOVE, SCROLL mit Tasten LEFT/RIGHT/MIDDLE und relativen dx/dy und Wiederholungszahl
• Kontrollfluss: IF / ELSE IF / ELSE / END_IF, WHILE / END_WHILE
• Funktionen und Aufrufe: FUNCTION / END_FUNCTION, CALL_FUNCTION, RETURN
• Variablen und Konstanten: VAR $name = ausdruck, DEFINE NAME wert; $?(Exit‑Code) als vorzeichenloser 16‑Bit‑Wert gepflegt
• Zufallsgeneratoren: RANDOM_LOWERCASE_LETTER, RANDOM_UPPERCASE_LETTER, RANDOM_LETTER, RANDOM_NUMBER, RANDOM_SPECIAL, RANDOM_CHAR
• Angriffsmodus‑Durchreichung: ATTACKMODE (wird an die Gadget‑Manager‑Ebene weitergeleitet, wenn anwendbar)

Hinweise zum Verhalten:

• Standardverzögerung: DEFAULTDELAY/DEFAULT_DELAY legt eine Basisverzögerung fest, die nach jedem ausführbaren Befehl angewendet wird (skaliert mit dem Laufzeit‑Verzögerungsmultiplikator).
• Ausdrucksauswertung: Arithmetik, Vergleiche und logische Ausdrücke werden in IF/WHILE und VAR‑Zuweisungen unterstützt; ungleich Null ist wahr.
• Wiederholung: REPEAT N dupliziert den vorherigen Befehl N‑fach während der Vorverarbeitung.
• Tastaturzuordnung: Vollständige HID‑Usage‑Zuordnung mit Layoutauswahl; übliche Aliase werden unterstützt (ESC/ESCAPE, BKSP/BACKSPACE usw.).
• Ausführungs‑Streams: Schritt/Start/Ende/Fehler‑Ereignisse werden mit Fortschritt ausgegeben, für Echtzeit‑UI‑Updates und Protokolle.

Maus/Zeiger‑Syntax‑Kurzreferenz:

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

Funktionsmatrix (Auswahl):

Hinweis: Der Validator zeigt Syntaxfehler, unbekannte Befehle und Strukturfehler vor der Ausführung an. Siehe Payload‑Editor für Validierungsergebnisse in der Benutzeroberfläche mit Zeilennummern.

Ausführungs‑Timing‑Highlights:

• Separater Ausführungs‑Verzögerungsmultiplikator und Tippgeschwindigkeitsfaktor (mit optionalem riskantem Schnellmodus).
• Periodischer Leerungsvorgang bei langen STRING‑Läufen, um Überläufe des Host‑Tastaturpuffers zu reduzieren.
• Host‑bewusste Rückstellung und Gnadenfrist für vorübergehende HID‑Trennungen.
• Hardware‑bewusste Schätzungskalibrierung, wenn Mikroschlaf nicht verfügbar ist.

Explizite Tasten‑ und Alias‑Unterstützung

Hinweis: Zusätzlich zu den aufgeführten Aliasen akzeptiert TapDucky snake_case‑Formen wie down_arrow, up_arrow, left_arrow, right_arrow, page_up, page_down, print_screen, scroll_lock, num_lock, caps_lock, string_delay, default_delay usw. Diese werden intern normalisiert.

• Modifikatoren (linke/rechte Varianten werden unterstützt, wo angegeben):

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

• System‑/Navigationstasten (Aliase inbegriffen):

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

• Funktionstasten:

  • F1–F24

• Numpad‑Tasten (Aliase inbegriffen):

  • 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

• Medientasten (Aliase inbegriffen):

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

• Alphanumerische Abkürzungen:

  • Einzelzeichen A–Z und Ziffern 0–9 werden auf die entsprechenden HID‑Usage‑Codes abgebildet.

Beispiele

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

Scheduler‑Trigger (Details)

• Einmalig
  • Wird einmal zu einem bestimmten Datum/einer bestimmten Uhrzeit ausgeführt, sofern dies im optionalen Zeitfenster liegt.
• App‑Start (Kaltstart)
  • Wird einmal ausgeführt, wenn die App von einem echten Kaltstart gestartet wird (nicht bei Wiederaufnahme aus dem Hintergrund).
• App‑Öffnen (Vordergrund)
  • Wird jedes Mal ausgeführt, wenn die App in den Vordergrund kommt; kann mehrmals ausgeführt werden.
• Sitzung aktiv
  • Wird ausgeführt, wenn die HID‑Sitzung aktiviert wird (USB‑Gadget bindet an UDC) – normalerweise wenn Du auf „Sitzung aktivieren“ tippst.

Payloads‑Verwaltung

• Erstelle/bearbeite Payloads mit Parametern und Standardwerten.
• Validiere Skripte live; öffne die DuckyScript‑Syntaxreferenz.
• Teile einzelne Payloads oder exportiere ein Paket; importiere aus dem GitHub‑Store.

Gerätediagnose

• Zeige Kernel/UDC‑Liste, HID‑Schreiberbereitschaft, aktiven Profilstatus, Anzahl der Host‑Konfigurationsanforderungen und mehr an.
• Kopiere Werte in die Zwischenablage und aktualisiere Schnappschuss/Diagnose unabhängig.

Entwicklerhinweise

• Alle privilegierten HID‑Aktionen erfordern Root und einen Kernel mit ConfigFS‑Gadget‑Unterstützung.
• Unter Android 8+ werden Benachrichtigungen über einen dedizierten Kanal verwendet; ein Vordergrunddienst hält die HID‑Sitzung aktiv.
• Die App vermeidet es, Laufzeit‑UI‑Strings in der Dienstebene an Android‑Ressourcen zu koppeln, um das Risiko von Ressourcenkonflikten zu verringern.

Anforderungen

• Gerootetes Android‑Gerät mit Linux‑USB‑Gadget‑ (ConfigFS) Unterstützung
• Android 11+
• Physisches Gerät (Emulatoren können das USB‑Gadget‑Verhalten nicht validieren)

Installation

1. Lade die neueste APK von den Releases herunter:

2. Installiere die Anwendung:

   • Aktiviere ggf. die Installation aus unbekannten Quellen.
   • Gewähre Root, wenn Du von Deinem Root‑Manager dazu aufgefordert wirst.

3. Starte und konfiguriere:

   • Öffne TapDucky.
   • Wähle in den erweiterten Einstellungen das HID‑Profil (Tastatur/Maus/Zusammengesetzt), VID/PID und das Tastaturlayout aus/ passe sie an.
   • Aktiviere eine Sitzung und führe einen Testbefehl von „Ausführen“ aus.

Verwendung

Ausführen eines Payloads

1. Erstelle oder importiere einen Payload (Registerkarte „Payloads“).
2. Validiere ihn und füge ggf. Parameter hinzu.
3. Gehe zu „Ausführen“, wähle den Payload aus, fülle die Parameter aus und klicke auf „Starten“.
4. Überprüfe die Ergebnisse in den Protokollen und im Ausführungsverlauf.

Planen eines Payloads

1. Öffne den Scheduler.
2. Erstelle einen Zeitplan, wähle den Trigger (Einmalig, Kaltstart, Vordergrund, Aktiv).
3. Lege ggf. ein tägliches Zeitfenster und Parameterüberschreibungen fest.
4. Speichere und stelle sicher, dass der Zeitplan aktiviert ist.

Importieren aus dem GitHub‑Store

1. Öffne den Payloads‑Store.
2. Verwalte Quellen (füge owner/repo oder die vollständige URL mit Branch/Pfad hinzu).
3. Zeige Dateien in der Vorschau an; TapDucky validiert DuckyScript und kann Digispark‑Skizzen konvertieren.
4. Importiere unterstützte Dateien direkt in Deine Payloads.

Screenshots

Mitwirken

Beiträge sind willkommen! Wenn Du helfen möchtest, TapDucky zu verbessern:

1. Forke das Repository.
2. Erstelle einen neuen Branch für Deine Funktion oder Fehlerbehebung.
3. Reiche einen Pull‑Request mit Deinen vorgeschlagenen Änderungen ein.

Lizenz

Dieses Projekt ist unter der GNU GPLv3‑Lizenz lizenziert. Siehe LICENSE.

Unterstützung

Wenn Du auf Probleme stößt oder Fragen hast, öffne bitte ein Issue im GitHub‑Repository oder kontaktiere den Maintainer.

Weitere Apps von KaijinLab!