TapDucky - Android USB HID キーストロークインジェクター

ルート化された Android 向けのオープンソース DuckyScript ランナー。USB Gadget (ConfigFS) をサポート
TapDucky を使用すると、USB キーボード、マウス、またはコンポジット HID デバイスをエミュレートして、承認されたテストと自動化のために Android 上で DuckyScript を作成、カスタマイズ、スケジュール、実行できます。ペイロードのパラメータ化、複数のスケジューラートリガー、実行ログ、自動 DuckyScript 検証とオプションの Digispark .ino 変換を備えた GitHub 連携ペイロードライブラリが含まれます。

概要

• USB HID ガジェットプロファイル（対応/ルート化デバイスでは外部 USB ドングル不要）:
  • キーボード、マウス、コンポジットプロファイル。VID/PID、メーカー/製品文字列、消費電力を設定可能。
• DuckyScript パイプライン:
  • 人間が判読できる問題/警告を表示するライブ検証、プレースホルダーパラメータ、遅延乗数、人間らしいタイミングのためのオプションのジッター。
• ペイロード管理:
  • 名前/説明/タグ/パラメータ付きのペイロードの作成/編集、クイック共有/エクスポート、組み込みテンプレート/ウィザード。
• GitHub ペイロードストア:
  • ソースの追加、リポジトリの閲覧、検証付きのファイルプレビュー、対応スクリプトのインポート。DuckyScript を自動検出し、可能な場合は Digispark .ino スケッチを変換。
• スケジューラー:
  • 日時指定の1回限り、アプリのコールドスタート時、アプリのフォアグラウンド時、または HID セッションのアーム時（device_connected）に実行。オプションで毎日の時間枠を設定可能。
• 実行とログ:
  • タブ式の実行ビュー、パラメータプロンプト、実行/キャンセル、実行履歴、エクスポート/クリアとレベルフィルタ付きの構造化ログ。
• デバイス診断:
  • デバイス、カーネル/ガジェット状態、UDC 情報、キーボードレイアウトのスナップショット。クリップボードへのコピー。エミュレーター検出に関する注記。

注: Linux USB gadget (ConfigFS) をサポートするルート化デバイスが必要です。エミュレーターは HID の動作を検証できないため、実機を使用してください。

機能

• ペイロードエディターとパラメータ

  • 名前/説明/タグ付きでペイロードを作成。
  • デフォルト値、必須フラグ、実行ごとの上書きを持つ型付きパラメータを追加。
  • 行/問題のマッピングとコマンド数を備えた組み込み DuckyScript バリデーター。
  • 単一のペイロードを共有するか、パックをエクスポート。

• GitHub ペイロードストア

  • 複数の GitHub ソース（ユーザー/リポジトリ/ブランチ/パス）を管理。
  • ディレクトリの閲覧と、形式検出付きのファイルプレビュー（DuckyScript、TapDucky JSON、変換された Digispark スクリプト (.ino)）。
  • 検証済みスクリプトをライブラリに直接インポート。検証に失敗した場合は理由付きのプレビューを表示。

• 実行とテスト

  • 実行前に検証。パラメータ値をプロンプト。実行 ID 付きで実行またはキャンセル。
  • クイック HID テスト: キーボードキー押下、マウス移動、Ctrl+Alt+Del。
  • エンジンベースの実行時間推定（実際のタイミングモデルと一致）。
  • 実行中にセッションをアクティブに保つためのワクロック制御。

• スケジューラーとトリガー

  • トリガー: one_time、app_cold_start、app_foreground、device_connected（セッションアーム時）。
  • オプションの毎日の時間枠（HH:MM → HH:MM）。深夜をまたぐ時間枠もサポート。
  • スケジュールの有効/無効、編集、削除。最終実行を追跡。
  • シークレットコードによるダイヤルショートカットバインディング（自動アーム+バックグラウンド実行）。
    • 対応コード: ##38250##, ##38251##, ##38252##, ##38253##
    • 各コードのバインドキー: 有効、モード（最後に実行 | 選択したペイロード）、ペイロード（モード = 選択したペイロードの場合）

• デバイスと HID プロファイル

  • 設定可能な ID/文字列/電力を持つキーボード、マウス、コンポジットプロファイルをアクティブ化。
  • キーボードレイアウトの選択とコード/ID の解決。
  • ステータスストリームには ACTIVE/IDLE、ライターの準備状態、ホスト構成要求が表示されます。

• ログと履歴

  • レベルフィルタ（all/info/debug/warn/error）付きのログタブ、共有用エクスポート、すべてクリア。
  • メタデータ付きの実行履歴の詳細と共有。

ユーザー向け

• クイックステータスカード、ペイロード/ライブラリ統計、スケジューラーサマリーを備えたダッシュボード。
• 初回セットアップ/インポート用の明確な空状態とステップバイステップのウィザード。
• Material 3 テーマ、ダイナミックライト/ダークカラースキーム。

技術/アーキテクチャ

• プラットフォームチャンネル（Android）:
  • Method Channel: org.kaijinlab.tap_ducky/gadget
    • checkRoot, checkSupport, listUdcs, getStatus, getDiagnostics
    • getKeyboardLayouts, setKeyboardLayout, resolveKeyboardLayoutId, setKeyboardLayoutByCode
    • activateProfile, deactivate, panicStop, retryOpenHidWriters
    • executeDuckyScript(script, delayMultiplier, executionId?), cancelExecution(executionId)
    • テストヘルパー: testKeyboardKey(label), testMouseMove(dx,dy,wheel,buttons), testCtrlAltDel()
  • イベントチャンネル:
    • org.kaijinlab.tap_ducky/gadget_logs
    • org.kaijinlab.tap_ducky/gadget_status
    • org.kaijinlab.tap_ducky/gadget_exec
• HID プロファイルモデル: キーボード/マウス/コンポジット（VID/PID、文字列、シリアル、電力を含む）。
• DuckyScript:
  • ステップへのパース。DELAY/STRING/キー/生コマンドをサポート。プレースホルダー解決。基本キー遅延。ジッター。
  • バリデーターは重大度と行マッピングを持つ問題を返し、エディター/ストア/実行フロー全体で使用。
  • TRY/CATCH/END_TRY、WAIT_FOR、SLEEP_UNTIL、FUNCTION 引数、スコープ付き変数。
  • Unicode フォールバックモード（warn+skip / skip / ASCII 翻字）。
  • 実行ストリーム内の構造化された実行エラーコード。
• スケジューリングエンジン:
  • トリガー（コールドスタート、フォアグラウンド、アーム時、1回限り）、毎日の時間枠ルール、SharedPreferences への永続化。
• 状態管理: Riverpod 3、go_router ナビゲーション、リポジトリ/サービス/コントローラーのクリーンな分離。

DuckyScript / キーストロークエンジン

TapDucky には、Android (Kotlin) でネイティブに実装された完全な DuckyScript スタイルのエンジンが含まれており、式の評価と構造化された制御フローをサポートします。キーボード、マウス/ポインター、タイミング、変数/定義、関数、シンプルな乱数ユーティリティに対応しています。

対応コマンドファミリー（概要）:

• テキストとタイミング: STRING、STRINGLN、STRING_DELAY、DELAY、DEFAULTDELAY/DEFAULT_DELAY、REM（および REM_BLOCK）
• キーとコンボ: ENTER、TAB、ESC、SPACE、BACKSPACE、矢印、ナビゲーションキー（HOME/END/PGUP/PGDN/INS/DEL）、F1–F24、メディアキー、テンキー
• 修飾キーコンボ: GUI/WIN/COMMAND、CTRL/CONTROL、ALT/OPTION、SHIFT と追加のキートークン（例: GUI r、CTRL ALT DEL）
• ホールド/リリースと注入修飾キー: HOLD、RELEASE、INJECT_MOD（後続のキータップにわたって持続する修飾キーマスクの設定/クリア）
• ポインター/マウス: MOUSE/POINTER CLICK、HOLD、DRAG、MOVE、SCROLL。ボタン LEFT/RIGHT/MIDDLE、相対 dx/dy、繰り返し回数をサポート
• 制御フロー: IF / ELSE IF / ELSE / END_IF、WHILE / END_WHILE
• 関数と呼び出し: FUNCTION / END_FUNCTION、CALL_FUNCTION、RETURN
• 変数と定数: VAR $name = expr、DEFINE NAME value。$?（終了コード）は符号なし 16 ビットとして保持
• 乱数ジェネレーター: RANDOM_LOWERCASE_LETTER、RANDOM_UPPERCASE_LETTER、RANDOM_LETTER、RANDOM_NUMBER、RANDOM_SPECIAL、RANDOM_CHAR
• アタックモードのパススルー: ATTACKMODE（該当する場合、ガジェットマネージャーレイヤーにプロキシ）

動作に関する注意事項:

• デフォルト遅延: DEFAULTDELAY/DEFAULT_DELAY は、各実行可能コマンドの後に適用される基本遅延を設定します（実行時の遅延乗数でスケーリング）。
• 式評価: IF/WHILE と VAR 代入で算術、比較、論理式をサポート。非ゼロは真。
• 繰り返し: REPEAT N は、プリプロセス中に直前のコマンドを N 回複製します。
• キーボードマッピング: レイアウト選択付きの完全な HID 使用法マッピング。一般的なエイリアスをサポート（ESC/ESCAPE、BKSP/BACKSPACE など）。
• 実行ストリーム: step/start/done/error イベントが進行状況とともに発行され、リアルタイムの UI 更新とログに使用されます。

マウス/ポインター構文のクイックリファレンス:

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

機能マトリックス（抜粋）: