OSS-Fuzz JavaScript 项目接入实战:基于 Jazzer.js 编写 Fuzz Target 与构建配置
OSS-Fuzz JavaScript 项目接入实战:基于 Jazzer.js 编写 Fuzz Target 与构建配置
本文面向希望在 OSS-Fuzz 中接入 Node.js / JavaScript(含 TypeScript)项目的开发者,系统讲解从 project.yaml 配置、Dockerfile 基础镜像,到 fuzz target 编写、build.sh 构建调用,再到 FuzzedDataProvider 结构化取数的完整流程。读完本文,你将掌握一套可直接照搬的 JavaScript 项目 fuzzing 接入方案,并能理解 OSS-Fuzz 为 JavaScript 提供的 compile_javascript_fuzzer 构建脚本的底层工作机制。仓库中的 javascript-example 与 typescript-example 两个官方示例项目,以及 compile_javascript_fuzzer 构建脚本源码,是本文所有结论的直接依据。
接入总览:为什么 JavaScript 项目需要专门流程
在 OSS-Fuzz 中接入一个 JavaScript / Node.js 项目,整体流程与通用的「Setting up a new project」非常相似——同样需要 project.yaml、Dockerfile、build.sh 和 fuzz target 这几类文件。区别在于关键实现细节:
- JavaScript 项目的模糊测试由 Jazzer.js 驱动,它会在构建阶段(
build.sh执行时)自动安装; - Jazzer.js 直接作用于 JavaScript 源码层进行插桩与覆盖率反馈,因此不仅限于纯 JavaScript,任何能够被转译成 JavaScript 的语言(最典型的就是 TypeScript)都可以接入;
- 由于在源码层工作,JavaScript fuzz target 的形态与 C/C++ 的
LLVMFuzzerTestOneInput完全不同,而是导出名为fuzz的 JavaScript 函数。
示例项目与文件结构
仓库中提供了两个可直接参考的示例项目:
- projects/javascript-example:最简单的纯 JavaScript fuzzing 项目,包含
Dockerfile、project.yaml、package.json、build.sh以及三个 fuzz target(fuzz_string_compare.js、fuzz_promise.js、fuzz_value_profiling.js),覆盖字符串比较、异步 Promise、二进制整数解析三类典型场景; - projects/typescript-example:展示如何 fuzz TypeScript 项目,包含
tsconfig.json、业务代码target.ts与 fuzz target fuzz_explore_me.ts,同时演示了 Jazzer.jsFuzzedDataProvider的用法。
两个示例项目的 Dockerfile 中有一条重要注释:推荐把 fuzz test 直接配置在项目自身的仓库中,并让它以 Jazzer.js 回归模式(regression mode)作为单元测试的一部分运行。这样 fuzz target 会随源代码变更持续保持同步,避免代码改动后 fuzz test 失效。
project.yaml:语言、引擎与 sanitizer 配置
JavaScript 项目的 project.yaml 中最关键的字段配置如下(完整示例见 projects/javascript-example/project.yaml):
language: javascript
除此之外,还需要注意三个约束:
- 仅支持 libFuzzer 引擎。目前
fuzzing_engines只支持libfuzzer:fuzzing_engines: - libfuzzer - 原生 sanitizer(ASan / UBSan)暂不支持。AddressSanitizer(
address)与 UndefinedBehaviorSanitizer(undefined)仅对带有原生 addon 的项目有意义,而这在 JavaScript 项目中属于较少见的使用场景。因此:sanitizers: - nonenone是 JavaScript 项目的默认 sanitizer,这一项在project.yaml中甚至可以不写。如果你的项目确实需要 ASan 或 UBSan,官方建议在 Jazzer.js 仓库提交 issue 说明需求。 - 可选字段
vendor_ccs。仓库示例中列出了维护者的邮箱列表(yakdan@code-intelligence.com等),用于指定收到崩溃报告通知的维护者,可按需配置。
Dockerfile:基于 JavaScript 专用基础镜像
JavaScript 项目的 Dockerfile 必须以专用基础镜像开头:
FROM gcr.io/oss-fuzz-base/base-builder-javascript
该基础镜像已预装 Node.js 19 与 npm。在此之外,通常只需要做常规操作:克隆项目源码、设置 WORKDIR、拷贝必要文件、安装项目特定依赖。以 projects/javascript-example/Dockerfile 为例:
FROM gcr.io/oss-fuzz-base/base-builder-javascript
COPY build.sh $SRC/
# 真实项目中,下一步通常是克隆你的仓库。
RUN mkdir -p $SRC/example
# 将 fuzz test 与 package.json 拷贝进示例项目目录。
COPY fuzz_string_compare.js fuzz_promise.js fuzz_value_profiling.js package.json $SRC/example/
WORKDIR $SRC/example
注意 package.json 是必须的(示例中只需声明项目名与版本即可,见 projects/javascript-example/package.json),npm install 依赖它工作。
编写 Fuzz Target:从 Buffer 到 fuzz 函数
在最简单的情况下,每个 fuzzer 就是一个导出 fuzz 函数的 JavaScript 文件,该函数接收一个类型为 Buffer 为例:
/**
* @param { Buffer } data
*/
module.exports.fuzz = function (data) {
const s = data.toString();
if (s.length !== 16) {
return;
}
if (
s.slice(0, 8) === "Awesome " &&
s.slice(8, 15) === "Fuzzing" &&
s[15] === "!"
) {
throw Error("Welcome to Awesome Fuzzing!");
}
};
这个 target 的工作逻辑非常直观:把原始字节 data 转为字符串后,依次比对三段内容;当输入恰好为 "Awesome Fuzzing!" 时抛出异常。在 Jazzer.js 中,fuzz 函数内抛出的任何异常/错误都会被视为一次崩溃(finding),OSS-Fuzz 会记录触发它的输入用于回归测试。
javascript-example 还展示了两种更有实战价值的写法:
- 异步场景(fuzz_promise.js):fuzz 函数返回
Promise,内部通过setTimeout模拟异步任务,用data.readInt8(0/1/2)读取前三个字节,当one + two + three === 42时reject抛错,并在.then中校验调用顺序——演示了如何处理真实项目中常见的回调与 Promise 逻辑; - 二进制解析场景(fuzz_value_profiling.js):直接基于
Buffer用data.readInt32BE(0/4/8/12)读取四个大端序 32 位整数,配合data.length < 16的提前返回守卫,适合 fuzz 协议解析类代码。
build.sh 与 compile_javascript_fuzzer:构建的幕后机制
build.sh 的职责分三步:安装项目依赖 → (必要时)把代码编译成 JavaScript → 调用预装的 compile_javascript_fuzzer 脚本构建 fuzzer。以 projects/javascript-example/build.sh 为例:
#!/bin/bash -eu
# 安装依赖。
npm install
# 安装 Jazzer.js。
npm install --save-dev @jazzer.js/core
# 构建 Fuzzer。
compile_javascript_fuzzer example fuzz_promise.js
compile_javascript_fuzzer example fuzz_string_compare.js --sync
compile_javascript_fuzzer example fuzz_value_profiling.js --sync
compile_javascript_fuzzer 的调用参数依次为:
- 项目在
$SRC目录下的相对路径(如example); - 项目内 fuzz test 的相对路径(如
fuzz_string_compare.js); - 其余参数原样转发给 Jazzer.js CLI(例如
--sync表示以同步模式执行 target;fuzz_promise.js未加该参数,因为它本身是异步的)。
从源码看,compile_javascript_fuzzer 脚本内部做了三件关键的事(对应 脚本第 18-35 行):
- 确保
@jazzer.js/core已安装,并将其源码连同项目一起复制到$OUT/$project目录; - 生成一个 fuzzer 执行包装脚本:脚本先用
basename -s .js去掉.js后缀得到 fuzzer 名称,随后写出一个 bash wrapper,其核心行为是把所有参数转发给$project_dir/node_modules/@jazzer.js/core/dist/cli.js,同时把环境变量$JAZZERJS_EXTRA_ARGS和--之后的所有参数一并透传(第 29-35 行); chmod +x赋予执行权限。
这里有一个值得注意的设计:生成的 wrapper 脚本内部包含 # LLVMFuzzerTestOneInput 注释行,其作用是让 OSS-Fuzz 的 check_build 校验逻辑能把这个脚本识别为合法的 fuzz target。也就是说,wrapper 是 libFuzzer 的 drop-in 替换品——它接受与 libFuzzer 完全相同的命令行 flags(如 -runs、-max_len 等),这些 flags 最终被转发给 Jazzer.js 使用的 libFuzzer 原生 addon。因此,JavaScript 项目的 fuzz 二进制在运行方式上与 C/C++ 项目保持一致,OSS-Fuzz 的基础设施无需为语言差异做额外适配。
FuzzedDataProvider:从原始字节到结构化数据
直接手写 Buffer 解析(如 readInt32BE + toString)虽然可行,但相当繁琐。为此 Jazzer.js 提供了 FuzzedDataProvider:它把 fuzzer 传入的原始输入字节翻译成实用的 JavaScript 基本类型,功能与其他语言的 FuzzedDataProvider(如 Java、C++ 版本)类似。原文档给出的基础用法如下:
const { FuzzedDataProvider } = require("@jazzer.js/core");
/**
* @param { Buffer } fuzzerInputData
*/
module.exports.fuzz = function (fuzzerInputData) {
const data = new FuzzedDataProvider(fuzzerInputData);
const i = data.consumeIntegral(4);
const s = data.consumeRemainingAsString();
exploreMe(i, s);
};
consumeIntegral(4):从输入中消费一个 4 字节(32 位)整数;consumeRemainingAsString():把剩余输入全部消费为字符串。
TypeScript 示例 fuzz_explore_me.ts 展示了同样的模式在 TypeScript 中的写法,并且参数个数更多,直接对接业务函数 exploreMe(定义于 target.ts):
import { FuzzedDataProvider } from "@jazzer.js/core"
import { exploreMe } from "./target";
export function fuzz(data: Buffer) {
const fdp = new FuzzedDataProvider(data)
exploreMe(
fdp.consumeIntegral(4),
fdp.consumeIntegral(4),
fdp.consumeRemainingAsString()
)
}
TypeScript 项目在 build.sh 中需要先用 tsc(或其他工具链)把 .ts 编译为 .js,再调用 compile_javascript_fuzzer 构建,这也是本文开头所说「任何可转译为 JavaScript 的语言均可接入」的具体落地方式。
本地验证与运行建议
在提交到 OSS-Fuzz 之前,可以先在本地做两件事验证 fuzz target 的正确性:
- 在项目目录执行
npm install --save-dev @jazzer.js/core,然后以回归模式直接运行 fuzz test(把已知的崩溃输入作为参数传入),确认 target 能正常抛错、可被 Jazzer.js CLI 执行——这也是官方推荐把 fuzz test 纳入单元测试的原因; - 构建出的 wrapper 脚本可当作普通 fuzzer 二进制直接运行,传入与 libFuzzer 一致的命令行参数即可启动模糊测试循环。
整体而言,OSS-Fuzz 对 JavaScript 项目的支持已经相当「开箱即用」:专用基础镜像自带 Node.js 与 npm,compile_javascript_fuzzer 封装了 @jazzer.js/core 的安装与 wrapper 生成,开发者只需把精力集中在 fuzz target 的编写质量上——而 FuzzedDataProvider 正是提升 target 效率与可读性的关键工具。