usbsnoop — sniffer de transferencias USB en vivo desde dos hooks fentry

Una fuente en tiempo real y coloreada del tráfico USB en todo el sistema — construida sobre los dos puntos de estrangulamiento universales de URB por los que pasa todo driver de controlador de host, por lo que funciona en xHCI/EHCI/OHCI/dwc por igual, sin tracepoints por controlador y sin usbmon. Totalmente portable con CO-RE.

Un lru_hash con clave el puntero URB une ambos: el submit registra una marca de tiempo de inicio, la finalización la lee para obtener la latencia submit→complete y luego la elimina. Esto refleja el emparejamiento petición/respuesta de httpbody — SUBMIT es la "petición" (lo que envía el host), COMPLETE la "respuesta" (lo que devuelve el dispositivo).

Las transferencias de control decodifican su paquete SETUP de 8 bytes al nombre de petición estándar (GET_DESCRIPTOR, SET_CONFIGURATION, …); las etapas de datos se muestran como texto cuando parecen textuales y como hexdump en caso contrario.

La salida es una línea por evento (compacta). La primera vez que aparece un dispositivo recibe una línea de leyenda ▸ (bus-dev, vid:pid, producto, velocidad de enlace); después, cada fila lleva solo la etiqueta corta DEV, de modo que las columnas de la izquierda se mantienen alineadas y escaneables bajo mucho tráfico. Cada fila muestra la hora, el tipo (SUBMIT/CMPLT), el tipo de transferencia, epNdir, la flecha de dirección (← dispositivo→host IN, → host→dispositivo OUT), recuentos de bytes, estado, latencia y el driver del kernel propietario, seguido de un · y el detalle más útil (SETUP decodificado, comando SCSI o una vista previa corta del payload). Pasa --hex para obtener el hexdump multilínea completo en su lugar. Los bytes hexadecimales se colorean por clase de valor (null azul, ASCII imprimible cian, espacios en blanco verde, otros controles magenta, alto/no-ASCII amarillo) en una TTY; la salida por pipe es plana.

Casos de uso

• Ingeniería inversa de periféricos — observa un dispositivo enumerar e intercambiar peticiones de control de proveedor e informes HID en vivo, sin sniffer de hardware ni configuración de usbmon. Los paquetes SETUP y los payloads se decodifican mientras tocas el dispositivo.
• Depuración de drivers / firmware — ve exactamente qué comandos envía tu driver o aplicación a un dispositivo y qué devuelve, con la latencia submit→complete en cada transferencia.
• Inspección de almacenamiento masivo / SCSI — los wrappers Bulk-Only Transport se decodifican al comando SCSI (READ(10) lba=… blocks=…, WRITE(10), CSW PASS/FAIL).
• Detección de errores — --errors-only saca a la superficie stalls (EPIPE), timeouts, babble y errores CRC en todos los dispositivos a la vez.
• Detección de dispositivos maliciosos — un dispositivo recién conectado muestra lo que hace en el instante en que se adjunta; la inyección HID estilo BadUSB aparece como informes INT o escrituras de control SET_REPORT que no disparaste.
• Captura para análisis offline — --json emite NDJSON; conéctalo a jq o a un archivo para comparar payloads entre ejecuciones.

Instalación

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

Luego ejecútalo directamente desde GitHub — yeet descarga el ejemplo y lo compila por ti, sin necesidad de clonar:

yeet run github:yeet-src/usbsnoop

Compilación

Para compilar desde un checkout local:

make

Vuelca el BTF del kernel a vmlinux.h (para struct urb, usb_device y el descriptor de dispositivo) y luego compila. Requiere clang, bpftool y un kernel con BTF.

Ejecución

yeet run .                              # all devices, runs until Ctrl-C
yeet run . -- --secs 30                 # stop after 30s (prints a summary)
yeet run . -- --vid 0x320f              # one vendor
yeet run . -- --vendor-id 0x046d --product-id 0xc52b # one device by id
yeet run . -- --bus 3 --dev 4           # one device by bus address
yeet run . -- --type control,int        # only these transfer types
yeet run . -- --no-data                 # metadata only, skip payload capture
yeet run . -- --max-data 64             # cap rendered payload at 64 bytes
yeet run . -- --errors-only             # only failed completions (stalls, timeouts)
yeet run . -- --hex                      # full multi-line hexdump per transfer
yeet run . -- --json | jq .             # NDJSON, one object per event

Opciones

Todo el filtrado ocurre en el lado del kernel, por lo que el tráfico filtrado nunca llega al espacio de usuario.

Cada línea de evento termina con el driver del kernel propietario entre corchetes ([hid_irq_in], [usb_api_blocking_completion]) — urb->complete se simboliza en el kernel mediante bpf_snprintf("%ps"), por lo que no se necesita consultar /proc/kallsyms. Las transferencias bulk de almacenamiento masivo decodifican su wrapper Bulk-Only Transport al comando SCSI (CBW READ(10) lba=… blocks=… / CSW PASS). En una salida temporizada (al alcanzar --secs) se imprime un resumen por dispositivo y un histograma de latencia log2; una salida con Ctrl-C lo omite (no hay hook de señal visible en JS).

Payloads dispersos (scatter-gather)

El tráfico bulk (almacenamiento masivo y similares) a menudo entrega a la pila un array struct scatterlist (urb->sg) en lugar de un único transfer_buffer lineal, por lo que el payload vive disperso entre páginas. usbsnoop recorre ese array y copia los bytes de cada segmento, pero alcanzarlos significa traducir una página a su dirección virtual del kernel — la operación inversa de page_to_virt en x86-64, que necesita los page_offset_base y vmemmap_base del kernel en ejecución (ambos aleatorizados por KASLR).

El aislado JS no puede leer /proc/kallsyms y el loader no tiene soporte ksym, así que pasas las dos direcciones de los símbolos y el lado de BPF las desreferencia:

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)

Sin esas opciones, las transferencias SG siguen mostrando metadatos completos, solo que sin bytes de payload — el comportamiento anterior. Esta vía es solo x86-64: en otras arquitecturas deja las opciones sin usar.

Límites

• Solo se capturan los primeros 16384 bytes de cada transferencia (una potencia de dos — el límite de lectura del verificador depende de ello). Los buffers más grandes se truncan; la cabecera sigue informando de la longitud real actual/requested. Cada registro del anillo lleva un data[16384] completo, por lo que el anillo de 8 MiB contiene ~512 eventos.
• Los payloads scatter-gather necesitan las opciones --page-offset-base / --vmemmap-base anteriores y un host x86-64; cada segmento se captura hasta una página, y solo se recorren los primeros 64 segmentos de una transferencia.
• Una transferencia enviada antes de que usbsnoop se adjuntara no tiene marca de inicio, por lo que su finalización no muestra latencia.
• Los descriptores USB son little-endian y se leen directamente — correcto en los hosts little-endian en los que se ejecuta BPF.