Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/jwilk/python-afl

American Fuzzy Lop fork server and instrumentation for pure-Python code
https://github.com/jwilk/python-afl

fuzzing security

Last synced: 9 days ago
JSON representation

American Fuzzy Lop fork server and instrumentation for pure-Python code

Host: GitHub
URL: https://github.com/jwilk/python-afl
Owner: jwilk
License: mit
Created: 2015-05-29T20:29:42.000Z (over 9 years ago)
Default Branch: master
Last Pushed: 2024-03-23T17:46:24.000Z (8 months ago)
Last Synced: 2024-08-09T00:21:57.912Z (3 months ago)
Topics: fuzzing, security
Language: Python
Homepage: https://jwilk.net/software/python-afl
Size: 339 KB
Stars: 348
Watchers: 16
Forks: 33
Open Issues: 14
Metadata Files:
- Readme: README.rst
- Funding: .github/FUNDING.yml
- License: LICENSE

Awesome Lists containing this project

README

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 ``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.

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.