usbsnoop — 基于两个 fentry 钩子的实时 USB 传输嗅探器

一个实时、彩色化的 USB 流量全系统馈送——构建于每个主机控制器驱动程序都会流经的两个通用 URB 瓶颈点之上，因此它同样适用于 xHCI/EHCI/OHCI/dwc，无需每个控制器的跟踪点，也无需 usbmon。完全 CO-RE 可移植。

一个以 URB 指针为键的 lru_hash 将两者缝合在一起：提交时打上开始时间戳，完成时读回该时间戳以获取提交到完成的延迟，然后将其删除。这镜像了 httpbody 的请求/响应配对——SUBMIT 是“请求”（主机发送的内容），COMPLETE 是“响应”（设备返回的内容）。

控制传输会将其 8 字节 SETUP 数据包解码为标准请求名称（GET_DESCRIPTOR、SET_CONFIGURATION、……）；数据阶段在看起来像文本时渲染为文本，否则渲染为十六进制转储。

输出是每事件一行（紧凑）。设备首次出现时会显示一行 ▸ 图例行（bus-dev、vid:pid、产品、链接速度）；之后每行仅携带简短的 DEV 标签，因此左侧列在高流量下保持对齐且易于扫描。每行显示时间、类型（SUBMIT/CMPLT）、传输类型、epNdir、方向箭头（← 设备→主机 IN，→ 主机→设备 OUT）、字节数、状态、延迟以及所属内核驱动程序，然后是一个 · 和最有用的细节（解码后的 SETUP、SCSI 命令或短负载预览）。传递 --hex 以使用完整的多行十六进制转储。十六进制字节在 TTY 上按值类别着色（null 蓝色、可打印 ASCII 青色、空白绿色、其他控制字符洋红色、高位/非 ASCII 黄色）；管道输出为纯文本。

使用场景

• 逆向工程外设 — 实时观察设备枚举、交换厂商控制请求和 HID 报告，无需硬件嗅探器或 usbmon 设置。在您操作设备时，SETUP 数据包和负载被解码。
• 驱动程序/固件调试 — 精确查看您的驱动程序或应用向设备发送了哪些命令以及返回了什么，每次传输都附带提交到完成的延迟。
• 大容量存储/SCSI 检查 — 批量仅传输包装器解码为 SCSI 命令（READ(10) lba=… blocks=…、WRITE(10)、CSW PASS/FAIL）。
• 捕获错误 — --errors-only 显示所有设备上的停止（EPIPE）、超时、胡言乱语和 CRC 错误。
• 发现恶意设备 — 新插入的设备立即显示其行为；BadUSB 风格的 HID 注入表现为您未触发的 INT 报告或 SET_REPORT 控制写入。
• 离线分析捕获 — --json 输出 NDJSON；通过管道传给 jq 或文件以比较不同运行间的负载。
• 性能排查 — 在定时退出时，您会获得每个设备的汇总和 log2 延迟直方图，以发现慢速或话多的设备。

安装

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

然后直接从 GitHub 运行它——yeet 会获取示例并为您构建，无需克隆：

yeet run github:yeet-src/usbsnoop

构建

要从本地 checkout 构建，请运行：

make

将内核的 BTF 转储到 vmlinux.h（用于 struct urb、usb_device 和设备描述符），然后编译。需要 clang、bpftool 和带有 BTF 的内核。

运行

yeet run .                              # 所有设备，运行直到 Ctrl-C
yeet run . -- --secs 30                 # 30 秒后停止（打印摘要）
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             # 仅显示失败的完成（停止、超时）
yeet run . -- --hex                      # 每次传输完整的多行十六进制转储
yeet run . -- --json | jq .             # NDJSON，每事件一个对象

标志

所有过滤都发生在内核端，因此被过滤掉的流量从不会到达用户空间。

每个事件行以括号中的所属内核驱动程序结尾（[hid_irq_in]、[usb_api_blocking_completion]）——urb->complete 在内核中通过 bpf_snprintf("%ps") 符号化，因此无需查找 /proc/kallsyms。大容量存储批量传输将其批量仅传输包装器解码为 SCSI 命令（CBW READ(10) lba=… blocks=… / CSW PASS）。在定时退出（达到 --secs）时，会打印每个设备的摘要和 log2 延迟直方图；Ctrl-C 退出则跳过（没有 JS 可见的信号钩子）。

分散-聚集负载

批量流量（大容量存储等）通常向栈传递一个 struct scatterlist 数组（urb->sg）而不是单个线性 transfer_buffer，因此负载分散在多个页面中。usbsnoop 遍历该数组并复制每个段的字节，但要访问它们需要将页面转换为其内核虚拟地址——x86-64 的 page_to_virt 的逆操作，这需要正在运行的内核的 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 字节（2 的幂——验证器的读取限制依赖于此）。更大的缓冲区会被截断；头部仍然报告真实的 actual/requested 长度。每个环形记录携带完整的 data[16384]，因此 8 MiB 的环形缓冲区可容纳约 512 个事件。
• 分散-聚集负载需要上述 --page-offset-base / --vmemmap-base 标志和 x86-64 主机；每个段最多捕获一个页面，并且仅遍历传输的前 64 个段。
• 在 usbsnoop 附加之前提交的传输没有开始时间戳，因此其完成时不显示延迟。
• USB 描述符是小端序并直接读取——在 BPF 运行的小端序主机上是正确的。