Feedback-directed fuzzing for Java
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Failed to load latest commit information.
bin
examples
experiments
fuzz
instrument
maven-plugin
scripts
.gitignore
LICENSE
Makefile
README.md
pom.xml
setup.sh

README.md

JQF: A feedback-directed fuzz testing platform for Java

JQF is built on top of junit-quickcheck, which itself lets you write Quickcheck-like generators and properties in a Junit-style test class. JQF enables better input generation using state-of-the-art fuzzing tools such as AFL.

JQF has been successful in discovering a number of bugs in widely used open-source software such as OpenJDK, Apache Maven and the Google Closure Compiler.

Quickstart

First, build JQF and the AFL proxy:

$ git clone https://github.com/rohanpadhye/jqf
$ jqf/setup.sh

Then, write a Junit-like test class annotated with @RunWith(JQF.class) and write some test methods annotated with @Fuzz. The arguments to the test methods will be generated by JQF:

@RunWith(JQF.class)
public class DateFormatterTest {

    /* Input params will be generated by JQF, many times. */
    /* Exceptions listed in the "throws" clause are considered normal (tests will pass on throw) */
    @Fuzz
    public void fuzzSimple(Date date, String format) throws IllegalArgumentException {
        // Create a simple date formatter using the input format string
        // May throw IllegalArgumentException for invalid formats
        DateFormat df = new SimpleDateFormat(format);

        // Format the date using the constructed formatter
        df.format(date);
    }
}

Compile with JQF on the classpath (using the provided handy script):

$ javac -cp $(jqf/scripts/classpath.sh) DateFormatterTest.java

Fuzz the method fuzzSimple with AFL:

$ jqf/bin/jqf-afl-fuzz DateFormatterTest fuzzSimple

Grab a coffee while AFL does its thing:

AFL status screen

Ooh! We found some crashes. Let's reproduce one such test case and see what the error was.

$ jqf/bin/jqf-repro DateFormatterTest fuzzSimple fuzz-results/crashes/id:000000
java.lang.ArrayIndexOutOfBoundsException: 127
	at java.text.SimpleDateFormat.subFormat(SimpleDateFormat.java)
	at java.text.SimpleDateFormat.format(SimpleDateFormat.java)
	at java.text.SimpleDateFormat.format(SimpleDateFormat.java)
	at java.text.DateFormat.format(DateFormat.java)

This shouldn't happen! DateFormat.format() does not specify that it will throw ArrayIndexOutOfBoundsException. Time to file a bug report :-)

Using JQF with Maven

Do you use Apache Maven to build your project? Great! Then you don't need to clone/build JQF and mess with classpaths and shell scripts.

Simply add a test-dependency to the JQF API in your pom.xml file as so:

<dependency>
    <groupId>edu.berkeley.cs.jqf</groupId>
    <artifactId>jqf-fuzz</artifactId>
    <version>1.0-beta-1</version>
    <scope>test</scope>
</dependency>

You can now have your JQF test classes be part of your standard JUnit test suite. When not run as a stand-alone fuzzing job on the command-line, these tests will be run like regular junit-quickcheck tests, i.e. 100 inputs will be generated randomly without feedback per @Fuzz annotated method.

You might also want to checkout the JQF Maven Plugin that lets you fuzz your application using mvn jqf:fuzz instead of having to clone this repo and run shell scripts.

Documentation

The JQF wiki contains lots more documentation including:

Contact the developers

We want your feedback! (haha, get it? get it?)

If you've found a bug in JQF or are having trouble getting JQF to work, please open an issue on the issue tracker. You can also use this platform to post feature requests.

If it's some sort of fuzzing emergency you can always send an email to the main developer: Rohan Padhye.