python-afl
python-afl copied to clipboard
jwilk
American Fuzzy Lop fork server and instrumentation for pure-Python code
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/
HOWTO
-
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
Nis 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.
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.
.. _TSTL: https://github.com/agroce/tstl
Bugs
Multi-threaded code is not supported.
Further reading
-
Taking a look at python-afl <https://barro.github.io/2018/01/taking-a-look-at-python-afl/>_ by Jussi Judin -
Introduction to Fuzzing in Python with AFL <https://alexgaynor.net/2015/apr/13/introduction-to-fuzzing-in-python-with-afl/>_ by Alex Gaynor -
AFL's README <https://lcamtuf.coredump.cx/afl/README.txt>_
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.
.. vim:ft=rst ts=3 sts=3 sw=3 et
jwilk