GitHub - jwilk/python-afl: American Fuzzy Lop fork server and instrumentation for pure-Python code (original) (raw)

This is experimental module that enablesAmerican 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:
• 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:
  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:
  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:
  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

• Taking a look at python-afl by Jussi Judin
• Introduction to Fuzzing in Python with AFL by Alex Gaynor
• AFL's README

Prerequisites

To build the module, you will need:

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

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