TapDucky - 안드로이드 USB HID 키스트로크 인젝터
루팅된 안드로이드에서 USB Gadget(ConfigFS)을 지원하는 오픈소스 DuckyScript 실행기
TapDucky는 USB 키보드, 마우스 또는 복합 HID 장치를 에뮬레이션하여 DuckyScript를 생성, 사용자 지정, 예약 및 실행할 수 있게 해주며, 승인된 테스트 및 자동화를 위해 설계되었습니다. 페이로드 매개변수화, 여러 스케줄러 트리거, 실행 로그, GitHub 기반 페이로드 라이브러리(자동 DuckyScript 검증 및 선택적 Digispark .ino 변환 포함)를 제공합니다.
개요
- USB HID 가젯 프로필 (지원되거나 루팅된 기기에서 외부 USB 동글 불필요):
- 키보드, 마우스 및 복합 프로필. VID/PID, 제조사/제품 문자열, 전력 소모 설정 가능.
- DuckyScript 파이프라인:
- 사람이 읽을 수 있는 문제/경고, 플레이스홀더 매개변수, 지연 배율, 선택적 지터(사람과 유사한 타이밍)를 포함한 실시간 검증.
- 페이로드 관리:
- 이름/설명/태그/매개변수로 페이로드 생성/편집, 빠른 공유/내보내기, 내장 템플릿/마법사.
- GitHub 페이로드 스토어:
- 소스 추가, 저장소 탐색, 검증 포함 파일 미리보기, 지원되는 스크립트 가져오기; DuckyScript 자동 감지 및 가능한 경우 Digispark
.ino 스케치 변환.
- 스케줄러:
- 날짜/시간에 한 번, 앱 콜드 스타트 시, 앱 포그라운드 시, HID 세션이 무장될 때(device_connected). 선택적 일일 시간 창.
- 실행 및 로그:
- 탭 실행 보기, 매개변수 프롬프트, 실행/취소, 실행 기록, 구조화된 로그(내보내기/지우기 및 레벨 필터).
- 기기 진단:
- 기기, 커널/가젯 상태, UDC 정보, 키보드 레이아웃 스냅샷; 클립보드 복사; 에뮬레이터 감지 참고.
참고: Linux USB gadget(ConfigFS)을 지원하는 루팅된 기기가 필요합니다. 에뮬레이터는 HID 동작을 검증할 수 없으므로 실제 기기를 사용하세요.
특징
-
페이로드 편집기 및 매개변수
- 이름/설명/태그로 페이로드 생성.
- 기본값, 필수 플래그, 실행별 재정의가 가능한 타입 매개변수 추가.
- 라인/이슈 매핑 및 명령 카운트가 포함된 내장 DuckyScript 검증기.
- 단일 페이로드 공유 또는 팩 내보내기.
-
GitHub 페이로드 스토어
- 여러 GitHub 소스(사용자/저장소/브랜치/경로) 관리.
- 디렉터리 탐색 및 형식 감지(DuckyScript, TapDucky JSON, Digispark 스크립트(.ino) 변환)를 통해 파일 미리보기.
- 검증된 스크립트를 라이브러리로 직접 가져오기; 검증 실패 시 이유가 포함된 미리보기 제공.
-
실행 및 테스트
- 실행 전 검증; 매개변수 값 프롬프트; 실행 ID와 함께 실행 또는 취소.
- 빠른 HID 테스트: 키보드 키 입력, 마우스 이동, Ctrl+Alt+Del.
- 엔진 기반 실행 시간 추정(실제 타이밍 모델과 일치).
- WakeLock 제어로 실행 중 세션 활성 유지.
-
스케줄러 및 트리거
- 트리거: one_time(한 번), app_cold_start(앱 콜드 스타트), app_foreground(앱 포그라운드), device_connected(세션 무장).
- 선택적 일일 시간 창(HH:MM → HH:MM), 자정 넘김 지원.
- 스케줄 활성화/비활성화, 편집 및 삭제; 마지막 실행 추적.
- 비밀 코드를 통한 다이얼 바로가기 바인딩(자동 무장 + 백그라운드 실행).
- 지원 코드: ##38250##, ##38251##, ##38252##, ##38253##
- 코드별 바인딩 키: 활성화 여부, 모드(마지막 실행 | 선택한 페이로드), 페이로드(모드가 선택한 페이로드일 때)
-
기기 및 HID 프로필
- 키보드, 마우스 또는 복합 프로필 활성화. ID/문자열/전력 설정 가능.
- 키보드 레이아웃 선택 및 코드/ID 해상도.
- 상태 스트림: ACTIVE/IDLE, 작성기 준비 상태, 호스트 구성 요청 표시.
-
로그 및 기록
- 레벨 필터(모두/정보/디버그/경고/오류)가 포함된 로그 탭, 공유를 위한 내보내기, 모두 지우기.
- 메타데이터 및 공유 기능이 포함된 실행 기록 세부 정보.
사용자 대상
- 빠른 상태 카드, 페이로드/라이브러리 통계, 스케줄러 요약이 있는 대시보드.
- 첫 설정/가져오기를 위한 명확한 빈 상태 및 단계별 마법사.
- Material 3 테마, 동적 라이트/다크 색상 구성.
기술/아키텍처
- 플랫폼 채널 (Android):
- 메서드 채널:
org.kaijinlab.tap_ducky/gadget
checkRoot, checkSupport, listUdcs, getStatus, getDiagnosticsgetKeyboardLayouts, setKeyboardLayout, resolveKeyboardLayoutId, setKeyboardLayoutByCodeactivateProfile, 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 할당에서 산술, 비교 및 논리 표현식 지원; 0이 아니면 참.
- 반복: REPEAT N은 전처리 중 이전 명령을 N번 복제합니다.
- 키보드 매핑: 레이아웃 선택이 포함된 전체 HID 사용 매핑; 일반 별칭 지원 (ESC/ESCAPE, BKSP/BACKSPACE 등).
- 실행 스트림: 단계/시작/완료/오류 이벤트가 진행률과 함께 방출되어 실시간 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]
기능 매트릭스 (선택):
참고: 검증기는 실행 전에 구문 오류, 알 수 없는 명령 및 구조 오류를 표시합니다. Payload Editor에서 라인 번호가 포함된 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
-
기능 키:
-
넘버패드 키 (별칭 포함):
- 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
스케줄러 트리거 (상세)
- 한 번 (One-time)
- 선택적 시간 창 내에 있는 경우 지정된 날짜/시간에 한 번 실행됩니다.
- 앱 시작 (콜드 스타트)
- 앱이 진정한 콜드 스타트에서 시작될 때 (백그라운드에서 재개될 때가 아님) 한 번 실행됩니다.
- 앱 열기 (포그라운드)
- 앱이 포그라운드로 올 때마다 실행됩니다. 여러 번 실행될 수 있습니다.
- 세션 무장 (Session Armed)
- HID 세션이 무장될 때 (USB 가젯이 UDC에 바인딩될 때) 실행됩니다. 일반적으로 "Arm Session"을 탭할 때 발생합니다.
페이로드 관리
- 매개변수 및 기본값으로 페이로드 생성/편집.
- 스크립트 실시간 검증; DuckyScript 구문 참조 열기.
- 개별 페이로드 공유 또는 팩 내보내기; GitHub Store에서 가져오기.
기기 진단
- 커널/UDC 목록, HID 작성기 준비 상태, 활성 프로필 상태, 호스트 구성 요청 수 등을 확인합니다.
- 값을 클립보드에 복사하고 스냅샷/진단을 독립적으로 새로 고칩니다.
개발자 참고 사항
- 모든 권한 있는 HID 작업은 루트와 ConfigFS 가젯을 지원하는 커널이 필요합니다.
- Android 8+에서는 알림에 전용 채널이 사용됩니다. 포그라운드 서비스는 HID 세션을 활성 상태로 유지합니다.
- 앱은 서비스 계층에서 런타임 UI 문자열을 Android 리소스와 결합하지 않아 리소스 병합 위험을 줄입니다.
요구 사항
- Linux USB Gadget(ConfigFS)을 지원하는 루팅된 Android 기기
- Android 11+
- 실제 기기 (에뮬레이터는 USB 가젯 동작을 검증할 수 없음)
설치
- 릴리스에서 최신 APK를 다운로드하세요:
-
애플리케이션을 설치하세요:
- 필요한 경우 알 수 없는 소스에서 설치를 활성화하세요.
- 루트 관리자에서 루트 권한을 요청하면 허용하세요.
-
실행 및 구성:
- TapDucky를 엽니다.
- 고급 설정에서 HID 프로필(키보드/마우스/복합), VID/PID, 키보드 레이아웃을 선택/조정합니다.
- 세션을 무장하고 Execute에서 테스트 명령을 실행합니다.
사용법
페이로드 실행
- 페이로드를 생성하거나 가져옵니다 (Payloads 탭).
- 검증하고 필요한 경우 매개변수를 추가합니다.
- Execute로 이동하여 페이로드를 선택하고 매개변수를 입력한 후 실행합니다.
- 결과는 Logs 및 Execution History에서 확인합니다.
페이로드 예약
- Scheduler를 엽니다.
- 스케줄을 만들고 트리거(한 번, 콜드 스타트, 포그라운드, 무장)를 선택합니다.
- 선택적으로 일일 시간 창 및 매개변수 재정의를 설정합니다.
- 저장하고 스케줄이 활성화되었는지 확인합니다.
GitHub Store에서 가져오기
- Payloads Store를 엽니다.
- 소스를 관리합니다 (
owner/repo 또는 전체 URL(브랜치/경로 포함) 추가).
- 파일을 미리 봅니다. TapDucky는 DuckyScript를 검증하고 Digispark 스케치를 변환할 수 있습니다.
- 지원되는 파일을 페이로드로 직접 가져옵니다.
스크린샷
기여
기여를 환영합니다! TapDucky 개선에 도움을 주시려면:
- 저장소를 포크하세요.
- 기능 또는 버그 수정을 위한 새 브랜치를 만드세요.
- 변경 사항이 포함된 풀 리퀘스트를 제출하세요.
라이선스
이 프로젝트는 GNU GPLv3 라이선스에 따라 라이선스가 부여됩니다. LICENSE를 참조하세요.
지원
문제가 발생하거나 질문이 있으면 GitHub 저장소에 이슈를 열거나 관리자에게 문의하세요.
KaijinLab의 다른 앱!
iodn/tap-ducky
