/usr/share/doc/python3-afl/README is in python3-afl 0.6.1-1build1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 | This is experimental module that enables
`American fuzzy lop`_ fork server and instrumentation for pure-Python code.
.. _American fuzzy lop: http://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 ``N`` is the number of inputs to process before restarting.
You shouldn't call ``afl.init()`` in this case.
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.
Further reading
---------------
* `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 <http://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
|