diff options
Diffstat (limited to 'docs/getting-started/new-project-guide/jvm_lang.md')
| -rw-r--r-- | docs/getting-started/new-project-guide/jvm_lang.md | 173 |
1 files changed, 173 insertions, 0 deletions
diff --git a/docs/getting-started/new-project-guide/jvm_lang.md b/docs/getting-started/new-project-guide/jvm_lang.md new file mode 100644 index 000000000..19e4ecbfe --- /dev/null +++ b/docs/getting-started/new-project-guide/jvm_lang.md @@ -0,0 +1,173 @@ +--- +layout: default +title: Integrating a Java/JVM project +parent: Setting up a new project +grand_parent: Getting started +nav_order: 4 +permalink: /getting-started/new-project-guide/jvm-lang/ +--- + +# Integrating a Java/JVM project +{: .no_toc} + +- TOC +{:toc} +--- + +The process of integrating a project written in Java or any other language +running on the Java Virtual Machine (JVM) with OSS-Fuzz is very similar to the +general +[Setting up a new project]({{ site.baseurl }}/getting-started/new-project-guide/) +process. The key specifics of integrating a JVM project are outlined below. + +## Jazzer + +Java fuzzing in OSS-Fuzz depends on +[Jazzer](https://github.com/CodeIntelligenceTesting/jazzer), which is +pre-installed on the OSS-Fuzz base docker images. As Jazzer operates directly +on the bytecode level, it can be applied to any project written in a JVM-based +language. More information on how Jazzer fuzz targets look like can be found in +its +[README's Usage section](https://github.com/CodeIntelligenceTesting/jazzer#usage). + +## Project files + +### Example project + +We recommend viewing +[json-sanitizer](https://github.com/google/oss-fuzz/tree/master/projects/json-sanitizer) +as an example of a simple Java-only fuzzing project. Additional examples, +including one for a Java project with native dependencies, are part of the +[java-example](https://github.com/google/oss-fuzz/tree/master/projects/java-example) +project. + +### project.yaml + +The `language` attribute must be specified as follows: + +```yaml +language: jvm +``` + +The only supported fuzzing engine is libFuzzer (`libfuzzer`). So far the only +supported sanitizer is AddressSanitizer (`address`), which needs to be +specified explicitly even for pure Java projects. + +```yaml +fuzzing_engines: + - libfuzzer +sanitizers: + - address +``` + +### Dockerfile + +The OSS-Fuzz base Docker images already come with OpenJDK 15 pre-installed. If +you need Maven to build your project, you can install it by adding the following +line to your Dockerfile: + +```docker +RUN apt-get update && apt-get install -y maven +``` + +Apart from this, you should usually not need to do more than to clone the +project, set a `WORKDIR`, and copy any necessary files, or install any +project-specific dependencies here as you normally would. + +### Fuzzers + +In the simplest case, every fuzzer consists of a single Java file with a +filename matching `*Fuzzer.java` and no `package` directive. An example fuzz +target could thus be a file `ExampleFuzzer.java` with contents: + +```java +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. + ... + } +} +``` + +### build.sh + +For JVM projects, `build.sh` does need some more significant modifications +over C/C++ projects. Below is an annotated example build script for a +Java-only project with single-file fuzz targets as described above: + +```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/sh +# LLVMFuzzerTestOneInput for fuzzer detection. +this_dir=\$(dirname \"\$0\") +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=\"-Xmx2048m\" \ +\$@" > $OUT/$fuzzer_basename + chmod u+x $OUT/$fuzzer_basename +done +``` + +## FuzzedDataProvider + +Jazzer provides a `FuzzedDataProvider` that can simplify the task of creating a +fuzz target by translating the raw input bytes received from the fuzzer into +useful primitive Java types. Its functionality is similar to +`FuzzedDataProviders` available in other languages, such as +[Python](https://github.com/google/atheris#fuzzeddataprovider) and +[C++](https://github.com/google/fuzzing/blob/master/docs/split-inputs.md). + +On OSS-Fuzz, the required library is available in the base docker images under +the path `$JAZZER_API_PATH`, which is added to the classpath by the example +build script shown above. Locally, the library can be obtained from +[Maven Central](https://search.maven.org/search?q=g:com.code-intelligence%20a:jazzer-api). + +A fuzz target using the `FuzzedDataProvider` would look as follows: + +```java +import com.code_intelligence.jazzer.api.FuzzedDataProvider; + +public class ExampleFuzzer { + public static void fuzzerTestOneInput(FuzzedDataProvider data) { + int number = data.consumeInt(); + String string = data.consumeRemainingAsString(); + // ... + } +} +``` + +For a list of convenience methods offered by `FuzzedDataProvider`, consult its +[javadocs](https://codeintelligencetesting.github.io/jazzer-api/com/code_intelligence/jazzer/api/FuzzedDataProvider.html). |