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

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]

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

注: バリデーターは、実行前に構文の問題、未知のコマンド、構造エラーを表示します。行番号付きの UI 内検証結果については、ペイロードエディターを参照してください。

実行タイミングのハイライト:

• 実行遅延乗数とタイピング速度係数を分離（オプションのリスクあり高速モード付き）。
• 長時間の STRING 実行中の定期的なフラッシュにより、ホストのキーバッファーオーバーランを軽減。
• 一時的な HID 切断に対するホスト認識型バックオフと猶予ウィンドウ。
• マイクロスリープが利用できない場合のハードウェア認識型推定キャリブレーション。

明示的なキーとエイリアスのサポート

注: 記載されているエイリアスに加えて、TapDucky は down_arrow、up_arrow、left_arrow、right_arrow、page_up、page_down、print_screen、scroll_lock、num_lock、caps_lock、string_delay、default_delay などのスネークケース形式も受け付けます。これらは内部的に正規化されます。

• 修飾キー（記載がある場合は左右のバリアントをサポート）:

  • 左: CTRL/CONTROL、SHIFT、ALT/OPTION、GUI/WINDOWS/COMMAND/WIN
  • 右: RCTRL/RCONTROL、RSHIFT、RALT、RGUI/RWINDOWS/RCOMMAND

• システム/ナビゲーションキー（エイリアスを含む）:

  • ENTER
  • ESC/ESCAPE
  • BACKSPACE/BKSP
  • TAB
  • SPACE
  • DELETE/DEL
  • INSERT/INS
  • HOME, END
  • PAGEUP, PAGEDOWN
  • 矢印: UP/UPARROW、DOWN/DOWNARROW、LEFT/LEFTARROW、RIGHT/RIGHTARROW
  • ロックキー: CAPSLOCK、NUMLOCK、SCROLLLOCK
  • PRINTSCREEN/PRINTSCRN/PRTSCN
  • PAUSE/BREAK
  • MENU/APP

• ファンクションキー:

  • F1–F24

• テンキー（エイリアスを含む）:

  • 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

• メディアキー（エイリアスを含む）:

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

• 英数字ショートカット:

  • 単一文字 A–Z と数字 0–9 は対応する HID 使用法コードにマッピングされます。

例

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

スケジューラートリガー（詳細）

• 1回限り
  • 指定した日時に1回だけ実行（オプションの時間枠内の場合）。
• アプリ起動（コールドスタート）
  • アプリが真のコールドスタートから起動したときに1回だけ実行（バックグラウンドから再開した場合を除く）。
• アプリオープン（フォアグラウンド）
  • アプリがフォアグラウンドに来るたびに実行。何度でも実行可能。
• セッションアーム時
  • HID セッションがアームされたとき（USB ガジェットが UDC にバインドされたとき）に実行。通常は「セッションをアーム」をタップしたとき。

ペイロード管理

• パラメータとデフォルト値を持つペイロードを作成/編集。
• スクリプトをライブで検証。DuckyScript 構文リファレンスを開く。
• 個々のペイロードを共有するか、パックをエクスポート。GitHub ストアからインポート。

デバイス診断

• カーネル/UDC リスト、HID ライターの準備状態、アクティブなプロファイル状態、ホスト構成要求数などを表示。
• 値をクリップボードにコピーし、スナップショット/診断を個別に更新。

開発者向けメモ

• すべての特権 HID 操作には、root と ConfigFS ガジェットをサポートするカーネルが必要です。
• Android 8+ では、通知は専用チャンネルを使用します。フォアグラウンドサービスが HID セッションをアクティブに保ちます。
• アプリは、リソースのマージリスクを減らすために、サービスレイヤーで実行時 UI 文字列を Android リソースに結合することを回避しています。

要件

• Linux USB Gadget (ConfigFS) をサポートするルート化 Android デバイス
• Android 11+
• 実機（エミュレーターは USB ガジェットの動作を検証できません）

インストール

1. リリースから最新の APK をダウンロード:

2. アプリケーションをインストール:

   • 必要に応じて不明なソースからのインストールを有効にします。
   • ルートマネージャーのプロンプトが表示されたら root を許可します。

3. 起動と設定:

   • TapDucky を開きます。
   • 詳細設定で、HID プロファイル（キーボード/マウス/コンポジット）、VID/PID、キーボードレイアウトを選択/調整します。
   • セッションをアームし、Execute からテストコマンドを実行します。

使い方

ペイロードの実行

1. ペイロードを作成またはインポートします（ペイロードタブ）。
2. 検証し、必要に応じてパラメータを追加します。
3. Execute に移動し、ペイロードを選択してパラメータを入力し、Run を実行します。
4. 結果はログと実行履歴で確認します。

ペイロードのスケジュール設定

1. スケジューラーを開きます。
2. スケジュールを作成し、トリガー（1回限り、コールドスタート、フォアグラウンド、アーム時）を選択します。
3. 必要に応じて、毎日の時間枠とパラメータの上書きを設定します。
4. 保存し、スケジュールが有効になっていることを確認します。

GitHub ストアからのインポート

1. ペイロードストアを開きます。
2. ソースを管理します（owner/repo またはブランチ/パス付きの完全な URL を追加）。
3. ファイルをプレビューします。TapDucky は DuckyScript を検証し、Digispark スケッチを変換できます。
4. 対応ファイルをペイロードに直接インポートします。

スクリーンショット

貢献

貢献を歓迎します！TapDucky の改善にご協力いただける場合は:

1. リポジトリをフォークします。
2. 機能またはバグ修正用の新しいブランチを作成します。
3. 提案する変更を含むプルリクエストを送信します。

ライセンス

このプロジェクトは GNU GPLv3 ライセンスの下でライセンスされています。LICENSE を参照してください。

サポート

問題が発生した場合やご質問がある場合は、GitHub リポジトリで issue を開くか、メンテナーに連絡してください。

KaijinLab のその他のアプリ！