/python-afl

American Fuzzy Lop fork server and instrumentation for pure-Python code

Primary LanguagePythonMIT LicenseMIT

This is experimental module that enables American Fuzzy Lop fork server and instrumentation for pure-Python code.

HOWTO

  • Add this code (ideally, after all other modules are already imported) to the target program:

    import afl
afl.init()

  • The instrumentation is currently implemented with a trace function, which is called whenever a new local scope is entered. You might need to wrap the code of the main program in a function to get it instrumented correctly.

  • Optionally, add this code at the end of the target program:

    os._exit(0)

    This should speed up fuzzing considerably, at the risk of not catching bugs that could happen during normal exit.

  • For persistent mode, wrap the tested code in this loop:

    while afl.loop(N):
   ...

    where N is the number of inputs to process before restarting.

    You shouldn't call afl.init() in this case.

    If you read input from sys.stdin, you must rewind it in every loop iteration:

    sys.stdin.seek(0)

    afl-fuzz ≥ 1.82b is required for this feature.

  • Use py-afl-fuzz instead of afl-fuzz:

    $ py-afl-fuzz [options] -- /path/to/fuzzed/python/script [...]

  • The instrumentation is a bit slow at the moment, so you might want to enable the dumb mode (-n), while still leveraging the fork server.

    afl-fuzz ≥ 1.95b is required for this feature.

Environment variables

The following environment variables affect python-afl behavior:

PYTHON_AFL_SIGNAL

If this variable is set, python-afl installs an exception hook that kills the current process with the selected signal. That way afl-fuzz can treat unhandled exceptions as crashes.

By default, py-afl-fuzz, py-afl-showmap, python-afl-cmin, and py-afl-tmin set this variable to SIGUSR1.

You can set PYTHON_AFL_SIGNAL to another signal; or set it to 0 to disable the exception hook.

PYTHON_AFL_PERSISTENT

Persistent mode is enabled only if this variable is set.

py-afl-fuzz sets this variable automatically, so there should normally no need to set it manually.

PYTHON_AFL_TSTL
TSTL test harness code is ignored if this variable is set; relevant only to users of TSTL interface to python-afl.

Bugs

Multi-threaded code is not supported.

Further reading

Prerequisites

To build the module, you will need:

  • Python 2.6+ or 3.2+
  • Cython ≥ 0.19 (only at build time)

py-afl-fuzz requires AFL proper to be installed.