/usr/share/doc/python3-afl/README.rst is in python3-afl 0.5.1-2build1.
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 | 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()
* 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.
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* 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.
.. vim:ts=3 sts=3 sw=3 et
|