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, 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/키/raw 명령 지원; 플레이스홀더 해상도; 기본 키 지연; 지터.
  • 검증기는 심각도 및 라인 매핑이 포함된 이슈를 반환하며, 편집기/스토어/실행 흐름에서 사용됨.
  • TRY/CATCH/END_TRY, WAIT_FOR, SLEEP_UNTIL, FUNCTION 인수, 범위 변수.
  • 유니코드 폴백 모드(경고+건너뛰기 / 건너뛰기 / ASCII 변환).
  • 실행 스트림에 구조화된 실행 오류 코드.
• 스케줄링 엔진:
  • 트리거(콜드 스타트, 포그라운드, 무장, 한 번), 일일 시간 창 규칙, 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 할당에서 산술, 비교 및 논리 표현식 지원; 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]

기능 매트릭스 (선택):