OSS-Fuzz JavaScript 项目接入实战:基于 Jazzer.js 编写 Fuzz Target 与构建配置

原创2026-09-23 10:10:221,901 阅读
文章标签:网络安全开发工具CI/CD

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.js FuzzedDataProvider 的用法。

两个示例项目的 Dockerfile 中有一条重要注释:推荐把 fuzz test 直接配置在项目自身的仓库中,并让它以 Jazzer.js 回归模式(regression mode)作为单元测试的一部分运行。这样 fuzz target 会随源代码变更持续保持同步,避免代码改动后 fuzz test 失效。

project.yaml:语言、引擎与 sanitizer 配置

JavaScript 项目的 project.yaml 中最关键的字段配置如下(完整示例见 projects/javascript-example/project.yaml):

language: javascript

除此之外,还需要注意三个约束:

  1. 仅支持 libFuzzer 引擎。目前 fuzzing_engines 只支持 libfuzzer:
    fuzzing_engines:
      - libfuzzer
    
  2. 原生 sanitizer(ASan / UBSan)暂不支持。AddressSanitizer(address)与 UndefinedBehaviorSanitizer(undefined)仅对带有原生 addon 的项目有意义,而这在 JavaScript 项目中属于较少见的使用场景。因此:
    sanitizers:
      - none
    
    none 是 JavaScript 项目的默认 sanitizer,这一项在 project.yaml 中甚至可以不写。如果你的项目确实需要 ASan 或 UBSan,官方建议在 Jazzer.js 仓库提交 issue 说明需求。
  3. 可选字段 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 的调用参数依次为:

  1. 项目在 $SRC 目录下的相对路径(如 example);
  2. 项目内 fuzz test 的相对路径(如 fuzz_string_compare.js);
  3. 其余参数原样转发给 Jazzer.js CLI(例如 --sync 表示以同步模式执行 target;fuzz_promise.js 未加该参数,因为它本身是异步的)。

从源码看,compile_javascript_fuzzer 脚本内部做了三件关键的事(对应 脚本第 18-35 行):

  1. 确保 @jazzer.js/core 已安装,并将其源码连同项目一起复制到 $OUT/$project 目录;
  2. 生成一个 fuzzer 执行包装脚本:脚本先用 basename -s .js 去掉 .js 后缀得到 fuzzer 名称,随后写出一个 bash wrapper,其核心行为是把所有参数转发给 $project_dir/node_modules/@jazzer.js/core/dist/cli.js,同时把环境变量 $JAZZERJS_EXTRA_ARGS 和 -- 之后的所有参数一并透传(第 29-35 行);
  3. 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 的正确性:

  1. 在项目目录执行 npm install --save-dev @jazzer.js/core,然后以回归模式直接运行 fuzz test(把已知的崩溃输入作为参数传入),确认 target 能正常抛错、可被 Jazzer.js CLI 执行——这也是官方推荐把 fuzz test 纳入单元测试的原因;
  2. 构建出的 wrapper 脚本可当作普通 fuzzer 二进制直接运行,传入与 libFuzzer 一致的命令行参数即可启动模糊测试循环。

整体而言,OSS-Fuzz 对 JavaScript 项目的支持已经相当「开箱即用」:专用基础镜像自带 Node.js 与 npm,compile_javascript_fuzzer 封装了 @jazzer.js/core 的安装与 wrapper 生成,开发者只需把精力集中在 fuzz target 的编写质量上——而 FuzzedDataProvider 正是提升 target 效率与可读性的关键工具。

登录后查看全文
oss-fuzz