OSS-Fuzz Java/JVM 项目接入指南:基于 Jazzer 的 fuzz target 编写与构建

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

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

该脚本的核心逻辑可以拆解为四步:

  1. 构建项目 jar:以 mvn package 正常构建项目,并借助 Maven help 插件读取 project.version,从而将带版本号的 jar 以固定名称复制到 $OUT,避免后续 classpath 拼接时受版本号影响。
  2. 定义 classpath:BUILD_CLASSPATH 供 javac 编译 fuzz target 使用,包含 $OUT 下的项目 jar 与 $JAZZER_API_PATH(Jazzer 的 API,如 FuzzedDataProvider、FuzzerSecurityIssueLow);RUNTIME_CLASSPATH 则指向运行时 fuzzer 所在目录 $this_dir,因为 OSS-Fuzz 运行时所有 jar 与 class 文件与可执行文件位于同一目录。
  3. 编译 fuzz target:遍历 $SRC 下所有 *Fuzzer.java,用 javac 编译并把 .class 文件复制到 $OUT。
  4. 生成执行包装脚本:脚本调用 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 持续模糊测试项目的迁移。

登录后查看全文
oss-fuzz