usbsnoop — живой сниффер USB-передач на двух fentry-хуках

Поток USB-трафика в реальном времени, системного масштаба, с цветовой разметкой — построен на двух универсальных точках прохождения URB, через которые прогоняются все драйверы хост-контроллеров, поэтому работает на xHCI/EHCI/OHCI/dwc одинаково, без tracepoint'ов для каждого контроллера и без usbmon. Полностью переносимый благодаря CO-RE.

lru_hash с ключом по указателю URB связывает эти два события: submit ставит время начала, completion считывает его для вычисления задержки submit→complete, а затем удаляет запись. Это повторяет схему пары запрос/ответ из httpbody — SUBMIT это «запрос» (что отправляет хост), COMPLETE — «ответ» (что возвращает устройство).

Для управляющих передач 8-байтовый SETUP-пакет декодируется в стандартное имя запроса (GET_DESCRIPTOR, SET_CONFIGURATION, …); стадии данных отображаются как текст, когда выглядят текстовыми, и как hexdump в противном случае.

Вывод — одна строка на событие (компактный). При первом появлении устройства выводится строка-легенда ▸ (bus-dev, vid:pid, продукт, скорость соединения); после этого каждая строка содержит только короткий тег DEV, поэтому левые колонки остаются выровненными и хорошо читаемыми при интенсивном трафике. Каждая строка показывает время, вид (SUBMIT/CMPLT), тип передачи, epNdir, стрелку направления (← устройство→хост IN, → хост→устройство OUT), количество байт, статус, задержку и драйвер ядра-владельца, затем · и наиболее полезную деталь (декодированный SETUP, SCSI-команду или краткий предпросмотр полезной нагрузки). Передайте --hex для полного многострочного hexdump вместо этого. Шестнадцатеричные байты раскрашиваются по классу значения (null — синий, печатный ASCII — голубой, пробелы — зелёный, прочие управляющие — пурпурный, старший/не-ASCII — жёлтый) на TTY; в конвейере вывод обычный.

Варианты применения

• Обратная разработка периферии — наблюдайте вживую, как устройство проходит перечисление и обменивается запросами vendor control и HID-отчётами, без аппаратного сниффера и настройки usbmon. SETUP-пакеты и полезные нагрузки декодируются, пока вы взаимодействуете с устройством.
• Отладка драйверов / прошивок — видно, какие именно команды ваш драйвер или приложение отправляет устройству и что возвращается, с задержкой submit→complete для каждой передачи.
• Инспекция массовых накопителей / SCSI — обёртки Bulk-Only Transport декодируются в SCSI-команды (READ(10) lba=… blocks=…, WRITE(10), CSW PASS/FAIL).
• Выявление ошибок — --errors-only показывает стойки (EPIPE), таймауты, babble и ошибки CRC сразу на всех устройствах.
• Обнаружение подозрительных устройств — только что подключённое устройство показывает, что оно делает в момент подключения; BadUSB-подобная HID-инъекция проявляется как INT-отчёты или управляющие записи SET_REPORT, которые вы не инициировали.
• Захват для офлайн-анализа — --json выводит NDJSON; передавайте в jq или в файл, чтобы сравнивать полезные нагрузки между запусками.

Установка

curl -fsSL https://yeet.cx | sh

Затем запускайте прямо из GitHub — yeet загружает пример и собирает его за вас, клонирование не требуется:

yeet run github:yeet-src/usbsnoop

Сборка

Чтобы собрать из локальной копии:

make

Сначала извлекает BTF ядра в vmlinux.h (для struct urb, usb_device и дескриптора устройства), затем компилирует. Требуются clang, bpftool и ядро с BTF.

Запуск

yeet run .                              # все устройства, работает до Ctrl-C
yeet run . -- --secs 30                 # остановиться через 30 c (вывести сводку)
yeet run . -- --vid 0x320f              # один вендор
yeet run . -- --vendor-id 0x046d --product-id 0xc52b # одно устройство по id
yeet run . -- --bus 3 --dev 4           # одно устройство по адресу на шине
yeet run . -- --type control,int        # только эти типы передач
yeet run . -- --no-data                 # только метаданные, без захвата полезной нагрузки
yeet run . -- --max-data 64             # ограничить отображаемую нагрузку 64 байтами
yeet run . -- --errors-only             # только неудачные завершения (stall'ы, таймауты)
yeet run . -- --hex                      # полный многострочный hexdump на каждую передачу
yeet run . -- --json | jq .             # NDJSON, один объект на событие

Флаги

Вся фильтрация выполняется на стороне ядра, поэтому отфильтрованный трафик никогда не достигает пользовательского пространства.

Каждая строка события заканчивается драйвером ядра-владельцем в скобках ([hid_irq_in], [usb_api_blocking_completion]) — urb->complete символизируется в ядре через bpf_snprintf("%ps"), так что обращение к /proc/kallsyms не требуется. Массовые bulk-передачи декодируют свою обёртку Bulk-Only Transport в SCSI-команду (CBW READ(10) lba=… blocks=… / CSW PASS). При завершении по таймеру (достижении --secs) печатаются сводка по каждому устройству и гистограмма задержек в лог2-шкале; завершение по Ctrl-C пропускает их (хука на сигнал из JS не существует).

Scatter-gather полезные нагрузки

Bulk-трафик (массовые накопители и им подобные) часто передаёт стеку массив struct scatterlist (urb->sg) вместо единого линейного transfer_buffer, поэтому полезная нагрузка разбросана по страницам. usbsnoop обходит этот массив и копирует байты каждого сегмента, но для доступа к ним нужно перевести страницу в её виртуальный адрес ядра — это операция, обратная page_to_virt на x86-64, для которой нужны page_offset_base и vmemmap_base работающего ядра (оба рандомизированы KASLR).

Изолят JS не может читать /proc/kallsyms, а загрузчик не поддерживает ksym, поэтому вы передаёте два адреса символов, а сторона BPF разыменовывает их:

yeet run . -- \
  --page-offset-base 0x$(sudo awk '$3=="page_offset_base"{print $1}' /proc/kallsyms) \
  --vmemmap-base     0x$(sudo awk '$3=="vmemmap_base"{print $1}'     /proc/kallsyms)

Без этих флагов SG-передачи по-прежнему показывают полные метаданные, только без байт полезной нагрузки — как и раньше. Этот путь работает только на x86-64: на других архитектурах оставляйте флаги выключенными.

Ограничения

• Захватываются только первые 16384 байта каждой передачи (степень двойки — ограничение верификатора на чтение зависит от этого). Буферы большего размера усекаются; заголовок по-прежнему сообщает истинную длину actual/requested. Каждая запись кольцевого буфера содержит полный data[16384], поэтому кольцо на 8 МиБ вмещает ~512 событий.
• Для scatter-gather полезных нагрузок нужны флаги --page-offset-base / --vmemmap-base выше и хост на x86-64; каждый сегмент захватывается до одной страницы, и обходятся только первые 64 сегмента передачи.
• Передача, отправленная до подключения usbsnoop, не имеет метки старта, поэтому её завершение показывается без задержки.
• USB-дескрипторы имеют little-endian порядок байт и читаются напрямую — это корректно на little-endian хостах, на которых работает BPF.