Реверс-инжиниринг¶

Протокол восстановлен по дампам USB-трафика вендорской утилиты. Дампы снимались в Windows через Wireshark с фильтром USBPcap, затем разбирались скриптом misc/analyze_pcap.py.

Методика¶

1. Снять полный захват операции: begin → data-begin → payload → commit → save.
2. Распарсить захват в лог control-трансферов.
3. Сравнить соседние операции, которые отличаются одним параметром.
4. Проверить гипотезу на железе без записи во флеш.
5. Закрепить результат тестом на подменном устройстве.

Для карты клавиш использовался отдельный приём: несколько индексов красились контрастными цветами, после чего проверялось, какие клавиши загорелись. Тёмные и холодные цвета на дальних клавишах плохо заметны, поэтому для картирования берут максимально контрастные цвета и мало точек за раз.

Инструменты¶

Запуск парсера:

gzip -dc raw-data/katana-v1/color-modes/01-static.pcapng.gz > /tmp/01-static.pcapng
./misc/analyze_pcap.py /tmp/01-static.pcapng /tmp/01-static.plain.txt

Без второго аргумента результат пишется в /tmp/tx_log.txt.

Формат строки лога:

SET #N if=I t=T rid=R len=L: <hex-байты>

• if — номер интерфейса, конфиг-канал имеет if=0;
• t — 21 для SET_REPORT, a1 для GET_REPORT;
• rid — report id, у всех команд равен 00;
• пакеты GET склеиваются по irpid: setup и data приходят разными записями, парсер сопоставляет их автоматически.

Проверка на железе¶

Проверять гипотезу нужно без save, чтобы не изнашивать флеш. Для этого подходят:

• katana.py mode ... --no-save;
• katana.py raw ... --no-save;
• katana.py paint ... --no-save;
• katana.py keys для чтения живого кадра.

После экспериментов полезно вернуть рабочее состояние командой default или применить сохранённый профиль. На macOS запись feature-репортов система не разрешает: проверка гипотез с записью возможна только на Linux.

Важные грабли¶

• pyusb с detach_kernel_driver ломает печать: используйте только hidraw.
• Сессия без 04 f0 клинит прошивку.
• После клина reset может не помочь с первого раза: повторите с паузой 5–10 секунд.
• f5 с begin и data-begin возвращает мусор: data-begin обезоруживает поток.
• Ответ ff на begin означает открытую сессию, и это нормально.
• Слепые слоты прошивка принимает молча.
• Пользователь различает цвета приблизительно, поэтому для картирования нужны контрастные цвета и мало точек за раз.

Датасет¶

Сырые дампы лежат в raw-data/katana-v1/. Пути собраны в manifest.json: в секции sets перечислены наборы, в секции refs — файлы-эталоны для тестов.

Новые дампы систематичны: в color-modes/ на каждый режим приходится полный набор параметров и поток кадров, а keybind/ покрывает сброс и привязку макроса. Чего нет в новых дампах: полных шкал яркости и скорости, стриминга 04 20, записи и исполнения реального макроса — за этим обращайтесь к _old/.

Подробный состав — в разделе Дампы.

Открытые вопросы¶

• Другие типы действий в переназначении: Fn-слой и прочие записи канала 04 11.
• Чтение таблицы переназначений из прошивки.
• Чтение содержимого макросов из прошивки.
• Смысл поля «число событий × 2» в заголовке блоба макросов.
• Реальный лимит макросов: заголовок рассчитан на 100 слотов, а данных хватает на несколько десятков событий.
• Сохранение макросов между переподключениями USB.
• Коллизия кодов 05 и 06 в макросах.
• Коды стрелок Up и Down и остальные медиа-клавиши макросов.

Что проверено¶