쓰기 전용 게이밍 마우스의 HID 프로토콜을 역공학해 Linux 설정 앱을 만들었습니다

AI 요약

Attack Shark X6에는 Windows용 공식 설정 도구만 있습니다. 이 프로젝트는 USB HID 프로토콜을 역공학해 Linux에서 마우스 설정을 바꾸는 데스크톱 앱을 만들었습니다. Go와 Wails v3로 백엔드를 구성하고 React와 Vite로 UI를 구현했습니다. Linux x86_64 AppImage와 사용자 계정에 설치하는 스크립트를 GitHub Releases에서 제공합니다.

프로토콜 분석과 장치 상태

개발자는 Windows 가상 머신에서 Wireshark로 USB 트래픽을 캡처하고, Ghidra로 공식 드라이버를 분석해 HID 리포트 구조를 파악했습니다. 장치는 사실상 쓰기 전용입니다. GET_REPORT 요청에는 STALL을 반환해 현재 설정을 읽을 수 없습니다. 마우스가 별도 인터럽트 엔드포인트로 보내는 정보는 배터리 잔량과 현재 DPI 단계입니다. 따라서 앱은 장치에 적용한 설정을 다시 확인할 수 없으며, 로컬 상태를 기준으로 관리합니다.

앱은 커널의 hidraw 인터페이스로 여러 장치를 찾고, 시리얼 번호를 기준으로 선택합니다. 배터리 상태와 마우스의 DPI 버튼 변경은 동글에서 수신하는 대로 UI에 표시합니다. DPI는 최대 8단계까지 설정하고, 각 단계는 50~26,000 범위에서 50 단위로 조절합니다. 단계별 색상과 현재 DPI 단계를 나타내는 원형 UI도 지원합니다. 설정 적용 시 hidraw로 56바이트 설정 리포트를 쓰며, 입력이 멈춘 뒤 1초가 지나면 자동 동기화합니다.

폴링레이트는 125·250·500·1,000Hz 중에서 고릅니다. 시리얼이 있는 장치는 선택한 값이 장치별로 저장되고, 시리얼이 없는 장치는 현재 세션에서만 유지됩니다. DPI, 폴링레이트, 절전 설정 외에도 RGB 효과와 색상, 센서와 디바운스 설정, 버튼 재매핑을 제공합니다. 설정 프로필은 버전 정보를 포함해 로컬에 저장되며 앱을 다시 실행해도 유지됩니다. 공장 초기화 기능도 있지만, 이 설정은 마우스 내부 프로필로 저장되지 않습니다. 매크로와 기기 내 프로필 저장은 아직 지원하지 않습니다.

설치와 복구

설치 프로그램은 GitHub Releases에서 서명된 메타데이터를 확인하고 최신 유효 릴리스를 선택합니다. 기본 설치는 안정 버전을 사용하며, 안정 버전이 없으면 RC나 main 브랜치 소스로 대체하지 않고 실패합니다. RC는 사용자가 베타 채널을 명시해야 설치합니다. 첫 설치 때 --install-udev를 지정하면 udev 규칙 설치를 안내합니다. 이 규칙은 활성 사용자의 접근을 TAG+="uaccess"와 장치 모드 0660으로 허용합니다. 앱을 root로 실행하거나 규칙을 모든 사용자에게 여는 0666으로 바꾸지 말라고 안내합니다.

설치된 앱은 새 서명 릴리스를 확인하지만, 교체 전 사용자 승인을 받습니다. 안정 버전은 안정 버전으로, RC는 더 새로운 RC로만 업데이트합니다. 업데이트는 사용자 홈 디렉터리의 AppImage 파일에 한정되며 권한 상승이나 udev 규칙 변경은 하지 않습니다. 설정 적용 뒤 마우스를 사용할 수 없게 되면 앱의 reset 명령으로 검증된 hidraw 장치 하나를 골라 DPI·폴링레이트·버튼 매핑을 포함한 공장 설정을 기록할 수 있습니다. 이 명령은 현재 설정을 대체하므로 복구 목적으로만 사용해야 합니다.

Reddit 반응

• @u/blakok14 — Attack Shark X6은 Windows 전용 공식 설정 도구가 있는 게이밍 마우스입니다. Linux에서 쓰고 싶어서 Windows 가상 머신에서 Wireshark로 USB 트래픽을 캡처하고, Ghidra로 공식 드라이버를 역어셈블해 HID 리포트 구조를 알아냈습니다. 흥미로운 점은 장치가 사실상 쓰기 전용이라는 것입니다. GET_REPORT는 항상 STALL을 반환해 마우스 설정을 읽을 수 없습니다. 장치가 스스로 보내는 정보는 별도 인터럽트 엔드포인트를 거치는 배터리 잔량과 활성 DPI 단계뿐입니다. 그래서 앱이 로컬 상태를 유일한 기준으로 관리해야 합니다. DPI 단계, RGB 모드와 색상, 폴링레이트, 버튼 재매핑 프로토콜을 파악한 뒤 Go와 Wails 데스크톱 앱을 만들었습니다. 첫 안정 버전을 막 출시했고, 서명된 자동 업데이트 기능도 넣었습니다. Debian이 아닌 배포판에서 WebKitGTK 도우미 프로세스 경로가 Debian식으로 하드코딩돼 발생하던 시작 오류는, execve와 posix_spawn을 가로채 번들 바이너리 경로로 돌리는 LD_PRELOAD shim으로 해결했습니다. 매크로와 장치 내 프로필 저장은 아직 남아 있으며, 해당 프로토콜은 아직 파악하지 못했습니다.
• @u/HaloLASO — 잘 만들었네요. 펌웨어가 온라인에 없다면 마우스를 열어서 덤프해볼 생각은 해보셨나요?
  • @u/blakok14 — 아니요, 그 생각은 못 했습니다. 한번 살펴볼 수도 있겠네요.
• @u/whatThePleb — AI가 쓴 엉터리 글이라 클린룸 방식이 아닙니다. 고맙습니다, 덕분에 아무것도 얻지 못했네요.

원문: GitHub / 번역·요약: Trawling