Package edu.berkeley.cs.jqf.fuzz.afl

Class AFLGuidance

java.lang.Object
edu.berkeley.cs.jqf.fuzz.afl.AFLGuidance
All Implemented Interfaces:
Guidance
Direct Known Subclasses:
PerfFuzzGuidance
public class AFLGuidance extends Object implements Guidance
A front-end that uses AFL for guided fuzzing.

An instance of this class actually communicates with a proxy that sits between AFL and JQF. The proxy is the target program launched by AFL; it passes messages back and forth between AFL and JQF and helps populate the shared memory coverage buffer that the JVM cannot access.

Author:
Rohan Padhye and Caroline Lemieux

  • Field Details

    • inputFile

      protected File inputFile
      The file in which AFL will write its input.

    • proxyInput

      protected final InputStream proxyInput
      The communication channel from AFL proxy to us.

    • proxyOutput

      protected final OutputStream proxyOutput
      The communication channel from us to the AFL proxy.

    • COVERAGE_MAP_SIZE

      protected static final int COVERAGE_MAP_SIZE
      The size of the "coverage" map that will be sent to AFL.
      See Also:

    • traceBits

      protected byte[] traceBits
      The "coverage" map that will be sent to AFL.

    • everything_ok

      protected boolean everything_ok
      Whether to keep executing more inputs.

    • feedback

      protected ByteBuffer feedback
      The bits that will be communicated to the AFL proxy.

  • Constructor Details

    • AFLGuidance

      public AFLGuidance(File inputFile, File inPipe, File outPipe) throws IOException
      Creates an instance of an AFLGuidance given file handles for I/O.
      Parameters:
      inputFile - the file that AFL will write inputs to
      inPipe - a FIFO-like pipe for receiving messages from the AFL proxy
      outPipe - a FIFO-like pipe for sending messages to the AFL proxy
      Throws:
      IOException - if any file or pipe could not be opened

    • AFLGuidance

      public AFLGuidance(String inputFileName, String inPipeName, String outPipeName) throws IOException
      Creates an instance of an AFLGuidance given file names for I/O.
      Parameters:
      inputFileName - the file that AFL will write inputs to
      inPipeName - a FIFO-like pipe for receiving messages from the AFL proxy
      outPipeName - a FIFO-like pipe for sending messages to the AFL proxy
      Throws:
      IOException - if any file or pipe could not be opened

  • Method Details

    • finalize

      public void finalize()
      Closes the pipes used to communicate with the AFL proxy.
      Overrides:
      finalize in class Object

    • observeGuidance

      public String observeGuidance()
      Description copied from interface: Guidance

      This method is only invoked during optional observability logging to provide the type of guidance used for input generation.

      Specified by:
      observeGuidance in interface Guidance

    • getInput

      public InputStream getInput() throws IllegalStateException, GuidanceException
      Returns an input stream containing the bytes that AFL has written to.
      Specified by:
      getInput in interface Guidance
      Returns:
      a stream of bytes to be used by the input generator(s)
      Throws:
      IllegalStateException - if the last hasInput() returned false
      GuidanceException - if there was an I/O error when opening the file

    • hasInput

      public boolean hasInput()
      Waits for the AFL proxy to send a ready signal.
      Specified by:
      hasInput in interface Guidance
      Returns:
      Returns true in the absence of I/O errors

    • handleResult

      public void handleResult(Result result, Throwable error)
      Notifies the AFL proxy that a run has completed and whether it was a success. 1

      This method also sends coverage information back to the AFL proxy, which is responsible for updating the shared memory region used by afl-fuzz.

      If the trial resulted in an assumption violation, we do not mark it is a crash, but we also do not send any coverage feedback so that AFL does not consider the last input interesting enough to keep in its queue.

      Specified by:
      handleResult in interface Guidance
      Parameters:
      result - the result of the fuzzing trial
      error - the exception thrown by the test, or null

    • generateCallBack

      public Consumer<TraceEvent> generateCallBack(Thread thread)
      Returns a callback to handle trace events.

      The call back is the same for all threads. This guidance does not use any synchronization and hence the feedback is not guaranteed to be reliable when multiple threads are used.

      Specified by:
      generateCallBack in interface Guidance
      Parameters:
      thread - the thread whose events to handle
      Returns:
      a callback to handle trace events

    • handleEvent

      protected void handleEvent(TraceEvent e)
      Records branch coverage by snooping on branch events and incrementing the branch-specific counter in the tracebits map.
      Parameters:
      e - the trace event to handle

    • incrementTraceBits

      protected void incrementTraceBits(int index)
      Increments the 8-bit counter at given index.

      Overflows are possible but ignored (as in AFL).

      Parameters:
      index - the key in the trace bits map

    • clearFeedbackBuffer

      protected void clearFeedbackBuffer()
      Clears the feedback buffer by resetting it to zero.

    • checkForTimeouts

      protected void checkForTimeouts() throws TimeoutException
      Throws:
      TimeoutException