Skip to main content

Fuzz test Python modules with libFuzzer.

Project description

buildstatus coverage


Use libFuzzer to fuzz test Python 3.6+ C extension modules.


clang 8 or later is required.

$ apt install clang
$ pip install pyfuzzer

Example Usage

Hello world

Use the default mutator pyfuzzer.mutators.generic when testing the module hello_world.

$ cd examples/hello_world
$ pyfuzzer run -l max_total_time=1 hello_world.c
<lots of libFuzzer output>

Print the function calls that found new code paths. This information is usually useful when writing unit tests.

$ pyfuzzer print_corpus
    tell(b'') = 5
    tell(b'\xfd#') = b'Hello!'
    tell(b'\x00') = True
    tell(b'\x00\xfd\x00') = 0
    tell(None) raises:
    Traceback (most recent call last):
      File "/home/erik/workspace/pyfuzzer/pyfuzzer/mutators/", line 35, in print_callable
        res = obj(*args)
    TypeError: expected bytes, NoneType found

See the hello_world for all files.

Hello world fatal error

Similar to the previous example, but triggers a fatal error when tell() is called with a bytes object longer than 2 bytes as its first argument.

$ cd examples/hello_world_fatal_error
$ pyfuzzer run hello_world.c
Fatal Python error: deallocating None

Current thread 0x00007f7ca99c2780 (most recent call first):

Print the function call that caused the crash. Just as expected, the first argument is clearly longer than 2 bytes.

$ pyfuzzer print_crashes
    tell(b'\n\xbf+') = None

See the hello_world_fatal_error for all files.

Custom mutator

Use the custom mutator hello_world_mutator when testing the module hello_world.

Testing with a custom mutator is often more efficient than using a generic one.

$ cd examples/hello_world_custom_mutator
$ pyfuzzer run -l max_total_time=1 -m hello_world.c

See the hello_world_custom_mutator for all files.


A mutator module uses data from libFuzzer to test a module. A mutator module must implement the function setup(module), where module is the module under test. It shall return a mutator instance that implements the methods test_one_input(self, data) and test_one_input_print(self, data), where data is the data generated by libFuzzer (as a bytes object).

test_one_input(self, data) performs the actual fuzz testing, while test_one_input_print(self, data) prints corpus and crashes.

A minimal mutator fuzz testing a CRC-32 algorithm could look like below. It simply calls crc_32() with data as its only argument.

from pyfuzzer.mutators.generic import print_callable

class Mutator:

    def __init__(self, module):
        self._module = module

    def test_one_input(self, data):
        return module.crc_32(data)

    def test_one_input_print(self, data):
        print_callable(self._module.crc_32, [data])

 def setup(module):
     return Mutator(module)


  • Add support to fuzz test pure Python modules by generating C code using Cython.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

pyfuzzer-0.19.0.tar.gz (12.4 kB view hashes)

Uploaded source

Supported by

AWS AWS Cloud computing Datadog Datadog Monitoring Facebook / Instagram Facebook / Instagram PSF Sponsor Fastly Fastly CDN Google Google Object Storage and Download Analytics Huawei Huawei PSF Sponsor Microsoft Microsoft PSF Sponsor NVIDIA NVIDIA PSF Sponsor Pingdom Pingdom Monitoring Salesforce Salesforce PSF Sponsor Sentry Sentry Error logging StatusPage StatusPage Status page