How google/atheris works
Atheris is a coverage-guided fuzzer for Python code and CPython native extensions. A user configures a test callback with Setup, then starts the fuzzing loop with Fuzz; generated inputs reach the callback, while instrumentation supplies coverage feedback for mutation-guided exploration. Python instrumentation can be enabled through import hooks, function decoration, or a whole-interpreter pass; experimental regex and string hooks and structure-aware mutators extend that workflow. The graph reflects documented behavior and source-index references; several native and optional subsystems were not excerpted, so their internal links are omitted.
Main entry points: atheris.cc Setup and Fuzz · core.cc Fuzz runtime · helpers.py Protobuf mutator adapter · instrument_bytecode.py Bytecode instrumentor
Components 19
Fuzzing API
- Setup and Fuzz
src/native/atheris.cc - Input callback
src/native/core.cc
Python Instrumentation
- Import instrumentation
src/import_hook.py - Bytecode instrumentor
src/instrument_bytecode.py - Python version support
src/version_dependent.py - Regex and string hooks
src/function_hooks.py
Native Engine
- Fuzz runtime
src/native/core.cc - Coverage counters
src/native/counters.h - Comparison tracing
src/native/tracer.h - Timeout handling
src/native/timeout.h - Code table generation
src/native/codetable_gen.cc - Fuzzed data provider
src/native/fuzzed_data_provider.cc - Mock libFuzzer
src/mock_libfuzzer/mock_libfuzzer_lib.h
Extensions
- Custom mutators
src/native/custom_mutator.cc - Custom crossovers
src/native/custom_crossover.cc - Protobuf mutator adapter
contrib/libprotobuf_mutator/atheris_libprotobuf_mutator/helpers.py - Protobuf mutation binding
contrib/libprotobuf_mutator/atheris_libprotobuf_mutator/mutator.cc - Example fuzz target
example_fuzzers/example_library.py
Other components
- Fuzzer author
Connections 21
- Fuzzer author → Setup and Fuzz: configures callback
- Setup and Fuzz → Input callback: registers
src/native/atheris.cc - Setup and Fuzz → Fuzz runtime: starts fuzzing
- Fuzz runtime → Input callback: invokes with input
src/native/core.cc - Fuzzer author → Import instrumentation: instruments imports
- Import instrumentation → Bytecode instrumentor: uses
src/import_hook.py - Bytecode instrumentor → Python version support: uses compatibility rules
src/instrument_bytecode.py - Fuzzer author → Bytecode instrumentor: decorates or instruments all
- Fuzzer author → Regex and string hooks: enables hooks
- Fuzz runtime → Coverage counters: initializes counters
src/native/core.cc - Fuzz runtime → Comparison tracing: uses tracing
src/native/core.cc - Fuzz runtime → Timeout handling: uses timeout handling
src/native/core.cc - Setup and Fuzz → Code table generation: exports code table generation
src/native/atheris.cc - Fuzzer author → Fuzzed data provider: consumes fuzz bytes
- Setup and Fuzz → Custom mutators: registers custom mutator
- Setup and Fuzz → Custom crossovers: registers custom crossover
- Protobuf mutator adapter → Setup and Fuzz: wraps setup
contrib/libprotobuf_mutator/atheris_libprotobuf_mutator/helpers.py - Protobuf mutator adapter → Protobuf mutation binding: calls mutation bindings
contrib/libprotobuf_mutator/atheris_libprotobuf_mutator/helpers.py - Protobuf mutator adapter → Input callback: adapts input callback
contrib/libprotobuf_mutator/atheris_libprotobuf_mutator/helpers.py - Mock libFuzzer → Fuzz runtime: supplies mock driver
- Fuzzer author → Example fuzz target: fuzzes example