# google/atheris architecture

> Architecture diagram of the GitHub repository google/atheris, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-11-16). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/google/atheris
- Repository: https://github.com/google/atheris

## Overview

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: [`src/native/atheris.cc`](https://github.com/google/atheris/blob/master/src/native/atheris.cc) (Setup and Fuzz), [`src/native/core.cc`](https://github.com/google/atheris/blob/master/src/native/core.cc) (Fuzz runtime), [`contrib/libprotobuf_mutator/atheris_libprotobuf_mutator/helpers.py`](https://github.com/google/atheris/blob/master/contrib/libprotobuf_mutator/atheris_libprotobuf_mutator/helpers.py) (Protobuf mutator adapter), [`src/instrument_bytecode.py`](https://github.com/google/atheris/blob/master/src/instrument_bytecode.py) (Bytecode instrumentor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Fuzzing API"]
  node_setup["Setup and Fuzz<br/>[atheris.cc]"]
  node_callback["Input callback<br/>[core.cc]"]
end

subgraph group_python["Python Instrumentation"]
  node_instrument_import["Import instrumentation<br/>[import_hook.py]"]
  node_bytecode["Bytecode instrumentor"]
  node_version["Python version support"]
  node_hooks["Regex and string hooks<br/>[function_hooks.py]"]
end

subgraph group_native["Native Engine"]
  node_core["Fuzz runtime<br/>[core.cc]"]
  node_coverage["Coverage counters<br/>[counters.h]"]
  node_tracer["Comparison tracing<br/>[tracer.h]"]
  node_timeout["Timeout handling<br/>[timeout.h]"]
  node_codetable["Code table generation<br/>[codetable_gen.cc]"]
  node_data_provider["Fuzzed data provider"]
  node_mock_engine["Mock libFuzzer"]
end

subgraph group_extensions["Extensions"]
  node_mutators["Custom mutators<br/>[custom_mutator.cc]"]
  node_crossovers["Custom crossovers"]
  node_protobuf_helpers["Protobuf mutator adapter<br/>[helpers.py]"]
  node_protobuf_native["Protobuf mutation binding<br/>[mutator.cc]"]
  node_example_target["Example fuzz target<br/>[example_library.py]"]
end

node_user(("Fuzzer author"))

node_user -->|"configures callback"| node_setup
node_setup -->|"registers"| node_callback
node_setup -->|"starts fuzzing"| node_core
node_core -->|"invokes with input"| node_callback
node_user -->|"instruments imports"| node_instrument_import
node_instrument_import -->|"uses"| node_bytecode
node_bytecode -->|"uses compatibility rules"| node_version
node_user -->|"decorates or instruments all"| node_bytecode
node_user -->|"enables hooks"| node_hooks
node_core -->|"initializes counters"| node_coverage
node_core -->|"uses tracing"| node_tracer
node_core -->|"uses timeout handling"| node_timeout
node_setup -->|"exports code table generation"| node_codetable
node_user -->|"consumes fuzz bytes"| node_data_provider
node_setup -->|"registers custom mutator"| node_mutators
node_setup -->|"registers custom crossover"| node_crossovers
node_protobuf_helpers -->|"wraps setup"| node_setup
node_protobuf_helpers -->|"calls mutation bindings"| node_protobuf_native
node_protobuf_helpers -->|"adapts input callback"| node_callback
node_mock_engine -.->|"supplies mock driver"| node_core
node_user -.->|"fuzzes example"| node_example_target

click node_setup "https://github.com/google/atheris/blob/master/src/native/atheris.cc"
click node_callback "https://github.com/google/atheris/blob/master/src/native/core.cc"
click node_instrument_import "https://github.com/google/atheris/blob/master/src/import_hook.py"
click node_bytecode "https://github.com/google/atheris/blob/master/src/instrument_bytecode.py"
click node_version "https://github.com/google/atheris/blob/master/src/version_dependent.py"
click node_hooks "https://github.com/google/atheris/blob/master/src/function_hooks.py"
click node_core "https://github.com/google/atheris/blob/master/src/native/core.cc"
click node_coverage "https://github.com/google/atheris/blob/master/src/native/counters.h"
click node_tracer "https://github.com/google/atheris/blob/master/src/native/tracer.h"
click node_timeout "https://github.com/google/atheris/blob/master/src/native/timeout.h"
click node_codetable "https://github.com/google/atheris/blob/master/src/native/codetable_gen.cc"
click node_data_provider "https://github.com/google/atheris/blob/master/src/native/fuzzed_data_provider.cc"
click node_mock_engine "https://github.com/google/atheris/blob/master/src/mock_libfuzzer/mock_libfuzzer_lib.h"
click node_mutators "https://github.com/google/atheris/blob/master/src/native/custom_mutator.cc"
click node_crossovers "https://github.com/google/atheris/blob/master/src/native/custom_crossover.cc"
click node_protobuf_helpers "https://github.com/google/atheris/blob/master/contrib/libprotobuf_mutator/atheris_libprotobuf_mutator/helpers.py"
click node_protobuf_native "https://github.com/google/atheris/blob/master/contrib/libprotobuf_mutator/atheris_libprotobuf_mutator/mutator.cc"
click node_example_target "https://github.com/google/atheris/blob/master/example_fuzzers/example_library.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_setup,node_callback toneBlue
class node_instrument_import,node_bytecode,node_version,node_hooks toneAmber
class node_core,node_coverage,node_tracer,node_timeout,node_codetable,node_data_provider,node_mock_engine toneMint
class node_mutators,node_crossovers,node_protobuf_helpers,node_protobuf_native,node_example_target toneRose
class node_user toneIndigo
```

## Components

### Fuzzing API

- [Setup and Fuzz](https://github.com/google/atheris/blob/master/src/native/atheris.cc): `src/native/atheris.cc`
- [Input callback](https://github.com/google/atheris/blob/master/src/native/core.cc): `src/native/core.cc`

### Python Instrumentation

- [Import instrumentation](https://github.com/google/atheris/blob/master/src/import_hook.py): `src/import_hook.py`
- [Bytecode instrumentor](https://github.com/google/atheris/blob/master/src/instrument_bytecode.py): `src/instrument_bytecode.py`
- [Python version support](https://github.com/google/atheris/blob/master/src/version_dependent.py): `src/version_dependent.py`
- [Regex and string hooks](https://github.com/google/atheris/blob/master/src/function_hooks.py): `src/function_hooks.py`

### Native Engine

- [Fuzz runtime](https://github.com/google/atheris/blob/master/src/native/core.cc): `src/native/core.cc`
- [Coverage counters](https://github.com/google/atheris/blob/master/src/native/counters.h): `src/native/counters.h`
- [Comparison tracing](https://github.com/google/atheris/blob/master/src/native/tracer.h): `src/native/tracer.h`
- [Timeout handling](https://github.com/google/atheris/blob/master/src/native/timeout.h): `src/native/timeout.h`
- [Code table generation](https://github.com/google/atheris/blob/master/src/native/codetable_gen.cc): `src/native/codetable_gen.cc`
- [Fuzzed data provider](https://github.com/google/atheris/blob/master/src/native/fuzzed_data_provider.cc): `src/native/fuzzed_data_provider.cc`
- [Mock libFuzzer](https://github.com/google/atheris/blob/master/src/mock_libfuzzer/mock_libfuzzer_lib.h): `src/mock_libfuzzer/mock_libfuzzer_lib.h`

### Extensions

- [Custom mutators](https://github.com/google/atheris/blob/master/src/native/custom_mutator.cc): `src/native/custom_mutator.cc`
- [Custom crossovers](https://github.com/google/atheris/blob/master/src/native/custom_crossover.cc): `src/native/custom_crossover.cc`
- [Protobuf mutator adapter](https://github.com/google/atheris/blob/master/contrib/libprotobuf_mutator/atheris_libprotobuf_mutator/helpers.py): `contrib/libprotobuf_mutator/atheris_libprotobuf_mutator/helpers.py`
- [Protobuf mutation binding](https://github.com/google/atheris/blob/master/contrib/libprotobuf_mutator/atheris_libprotobuf_mutator/mutator.cc): `contrib/libprotobuf_mutator/atheris_libprotobuf_mutator/mutator.cc`
- [Example fuzz target](https://github.com/google/atheris/blob/master/example_fuzzers/example_library.py): `example_fuzzers/example_library.py`

### Other components

- **Fuzzer author**

## Connections

- Fuzzer author → Setup and Fuzz: configures callback
- Setup and Fuzz → Input callback: registers (evidence: `src/native/atheris.cc`)
- Setup and Fuzz → Fuzz runtime: starts fuzzing
- Fuzz runtime → Input callback: invokes with input (evidence: `src/native/core.cc`)
- Fuzzer author → Import instrumentation: instruments imports
- Import instrumentation → Bytecode instrumentor: uses (evidence: `src/import_hook.py`)
- Bytecode instrumentor → Python version support: uses compatibility rules (evidence: `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 (evidence: `src/native/core.cc`)
- Fuzz runtime → Comparison tracing: uses tracing (evidence: `src/native/core.cc`)
- Fuzz runtime → Timeout handling: uses timeout handling (evidence: `src/native/core.cc`)
- Setup and Fuzz → Code table generation: exports code table generation (evidence: `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 (evidence: `contrib/libprotobuf_mutator/atheris_libprotobuf_mutator/helpers.py`)
- Protobuf mutator adapter → Protobuf mutation binding: calls mutation bindings (evidence: `contrib/libprotobuf_mutator/atheris_libprotobuf_mutator/helpers.py`)
- Protobuf mutator adapter → Input callback: adapts input callback (evidence: `contrib/libprotobuf_mutator/atheris_libprotobuf_mutator/helpers.py`)
- Mock libFuzzer → Fuzz runtime: supplies mock driver
- Fuzzer author → Example fuzz target: fuzzes example
