OSS-Fuzz Java/JVM 项目接入指南:基于 Jazzer 的 fuzz target 编写与构建
OSS-Fuzz Java/JVM 项目接入指南:基于 Jazzer 的 fuzz target 编写与构建
OSS-Fuzz 对 Java 及任何运行在 JVM 上的语言(Kotlin、Scala、Groovy 等)提供了一套与 C/C++ 项目略有不同的接入流程,其核心引擎是运行在字节码层面的模糊测试工具 Jazzer。阅读本文后,你将掌握 JVM 项目接入 OSS-Fuzz 所需的完整配置方法:从 project.yaml 的 language: jvm 声明、基于 base-builder-jvm 镜像的 Dockerfile 编写、build.sh 中 Jazzer 驱动包装脚本的生成逻辑,到使用 FuzzedDataProvider 编写健壮 fuzz target 的实战技巧。
概述:JVM 项目接入 OSS-Fuzz 的整体流程
将 Java 或其他 JVM 语言项目接入 OSS-Fuzz 的整体过程,与通用的新项目接入指南基本一致,核心差异集中在语言声明、基础镜像、构建脚本与 fuzz target 的组织方式上。接入一个 JVM 项目通常需要以下文件:
project.yaml:声明项目元信息,其中language必须为jvm;Dockerfile:基于gcr.io/oss-fuzz-base/base-builder-jvm构建环境并拉取项目源码;build.sh:编译项目、打包 jar、编译所有 fuzz target,并为每个 target 生成可执行包装脚本;- 若干个
*Fuzzer.java文件:每个文件即一个 fuzz target,实现fuzzerTestOneInput入口。
仓库中提供了两个可直接参考的完整示例:json-sanitizer(纯 Java 项目)与 java-example(含原生依赖的 Java 项目),下文将结合这两个示例的源码逐项说明。
Jazzer:JVM 模糊测试的核心引擎
Java 模糊测试在 OSS-Fuzz 中完全依赖 Jazzer,它已预装在 OSS-Fuzz 的基础 Docker 镜像中,无需在 Dockerfile 中额外安装。Jazzer 直接作用于字节码层面(bytecode level),因此可以应用于任何基于 JVM 的语言所编写的项目,而无需关心该项目源代码的语言形态。
从仓库中 base-builder-jvm 的 Dockerfile 可以看到,镜像构建阶段会克隆 Jazzer 源码并以固定版本(0.26.0 对应的 commit 86378b7a20f08165e72a45582d6a9a5091212318)通过 Bazel 编译,产物包括:
jazzer_agent_deploy.jar(字节码插桩 agent),安装到/usr/local/bin/jazzer_agent_deploy.jar;jazzer_driver(启动驱动),安装到/usr/local/bin/jazzer_driver;jazzer_api_deploy.jar(fuzz target 编译期 API),通过环境变量JAZZER_API_PATH暴露,值为/usr/local/lib/jazzer_api_deploy.jar;jazzer_junit.jar(JUnit 集成),通过环境变量JAZZER_JUNIT_PATH暴露,值为/usr/local/bin/jazzer_junit.jar。
由于 Jazzer 的 fuzz target 入口签名与 libFuzzer 的 LLVMFuzzerTestOneInput 在概念上一致(驱动在注释中标记 # LLVMFuzzerTestOneInput for fuzzer detection. 以便 OSS-Fuzz 自动识别),因此 JVM 项目默认即与 libFuzzer 引擎配合使用。
项目文件组织
参考示例项目
官方推荐以 json-sanitizer 作为纯 Java 项目的接入范例。该目录包含 project.yaml、Dockerfile、build.sh 以及三个 fuzz target(ValidJsonFuzzer.java、IdempotenceFuzzer.java、DenylistFuzzer.java),结构简洁,适合作为模板。
对于带原生(native)依赖的 Java 项目,java-example 提供了更完整的参考,其目录结构如下:
projects/java-example/
├── Dockerfile
├── ExampleFuzzTest.java
├── ExampleFuzzer.java
├── ExampleFuzzerNative.cpp
├── ExampleFuzzerNative.h
├── ExampleFuzzerNative.java
├── ExampleValueProfileFuzzer.java
├── MutatorFuzzTest.java
├── default.options
└── project.yaml
其中 ExampleFuzzerNative.java 通过 System.loadLibrary("native") 加载由 ExampleFuzzerNative.cpp 编译出的共享库,展示了 JNI 场景下如何同时构建 Java 与 C++ 代码并链接进 fuzz target。
project.yaml
JVM 项目的 project.yaml 与 C/C++ 项目的主要区别在于 language 字段必须指定为 jvm:
language: jvm
目前唯一受支持的 fuzzing engine 是 libFuzzer(libfuzzer),受支持的 sanitizer 只有 AddressSanitizer(address)与 UndefinedBehaviorSanitizer(undefined)两种。对于纯 Java 项目,通常只需指定 address:
fuzzing_engines:
- libfuzzer
sanitizers:
- address
以仓库中的 json-sanitizer/project.yaml 为证,其配置即为此形态;而 java-example/project.yaml 由于包含原生 C++ 代码(涉及不受 JVM 内存管理约束的本地内存访问),同时启用了 address 与 undefined 两种 sanitizer。该示例还展示了 base_os_version: ubuntu-24-04 与 disabled: true(示例项目不参与日常调度)等可选字段的写法,以及 vendor_ccs(供应商联系人,用于接收构建问题通知)的配置方式。
Dockerfile
JVM 项目的 Dockerfile 必须从基础镜像 gcr.io/oss-fuzz-base/base-builder-jvm 开始构建:
FROM gcr.io/oss-fuzz-base/base-builder-jvm
从 base-builder-jvm 的 Dockerfile 可以看到,该镜像预装了 OpenJDK,并设置了以下关键环境变量:
| 环境变量 | 值 | 用途 |
|---|---|---|
JAVA_HOME |
/usr/lib/jvm/java-17-openjdk-amd64 |
Java 主版本路径 |
JAVA_15_HOME |
/usr/lib/jvm/java-15-openjdk-amd64 |
兼容旧版构建脚本的 JDK 15 路径 |
JVM_LD_LIBRARY_PATH |
$JAVA_HOME/lib/server |
JVM 本地库路径(wrapper 脚本中 LD_LIBRARY_PATH 的组成部分) |
JAZZER_API_PATH |
/usr/local/lib/jazzer_api_deploy.jar |
Jazzer API jar 路径 |
JAZZER_JUNIT_PATH |
/usr/local/bin/jazzer_junit.jar |
Jazzer JUnit 集成 jar 路径 |
如果项目使用 Maven 构建,需要在 Dockerfile 中显式安装:
RUN apt-get update && apt-get install -y maven
这一步在 json-sanitizer 的 Dockerfile 与 java-example 中均有体现。除此之外,Dockerfile 通常只需要克隆项目源码、设置 WORKDIR、复制必要的构建文件与 fuzz target 源文件,以及安装项目特有的依赖即可。json-sanitizer 的 Dockerfile 还展示了两个进阶技巧:拼接多个 fuzzing dictionaries 生成 .dict 文件,以及将公开语料打包为 *_seed_corpus.zip 种子语料库(例如从 go-fuzz-corpus 的 JSON 语料生成),这些产物会被 build.sh 移入 $OUT 供运行时使用。
Fuzz target 的编写规范
在最简单的情况下,每个 fuzzer 就是一个单独的 Java 文件:文件名以 *Fuzzer.java 结尾,且不含 package 声明(这样类名即文件名,便于 Jazzer 通过 --target_class 定位)。最简单的 fuzz target 形如:
public class ExampleFuzzer {
public static void fuzzerTestOneInput(byte[] input) {
...
// Call a function of the project under test with arguments derived from
// input and throw an exception if something unwanted happens.
...
}
}
fuzzerTestOneInput 接收原始字节数组,测试逻辑将字节数组转换为项目 API 的参数并调用被测函数,一旦发现异常行为(例如断言失败、抛出 IllegalStateException、FuzzerSecurityIssueLow 等),即视为发现缺陷并上报。
仓库中的真实示例 ExampleFuzzer.java 还展示了可选入口 fuzzerInitialize()——它在首次调用 fuzzerTestOneInput 之前执行一次,适合放置一次性初始化逻辑。
值得指出的是,JVM 项目的 fuzz target 并不局限于单一入口:*FuzzTest.java 结尾的类可作为 JUnit 风格的 fuzz test(见 ExampleFuzzTest.java),java-example 的 build.sh 中有对应的编译与包装逻辑。
build.sh:JVM 项目的关键差异点
对于 JVM 项目,build.sh 相对 C/C++ 项目需要更多针对性改动。下面是一个针对"纯 Java 项目 + 单文件 fuzz target"的带注释示例(与 json-sanitizer/build.sh 及 java-example/build.sh 的骨架一致):
# Step 1: Build the project
# Build the project .jar as usual, e.g. using Maven.
mvn package
# In this example, the project is built with Maven, which typically includes the
# project version into the name of the packaged .jar file. The version can be
# obtained as follows:
CURRENT_VERSION=$(mvn org.apache.maven.plugins:maven-help-plugin:3.2.0:evaluate \
-Dexpression=project.version -q -DforceStdout)
# Copy the project .jar into $OUT under a fixed name.
cp "target/sample-project-$CURRENT_VERSION.jar" $OUT/sample-project.jar
# Specify the projects .jar file(s), separated by spaces if there are multiple.
PROJECT_JARS="sample-project.jar"
# Step 2: Build the fuzzers (should not require any changes)
# The classpath at build-time includes the project jars in $OUT as well as the
# Jazzer API.
BUILD_CLASSPATH=$(echo $PROJECT_JARS | xargs printf -- "$OUT/%s:"):$JAZZER_API_PATH
# All .jar and .class files lie in the same directory as the fuzzer at runtime.
RUNTIME_CLASSPATH=$(echo $PROJECT_JARS | xargs printf -- "\$this_dir/%s:"):\$this_dir
for fuzzer in $(find $SRC -name '*Fuzzer.java'); do
fuzzer_basename=$(basename -s .java $fuzzer)
javac -cp $BUILD_CLASSPATH $fuzzer
cp $SRC/$fuzzer_basename.class $OUT/
# Create an execution wrapper that executes Jazzer with the correct arguments.
echo "#!/bin/bash
# LLVMFuzzerTestOneInput for fuzzer detection.
this_dir=\$(dirname \"\$0\")
if [[ \"\$@\" =~ (^| )-runs=[0-9]+($| ) ]]; then
mem_settings='-Xmx1900m:-Xss900k'
else
mem_settings='-Xmx2048m:-Xss1024k'
fi
LD_LIBRARY_PATH=\"$JVM_LD_LIBRARY_PATH\":\$this_dir \
\$this_dir/jazzer_driver --agent_path=\$this_dir/jazzer_agent_deploy.jar \
--cp=$RUNTIME_CLASSPATH \
--target_class=$fuzzer_basename \
--jvm_args=\"\$mem_settings:-Djava.awt.headless=true\" \
\$@" > $OUT/$fuzzer_basename
chmod +x $OUT/$fuzzer_basename
done
该脚本的核心逻辑可以拆解为四步:
- 构建项目 jar:以
mvn package正常构建项目,并借助 Maven help 插件读取project.version,从而将带版本号的 jar 以固定名称复制到$OUT,避免后续 classpath 拼接时受版本号影响。 - 定义 classpath:
BUILD_CLASSPATH供javac编译 fuzz target 使用,包含$OUT下的项目 jar 与$JAZZER_API_PATH(Jazzer 的 API,如FuzzedDataProvider、FuzzerSecurityIssueLow);RUNTIME_CLASSPATH则指向运行时 fuzzer 所在目录$this_dir,因为 OSS-Fuzz 运行时所有 jar 与 class 文件与可执行文件位于同一目录。 - 编译 fuzz target:遍历
$SRC下所有*Fuzzer.java,用javac编译并把.class文件复制到$OUT。 - 生成执行包装脚本:脚本调用
jazzer_driver,传入--agent_path(字节码插桩 agent)、--cp(运行时 classpath)、--target_class(入口类名)与--jvm_args(JVM 参数)。
包装脚本中有两个值得注意的细节:
- 内存参数自适应:通过
-runs=N参数判断当前是否处于回归测试(reproduce/regression)模式——回归测试时使用-Xmx1900m:-Xss900k,常规模糊测试使用-Xmx2048m:-Xss1024k,避免在资源受限场景下 OOM; - 本地库链接:通过
LD_LIBRARY_PATH="$JVM_LD_LIBRARY_PATH":$this_dir将 JVM 自身本地库($JAVA_HOME/lib/server)与 fuzzer 目录一并加入链接路径,这是 JNI 场景(如 java-example)能够加载.so的关键。
带原生依赖的 build.sh 差异
对于含 native 代码的 Java 项目,java-example/build.sh 展示了额外的构建步骤:
# Build native library.
JVM_INCLUDES="-I$JAVA_HOME/include -I$JAVA_HOME/include/linux"
mkdir -p "$OUT"/native
$CXX $CXXFLAGS $JVM_INCLUDES -fPIC -shared \
ExampleFuzzerNative.cpp -o $OUT/native/libnative.so
即使用 $CXX $CXXFLAGS(OSS-Fuzz 提供的插桩编译器)将 C++ 源码编译为共享库放入 $OUT/native,并在 wrapper 脚本中通过 LD_LIBRARY_PATH=...:$this_dir/native 将其加入链接路径。同时该脚本还演示了如何通过 curl 从 Maven 仓库拉取 fuzz target 自身所需的第三方依赖(如 JUnit 相关 jar),并将其加入 BUILD_CLASSPATH。
此外,java-example 中针对 *FuzzerNative 类选择 jazzer_driver_with_sanitizer 驱动,并在 wrapper 中追加 ASAN_OPTIONS=...:detect_leaks=0,这是因为 sanitizer 已由 native 库的编译过程($CXXFLAGS)注入,运行驱动时需要显式指定相应的 sanitizer 驱动与选项。
FuzzedDataProvider:将字节流转换为结构化输入
Jazzer 提供了 FuzzedDataProvider 工具类,用于把 fuzzer 产生的原始输入字节翻译成 Java 的基本类型,显著简化 fuzz target 的编写。其功能与 Python(Atheris)及 C++ 生态中的 FuzzedDataProvider 类似。
在 OSS-Fuzz 环境下,该库位于基础镜像的 $JAZZER_API_PATH 路径(/usr/local/lib/jazzer_api_deploy.jar),示例 build.sh 已将其加入编译 classpath。本地开发时可以从 Maven Central 获取 com.code-intelligence:jazzer-api 工件。
使用 FuzzedDataProvider 的 fuzz target 形如:
import com.code_intelligence.jazzer.api.FuzzedDataProvider;
public class ExampleFuzzer {
public static void fuzzerTestOneInput(FuzzedDataProvider data) {
int number = data.consumeInt();
String string = data.consumeRemainingAsString();
// ...
}
}
FuzzedDataProvider 提供了一系列便捷方法:consumeInt()、consumeLong()、consumeBytes(n)、consumeString(n)、consumeRemainingAsString()、consumeBoolean() 等,可将输入字节按需切分为不同类型的参数。使用该 API 有两个显著收益:一是避免手写字节解析的样板代码,二是保证所有输入字节都被消费完,减少因截断输入而陷入死循环的几率。
仓库中 ExampleFuzzer.java 通过 data.consumeRemainingAsString() 获取完整字符串;ValidJsonFuzzer.java 则是一个教科书式的完整用例:先用 consumeRemainingAsString() 取输入并调用被测的 JsonSanitizer.sanitize,随后用 Gson 验证输出是否为合法 JSON,若非法则抛出 FuzzerSecurityIssueLow——这正是"以异常作为缺陷信号"的典型模式。
进阶:value profiling 与 fuzz test 形态
java-example 中的 ExampleValueProfileFuzzer.java 演示了一个进阶场景:当比较对象与输入字节之间不存在直接对应关系(例如先做 Base64 编码再比较,或对 long 做异或后再比较)时,普通覆盖率引导难以推进。此时需要为 fuzz target 配置 -use_value_profile=1(value profile 模式),使 fuzzer 能够逐步逼近被比较的常量值;配合 --fake_pcs 可以消除多个相同类型比较之间的混淆。这类参数通常通过 default.options 文件(见 java-example/default.options)或 wrapper 脚本参数传递给 Jazzer,实际启用与否由项目自身的 .options 文件控制。
此外,JVM 项目还支持 JUnit 风格的 fuzz test:以 *FuzzTest.java 命名的类可结合 Jazzer 的 JUnit 集成($JAZZER_JUNIT_PATH)运行,ExampleFuzzTest.java 与 MutatorFuzzTest.java 提供了参考实现,对应的编译与 wrapper 生成逻辑见 java-example/build.sh。
常见问题与调试建议
- 编译期找不到 Jazzer API:确认 build.sh 中
BUILD_CLASSPATH包含$JAZZER_API_PATH,该变量由base-builder-jvm镜像预设,不要自行硬编码路径以免与镜像版本脱节。 - 运行时类找不到:检查
RUNTIME_CLASSPATH是否覆盖了所有项目 jar 与依赖 jar,以及.class文件是否确实被复制到了$OUT(wrapper 中$this_dir指向运行时目录)。 - Maven 打包产物带版本号:使用
mvn org.apache.maven.plugins:maven-help-plugin:3.2.0:evaluate -Dexpression=project.version -q -DforceStdout动态读取版本,再以固定名称复制,避免 classpath 拼接失效。 - native 库无法加载:确保 wrapper 中
LD_LIBRARY_PATH同时包含$JVM_LD_LIBRARY_PATH与 native 库所在目录(如$this_dir/native)。 - 回归测试内存溢出:wrapper 已根据
-runs=N自动切换内存参数;若仍出现 OOM,可参照该模式为特定 fuzz target 定制 JVM 参数。
总结
接入一个 JVM 项目到 OSS-Fuzz,本质上是围绕 Jazzer 组织四类文件:以 language: jvm 声明 project.yaml、基于 base-builder-jvm 编写 Dockerfile、按"构建 jar → 编译 fuzz target → 生成 Jazzer wrapper"三段式编写 build.sh,并编写以 fuzzerTestOneInput 为入口的 *Fuzzer.java。在动手前,建议先通读 json-sanitizer(纯 Java)与 java-example(含 native 依赖)两个参考项目,再对照 JVM 接入指南逐步实现,即可快速完成从普通 Java 项目到 OSS-Fuzz 持续模糊测试项目的迁移。