Skip to content

Commit aea240d

Browse files
oetroetr
committed
chore: restructure the docs
1 parent f7734bc commit aea240d

File tree

8 files changed

+538
-327
lines changed

8 files changed

+538
-327
lines changed

‎README.md‎

Lines changed: 157 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -22,21 +22,6 @@
2222
<a href="https://twitter.com/CI_Fuzz" target="_blank">Twitter</a>
2323
</div>
2424

25-
> [!IMPORTANT]
26-
> **Jazzer** is back under the **Apache 2.0 license**!
27-
>
28-
> We previously paused open-source maintenance but the incredible feedback, support, and ideas from
29-
> the community motivated us to find a way to bring Jazzer back to the
30-
> open-source world.
31-
>
32-
> Thanks to your enthusiasm and contributions, and a special callout to the
33-
> [OSS-Fuzz](https://github.com/google/oss-fuzz) team 🚀.
34-
>
35-
> Visit [code-intelligence.com](https://code-intelligence.com) for more
36-
> information.
37-
>
38-
> The Code Intelligence team
39-
4025
Jazzer is a coverage-guided, in-process fuzzer for the JVM platform developed by [Code Intelligence](https://code-intelligence.com).
4126
It is based on [libFuzzer](https://llvm.org/docs/LibFuzzer.html) and brings many of its instrumentation-powered mutation features to the JVM.
4227

@@ -45,49 +30,135 @@ Jazzer currently supports the following platforms:
4530
* macOS 12+ x86_64 & arm64
4631
* Windows x86_64
4732

48-
## Using Jazzer via...
33+
## Setup
34+
35+
Jazzer integrates seamlessly with JUnit (version 5.9.0 or newer), allowing you to write fuzz tests alongside your regular unit tests.
36+
The recommended way to get started is by adding the `jazzer-junit` dependency to your project.
37+
This package is available on [Maven Central](https://central.sonatype.com/artifact/com.code-intelligence/jazzer-junit) and is signed with [this key](deploy/maven.pub).
38+
39+
You can use Jazzer with popular build tools:
40+
41+
### Maven
42+
43+
Add the following to your `pom.xml`:
44+
45+
```xml
46+
<dependency>
47+
<groupId>com.code-intelligence</groupId>
48+
<artifactId>jazzer-junit</artifactId>
49+
<version>LATEST VERSION</version>
50+
</dependency>
51+
```
52+
53+
A complete example project using Maven is available in [`examples/junit`](examples/junit).
54+
55+
### Gradle
56+
57+
Include Jazzer in your `build.gradle`:
58+
59+
```gradle
60+
implementation group: 'com.code-intelligence', name: 'jazzer-junit', version: '<LATEST VERSION>'
61+
```
62+
63+
### Bazel
64+
65+
Jazzer is supported via [rules_fuzzing](https://github.com/bazelbuild/rules_fuzzing), the official Bazel rules for fuzzing.
66+
For setup instructions, see [the README](https://github.com/bazelbuild/rules_fuzzing#java-fuzzing).
4967

50-
### JUnit 5
68+
With Jazzer set up, you can start writing fuzz tests and benefit from automated bug discovery and improved code coverage.
5169

52-
The following steps assume that JUnit 5.9.0 or higher is set up for your project, for example based on the official [junit5-samples](https://github.com/junit-team/junit5-samples).
70+
## Writing fuzz tests
5371

54-
1. Add a dependency on `com.code-intelligence:jazzer-junit:<latest version>`.
55-
All Jazzer Maven artifacts are signed with [this key](deploy/maven.pub).
56-
2. Add a new *fuzz test* to a new or existing test class: a method annotated with [`@FuzzTest`](https://codeintelligencetesting.github.io/jazzer-docs/jazzer-junit/com/code_intelligence/jazzer/junit/FuzzTest.html) and at least one parameter.
57-
A list of supported parameter types can be found in the [documentation](docs/junit-integration.md#supported-types).
58-
3. Assuming your test class is called `com.example.MyFuzzTests`, create the *inputs directory* `src/test/resources/com/example/MyFuzzTestsInputs`.
59-
4. Run a fuzz test with the environment variable `JAZZER_FUZZ` set to `1` to let the fuzzer rapidly try new sets of arguments.
60-
If the fuzzer finds arguments that make your fuzz test fail or even trigger a security issue, it will store them in the inputs directory.
61-
In this mode, only a single fuzz test is executed per test run (see [#599](https://github.com/CodeIntelligenceTesting/jazzer/issues/599) for details).
62-
5. Run the fuzz test without `JAZZER_FUZZ` set to execute it only on the inputs in the inputs directory.
63-
This mode, which behaves just like a traditional unit test, ensures that issues previously found by the fuzzer remain fixed and can also be used to debug the fuzz test on individual inputs.
72+
To write a fuzz test, add a method to your test class and annotate it with [`@FuzzTest`](https://codeintelligencetesting.github.io/jazzer-docs/jazzer-junit/com/code_intelligence/jazzer/junit/FuzzTest.html).
73+
Jazzer will automatically generate and mutate inputs for your method parameters.
74+
You can use primitives, strings, arrays, and many standard library classes.
75+
See the [mutation framework documentation](docs/mutation-framework.md#supported-types) for details.
76+
To run a fuzz test in [fuzzing mode](#fuzzing-mode), set environment variable `JAZZER_FUZZ` to a truthy value:
77+
```bash
78+
JAZZER_FUZZ=1 mvn test org.example.ParserTests
79+
```
6480

65-
A simple property-based fuzz test could look like this:
81+
Here is an example that demonstrates fuzzing security-relevant logic:
6682

6783
```java
84+
package org.example;
85+
import com.code_intelligence.jazzer.junit.FuzzTest;
86+
import com.code_intelligence.jazzer.mutation.annotation.NotNull;
87+
import com.code_intelligence.jazzer.mutation.annotation.InRange;
88+
import com.code_intelligence.jazzer.mutation.annotation.WithUtf8Length;
89+
import org.junit.jupiter.api.Test;
90+
import static org.junit.jupiter.api.Assertions.*;
91+
6892
class ParserTests {
6993
@Test
7094
void unitTest() {
7195
assertEquals("foobar", SomeScheme.decode(SomeScheme.encode("foobar")));
7296
}
7397

7498
@FuzzTest
75-
void fuzzTest(@NotNull String input) {
99+
void fuzzTest_decode(@NotNull String input) {
76100
assertEquals(input, SomeScheme.decode(SomeScheme.encode(input)));
77101
}
102+
103+
@FuzzTest
104+
void fuzzTest_decodeWithN(@NotNull @WithUtf8Length(min=10, max=200) String input, @InRange(min=-10, max=10) int n) {
105+
assertEquals(input, SomeScheme.decode(SomeScheme.encode(input)));
106+
assertTrue(n >= -10 && n <= 10);
107+
}
78108
}
79109
```
110+
A complete Maven example project can be found in [examples/junit](examples/junit).
111+
112+
113+
## Running Jazzer
114+
115+
Jazzer can be run in two ways: using the JUnit integration or by using Jazzer standalone.
116+
117+
### Using JUnit integration
118+
119+
To run fuzz tests, use your build system as you would for regular tests.
120+
Methods annotated with `@FuzzTest` can be executed in two modes: regression mode and fuzzing mode.
121+
122+
123+
#### Regression mode
124+
125+
In regression mode, Jazzer runs each fuzz test with crashing inputs found in its corresponding [*inputs directory*](#inputs-directory).
126+
This mode behaves like a traditional unit test: it verifies that previously discovered issues remain fixed and helps debug the fuzz test with specific inputs.
127+
By default, Jazzer operates in regression mode unless fuzzing mode is explicitly enabled.
80128

81-
A complete Maven example project can be found in [`examples/junit`](examples/junit).
129+
If you want that Jazzer also uses the inputs from the [*generated corpus directory*](#generated-corpus-directory), set the environment variable `JAZZER_COVERAGE=1`.
82130

83-
A detailed description of the JUnit integration can be found in the [documentation](docs/junit-integration.md).
84131

85-
### GitHub releases
132+
#### Fuzzing mode
86133

87-
You can also use GitHub release archives to run a standalone Jazzer binary that starts its own JVM configured for fuzzing:
134+
This mode helps uncover new bugs and improve test coverage.
135+
Enable fuzzing mode by setting the environment variable `JAZZER_FUZZ=1` before running your tests.
136+
Jazzer will execute a single fuzz test, automatically generating and mutating inputs to maximize code coverage and find bugs.
137+
If Jazzer discovers an input that generates new coverage, it is stored in the [*generated corpus directory*](#generated-corpus-directory) of the fuzz test.
138+
If Jazzer discovers an input that causes a fuzz test to fail (such as an uncaught exception or a triggered sanitizer), it stores the crashing input in the [*inputs directory*](#inputs-directory).
139+
140+
141+
### Jazzer standalone
142+
There are two ways to use Jazzer standalone: by calling the Jazzer main class directly or by using the `jazzer` binary.
143+
144+
#### Calling the Jazzer main class directly
145+
146+
To call Jazzer directly you need to pass it the project classpath, the path to the `jazzer.jar` and `jazzer-junit.jar`
147+
along with the Jazzer main class `com.code_intelligence.jazzer.Jazzer` and target class that contains the Fuzz Test.
148+
149+
```shell
150+
java -cp <classpath>;<path/to/jazzer.jar>;<path/to/jazzer-junit.jar> com.code_intelligence.jazzer.Jazzer --target_class=<fuzz-test-class> [args...]
151+
```
152+
153+
Optionally you can add other Jazzer arguments with double dash command-line flags.
154+
Because Jazzer is based on libFuzzer, all available libFuzzer arguments can be added with single dash command-line flags.
155+
Please refer to [libFuzzer](https://llvm.org/docs/LibFuzzer.html) for documentation.
156+
157+
#### Using the `jazzer` binary
158+
Jazzer is available as a standalone binary from the GitHub release archives that starts its own JVM configured for fuzzing:
88159

89160
1. Download and extract the latest release from the [GitHub releases page](https://github.com/CodeIntelligenceTesting/jazzer/releases).
90-
2. Add a new class to your project with a <code>public static void fuzzerTestOneInput(String par1, int par2, int[] par3, ...)</code> method, with the parameters you want to use in the fuzz test.
161+
2. Add a new class to your project with a `public static void fuzzerTestOneInput(String par1, int par2, int[] par3, ...)` method, with the parameters you want to use in the fuzz test.
91162
3. Compile your fuzz test with `jazzer_standalone.jar` on the classpath.
92163
4. Run the `jazzer` binary (`jazzer.exe` on Windows), specifying the classpath and fuzz test class:
93164

@@ -97,31 +168,70 @@ You can also use GitHub release archives to run a standalone Jazzer binary that
97168

98169
If you see an error saying that `libjvm.so` has not been found, make sure that `JAVA_HOME` points to a JDK.
99170

100-
The [`examples`](examples/src/main/java/com/example) directory includes both toy and real-world examples of fuzz tests.
171+
## Directories and files
101172

102-
### Bazel
173+
Jazzer uses two directories to store inputs: the *generated corpus directory* and the *inputs directory*.
174+
175+
### Generated corpus directory
176+
177+
The *generated corpus directory* is where Jazzer saves inputs that generate new coverage during fuzzing.
178+
It is located in `.cifuzz-corpus/<package>/<FuzzTestClass>/<fuzzTestMethod>`, where `<package>`, `<FuzzTestClass>`, and `<fuzzTestMethod>` correspond to the package name, class name, and method name of the fuzz test, respectively.
179+
For example, if the fuzz test is in the class `src/test/java/com/example/ValidFuzzTestsInputs.java`, method `byteFuzz`, the corpus directory is located in `.cifuzz-corpus/com.example.ValidFuzzTestsInputs/byteFuzz`.
180+
181+
182+
### Inputs directory
103183

104-
Support for Jazzer is available in [rules_fuzzing](https://github.com/bazelbuild/rules_fuzzing), the official Bazel rules for fuzzing.
105-
See [the README](https://github.com/bazelbuild/rules_fuzzing#java-fuzzing) for instructions on how to use Jazzer in a Java Bazel project.
184+
Any input that triggers a crash during fuzzing is saved to the *inputs directory*.
185+
This directory is derived from the package and class name of the fuzz test.
186+
For example, if the fuzz test is in the class `src/test/java/com/example/ValidFuzzTestsInputs.java`, method `byteFuzz`, the *inputs directory* is located in `src/test/resources/com/example/ValidFuzzTestsInputs/byteFuzz`.
187+
If this directory does not exist, Jazzer will save crash inputs in the directory from which the tests are executed.
106188

107-
### OSS-Fuzz
189+
190+
## Sanitizers / bug detectors
191+
192+
Sanitizers (also called *bug detectors*) are built-in checks that help Jazzer find security issues in your application while fuzzing.
193+
They automatically monitor the program under test for risky behaviors, such as unsafe file access or network requests, and report them back with detailed information.
194+
This way, you don’t just learn that an input caused a crash, but you also get insight into what kind of vulnerability it triggered.
195+
196+
If you've worked with C or C++ before, you may know sanitizers like [AddressSanitizer](https://clang.llvm.org/docs/AddressSanitizer.html) or [UndefinedBehaviorSanitizer](https://clang.llvm.org/docs/UndefinedBehaviorSanitizer.html).
197+
Jazzer sanitizers serve a similar purpose, but they are designed specifically for Java and JVM applications.
198+
Instead of low-level memory errors, they focus on common security issues in Java software, such as **Server-Side Request Forgery** (SSRF), **File Path Traversal**, **Os Command Injection**, etc.
199+
200+
Sanitizers not only detect dangerous conditions but also make fuzzing smarter.
201+
By providing feedback to the fuzzer about what they detect, they can guide input generation towards the kinds of values most likely to trigger vulnerabilities.
202+
This makes it possible to find complex bugs more quickly and with less manual effort.
203+
204+
You can browse all available sanitizers in the [Jazzer codebase](sanitizers/src/main/java/com/code_intelligence/jazzer/sanitizers).
205+
Each sanitizer can be disabled using [`disabled_hooks`](docs/arguments-and-configuration-options.md).
206+
207+
208+
### Configure sanitizers using BugDetectorsAPI
209+
210+
Some sanitizers can also be configured at runtime using the BugDetectorsAPI to adjust how they detect vulnerabilities.
211+
Currently, this applies to Server-Side Request Forgery and File Path Traversal sanitizers.
212+
For details, check out the [API documentation](https://codeintelligencetesting.github.io/jazzer-docs/jazzer-api/com/code_intelligence/jazzer/api/BugDetectors.html).
213+
214+
215+
## OSS-Fuzz
108216

109217
[Code Intelligence](https://code-intelligence.com) and Google have teamed up to bring support for Java, Kotlin, and other JVM-based languages to [OSS-Fuzz](https://github.com/google/oss-fuzz), Google's project for large-scale fuzzing of open-source software.
110218
Read [the OSS-Fuzz guide](https://google.github.io/oss-fuzz/getting-started/new-project-guide/jvm-lang/) to learn how to set up a Java project.
111219

112-
## Building from source
220+
## Trophies
221+
222+
A list of security issues and bugs found by Jazzer is maintained [here](docs/trophies.md).
223+
If you found something interesting and the information is public, please send a PR to add it to the list.
113224

114-
Information on building and testing Jazzer for development can be found in [CONTRIBUTING.md](CONTRIBUTING.md)
115225

116226
## Further documentation
117227

118-
* [Common options and workflows](docs/common.md)
228+
* [Arguments and Configuration Options](docs/arguments-and-configuration-options.md)
229+
* [Mutation framework](docs/mutation-framework.md)
119230
* [Advanced techniques](docs/advanced.md)
231+
* [Building Jazzer from source](CONTRIBUTING.md)
232+
* [JUnit integration implementation details](docs/dev-junit-implementation-details.md)
233+
* [Autofuzz (*DEPRECATED*)](docs/autofuzz.md)
120234

121-
## Findings
122-
123-
A list of security issues and bugs found by Jazzer is maintained [here](docs/findings.md).
124-
If you found something interesting and the information is public, please send a PR to add it to the list.
125235

126236
## Credit
127237

0 commit comments

Comments
 (0)