OSS-Fuzz 接入 JavaScript / Node.js 项目实战指南:从 project.yaml 到 Jazzer.js Fuzz Target 的完整落地

原创2026-09-22 18:28:022,343 阅读
文章标签:测试质量保障应用安全网络安全CI/CDDevOps容器编排

OSS-Fuzz 接入 JavaScript / Node.js 项目实战指南:从 project.yaml 到 Jazzer.js Fuzz Target 的完整落地

本文以 OSS-Fuzz 官方文档 docs/getting-started/new-project-guide/javascript_lang.md 为主线,系统讲解如何在 OSS-Fuzz 中为 JavaScript(Node.js)及可转译为 JavaScript 的项目(如 TypeScript)搭建持续模糊测试(fuzzing)工程。你将掌握 project.yaml、Dockerfile、build.sh、fuzz target 编写与 FuzzedDataProvider 使用的完整流程,并了解 Jazzer.js 在底层如何驱动 libFuzzer 执行模糊测试。读完即可参照 projects/javascript-example 与 projects/typescript-example 两个官方示例项目,把自有 JS 项目接入 OSS-Fuzz。

JavaScript 项目接入 OSS-Fuzz 的整体流程

将 JavaScript(Node.js)项目集成进 OSS-Fuzz 的过程,与通用的 Setting up a new project 流程高度相似:同样需要提供 project.yaml(项目元数据)、Dockerfile(构建环境)、build.sh(构建脚本)以及若干 fuzz target(模糊测试入口)。JavaScript 项目的关键差异集中体现在三处:

  1. 语言与引擎选择:language 必须声明为 javascript,fuzzing engine 仅支持 libFuzzer,sanitizer 使用 none;
  2. 基础镜像:Dockerfile 以 gcr.io/oss-fuzz-base/base-builder-javascript 为起点,镜像内预装 Node.js 与 npm;
  3. 模糊测试引擎:JS 模糊测试由 Jazzer.js 驱动,它工作在 JavaScript 源码层面,因此对任何可转译为 JavaScript 的语言(如 TypeScript)都适用。

下文将按照 "环境 → 配置 → 编写 fuzz target → 构建 → 数据提供器" 的顺序逐步展开。

Jazzer.js:JavaScript 模糊测试引擎

OSS-Fuzz 中的 JavaScript 模糊测试由 Jazzer.js 提供能力,该引擎在构建阶段由基础镜像自动安装。

与基于 JVM 的 Jazzer(Java)不同,Jazzer.js 直接作用于 JavaScript 源码层面(source-code level),这意味着:

  • 它不需要把被测代码编译成特殊格式,普通 Node.js 模块即可被 fuzz;
  • 任何能转译为 JavaScript 的语言(典型如 TypeScript)都能复用同一套 fuzz 流程;
  • fuzz target 以普通 Node.js 模块形式存在,导出名为 fuzz 的函数即可,fuzz target 的具体形态可参考 Jazzer.js 官方的 Usage 文档。

Jazzer.js 在底层依赖 libFuzzer 的 native addon 完成覆盖率引导(coverage-guided)的变异与反馈,同时负责将命令行参数转发给该 addon——这正是 compile_javascript_fuzzer 生成的包装脚本能"无缝替换 libFuzzer"的原因(详见下文 build.sh 一节)。

官方示例项目:从零理解文件组织

仓库内提供了两个可直接对照学习的示例项目:

示例 路径 说明
JavaScript 示例 projects/javascript-example 最简单的 JS 模糊测试工程,包含 3 个 fuzz target 与完整构建脚本
TypeScript 示例 projects/typescript-example 展示 TS 项目的接入方式,并演示了 FuzzedDataProvider 的用法

javascript-example 的完整文件清单如下:

  • project.yaml:项目元数据(语言、引擎、sanitizer);
  • Dockerfile:基于 base-builder-javascript 镜像,把 fuzz target 拷贝进 $SRC/example;
  • package.json:npm 依赖描述;
  • fuzz_string_compare.js、fuzz_promise.js、fuzz_value_profiling.js:三个不同风格的 fuzz target;
  • build.sh:依赖安装与 fuzzer 构建脚本。

typescript-example 则额外包含 tsconfig.json、target.ts 与 fuzz_explore_me.ts,展示 TypeScript 源码经编译后进入 fuzz 流程的标准做法。

project.yaml:语言、引擎与 Sanitizer 声明

JavaScript 项目的 project.yaml 中,language 属性必须声明为:

language: javascript

引擎与 sanitizer 的约束如下:

  • fuzzing engine 仅支持 libFuzzer(libfuzzer),目前没有其他可选项;
  • 原生 sanitizer(如 AddressSanitizer address、UndefinedBehaviorSanitizer undefined)暂不支持。这类 sanitizer 只在项目包含原生插件(native addons)时才需要,而这对 JavaScript 项目来说属于较少见的情况。如果你确实需要 ASan 或 UBSan,官方建议在 Jazzer.js 仓库提交 issue 提出需求;
  • none 是 JavaScript 项目的默认 sanitizer,因此在 project.yaml 中显式书写是可选的,但建议显式声明以增强可读性。

一个完整的 project.yaml 配置如下(取自 projects/javascript-example/project.yaml,typescript-example 与之相同):

homepage: https://github.com/CodeIntelligenceTesting/jazzer.js
language: javascript
main_repo: https://github.com/CodeIntelligenceTesting/jazzer.js
fuzzing_engines:
- libfuzzer
sanitizers:
- none
vendor_ccs:
- yakdan@code-intelligence.com
- norbert.schneider@code-intelligence.com
- peter.samarin@code-intelligence.com

其中 vendor_ccs 用于声明该项目模糊测试的维护联系人(本项目为 Jazzer.js 团队),实际接入你自己的项目时,应替换为对应的维护者邮箱。

Dockerfile:基于 base-builder-javascript 搭建构建环境

JavaScript 项目的 Dockerfile 必须以基础镜像开头:

FROM gcr.io/oss-fuzz-base/base-builder-javascript

该 OSS-Fuzz 基础镜像已预装 Node.js 19 与 npm,因此通常无需再安装 Node 运行时。镜像内还预装了 compile_javascript_fuzzer 构建脚本(详见下文)。Dockerfile 中通常只需要:

  1. 克隆目标项目源码(或像示例那样把 fuzz target 直接拷贝进镜像);
  2. 设置 WORKDIR;
  3. 按需安装项目特定依赖、拷贝必要文件。

以 projects/javascript-example/Dockerfile 为模板:

FROM gcr.io/oss-fuzz-base/base-builder-javascript

COPY build.sh $SRC/

# For real projects, you would clone your repo in the next step.
RUN mkdir -p $SRC/example

# Ideally, you have already configured fuzz tests in your repo so that they
# run (in Jazzer.js regression mode) as part of unit testing. Keeping the fuzz
# tests in sync with the source code ensures that they are adjusted continue
# to work after code changes. Here, we copy them into the example project directory.
COPY fuzz_string_compare.js fuzz_promise.js fuzz_value_profiling.js package.json $SRC/example/

WORKDIR $SRC/example

注意示例注释中强调的最佳实践:建议把 fuzz test 与源码放在同一仓库中,并让它们在单元测试阶段以 Jazzer.js 回归模式(regression mode)运行,这样当源码变更导致 fuzz target 失效时能被及时发现,保持 fuzz 测试与代码同步演进。

Fuzz Target:最简单的形态是导出一个 fuzz 函数

在最简单的情况下,每个 fuzzer 就是一个导出了名为 fuzz 的函数的单个 JavaScript 文件,该函数接收一个参数,类型为 Node.js 的 Buffer。

以下是一个名为 fuzz_string_compare.js 的示例 fuzz target(与 projects/javascript-example/fuzz_string_compare.js 内容一致):

/**
 * @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 演示了模糊测试的核心机制:fuzzer 不断生成随机输入并调用 fuzz(data),一旦输入恰好满足 s === "Awesome Fuzzing!" 这一串条件,代码就会抛出 Error。Jazzer.js 基于 libFuzzer 的覆盖率反馈会逐步引导变异方向,最终"发现"这条路径,从而触发一个可被报告的崩溃(crash)。

异步 fuzz target:基于 Promise 的写法

JavaScript 生态大量使用异步 API,因此 fuzz target 也可以返回 Promise。示例 projects/javascript-example/fuzz_promise.js 展示了这一点:它在 setTimeout 回调中读取三个字节,若满足 one + two + three === 42 则 reject 一个 Error,并额外校验了异步调用的执行顺序:

let lastInvocationCount = 0;
let invocationCount = lastInvocationCount + 1;

/**
 * @param { Buffer } data
 */
module.exports.fuzz = function (data) {
	return new Promise((resolve, reject) => {
		if (data.length < 3) {
			resolve(invocationCount++);
			return;
		}
		setTimeout(() => {
			let one = data.readInt8(0);
			let two = data.readInt8(1);
			let three = data.readInt8(2);
			if (one + two + three === 42) {
				reject(
					new Error(
						`${one} + ${two} + ${three} = 42 (invocation ${invocationCount})`
					)
				);
			} else {
				resolve(invocationCount++);
			}
		}, 10);
	}).then((value) => {
		if (value !== lastInvocationCount + 1) {
			throw new Error(
				`Invalid invocation order, received ${value} but last invocation was ${lastInvocationCount}.`
			);
		}
		lastInvocationCount = value;
	});
};

使用 Buffer 原生方法的数值解析 target

projects/javascript-example/fuzz_value_profiling.js 展示了直接用 data.readInt32BE() 从 Buffer 中读取大端 32 位整数,并对结果做 XOR 校验后抛错的模式:

/**
 * @param {number} n
 */
function encrypt(n) {
	return n ^ 0x11223344;
}

/**
 * @param { Buffer } data
 */
module.exports.fuzz = function (data) {
	if (data.length < 16) {
		return;
	}
	if (
		encrypt(data.readInt32BE(0)) === 0x50555637 &&
		encrypt(data.readInt32BE(4)) === 0x7e4f5664 &&
		encrypt(data.readInt32BE(8)) === 0x5757493e &&
		encrypt(data.readInt32BE(12)) === 0x784c5465
	) {
		throw Error("XOR with a constant is not a secure encryption method ;-)");
	}
};

该 target 还带有 --sync 构建参数的使用场景(同步模式,详见下文 build.sh)。

build.sh:借助 compile_javascript_fuzzer 一键构建

OSS-Fuzz 的 JavaScript 基础镜像预装了 compile_javascript_fuzzer 脚本。在 build.sh 中,你需要:

  1. 安装项目依赖;
  2. 如有必要,把 TypeScript 等语言编译为 JavaScript;
  3. 调用 compile_javascript_fuzzer 构建各个 fuzzer。

compile_javascript_fuzzer 脚本承担两项关键职责:

  • 确保 @jazzer.js/core 已安装,从而可以使用其 CLI 执行 fuzz 测试;
  • 生成一个 libFuzzer 的"即插即用"包装脚本——生成的脚本接受与 libFuzzer 相同的命令行参数,底层只是把这些参数转发给 Jazzer.js 所用的 libFuzzer native addon。

以 javascript-example 的 projects/javascript-example/build.sh 为例:

#!/bin/bash -eu

# Install dependencies.
npm install

# Install Jazzer.js
npm install --save-dev @jazzer.js/core

# Build Fuzzers.
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)
其余参数 原样转发给 Jazzer.js CLI(如 --sync 表示同步模式执行)

--sync 标志指示 Jazzer.js 以同步方式执行 fuzz target,适用于不依赖异步操作的简单 target;对于返回 Promise 的异步 target(如 fuzz_promise.js),则不加该标志,让 Jazzer.js 处理异步完成。构建完成后,OSS-Fuzz 的回归(regression)与持续模糊测试阶段会直接运行这些生成的 libFuzzer 包装脚本。

FuzzedDataProvider:把原始字节翻译成 JS 原生类型

Jazzer.js 提供了 FuzzedDataProvider,它的作用是把 fuzzer 输入的原始字节流翻译成便于使用的 JavaScript 原始类型,从而显著简化 fuzz target 的编写。其功能与 Java、C++ 等其他语言中的 FuzzedDataProvider 类似(C++ 侧的通用思路可参考 Google 的 split-inputs 文档)。

使用 FuzzedDataProvider 的 fuzz target 写法如下:

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);
};

代码要点:

  • 从 @jazzer.js/core 中解构引入 FuzzedDataProvider;
  • 用 fuzzer 传入的 Buffer 构造 provider 实例;
  • consumeIntegral(4) 从输入中消费一个 4 字节整数;
  • consumeRemainingAsString() 把剩余输入整体消费为字符串;
  • 随后用这两个"有意义"的值调用被测函数 exploreMe(i, s)。

这正是 projects/typescript-example 中 fuzz_explore_me.ts 所演示的模式:TypeScript 项目把 fuzz target 写成 .ts 文件,构建时编译为 JavaScript 后同样通过 compile_javascript_fuzzer 构建。该示例也证明了所有可转译为 JavaScript 的语言都能无缝复用这套 fuzz 流程。

实战自查清单

完成 JavaScript 项目接入后,可用以下清单快速自查:

  1. project.yaml 中 language: javascript、fuzzing_engines: [libfuzzer]、sanitizers: [none] 是否齐全;
  2. Dockerfile 是否以 FROM gcr.io/oss-fuzz-base/base-builder-javascript 开头;
  3. fuzz target 是否导出了 module.exports.fuzz = function (data) { ... },且参数类型为 Buffer;
  4. build.sh 是否依次完成 npm install、安装 @jazzer.js/core、调用 compile_javascript_fuzzer;
  5. 是否按 target 的同步/异步特性正确使用 --sync 标志;
  6. 复杂输入解析是否优先考虑 FuzzedDataProvider(consumeIntegral、consumeRemainingAsString 等)以提升命中率。

将上述文件放入 projects/<your-project>/ 目录并提交后,即可按 OSS-Fuzz 的通用项目提交流程申请接入,由 OSS-Fuzz 基础设施持续运行模糊测试并报告崩溃。

登录后查看全文
oss-fuzz