syzkaller 的 Fuchsia 系统调用描述:sys/fuchsia 目录结构与 FIDL 驱动的 syzlang 定义
syzkaller 的 Fuchsia 系统调用描述:sys/fuchsia 目录结构与 FIDL 驱动的 syzlang 定义
本篇指南围绕 syzkaller 仓库中
sys/fuchsia目录展开,系统讲解 Fuchsia 内核(Zircon)系统调用描述的定义方式:哪些文件负责描述 Zircon vDSO 系统调用、如何用 syzlang 语言手工编写.txt描述、如何将 FIDL 接口自动生成为.syz.txt文件,以及对应的常量文件、工具链与更新流程。读完本文,你将能独立阅读、修改并重新生成 Fuchsia 目标的系统调用描述,也能理解该目标当前“手工维护 + 部分自动生成”的混合状态及其实战约束。
一、Fuchsia 目标与 sys/fuchsia 目录的定位
syzkaller 是一个无监督的、基于覆盖率引导的内核模糊测试器,其针对不同操作系统维护着各自的系统调用描述。Fuchsia 目标的全部系统调用定义集中在 sys/fuchsia 目录下,描述对象是 Fuchsia 的内核——Zircon。
在 syzkaller 的目标注册表中,Fuchsia 是与 Linux、Darwin、FreeBSD、NetBSD、OpenBSD 并列的一等 OS 目标(见 sys/targets/targets.go 中 Fuchsia = "fuchsia" 的定义)。从目标配置可以看到 Fuchsia 的两个显著特点:
- 不依赖
__NR_*系统调用号(SyscallNumbers: false),因为 Zircon 的系统调用通过 vDSO 以函数调用形式暴露,而不是传统的 int 指令编号; - 执行器不使用 fork server(
ExecutorUsesForkServer: false),这与 Unix 类目标的执行模型不同。
目录本身由 go:generate 指令驱动(见 sys/fuchsia/init.go 顶部的 //go:generate go run fidlgen/main.go),并且通过 init.go 中的 InitTarget 为 Fuchsia 目标注入数据内存映射逻辑(targets.MakeSyzMmap),保证模糊测试程序在 Zircon 下能够用 syz_mmap 分配参数缓冲区。
二、事实来源:Zircon vDSO 中的 FIDL 文件
Fuchsia 系统调用的权威定义并不在 syzkaller 仓库中,而在 Fuchsia 源码树 zircon/vdso/ 目录下的 FIDL 文件中。这些 .fidl 文件用 FIDL(Fuchsia Interface Definition Language)描述每个系统调用的签名,注释中附带英文说明和 C++ 原型,是 Zircon ABI 的单一事实来源。
sys/fuchsia/README.md 明确约定:针对 vDSO 中的每一个 FIDL 文件,本目录都应有一个对应的 .txt 文件,用 syzkaller 的 syzlang 语言(语法规范见 docs/syscall_descriptions_syntax.md)描述对应的系统调用。二者的对应关系在 .txt 文件的头部注释中直接标明,例如:
- channel.txt 第 4 行注释指向
zircon/vdso/channel.fidl; - bti.txt 第 4 行注释指向
zircon/vdso/bti.fidl; - rights.txt 第 4 行注释指向
zircon/vdso/rights.fidl; - sys.txt 则指向 Zircon 的 syscalls 文档。
当前维护状态(来自原文档的明确声明):这些 Zircon 系统调用描述目前由人工手工更新。原文档直言“希望这在不久的将来改变(Real Soon Now)”,届时会同步更新本说明文件。这一点也反映在 docs/fuchsia/README.md 的已知问题清单中——“System call definitions require manual updates”(系统调用定义需要手工更新)是 Fuchsia 支持不完整的三大已知问题之一。
三、手工维护的 .txt:Zircon 系统调用的 syzlang 描述
3.1 基础模式:以 channel.txt 为例
channel.txt 完整演示了 syzlang 描述一个 Zircon 系统调用的标准写法:
include <zircon/syscalls.h>
resource zx_chan[zx_handle]
zx_channel_call(handle zx_chan, options const[0], deadline zx_time, args ptr[in, zx_channel_call_args], actual_bytes ptr[out, int32], actual_handles ptr[out, int32])
zx_channel_create(options const[0], out0 ptr[out, zx_chan], out1 ptr[out, zx_chan])
zx_channel_read(handle zx_chan, options flags[chan_read_options], bytes ptr[out, array[int8]], handles ptr[out, zx_handle], num_bytes len[bytes], num_handles len[handles], actual_bytes ptr[out, int32], actual_handles ptr[out, int32])
zx_channel_write(handle zx_chan, options flags[chan_write_options], bytes ptr[in, array[int8]], num_bytes len[bytes], handles ptr[in, array[zx_handle]], num_handles len[handles])
值得注意的 syzlang 特性:
include <zircon/syscalls.h>:声明该描述依赖的头文件,这些头文件由 Fuchsia 构建产物提供,用于在生成 C 代码时获取正确的类型和常量定义;resource zx_chan[zx_handle]:zx_chan是基于zx_handle的派生资源类型。Fuchsia 中几乎所有内核对象都以zx_handle为基类派生自己的资源类型(如zx_vmo、zx_socket、zx_port、zx_bti),这样 syzkaller 的类型系统就能保证“只有同类型句柄才能传给对应系统调用”;const[0]:某些参数在 Zircon ABI 中被硬编码为 0(如zx_channel_create的 options 目前只有保留位),直接用常量锁定,避免模糊测试浪费探索空间;ptr[in, ...]/ptr[out, ...]:区分输入/输出缓冲区,array[int8]表示字节数组,len[bytes]把长度参数与缓冲区绑定,保证生成程序时长度与缓冲区大小一致;- flags 与 flags 类型:文件末尾定义
chan_read_options = ZX_CHANNEL_READ_MAY_DISCARD、chan_write_options = ZX_CHANNEL_WRITE_USE_IOVEC等可枚举标志集合。
3.2 结构体与联合体:完整描述 ABI
channel.txt 还定义了 zx_channel_call 需要的参数结构体 zx_channel_call_args,以及句柄信息类结构体 zx_handle_info、zx_channel_iovec、zx_handle_disposition。zx_port_packet 系列(见 port.txt)则展示了用 syzlang 描述端口数据包的复杂模式:zx_packet_user、zx_packet_signal、zx_packet_interrupt、zx_packet_page_request 四个变体组合成一个可选的 zx_port_packet_payload 联合体,最终被 zx_port_packet 引用。
其中 zx_packet_user.key 使用了 proc[1000, 16, int64] 这种过程化类型——它让 syzkaller 在生成程序时按 16 字节的对齐要求产出进程号,用于 zx_port_cancel(port zx_port, source zx_handle, key proc[1000, 16]) 的场景。
3.3 常量的另一种写法:rights.txt
句柄权限是 Fuchsia 安全模型的核心,rights.txt 用一行定义了完整的 zx_rights 标志位集合:
zx_rights = ZX_RIGHT_NONE, ZX_RIGHT_DUPLICATE, ZX_RIGHT_TRANSFER, ZX_RIGHT_READ, ZX_RIGHT_WRITE, ZX_RIGHT_EXECUTE, ZX_RIGHT_MAP, ZX_RIGHT_GET_PROPERTY, ZX_RIGHT_SET_PROPERTY, ZX_RIGHT_ENUMERATE, ZX_RIGHT_DESTROY, ZX_RIGHT_SET_POLICY, ZX_RIGHT_GET_POLICY, ZX_RIGHT_SIGNAL, ZX_RIGHT_SIGNAL_PEER, ZX_RIGHT_WAIT, ZX_RIGHT_INSPECT, ZX_RIGHT_MANAGE_JOB, ZX_RIGHT_MANAGE_PROCESS, ZX_RIGHT_MANAGE_THREAD, ZX_RIGHT_APPLY_PROFILE, ZX_RIGHT_MANAGE_SOCKET, ZX_RIGHT_SAME_RIGHTS
3.4 架构相关描述:restricted 与 sys.txt
restricted 是一个架构相关的特权系统调用描述文件,头部注释直接注明“architecture-dependant”:
include <zircon/syscalls.h>
# architecture-dependant
restricted_read(state ptr[in, array[int8]], state_size len[state])
sys.txt 则承担“syzkaller 基础设施”角色,定义了不来自 Zircon vDSO 的辅助调用:
syz_execute_func(text ptr[in, text[target]]) (disabled)
get_root_resource() zx_root_resource
syz_mmap(addr vma, len len[addr])
syz_process_self() zx_process
syz_thread_self() zx_thread
syz_vmar_root_self() zx_vmar
syz_job_default() zx_job
这些 syz_* 前缀的伪系统调用由 syzkaller 执行器在 Fuchsia 侧实现(对应 executor/common_fuchsia.h 中的运行时支持),用于分配参数内存、获取当前进程/线程/根 VMAR/默认 job 句柄等。
3.5 POSIX 子集:posix.txt
Zircon 之上还运行着 POSIX 兼容层,posix.txt 覆盖了这部分 libc 调用(open/read/write/poll/stat/管道/目录操作等),并定义了 fd、uid、gid 资源。文件头注释说明:这些调用实际由 ulib/fs 服务而非内核处理,“但没有理由不模糊它们”。其内容采用与 Linux 描述一致的 POSIX 头文件体系(<sys/types.h>、<fcntl.h>、<poll.h> 等),且定义了 iovec_in/iovec_out、pollfd、timespec、timeval、fd_set 等标准结构体,以及 open_flags、open_mode、seek_whence、at_flags 等标志集合。
四、架构相关的 .const 常量文件
每个 .txt 描述文件对应的常量值单独存放在按架构区分的 .const 文件中,命名规则为 文件名_架构.const,例如:
- channel_amd64.const
- channel_arm64.const
- vmo_amd64.const / vmo_arm64.const
常量文件由工具生成(文件头标注 # AUTOGENERATED FILE),内容是把 syzlang 中用到的宏名解析为具体数值,例如:
ZX_CHANNEL_READ_MAY_DISCARD = 1
ZX_CHANNEL_WRITE_USE_IOVEC = 2
每个 *.txt 都配有 amd64/arm64 两份常量文件,与 Fuchsia 支持的两个主要架构对应;fuchsia_*.syz.txt 系列同样有 _amd64.const/_arm64.const 成对文件。常量值来自 Fuchsia 构建产物中的头文件,因此一旦 Fuchsia 侧头文件变化,需要重新执行提取流程刷新这些数值。
五、FIDL 自动生成链路:fuchsia_*.syz.txt 与 fidlgen
5.1 自动生成的文件
与手工维护的 Zircon 系统调用不同,FIDL 接口描述不需要手工更新——它们由 make extract 自动提取(原文档明确声明)。目录下以 fuchsia_*.syz.txt 命名的文件(如 fuchsia_io.syz.txt、fuchsia_net.syz.txt、fuchsia_cobalt.syz.txt)均由 fidlgen 生成,文件头统一标注 # WARNING: This file is machine generated by fidlgen.
这些文件将 FIDL 库编译后的 JSON IR(中间表示)翻译成 syzlang 结构体描述。以 fuchsia_io.syz.txt 为例,其内容是按 FIDL 的 InLine/OutOfLine/Handles 三段式划分的结构体:
fuchsia_io_FileObjectHandles {
event zx_handle
stream zx_handle
} [packed]
fuchsia_io_NodeAttributesInLine {
mode int32
id int64
content_size int64
storage_size int64
link_count int64
creation_time int64
modification_time int64
} [packed]
[packed] 与 [varlen] 是 syzlang 中对齐控制标记;FIDL 的联合体(union)被翻译为 syzlang 的变体列表,并保留 fidl_union_member[1, ...] 形式的成员标记(见 fuchsia_net.syz.txt 中的 fuchsia_net_IpAddressInLine),同时引入 fidl_string、fidl_vector、fidl_aligned[stringnoz] 等 FIDL 专用类型来表达可变长字符串与向量。
5.2 fidlgen 工具链实现
自动生成的核心实现在 sys/fuchsia/fidlgen/main.go 与 sys/fuchsia/layout/fidl_mappings.go:
- 入口依赖两个环境变量:
TARGETARCH(目标架构)与SOURCEDIR(Fuchsia 源码树路径),后者必须存在,且要能找到 Fuchsia 构建产物out/<arch>/host_x64/fidlgen_syzkaller可执行文件; - layout/fidl_mappings.go 中的
AllFidlLibraries硬编码了当前需要提取的全部 FIDL 库列表:fuchsia.cobalt、fuchsia.devicesettings、fuchsia.hardware.ethernet、fuchsia.io、fuchsia.ldsvc、fuchsia.mem、fuchsia.net、fuchsia.process、fuchsia.scpi; - 每个 FIDL 库的 JSON IR 位于 Fuchsia 构建产物
out/<arch>/fidling/gen/sdk/fidl/<library>.<name>.fidl.json(由PathToJSONIr计算),fidlgen 主程序调用 Fuchsia 侧的fidlgen_syzkaller,以-json <ir>和-output-syz <base>.syz.txt参数产出 syzlang 文件; - 生成完毕后,main.go 会重新解析目录下全部
*.txt(ast.ParseGlob),再通过compiler.CollectUnused找出未被引用的节点并剪枝(desc.Filter),最后按文件回写格式化结果。这一步保证了自动生成的文件与手工文件在编译层面的一致性和整洁度。
5.3 更新流程与已知问题
当需要更新系统调用/FIDL 定义时,流程为(详见 docs/fuchsia/README.md):
# 在 syzkaller 检出目录中执行,SOURCEDIR 指向 Fuchsia 检出
make extract TARGETOS=fuchsia SOURCEDIR=${SOURCEDIR}
make generate
make extract 触发 go generate ./sys/fuchsia(即 init.go 中的 go:generate 指令),进而运行 fidlgen/main.go。需要强调的是:FIDL 定义提取要求 Fuchsia 已按每个架构重新构建,因为 JSON IR 与 fidlgen_syzkaller 都来自 Fuchsia 构建产物。
原文档对当前状态给出了两条重要警示:
make extract命令目前不可用(docs/fuchsia/README.md 明确标注 “Caveat: This command does not currently work”,setup.sh 的update子命令同样直接输出 “NOTE: This command does not currently work.”);- 手工更新 Zircon 系统调用时,如果该调用被 executor/common_fuchsia.h 使用,必须同步更新执行器中的对应用法,否则描述与执行器实现会脱节。
若 FIDL 库在 Fuchsia 侧被删除或重命名,make extract 会报错“找不到 fidl.json 文件”。此时需要修改 fidlgen/main.go(或 layout 中的库列表)以反映变更,并清理过时的自动生成文件(docs/fuchsia/README.md 的 Troubleshooting 一节给出了具体排查路径)。
六、从描述到运行:构建 Fuchsia 目标并启动 syz-manager
6.1 构建 Fuchsia
先获取 Fuchsia 源码并设置 SOURCEDIR 环境变量,然后为 x64 构建(docs/fuchsia/README.md):
export SOURCEDIR=/home/you/fuchsia
fx --dir "out/x64" set core.x64 \
--with-base "//bundles/tools" \
--with-base "//src/testing/fuzzing/syzkaller" \
--args=syzkaller_dir='"/full/path/to/syzkaller"' \
--variant=kasan
fx build
arm64 构建使用 core.arm64 配置,并将 fx build 换成 fx clean-build。其中 --with-base "//src/testing/fuzzing/syzkaller" 将 syzkaller 执行器组件打进镜像,--variant=kasan 开启 KASAN 以便捕获内存错误。
6.2 构建 syzkaller 二进制
在 syzkaller 检出中(假设 Fuchsia 已按 x64 构建):
make TARGETOS=fuchsia TARGETARCH=amd64 SOURCEDIR=${SOURCEDIR}
6.3 准备镜像并启动 syz-manager
运行 syz-manager 前,需要从 Fuchsia 构建的 product bundle 中取出镜像文件,并把 SSH 公钥打进 ZBI 以便登录:
product_bundle_path="$(ffx config get product.path | tr -d '"')"
fxfs_path="$(ffx product get-image-path "$product_bundle_path" --slot a --image-type fxfs)"
zbi_path="$(ffx product get-image-path "$product_bundle_path" --slot a --image-type zbi)"
multiboot_path="$(ffx product get-image-path "$product_bundle_path" --slot a --image-type qemu-kernel)"
ffx config check-ssh-keys
auth_keys_path="$(ffx config get ssh.pub | tr -d '"')"
priv_key_path="$(ffx config get ssh.priv | tr -d '"')"
# 将公钥写入 ZBI;注意:每次 fx build 后都需重新执行
fx host-tool zbi -o "${SOURCEDIR}/out/x64/fuchsia-ssh.zbi" \
"${zbi_path}" \
--entry "data/ssh/authorized_keys=${auth_keys_path}"
然后编写 syz-manager 配置(docs/fuchsia/README.md 提供的起始模板):
{
"name": "fuchsia",
"target": "fuchsia/amd64",
"http": ":12345",
"workdir": "/workdir.fuchsia",
"kernel_obj": "/fuchsia/out/syz/kernel_x64-kasan/obj/zircon/kernel",
"syzkaller": "/syzkaller",
"image": "$fxfs_path",
"sshkey": "$priv_key_path",
"reproduce": false,
"cover": false,
"procs": 8,
"type": "qemu",
"vm": {
"count": 10,
"cpu": 4,
"mem": 2048,
"kernel": "${multiboot_path}",
"initrd": " ${SOURCEDIR}/out/x64/fuchsia-ssh.zbi"
}
}
其中 "cover": false 反映了 Fuchsia 目标当前不支持覆盖率反馈的现状(docs/fuchsia/README.md 的已知问题之一),"reproduce": false 同样出于当前实现限制。启动:
bin/syz-manager -config manager.cfg
可能需要把 qemu 加入 PATH:
export PATH="$SOURCEDIR/prebuilt/third_party/qemu/linux-x64/bin:$PATH"
6.4 一键脚本
setup.sh 封装了上述全部步骤,支持三个子命令:
setup.sh build <syzkaller目录> <fuchsia目录>:构建 Fuchsia 与 syzkaller(x64);setup.sh [-d] run <syzkaller目录> <fuchsia目录>:在 Fuchsia 模拟器上运行 syz-manager,-d附加--debug;setup.sh update <syzkaller目录> <fuchsia目录>:更新系统调用定义(当前为 TODO 状态,直接提示不可用)。
脚本内部自动完成了镜像路径查询、SSH 密钥注入、fxfs 镜像拷贝、manager 配置生成与 qemu PATH 设置,是快速上手 Fuchsia 目标的首选入口。
七、用测试程序验证描述
sys/fuchsia/test 目录为每种资源/对象提供了手工编写的 syzlang 测试程序(cprng、event、eventpair、pipe、port、socket、stream、vmar、vmo、channel 等),这些程序随 make generate 参与编译验证,确保描述文件语法正确且资源类型推导符合预期。例如 test/cprng 验证 zx_cprng_draw 的缓冲区读写,test/eventpair 则完整演练了事件对(eventpair)的创建、zx_object_signal_peer 置位、zx_object_wait_one 等待与句柄关闭的闭环:
zx_eventpair_create(0x0, &AUTO=<r0=>0x0, &AUTO=<r1=>0x0)
zx_object_signal_peer(r0, 0x0, 0XFF000000)
zx_object_wait_one(r1, 0X01000000, 0x0, 0x0)
zx_handle_close(r0)
zx_handle_close(r1)
test/vmo、test/stream 等则用 zx_vmo_create(0x100, 0x0, &AUTO=<r0=>0x0) 形式验证 VMO 创建与资源引用。这些用例是描述文件“可编译、可执行”的直接证据,新增或修改 .txt 后应同步考虑补充测试程序。
八、总结:当前状态与实战建议
综合 sys/fuchsia/README.md 与 docs/fuchsia/README.md,Fuchsia 目标当前的定位可以概括为:
- Zircon 系统调用描述:手工维护,与
zircon/vdso/的 FIDL 文件一一对应,修改后需同步执行器(executor/common_fuchsia.h)中的相关用法; - FIDL 接口描述:自动生成,由 fidlgen 工具链从 Fuchsia 构建产物的 JSON IR 提取,但当前的 extract 命令尚不可用,FIDL 库列表需在 layout/fidl_mappings.go 中维护;
- 已知局限:崩溃解析(crash parsing)不可靠、覆盖率反馈不支持,导致 manager 配置中需显式关闭
cover与reproduce; - 运行路径:通过 setup.sh 或手工执行 fx 构建 +
make TARGETOS=fuchsia+bin/syz-manager,在 qemu 上启动 Fuchsia 模糊测试。
对于希望在 Fuchsia 目标上做贡献的开发者,最直接的切入点是:对照 zircon/vdso/ 中新增或变更的 FIDL 文件,在 sys/fuchsia 下补充或修正对应的 .txt 描述,更新 _amd64.const/_arm64.const 常量文件,并借助 sys/fuchsia/test 中的测试程序验证——这正是该目录当前“手工为主、自动化为辅”的工作流核心。