Package edu.berkeley.cs.jqf.fuzz.ei

Class ExecutionIndexingGuidance

java.lang.Object

edu.berkeley.cs.jqf.fuzz.ei.ZestGuidance

edu.berkeley.cs.jqf.fuzz.ei.ExecutionIndexingGuidance

All Implemented Interfaces:

Guidance

public class ExecutionIndexingGuidance
extends ZestGuidance

A guidance that represents inputs as maps from execution indexes to parameters.

Author:

Rohan Padhye

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
class	ExecutionIndexingGuidance.MappedInput	A candidate test input represented as a map from execution indices to integer values.
class	ExecutionIndexingGuidance.MappedSeedInput

Nested classes/interfaces inherited from class edu.berkeley.cs.jqf.fuzz.ei.ZestGuidance

ZestGuidance.Input<K>, ZestGuidance.LinearInput, ZestGuidance.SeedInput

Field Summary

Fields

Modifier and Type	Field	Description
protected Thread	appThread	The thread being instrumented for coverage-guided fuzzing.
protected Map<Integer,Integer>	coverageHashToSavedInputIdx	Maps a hash code of coverage bits to an index in savedInputs queue.
protected double	DEMAND_DRIVEN_SPLICING_PROBABILITY	Probability of splicing in ExecutionIndexingGuidance.MappedInput.getOrGenerateFresh(ExecutionIndex, Random)
protected AbstractExecutionIndexingState	eiState	The execution indexing logic.
protected String	entryPoint	The entry point to the test method we are fuzzing.
protected int	MAX_SPLICE_SIZE	Max number of contiguous bytes to splice in from another input during the splicing stage.
protected double	MEAN_MUTATION_COUNT	Mean number of mutations to perform in each round.
protected double	MEAN_MUTATION_SIZE	Mean number of contiguous bytes to mutate in each mutation.
protected double	MUTATION_ZERO_PROBABILITY	Probability that a standard mutation sets the byte to just zero instead of a random value.
protected boolean	SPLICE_SUBTREE	Whether to splice only in the same sub-tree
protected double	STANDARD_SPLICING_PROBABILITY	Probability of splicing in ExecutionIndexingGuidance.MappedInput.fuzz(Random, Map)
protected boolean	testEntered	Whether the the entry point has been encountered in the current run.

Fields inherited from class edu.berkeley.cs.jqf.fuzz.ei.ZestGuidance

allInputsDirectory, blind, branchCount, console, coverageFile, currentInput, currentInputFile, currentParentInputIdx, cyclesCompleted, DISABLE_SAVE_NEW_COUNTS, EXACT_CRASH_PATH, EXIT_ON_CRASH, firstThread, GENERATE_EOF_WHEN_OUT, lastNumTrials, lastRefreshTime, LIBFUZZER_COMPAT_OUTPUT, LOG_ALL_INPUTS, logFile, MAX_INPUT_SIZE, maxCoverage, maxDurationMillis, maxTrials, multiThreaded, NUM_CHILDREN_BASELINE, NUM_CHILDREN_MULTIPLIER_FAVORED, numChildrenGeneratedForCurrentParentInput, numFavoredLastCycle, numSavedInputs, numTrials, numValid, outputDirectory, QUIET_MODE, random, responsibleInputs, runCoverage, runStart, SAVE_ONLY_VALID, savedCorpusDirectory, savedFailuresDirectory, savedInputs, seedInputs, singleRunTimeoutMillis, startTime, STATS_REFRESH_TIME_PERIOD, statsFile, STEAL_RESPONSIBILITY, testName, totalCoverage, uniqueFailures, validCoverage, validityFuzzing, verbose

Constructor Summary

Constructors

Constructor	Description
ExecutionIndexingGuidance(String testName, Duration duration, File outputDirectory, File[] seedFiles)	Creates a new EI guidance instance with seed input files and optional duration.
ExecutionIndexingGuidance(String testName, Duration duration, Long trials, File outputDirectory, File seedInputDir, Random sourceOfRandomness)	Constructs a new EI guidance instance with seed input directory and optional duration, optional trial limit, an possibly deterministic PRNG.
ExecutionIndexingGuidance(String testName, Duration duration, Long trials, File outputDirectory, Random sourceOfRandomness)	Constructs a new EI guidance instance with optional duration, optional trial limit, and possibly deterministic PRNG.

Method Summary

Modifier and Type	Method	Description
protected void	completeCycle()	Handles the end of fuzzing cycle (i.e., having gone through the entire queue)
protected ZestGuidance.Input<?>	createFreshInput()	Spawns a new input from thin air (i.e., actually random)
protected InputStream	createParameterStream()	Returns an InputStream that delivers parameters to the generators.
Consumer<TraceEvent>	generateCallBack(Thread thread)	Returns a callback generator for a thread's event trace.
InputStream	getInput()	Returns a reference to a stream of values return from the pseudo-random number generator.
protected String	getTitle()	Returns the banner to be displayed on the status screen
protected void	handleEvent(TraceEvent e)	Handles a trace event generated during test execution
void	handleResult(Result result, Throwable error)	Handles the result of a test execution.
void	run(TestClass testClass, FrameworkMethod method, Object[] args)	Runs a test method with generated arguments as input.
protected void	saveCurrentInput(org.eclipse.collections.impl.set.mutable.primitive.IntHashSet responsibilities, String why)	Saves an interesting input to the queue.

Methods inherited from class edu.berkeley.cs.jqf.fuzz.ei.ZestGuidance

appendLineToFile, checkSavingCriteriaSatisfied, computeResponsibilities, conditionallySynchronize, displayStats, getStatNames, getTargetChildrenForParent, getTotalCoverage, hasInput, infoLog, millisToDuration, setBlind, updateCoverageFile, writeCurrentInputToFile

Methods inherited from class java.lang.Object

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

Methods inherited from interface edu.berkeley.cs.jqf.fuzz.guidance.Guidance

observeGeneratedArgs

Field Detail

eiState

protected AbstractExecutionIndexingState eiState

The execution indexing logic.

appThread

protected Thread appThread

The thread being instrumented for coverage-guided fuzzing.

entryPoint

protected String entryPoint

The entry point to the test method we are fuzzing.

testEntered

protected boolean testEntered

Whether the the entry point has been encountered in the current run.

coverageHashToSavedInputIdx

protected Map<Integer,Integer> coverageHashToSavedInputIdx

Maps a hash code of coverage bits to an index in savedInputs queue.

MEAN_MUTATION_COUNT

protected final double MEAN_MUTATION_COUNT

Mean number of mutations to perform in each round.

See Also:

Constant Field Values

MEAN_MUTATION_SIZE

protected final double MEAN_MUTATION_SIZE

Mean number of contiguous bytes to mutate in each mutation.

See Also:

Constant Field Values

MUTATION_ZERO_PROBABILITY

protected final double MUTATION_ZERO_PROBABILITY

Probability that a standard mutation sets the byte to just zero instead of a random value.

See Also:

Constant Field Values

MAX_SPLICE_SIZE

protected final int MAX_SPLICE_SIZE

Max number of contiguous bytes to splice in from another input during the splicing stage.

See Also:

Constant Field Values

SPLICE_SUBTREE

protected final boolean SPLICE_SUBTREE

Whether to splice only in the same sub-tree

STANDARD_SPLICING_PROBABILITY

protected final double STANDARD_SPLICING_PROBABILITY

Probability of splicing in ExecutionIndexingGuidance.MappedInput.fuzz(Random, Map)

See Also:

Constant Field Values

DEMAND_DRIVEN_SPLICING_PROBABILITY

protected final double DEMAND_DRIVEN_SPLICING_PROBABILITY

Probability of splicing in ExecutionIndexingGuidance.MappedInput.getOrGenerateFresh(ExecutionIndex, Random)

See Also:

Constant Field Values

Constructor Detail

ExecutionIndexingGuidance

public ExecutionIndexingGuidance(String testName,
                                 Duration duration,
                                 Long trials,
                                 File outputDirectory,
                                 Random sourceOfRandomness)
                          throws IOException

Constructs a new EI guidance instance with optional duration, optional trial limit, and possibly deterministic PRNG.

Parameters:

testName - the name of test to display on the status screen

duration - the amount of time to run fuzzing for, where null indicates unlimited time.

trials - the number of trials for which to run fuzzing, where null indicates unlimited trials.

outputDirectory - the directory where fuzzing results will be written

sourceOfRandomness - a pseudo-random number generator

Throws:

IOException - if the output directory could not be prepared

ExecutionIndexingGuidance

public ExecutionIndexingGuidance(String testName,
                                 Duration duration,
                                 Long trials,
                                 File outputDirectory,
                                 File seedInputDir,
                                 Random sourceOfRandomness)
                          throws IOException

Constructs a new EI guidance instance with seed input directory and optional duration, optional trial limit, an possibly deterministic PRNG.

Parameters:

testName - the name of test to display on the status screen

duration - the amount of time to run fuzzing for, where null indicates unlimited time.

trials - the number of trials for which to run fuzzing, where null indicates unlimited trials.

outputDirectory - the directory where fuzzing results will be written

seedInputDir - the directory containing one or more input files to be used as initial inputs

sourceOfRandomness - a pseudo-random number generator

Throws:

IOException - if the output directory could not be prepared

ExecutionIndexingGuidance

public ExecutionIndexingGuidance(String testName,
                                 Duration duration,
                                 File outputDirectory,
                                 File[] seedFiles)
                          throws IOException

Creates a new EI guidance instance with seed input files and optional duration.

Parameters:

testName - the name of test to display on the status screen

duration - the amount of time to run fuzzing for, where null indicates unlimited time.

outputDirectory - the directory where fuzzing results will be written

Throws:

IOException - if the output directory could not be prepared

Method Detail

getTitle

protected String getTitle()

Returns the banner to be displayed on the status screen

Overrides:

getTitle in class ZestGuidance

createFreshInput

protected ZestGuidance.Input<?> createFreshInput()

Spawns a new input from thin air (i.e., actually random)

Overrides:

createFreshInput in class ZestGuidance

Returns:

a fresh input

createParameterStream

protected InputStream createParameterStream()

Returns an InputStream that delivers parameters to the generators. Note: The variable `currentInput` has been set to point to the input to mutate.

Overrides:

createParameterStream in class ZestGuidance

Returns:

an InputStream that delivers parameters to the generators

getInput

public InputStream getInput()
                     throws GuidanceException

Description copied from interface: Guidance

Returns a reference to a stream of values return from the pseudo-random number generator.

This method is guaranteed to be invoked by JQF at most once after each invocation of Guidance.hasInput() that has returned true.

If Guidance.hasInput() returns false or has not been invoked since the last call to Guidance.getInput(), then invoking this method may throw an IllegalStateException.

Specified by:

getInput in interface Guidance

Overrides:

getInput in class ZestGuidance

Returns:

a stream of bytes to be used by the input generator(s)

Throws:

GuidanceException - if there was an I/O or other error in generating the input stream

run

public void run(TestClass testClass,
                FrameworkMethod method,
                Object[] args)
         throws Throwable

Description copied from interface: Guidance

Runs a test method with generated arguments as input.

By default, this method simply runs the test method using a JUnit TrialRunner. Guidances can override this method to customize how test execution should be performed once inputs are generated. For example, a guidance that supports non-deterministic test code may wish to execute multiple trials per generated input.

Parameters:

testClass - the test class

method - the test method within the test class

args - the arguments to the test method (i.e., the test input)

Throws:

Throwable - any exception that may be thrown during test execution

handleResult

public void handleResult(Result result,
                         Throwable error)
                  throws GuidanceException

Handles the result of a test execution. This method mostly delegates to the ZestGuidance, but additionally incorporates some custom logic to support minimization

Specified by:

handleResult in interface Guidance

Overrides:

handleResult in class ZestGuidance

Parameters:

result - the result of the fuzzing trial

error - the error thrown during the trial, or null

Throws:

GuidanceException - if there was an I/O or other error in handling the result

saveCurrentInput

protected void saveCurrentInput(org.eclipse.collections.impl.set.mutable.primitive.IntHashSet responsibilities,
                                String why)
                         throws IOException

Saves an interesting input to the queue.

Overrides:

saveCurrentInput in class ZestGuidance

Throws:

IOException

completeCycle

protected void completeCycle()

Handles the end of fuzzing cycle (i.e., having gone through the entire queue)

Overrides:

completeCycle in class ZestGuidance

generateCallBack

public Consumer<TraceEvent> generateCallBack(Thread thread)

Description copied from interface: Guidance

Returns a callback generator for a thread's event trace.

The application under test is instrumented such that each thread generates a sequence of TraceEvents that may be handled by a separate callback method (though it may also be the same callback).

The callback provided by this method will typically be used for collection execution information such as branch coverage, which in turn is used for constructing the next input stream.

This method is a supplier of event consumers. It is invoked once per new application thread spawned during fuzzing.

Specified by:

generateCallBack in interface Guidance

Overrides:

generateCallBack in class ZestGuidance

Parameters:

thread - the thread whose events to handle

Returns:

a callback that handles trace events generated by that thread

handleEvent

protected void handleEvent(TraceEvent e)

Handles a trace event generated during test execution

Overrides:

handleEvent in class ZestGuidance

Parameters:

e - the trace event to be handled