Atheris

Atheris

Atheris is a coverage-guided Python fuzzer built on libFuzzer. It enables fuzzing of both pure Python code and Python C extensions with integrated AddressSanitizer support for detecting memory corruption issues.

When to Use

Choose Atheris when:

• Fuzzing pure Python code with coverage guidance
• Testing Python C extensions for memory corruption
• Integration with libFuzzer ecosystem is desired
• AddressSanitizer support is needed

Quick Start

import sysimport atheris
@atheris.instrument_funcdef TestOneInput(data: bytes):    if len(data) == 4:        if data[0] == 0x46:  # "F"            if data[1] == 0x55:  # "U"                if data[2] == 0x5A:  # "Z"                    if data[3] == 0x5A:  # "Z"                        raise RuntimeError("You caught me")
def main():    atheris.Setup(sys.argv, TestOneInput)    atheris.Fuzz()
if __name__ == "__main__":    main()

Run:

uv run python fuzz.py

Installation

Atheris supports 32-bit and 64-bit Linux, and macOS. We recommend fuzzing on Linux because it's simpler to manage and often faster.

Prerequisites

• Python 3.7 or later
• Recent version of clang (preferably latest release)
• For Docker users: Docker Desktop

Linux/macOS

uv init --bare   # once, if the harness directory is not yet a uv projectuv add atheris

Docker Environment (Recommended)

For a fully operational Linux environment with all dependencies configured:

# https://hub.docker.com/_/pythonARG PYTHON_VERSION=3.11
FROM python:$PYTHON_VERSION-slim-bookworm
RUN python --version
RUN apt update && apt install -y \    ca-certificates \    wget \    && rm -rf /var/lib/apt/lists/*
# LLVM builds version 15-19 for Debian 12 (Bookworm)# https://apt.llvm.org/bookworm/dists/ARG LLVM_VERSION=19
RUN echo "deb http://apt.llvm.org/bookworm/ llvm-toolchain-bookworm-$LLVM_VERSION main" > /etc/apt/sources.list.d/llvm.listRUN echo "deb-src http://apt.llvm.org/bookworm/ llvm-toolchain-bookworm-$LLVM_VERSION main" >> /etc/apt/sources.list.d/llvm.listRUN wget -qO- https://apt.llvm.org/llvm-snapshot.gpg.key > /etc/apt/trusted.gpg.d/apt.llvm.org.asc
RUN apt update && apt install -y \    build-essential \    clang-$LLVM_VERSION \    && rm -rf /var/lib/apt/lists/*
ENV APP_DIR "/app"RUN mkdir $APP_DIRWORKDIR $APP_DIR
ENV VIRTUAL_ENV "/opt/venv"RUN python -m venv $VIRTUAL_ENVENV PATH "$VIRTUAL_ENV/bin:$PATH"
# https://github.com/google/atheris/blob/master/native_extension_fuzzing.md#step-1-compiling-your-extensionENV CC="clang-$LLVM_VERSION"ENV CFLAGS "-fsanitize=address,fuzzer-no-link"ENV CXX="clang++-$LLVM_VERSION"ENV CXXFLAGS "-fsanitize=address,fuzzer-no-link"ENV LDSHARED="clang-$LLVM_VERSION -shared"ENV LDSHAREDXX="clang++-$LLVM_VERSION -shared"ENV ASAN_SYMBOLIZER_PATH="/usr/bin/llvm-symbolizer-$LLVM_VERSION"
# Allow Atheris to find fuzzer sanitizer shared libs# https://github.com/google/atheris#building-from-sourceRUN LIBFUZZER_LIB=$($CC -print-file-name=libclang_rt.fuzzer_no_main-$(uname -m).a) \    python -m pip install --no-binary atheris atheris
# https://github.com/google/atheris/blob/master/native_extension_fuzzing.md#option-a-sanitizerlibfuzzer-preloadsENV LD_PRELOAD "$VIRTUAL_ENV/lib/python3.11/site-packages/asan_with_fuzzer.so"
# 1. Skip memory allocation failures for now, they are common, and low impact (DoS)# 2. https://github.com/google/atheris/blob/master/native_extension_fuzzing.md#leak-detectionENV ASAN_OPTIONS "allocator_may_return_null=1,detect_leaks=0"
CMD ["/bin/bash"]

Build and run:

docker build -t atheris .docker run -it atheris

Verification

python -c "import atheris; print(atheris.__version__)"

Writing a Harness

Harness Structure for Pure Python

import sysimport atheris
@atheris.instrument_funcdef TestOneInput(data: bytes):    """    Fuzzing entry point. Called with random byte sequences.
    Args:        data: Random bytes generated by the fuzzer    """    # Add input validation if needed    if len(data) < 1:        return
    # Call your target function    try:        your_target_function(data)    except ValueError:        # Expected exceptions should be caught        pass    # Let unexpected exceptions crash (that's what we're looking for!)
def main():    atheris.Setup(sys.argv, TestOneInput)    atheris.Fuzz()
if __name__ == "__main__":    main()

Structured Input with FuzzedDataProvider

A target taking several typed arguments wastes most of the fuzzer's inputs if the harness slices data by hand, because every mutation shifts the byte offsets of everything after it. atheris.FuzzedDataProvider splits one bytes input into typed values instead:

fdp = atheris.FuzzedDataProvider(data)name = fdp.ConsumeUnicodeNoSurrogates(fdp.ConsumeIntInRange(0, 64))strict = fdp.ConsumeBool()

See structured-input.md [blocked] for the full method reference, the fixed-draw- order rule, and what each method returns once the buffer runs dry.

Harness Rules

See Also: For detailed harness writing techniques, patterns for handling complex inputs, and advanced strategies, see the fuzz-harness-writing technique skill.

Fuzzing Pure Python Code

For fuzzing broader parts of an application or library, use instrumentation functions:

import atheriswith atheris.instrument_imports():    import your_module    from another_module import target_function
def TestOneInput(data: bytes):    target_function(data)
atheris.Setup(sys.argv, TestOneInput)atheris.Fuzz()

Instrumentation Options:

• atheris.instrument_func - Decorator for single function instrumentation
• atheris.instrument_imports() - Context manager for instrumenting all imported modules
• atheris.instrument_all() - Instrument all Python code system-wide

Fuzzing Python C Extensions

Python C extensions require compilation with specific flags for instrumentation and sanitizer support.

Environment Configuration

If using the provided Dockerfile, these are already configured. For local setup:

export CC="clang"export CFLAGS="-fsanitize=address,fuzzer-no-link"export CXX="clang++"export CXXFLAGS="-fsanitize=address,fuzzer-no-link"export LDSHARED="clang -shared"

Example: Fuzzing cbor2

Install the extension from source:

CBOR2_BUILD_C_EXTENSION=1 uv add --no-binary-package cbor2 'cbor2==5.6.4'

The --no-binary-package flag ensures the C extension is compiled locally with instrumentation rather than pulled as a prebuilt wheel. Persist that choice with no-binary-package = ["cbor2"] under [tool.uv] in pyproject.toml, or a later uv sync can silently swap in an uninstrumented wheel.

Create cbor2-fuzz.py:

import sysimport atheris
# _cbor2 ensures the C library is importedfrom _cbor2 import loads
def TestOneInput(data: bytes):    try:        loads(data)    except Exception:        # We're searching for memory corruption, not Python exceptions        pass
def main():    atheris.Setup(sys.argv, TestOneInput)    atheris.Fuzz()
if __name__ == "__main__":    main()

Run:

uv run python cbor2-fuzz.py

Important: When running locally (not in Docker), you must set LD_PRELOAD manually.

Corpus Management

Creating Initial Corpus

mkdir corpus# Add seed inputsecho "test data" > corpus/seed1echo '{"key": "value"}' > corpus/seed2

Run with corpus:

uv run python fuzz.py corpus/

Corpus Minimization

Atheris inherits corpus minimization from libFuzzer:

uv run python fuzz.py -merge=1 new_corpus/ old_corpus/

See Also: For corpus creation strategies, dictionaries, and seed selection, see the fuzzing-corpus technique skill.

Running Campaigns

Basic Run

uv run python fuzz.py

With Corpus Directory

uv run python fuzz.py corpus/

Common Options

# Run for 10 minutesuv run python fuzz.py -max_total_time=600
# Limit input sizeuv run python fuzz.py -max_len=1024
# Run with multiple workersuv run python fuzz.py -workers=4 -jobs=4

Interpreting Output

Sanitizer Integration

AddressSanitizer (ASan)

AddressSanitizer is automatically integrated when using the provided Docker environment or when compiling with appropriate flags.

For local setup:

export CFLAGS="-fsanitize=address,fuzzer-no-link"export CXXFLAGS="-fsanitize=address,fuzzer-no-link"

Configure ASan behavior:

export ASAN_OPTIONS="allocator_may_return_null=1,detect_leaks=0"

LD_PRELOAD Configuration

For native extension fuzzing:

export LD_PRELOAD="$(python -c 'import atheris; import os; print(os.path.join(os.path.dirname(atheris.__file__), "asan_with_fuzzer.so"))')"

See Also: For detailed sanitizer configuration, common issues, and advanced flags, see the address-sanitizer and undefined-behavior-sanitizer technique skills.

Common Sanitizer Issues

Advanced Usage

Tips and Tricks

Custom Instrumentation

Fine-tune what gets instrumented:

import atheris
# Instrument only specific moduleswith atheris.instrument_imports():    import target_module# Don't instrument test harness code
def TestOneInput(data: bytes):    target_module.parse(data)

Performance Tuning

UndefinedBehaviorSanitizer (UBSan)

Add UBSan to catch additional bugs:

export CFLAGS="-fsanitize=address,undefined,fuzzer-no-link"export CXXFLAGS="-fsanitize=address,undefined,fuzzer-no-link"

Note: Modify flags in Dockerfile if using containerized setup.

Real-World Examples

Two complete harnesses — a pure-Python parser and an HTTP response parser — are in examples.md [blocked].

Troubleshooting

Related Skills

Technique Skills

Related Fuzzers

Resources

Key External Resources

Atheris GitHub Repository Official repository with installation instructions, examples, and documentation for fuzzing both pure Python and native extensions.

Native Extension Fuzzing Guide Comprehensive guide covering compilation flags, LD_PRELOAD setup, sanitizer configuration, and troubleshooting for Python C extensions.

Continuously Fuzzing Python C Extensions Trail of Bits blog post covering CI/CD integration, ClusterFuzzLite setup, and real-world examples of fuzzing Python C extensions in continuous integration pipelines.

ClusterFuzzLite Python Integration Guide for integrating Atheris fuzzing into CI/CD pipelines using ClusterFuzzLite for automated continuous fuzzing.

Video Resources

Videos and tutorials are available in the main Atheris documentation and libFuzzer resources.