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