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

Class 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 Detail

      • 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:
        Constant Field Values

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

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

      • finalize

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

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