-
Notifications
You must be signed in to change notification settings - Fork 114
Home
JQF is a ...
TODO: Some examples of a fuzz test and a run script
Getting started with JQF is easy. It mostly uses Apache Maven to manage its build infrastructure. The README typically has the most up-to-date instructions on requirements as well as instructions to compile and run.
JQF builds on top of junit-quickcheck, so any valid quickcheck property and input generator works with JQF. The junit-quickcheck documentation is a great place to learn to write quickcheck tests and generators. Just remember to update the annotations on your test class from @RunWith(JUnitQuickcheck.class) to @RunWith(JQF.class) and the annotations on your test methods from @Property to @Fuzz if you want them to work with JQF.
For a JQF-centric tutorial on writing an effective fuzz target, see Writing a JQF test.
JQF ships with out-of-the-box support for fuzzing with American Fuzzy Lop (AFL). AFL has been used to find numerous bugs in C (and LLVM) programs using lightweight instrumentation and coverage-guided fuzzing. If you've never used AFL before, the AFL quickstart guide may be a worthwhile read. In a nutshell, you want to run afl-fuzz on an instrumented program (known as the target), providing an input and output directory that respectively contain the input files to start with (known as the seeds) and where AFL will save the fuzzed inputs that it considers interesting (either because they found new code coverage or they resulted in a crash). JQF lets you run AFL on Java programs, so you can skip the steps relating to instrumenting C programs with afl-gcc or afl-clang. Instead, you give AFL the target program jqf-afl, which takes as arguments the Java test class and method that you want to fuzz. Simple enough. See Fuzzing Java with AFL for more details.
One of JQF's core features is its ease of extensibility. Although a coverage-guided fuzz-with-AFL mode is provided out of the box, you can easily change the front-end to use different types of feedback (other than branch coverage) and input generation techniques other than AFL. See Extending JQF: The Guidance Interface.
If you delve into the API exposed by JQF, you may also be interested in knowing more about the program instrumentation that JQF uses and the way it generates trace events for use in guided fuzzing. We've outlined some key points in the article on Implementation Details.
We want your feedback! (haha, get it? get it?)
If you've found a bug 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.
The source code examples in the wiki pages can be freely re-used under the same license as the rest of JQF.