usbsnoop — sniffer live dei trasferimenti USB tramite due hook fentry

Un feed in tempo reale e colorizzato del traffico USB a livello di sistema — costruito sui due punti di passaggio URB universali attraverso cui passa ogni driver host-controller, quindi funziona su xHCI/EHCI/OHCI/dwc allo stesso modo, senza tracepoint per-controller e senza usbmon. Pienamente portabile CO-RE.

Una lru_hash indicizzata dal puntatore URB unisce i due eventi: submit registra un tempo di inizio, il completamento lo rilegge per calcolare la latenza submit→complete, poi lo elimina. Questo rispecchia l'abbinamento richiesta/risposta di httpbody — SUBMIT è la "richiesta" (ciò che l'host invia), COMPLETE la "risposta" (ciò che il dispositivo restituisce).

I control transfer vedono decodificato il loro pacchetto SETUP di 8 byte nel nome standard della richiesta (GET_DESCRIPTOR, SET_CONFIGURATION, …); gli stadi di dati vengono mostrati come testo quando appaiono testuali e come hexdump altrimenti.

L'output è una riga per evento (compatto). La prima volta che appare un dispositivo, riceve una riga legenda ▸ (bus-dev, vid:pid, prodotto, velocità di link); dopo di che ogni riga riporta solo il tag breve DEV, così le colonne a sinistra restano allineate e scansionabili sotto traffico intenso. Ogni riga mostra tempo, tipo (SUBMIT/CMPLT), tipo di trasferimento, epNdir, la freccia di direzione (← device→host IN, → host→device OUT), conteggi di byte, stato, latenza e il driver kernel proprietario, poi un · e il dettaglio più utile (SETUP decodificato, comando SCSI o una breve anteprima del payload). Passa --hex per l'hexdump completo su più righe. I byte esadecimali sono colorati in base alla classe di valore (null blu, ASCII stampabile ciano, spazi bianchi verdi, altri caratteri di controllo magenta, alto/non-ASCII giallo) su TTY; l'output tramite pipe è in chiaro.

Casi d'uso

• Reverse-engineering di periferiche — osserva un dispositivo enumerare e scambiare richieste di controllo vendor e report HID dal vivo, senza sniffer hardware né configurazione di usbmon. I pacchetti SETUP e i payload vengono decodificati mentre interagisci con il dispositivo.
• Debug di driver / firmware — vedi esattamente quali comandi il tuo driver o la tua app invia a un dispositivo e cosa arriva in risposta, con la latenza submit→complete su ogni trasferimento.
• Ispezione mass-storage / SCSI — i wrapper Bulk-Only Transport vengono decodificati nel comando SCSI (READ(10) lba=… blocks=…, WRITE(10), CSW PASS/FAIL).
• Individuare errori — --errors-only mette in evidenza stall (EPIPE), timeout, babble ed errori CRC su tutti i dispositivi contemporaneamente.
• Scovare dispositivi rogue — un dispositivo appena collegato mostra cosa fa nell'istante in cui si aggancia; l'iniezione HID stile BadUSB emerge come report INT o scritture di controllo SET_REPORT che non hai innescato.
• Cattura per analisi offline — --json emette NDJSON; invialo tramite pipe a jq o a un file per confrontare i payload tra diverse esecuzioni.

Install

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

Poi eseguilo direttamente da GitHub — yeet scarica l'esempio e lo compila per te, senza bisogno di clonare:

yeet run github:yeet-src/usbsnoop

Build

Per compilare invece da un checkout locale:

make

Scarica il BTF del kernel in vmlinux.h (per struct urb, usb_device e il device descriptor), poi compila. Richiede clang, bpftool e un kernel con BTF.

Run

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

Flags

Tutto il filtraggio avviene lato kernel, quindi il traffico filtrato non raggiunge mai lo spazio utente.

Ogni riga di evento termina con il driver kernel proprietario tra parentesi quadre ([hid_irq_in], [usb_api_blocking_completion]) — urb->complete viene simbolizzato in-kernel tramite bpf_snprintf("%ps"), quindi non serve alcuna interrogazione di /proc/kallsyms. I bulk transfer di mass-storage decodificano il loro wrapper Bulk-Only Transport nel comando SCSI (CBW READ(10) lba=… blocks=… / CSW PASS). Su un'uscita a tempo (raggiungimento di --secs) vengono stampati un riepilogo per dispositivo e un istogramma delle latenze in log2; un'uscita con Ctrl-C lo salta (non c'è alcun hook di segnale visibile a JS).

Payload scatter-gather

Il traffico bulk (mass storage e simili) spesso passa allo stack un array struct scatterlist (urb->sg) invece di un singolo transfer_buffer lineare, quindi il payload è sparso su più pagine. usbsnoop percorre quell'array e copia i byte di ogni segmento, ma raggiungerli significa tradurre una pagina nel suo indirizzo virtuale di kernel — l'inverso di page_to_virt di x86-64, che richiede page_offset_base e vmemmap_base del kernel in esecuzione (entrambi randomizzati da KASLR).

L'isolato JS non può leggere /proc/kallsyms e il loader non ha supporto ksym, quindi passi i due indirizzi dei simboli e il lato BPF li dereferenzia:

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)

Senza questi flag, i trasferimenti SG mostrano comunque tutti i metadati, solo nessun byte di payload — il comportamento precedente. Questo percorso è solo x86-64: sulle altre architetture lascia i flag disattivati.

Limiti

• Solo i primi 16384 byte di ogni trasferimento vengono catturati (una potenza di due — il read-clamp del verifier dipende da questo). I buffer più grandi vengono troncati; l'header riporta comunque la lunghezza reale actual/requested. Ogni record dell'anello porta un data[16384] completo, quindi l'anello da 8 MiB contiene ~512 eventi.
• I payload scatter-gather richiedono i flag --page-offset-base / --vmemmap-base di cui sopra e un host x86-64; ogni segmento viene catturato fino a una pagina e vengono percorsi solo i primi 64 segmenti di un trasferimento.
• Un trasferimento inviato prima che usbsnoop si agganciasse non ha un timestamp di inizio, quindi il suo completamento non mostra alcuna latenza.
• I descrittori USB sono little-endian e vengono letti direttamente — corretto sugli host little-endian su cui gira BPF.