Package com.code_intelligence.jazzer.api

Class Jazzer

java.lang.Object

com.code_intelligence.jazzer.api.Jazzer

public final class Jazzer
extends java.lang.Object

Static helper methods that hooks can use to provide feedback to the fuzzer.

Field Summary

Fields

Modifier and Type	Field	Description
static int	SEED	A 32-bit random number that hooks can use to make pseudo-random choices between multiple possible mutations they could guide the fuzzer towards.

Method Summary

Modifier and Type	Method	Description
static void	exploreState(byte state, int id)	Instructs the fuzzer to attain as many possible values for the absolute value of state as possible.
static void	guideTowardsContainment(java.lang.String haystack, java.lang.String needle, int id)	Instructs the fuzzer to guide its mutations towards making haystack contain needle as a substring.
static void	guideTowardsEquality(byte[] current, byte[] target, int id)	Instructs the fuzzer to guide its mutations towards making current equal to target.
static void	guideTowardsEquality(java.lang.String current, java.lang.String target, int id)	Instructs the fuzzer to guide its mutations towards making current equal to target.
static void	onFuzzTargetReady(java.lang.Runnable callback)	Register a callback to be executed right before the fuzz target is executed for the first time.
static void	reportFindingFromHook(java.lang.Throwable finding)	Make Jazzer report the provided Throwable as a finding.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

SEED

public static final int SEED

A 32-bit random number that hooks can use to make pseudo-random choices between multiple possible mutations they could guide the fuzzer towards. Hooks must not base the decision whether or not to report a finding on this number as this will make findings non-reproducible.

This is the same number that libFuzzer uses as a seed internally, which makes it possible to deterministically reproduce a previous fuzzing run by supplying the seed value printed by libFuzzer as the value of the -seed.

Method Detail

guideTowardsEquality

public static void guideTowardsEquality(java.lang.String current,
                                        java.lang.String target,
                                        int id)

Instructs the fuzzer to guide its mutations towards making current equal to target.

If the relation between the raw fuzzer input and the value of current is relatively complex, running the fuzzer with the argument -use_value_profile=1 may be necessary to achieve equality.

Parameters:

current - a non-constant string observed during fuzz target execution

target - a string that current should become equal to, but currently isn't

id - a (probabilistically) unique identifier for this particular compare hint

guideTowardsEquality

public static void guideTowardsEquality(byte[] current,
                                        byte[] target,
                                        int id)

Instructs the fuzzer to guide its mutations towards making current equal to target.

If the relation between the raw fuzzer input and the value of current is relatively complex, running the fuzzer with the argument -use_value_profile=1 may be necessary to achieve equality.

Parameters:

current - a non-constant byte array observed during fuzz target execution

target - a byte array that current should become equal to, but currently isn't

id - a (probabilistically) unique identifier for this particular compare hint

guideTowardsContainment

public static void guideTowardsContainment(java.lang.String haystack,
                                           java.lang.String needle,
                                           int id)

Instructs the fuzzer to guide its mutations towards making haystack contain needle as a substring.

If the relation between the raw fuzzer input and the value of haystack is relatively complex, running the fuzzer with the argument -use_value_profile=1 may be necessary to satisfy the substring check.

Parameters:

haystack - a non-constant string observed during fuzz target execution

needle - a string that should be contained in haystack as a substring, but currently isn't

id - a (probabilistically) unique identifier for this particular compare hint

exploreState

public static void exploreState(byte state,
                                int id)

Instructs the fuzzer to attain as many possible values for the absolute value of state as possible.

Call this function from a fuzz target or a hook to help the fuzzer track partial progress (e.g. by passing the length of a common prefix of two lists that should become equal) or explore different values of state that is not directly related to code coverage (see the MazeFuzzer example).

Note: This hint only takes effect if the fuzzer is run with the argument -use_value_profile=1.

Parameters:

state - a numeric encoding of a state that should be varied by the fuzzer

id - a (probabilistically) unique identifier for this particular state hint

reportFindingFromHook

public static void reportFindingFromHook(java.lang.Throwable finding)

Make Jazzer report the provided Throwable as a finding.

Note: This method must only be called from a method hook. In a fuzz target, simply throw an exception to trigger a finding.

Parameters:

finding - the finding that Jazzer should report

onFuzzTargetReady

public static void onFuzzTargetReady(java.lang.Runnable callback)

Register a callback to be executed right before the fuzz target is executed for the first time.

This can be used to disable hooks until after Jazzer has been fully initializing, e.g. to prevent Jazzer internals from triggering hooks on Java standard library classes.

Parameters:

callback - the callback to execute