Skip to content
master
Go to file
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
doc
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

README.rst

This is experimental module that enables American Fuzzy Lop fork server and instrumentation for pure-Python code.

HOWTO

  • Add this code (ideally, after all other modules are already imported) to the target program:

    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.

  • Optionally, add this code at the end of the target program:

    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:

    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:

    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.

Bugs

Multi-threaded code is not supported.

Further reading

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.

About

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

Resources

License

Sponsor this project

Learn more about GitHub Sponsors

Packages

No packages published
You can’t perform that action at this time.