Syzkaller USB 设备仿真 syzlang 指南:基于 raw-gadget/dummy_hcd 的驱动探测与禁止 sysfs 绑定约束
Syzkaller USB 设备仿真 syzlang 指南:基于 raw-gadget/dummy_hcd 的驱动探测与禁止 sysfs 绑定约束
本篇指南围绕 docs/linux/syzlang/skills/usb.md 展开,讲解如何为 syzkaller 编写与修复面向 Linux USB 子系统的 syzlang 程序:通过 syz_usb_connect 系列伪系统调用在 raw-gadget + dummy_hcd 环境中仿真 USB 设备、完成枚举与控制/端点数据传输,并严格规避被禁止的 sysfs 驱动绑定路径。读完本文,你将掌握 USB 仿真程序的完整生命周期(连接→控制传输→端点 I/O→断开),理解 syzkaller 为何把 /sys/bus/usb/drivers/ 下的绑定接口"中和"为 ./file0,并能结合仓库源码(sys/linux/vusb.txt、sys/linux/init.go)写出被维护者接受的有效 USB 驱动探测程序。
为什么需要仿真 USB 设备
syzkaller 的 Linux USB 模糊测试不依赖物理硬件(如 Facedancer 板卡)或虚拟机软件特性(如 QEMU usbredir),而是完全运行在被测内核内部:Raw Gadget 内核模块提供 Linux USB Gadget 子系统的底层接口,Dummy HCD/UDC 在内核内部搭建一对互联的虚拟 USB Device/Host 控制器,配合 KCOV 的远程覆盖率收集能力,syzkaller 可以"站在 USB 设备一侧"对主机端驱动进行覆盖率引导的模糊测试。完整背景与搭建步骤见 docs/linux/external_fuzzing_usb.md。
在这种模式下,一个 syzlang 程序中的 syz_usb_* 伪系统调用,实际上就是在扮演一个"虚拟 USB 外设":向内核主机控制器枚举自身、响应控制请求、与驱动交换数据包。因此编写这类程序的核心纪律是:想探测哪个 USB 驱动,就用 syz_usb_connect 等伪系统调用仿真出符合该驱动预期的设备,而不是试图在宿主机 sysfs 里手动把驱动绑到设备上——后者正是 syzkaller 明令禁止并会主动中和的做法。
连接设备:syz_usb_connect
连接一个仿真 USB 设备的入口是:
syz_usb_connect(speed, dev_len, dev, conn)
参数含义(与 sys/linux/vusb.txt 中 syz_usb_connect 定义对应):
| 参数 | 含义 |
|---|---|
speed |
设备速度。skills 指南给出的速记映射:0x0 = Full,0x1 = High,0x2 = Super;该参数在 syzlang 中实际声明为 flags<a href="https://link.gitcode.com/i/9387ced50a907b9a63bbd65a488634f4" target="_blank">usb_device_speed](见 [vusb.txt),完整取值集合来自内核头文件,包含 USB_SPEED_UNKNOWN/LOW/FULL/HIGH/WIRELESS/SUPER/SUPER_PLUS(vusb.txt) |
dev_len |
设备描述符数据的长度,由 len[dev] 自动推导 |
dev |
USB 描述符(usb_device_descriptor),是嵌套复杂结构体的入口 |
conn |
连接描述符 vusb_connect_descriptors(可传 0,如 ath9k 变体) |
其中 dev 参数用于承载设备、配置、接口、端点等完整描述符层级。由于这些结构体嵌套复杂、字段繁多,syzkaller 允许用 ANY squashing 语法直接塞入原始字节:
&(0x7f0000000040)=ANY=[@ANYBLOB="120100..."]
ANY=<a href="https://link.gitcode.com/i/750c64e52f0798ed39e24942b32c1729" target="_blank">@ANYBLOB="..."] 表示"以任意二进制 blob 填充该处结构",十六进制串即描述符的原始字节。这是生成复杂 USB 描述符时最常用的手段——让变异器把整个描述符当作字节串去改写,从而探测内核 USB 栈对畸形描述符的解析路径。可对照 [sys/linux/test/vusb 中的种子程序,其 dev 参数即为逐字段展开的 usb_device_descriptor 结构体实例。
syz_usb_connect 完成的是枚举过程:处理从设备接入到收到 SET_CONFIGURATION 请求为止的全部控制请求(见 external_fuzzing_usb.md 的 Internals 一节)。其执行带 timeout<a href="https://link.gitcode.com/i/9350c629860c643bcd2ca24dbddc03a6" target="_blank">3000], prog_timeout[3000], remote_cover 属性,意味着允许最多 3000ms 执行时长、程序整体超时同步放宽,并参与远程覆盖率收集([vusb.txt)。
特殊设备:syz_usb_connect_ath9k
部分驱动在 SET_CONFIGURATION 之后还会立即期望设备处理若干后续控制请求(典型如固件下载),否则驱动会中止并断开设备。针对这类场景,syzkaller 提供了专门的 syz_usb_connect_ath9k 伪系统调用(vusb.txt),它除了执行枚举外,还会在 C 层处理 ath9k 驱动预期的 post-SET_CONFIGURATION 固件下载请求(实现见 executor/common_usb.h 与 executor/common_usb_linux.h)。
注意其签名的差异:
syz_usb_connect_ath9k(speed const[USB_SPEED_HIGH], dev_len, dev, conn_descs const[0])
speed固定为USB_SPEED_HIGH;conn_descs固定为0,不需要额外的连接描述符;- 配套的端点写入变体
syz_usb_ep_write$ath9k_ep1/syz_usb_ep_write$ath9k_ep2以ath9k_bulk_frame、htc_frame等驱动私有协议帧为载荷(vusb.txt)。
控制传输:syz_usb_control_io
枚举完成后,仿真设备需要继续响应驱动发来的控制请求(IN/OUT):
syz_usb_control_io(conn, req, res)
req为vusb_descriptors,描述设备在收到控制请求时返回的各类描述符(generic、string、BOS、hub 等);res为vusb_responses,描述对各类标准/类/厂商请求的应答(如GET_INTERFACE、GET_CONFIGURATION,以及 HID/CDC/asix 等驱动专属请求的响应,见 vusb.txt)。
syz_usb_control_io 处理的是 post-enumeration 的控制请求。对于 HID、printer、CDC ECM/NCM、UAC 等类别,syzkaller 提供了 syz_usb_control_io$hid、$printer、$cdc_ecm 等变体,各自带有类别专属的 vusb_descriptors_XXX / vusb_responses_XXX 结构,例如 HID 变体额外支持 HID_DT_REPORT、HID_REQ_GET_REPORT、HID_REQ_GET_PROTOCOL 等(vusb.txt)。执行属性为 timeout<a href="https://link.gitcode.com/i/913e4aee36cc4fbe903050d8b6cc9a06" target="_blank">300], remote_cover([vusb.txt)。
端点 I/O:syz_usb_ep_write / syz_usb_ep_read
与驱动交换数据包使用端点读写伪系统调用:
syz_usb_ep_write(conn, ep, len, data)
syz_usb_ep_read(conn, ep, len, data)
syz_usb_ep_write处理端点上的非控制 IN 请求(设备→主机方向的数据发送);syz_usb_ep_read处理端点上的非控制 OUT 请求(主机→设备方向的数据接收),其data为buffer[out]输出缓冲区;- 端点地址
ep按 USB 惯例编码:0x81表示方向位为 IN 的 1 号端点,0x02表示方向位为 OUT 的 2 号端点;data长度上限 256 字节(vusb.txt)。
生成程序时应结合目标设备描述符里声明的端点地址来配对使用,确保写入/读取的端点与驱动实际通信的端点一致。ath9k 等驱动专属变体则通过 syz_usb_ep_write$ath9k_ep1(ep=0x82)、$ath9k_ep2(ep=0x83) 固定端点并绑定专用协议帧结构(vusb.txt)。
断开连接:syz_usb_disconnect
syz_usb_disconnect(conn)
conn 为 fd_usb 资源(即之前 syz_usb_connect 返回的仿真设备 fd),断开后设备从虚拟总线上移除,触发驱动的 disconnect 路径(vusb.txt)。一个完整的仿真生命周期通常是:syz_usb_connect →(若干 syz_usb_control_io / syz_usb_ep_write / syz_usb_ep_read)→ syz_usb_disconnect,这样既能覆盖驱动的 probe 路径,也能覆盖 remove/disconnect 路径。
禁止 sysfs 驱动绑定:必须绕开的中和路径
编写 USB 相关 syzlang 程序有一条硬性约束:
禁止使用 sysfs 驱动绑定/解绑端点,包括
/sys/bus/usb/drivers/下的/bind、/unbind、/driver_override、/drivers_probe、/new_id等路径。
原因(skill 文档与 sys/linux/init.go 注释一致):手动把驱动绑定到不兼容设备、通过 driver_override 强制绑定、或用 new_id 动态添加驱动 ID,会把驱动挂到不匹配的硬件上,甚至解绑核心平台设备,制造出维护者会以"非法 root 操作"为由拒绝的无效崩溃。因此 syzkaller 的做法不是禁止这些系统调用,而是在程序生成阶段主动把这些路径"中和"(neutralize)为 ./file0:
- 对
open/openat/openat2/creat/symlink/link等路径类系统调用,neutralizePaths遍历其字符串参数(init.go); isForbiddenBindingPath匹配规则:路径包含/bus/、/devices/或/device/,且以/bind、/unbind、/driver_override、/drivers_probe、/new_id结尾,即判定为禁止路径(init.go);- 命中后数据参数被替换为
./file0(定长缓冲按原大小、变长缓冲带\x00结尾),使程序实际打开的是一个不存在的相对路径文件,而不是触碰 sysfs 绑定接口。
正确做法:探测 USB 驱动必须通过 syz_usb_connect 仿真设备来完成——让驱动在正常枚举流程中自行匹配并 probe 该设备,而不是用 sysfs 手工把驱动"塞"给设备。这也是该 skill 文档存在的意义:约束 LLM 生成/修复程序时不要写出会被中和、且必然产生无效崩溃的 sysfs 绑定代码。
结合源码的实战要点
类别与驱动专属变体
除通用变体外,sys/linux/vusb.txt 已内置多套类别/驱动专属描述符与配套伪系统调用变体,覆盖:HID($hid)、打印机($printer)、CDC ECM($cdc_ecm)、CDC NCM($cdc_ncm)、UAC1/2/3 音频($uac1/$uac2/$uac3)、MIDI($midi)、Wi-Fi 网卡 ath9k(syz_usb_connect_ath9k)、USB 网卡 rtl8150($rtl8150)、sierra_net($sierra_net)、lan78xx($lan78xx)等。这些变体既用于通过固定描述符快速穿透 probe 进入 post-probe 逻辑,也用于触发驱动枚举路径的各类校验分支(详见 vusb.txt 与 external_fuzzing_usb.md)。
USB ID 自动注入
为了覆盖驱动按 usb_device_id 匹配表实现的 quirks,syzkaller 在程序生成时会把自动提取的 USB ID 注入到设备描述符的 idVendor/idProduct/bcdDevice 等字段(HID、printer 与通用变体,见 sys/linux/init_vusb.go 的 generateUsbHidDeviceDescriptor、generateUsbPrinterDeviceDescriptor)。ID 列表维护在 sys/linux/init_vusb_ids.go,可用 tools/syz-usbgen/usbgen.go 依据内核日志更新。这意味着你看到的种子程序(如 sys/linux/test/vusb)里的 idVendor 等字段在运行前会被改写为真实设备 ID——这是刻意设计,不要试图"修正"它。
种子程序与 run-tests 验证
仓库在 sys/linux/test/ 提供以 vusb 前缀命名的种子程序(vusb、vusb_hid、vusb_ath9k、vusb_cdc_ecm、vusb_uac1/2/3、vusb_printer 等),它们的作用有二:一是作为 seed 让 fuzzer 无需详尽的 syzlang 描述即可深入驱动代码;二是作为 runtests 验证 USB 仿真功能、防止描述变更破坏生成:
./bin/syz-manager -config usb-manager.cfg -mode run-tests -tests vusb
环境前提速查
按 external_fuzzing_usb.md 的要求:内核 ≥ 5.7;启用 CONFIG_USB_RAW_GADGET=y 与 CONFIG_USB_DUMMY_HCD=y;管理器配置中开启上述 5 个伪系统调用(或其变体);sandbox 设为 none;内核命令行传入 dummy_hcd.num=N(N 与 procs 一致);日志的 machine check 中应看到 USBEmulation 与 ExtraCoverage 均为 enabled。参考现成内核配置见 dashboard/config/linux/upstream-usb.config。
小结:USB syzlang 程序编写清单
- 用
syz_usb_connect(必要时用syz_usb_connect_ath9k)仿真目标设备,dev用 ANY squashing 或展开结构描述描述符; - 用
syz_usb_control_io应答枚举后控制请求,用syz_usb_ep_write/syz_usb_ep_read(注意0x81=IN、0x02=OUT 的端点编码)交换数据; - 用
syz_usb_disconnect收尾,覆盖 disconnect 路径; - 绝不在程序中通过
/sys/bus/usb/drivers/下的/bind、/unbind、/driver_override、/drivers_probe、/new_id手工绑定驱动——这些路径会被中和成./file0,探测驱动只能靠设备仿真。
遵循以上约束生成的程序,才能稳定命中 drivers/usb/core/* 与各类 USB 驱动的真实代码路径,并产出被内核维护者认可的崩溃报告。