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

  • Field Details

    • 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:

    • MEAN_MUTATION_SIZE

      protected final double MEAN_MUTATION_SIZE
      Mean number of contiguous bytes to mutate in each mutation.
      See Also:

    • 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:

    • 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:

    • DEMAND_DRIVEN_SPLICING_PROBABILITY

      protected final double DEMAND_DRIVEN_SPLICING_PROBABILITY
      Probability of splicing in ExecutionIndexingGuidance.MappedInput.getOrGenerateFresh(ExecutionIndex, Random)
      See Also:

  • Constructor Details

    • 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, Long trials, File outputDirectory, File[] seedFiles, Random sourceOfRandomness) 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.
      trials - the number of trials for which to run fuzzing, where null indicates unlimited trials.
      outputDirectory - the directory where fuzzing results will be written
      seedFiles - the seed input files to be used as initial inputs
      sourceOfRandomness - a pseudo-random number generator
      Throws:
      IOException - if the output directory could not be prepared

  • Method Details

    • 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

    • beforeRun

      public void beforeRun()
      Description copied from interface: Guidance
      Runs once before each trial, after its arguments are generated.

      This is a hook for per-trial setup that a guidance needs but that is not itself test execution. For example, a coverage-guided guidance installs its coverage listener here. The default does nothing.

    • 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