Syzkaller USB 设备仿真 syzlang 指南:基于 raw-gadget/dummy_hcd 的驱动探测与禁止 sysfs 绑定约束

原创2026-10-08 23:23:442,236 阅读
文章标签:网络安全开发工具质量保障

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 程序编写清单

  1. 用 syz_usb_connect(必要时用 syz_usb_connect_ath9k)仿真目标设备,dev 用 ANY squashing 或展开结构描述描述符;
  2. 用 syz_usb_control_io 应答枚举后控制请求,用 syz_usb_ep_write/syz_usb_ep_read(注意 0x81=IN、0x02=OUT 的端点编码)交换数据;
  3. 用 syz_usb_disconnect 收尾,覆盖 disconnect 路径;
  4. 绝不在程序中通过 /sys/bus/usb/drivers/ 下的 /bind、/unbind、/driver_override、/drivers_probe、/new_id 手工绑定驱动——这些路径会被中和成 ./file0,探测驱动只能靠设备仿真。

遵循以上约束生成的程序,才能稳定命中 drivers/usb/core/* 与各类 USB 驱动的真实代码路径,并产出被内核维护者认可的崩溃报告。

登录后查看全文
syzkaller