python-afl

To enable American Fuzzy Lop (AFL) fork server and instrumentation for pure-Python code, add afl.init() to your target program. It is recommended to do this after all other modules have been imported.

Note that instrumentation is implemented via a Python trace function that triggers whenever a new local scope is entered. For correct instrumentation, you may need to wrap your main program logic inside a function.

import afl
afl.init()

Instead of using the standard afl-fuzz, use py-afl-fuzz to fuzz Python scripts.

To improve performance when instrumentation is slow, you can enable "dumb mode" using the -n flag. This leverages the fork server while reducing instrumentation overhead.

Requirements:

• For dumb mode (-n), afl-fuzz version 1.95b or higher is required.

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

# Example with dumb mode
py-afl-fuzz -n [options] -- /path/to/fuzzed/python/script

To build the python-afl module, ensure you have the following:

• Python: 2.6+ or 3.2+
• Cython: $\ge$ 0.28 (required at build time)

To run py-afl-fuzz, you must have the standard AFL (American Fuzzy Lop) installed on your system.

Persistent mode allows processing multiple inputs before restarting the process, which significantly speeds up fuzzing.

To use it:

1. Wrap your tested code in a while afl.loop(N): loop, where N is the number of inputs to process before a restart.
2. Do not call afl.init() when using persistent mode.
3. If your code reads from sys.stdin, you must call sys.stdin.seek(0) at the start of every loop iteration to rewind the input.

Requirements:

• afl-fuzz version 1.82b or higher.
• The environment variable PYTHON_AFL_PERSISTENT must be set (this is done automatically by py-afl-fuzz).

import sys
import afl

# Note: Do NOT call afl.init() here for persistent mode

while afl.loop(100): # N=100
    sys.stdin.seek(0)
    # ... your test code ...

The following environment variables control the behavior of python-afl: