Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
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: 2 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.
Further reading
---------------* `Taking a look at python-afl `_ by Jussi Judin
* `Introduction to Fuzzing in Python with AFL `_ by Alex Gaynor
* `AFL's README `_Prerequisites
-------------To build the module, you will need:
* Python 2.6+ or 3.2+
* Cython ≥ 0.28 (only at build time)*py-afl-fuzz* requires AFL proper to be installed.
.. vim:ft=rst ts=3 sts=3 sw=3 et