This is experimental module that enables
American Fuzzy Lop_ fork server and instrumentation for pure-Python code.
.. _American Fuzzy Lop: https://lcamtuf.coredump.cx/afl/
Add this code (ideally, after all other modules are already imported) to the target program:
.. code:: python
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.
.. _trace function: https://docs.python.org/2/library/sys.html#sys.settrace
Optionally, add this code at the end of the target program:
.. code:: python
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:
.. code:: python
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:
.. code:: python
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.
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.
.. _TSTL: https://github.com/agroce/tstl
Multi-threaded code is not supported.
Taking a look at python-afl <https://barro.github.io/2018/01/taking-a-look-at-python-afl/>_ by Jussi JudinIntroduction to Fuzzing in Python with AFL <https://alexgaynor.net/2015/apr/13/introduction-to-fuzzing-in-python-with-afl/>_ by Alex GaynorAFL's README <https://lcamtuf.coredump.cx/afl/README.txt>_To build the module, you will need:
py-afl-fuzz requires AFL proper to be installed.
.. vim:ft=rst ts=3 sts=3 sw=3 et