# googleprojectzero/jackalope architecture

> Architecture diagram of the GitHub repository googleprojectzero/jackalope, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-20). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/googleprojectzero/jackalope
- Repository: https://github.com/googleprojectzero/jackalope

## Overview

##### Main Components
- Fuzzer Process (client)
– Core class: Fuzzer (manages corpus, coverage, scheduling)
– Threads: multiple fuzzing threads (-nthreads)
– Subcomponents (via factory/strategy pattern):
- Mutator Engine
- SampleDelivery (file or shared-memory)
- Instrumentation (TinyInst or sancov)
- PRNG (Mersenne Twister)
- RangeTracker (optional for read‐range tracking)
- Target Binary
– Receives sample via file or shared memory
– Runs under instrumentation/debugger
- Server Process (optional)
– Central coordinator for multi-machine fuzzing
– Collects “new coverage” samples and crashes from clients
– Distributes corpus updates back to clients
- Client Module
– Networking layer to talk to Server (over TCP/IPC)
– Used when “-server” or “-start_server” flags set

##### Relationships & Data Flows
a. Startup
– Fuzzer reads input directory (“-in”) → initializes corpus
– Optionally spawn Server (-start_server)
– Clients connect to Server (-server <address>)
b. Fuzz Loop (per thread)
1. Fuzzer pops a Sample from corpus queue
2. MutatorEngine.Mutate(Sample) → mutated Sample
3. SampleDelivery.Deliver(mutated Sample) → writes file or shmem
4. Instrumentation.Run(target, arguments) → executes target, gathers coverage data
5. Fuzzer analyzes coverage:
- If new coverage → enqueue Sample, notify Server via Client
- If crash → record crash, resend to Server for triage
6. AdjustSamplePriority(sample) → reinsert or discard
c. Server–Client
– Clients send “new sample + coverage metadata”
– Server merges into global corpus, broadcasts to other clients
– Server maintains persistent storage of best corpus

##### Architectural Patterns
- Plugin / Strategy Pattern: factories in Fuzzer for Mutator, Instrumentation, SampleDelivery, PRNG
- Multi-threading & concurrency: Fuzzer schedules jobs to worker threads; uses mutex, thread, shm helpers
- Client–Server / distributed fuzzer pattern
- Extension points: subclassing Fuzzer enables custom behavior

– Fuzzer (fuzzer.cpp/h)
– Mutator (mutator.cpp/h + mutators/grammar/)
– Instrumentation (instrumentation.cpp/h, sancov*, tinyinstinstrumentation.cpp/h)
– SampleDelivery (sampledelivery.cpp/h, shm.cpp/h)
– PRNG (prng.cpp/h, third_party/Mersenne/)
– Server (server.cpp/h)
– Client (client.cpp/h)
– RangeTracker (rangetracker.cpp/h)
– Minimizer (minimizer.cpp/h)
– Directory (directory.cpp/h)
– Mutex, Thread wrappers (mutex.cpp/h, thread.cpp/h)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Fuzzer Process
    subgraph "Fuzzer Process"
        direction TB
        Main["main.cpp"]:::util
        Fuzzer["Fuzzer"]:::core
        Corpus[(Corpus Storage)]:::external
        ThreadPool["Thread Pool"]:::util
        subgraph "Plugin Factories"
            direction TB
            MutatorEngine["Mutator Engine"]:::core
            SampleDelivery["Sample Delivery"]:::inst
            Instrumentation["Instrumentation"]:::inst
            PRNG["PRNG"]:::core
            RangeTracker["RangeTracker (optional)"]:::util
        end
    end

    %% Server & Client
    subgraph "Distribution"
        direction TB
        Client["Client Module"]:::network
        Server["Server Process"]:::network
    end

    %% Utilities
    subgraph "Utilities & Helpers"
        direction TB
        Directory["Directory"]:::util
        Thread["Thread"]:::util
        Mutex["Mutex"]:::util
        Sample["Sample"]:::util
        RunResult["RunResult"]:::util
        Minimizer["Minimizer"]:::util
    end

    %% Target
    Target["Target Binary @@"]:::external

    %% Flows
    Main --> Fuzzer
    Fuzzer --> Corpus
    Fuzzer --> ThreadPool
    Fuzzer --> MutatorEngine
    Fuzzer --> SampleDelivery
    Fuzzer --> Instrumentation
    Fuzzer --> PRNG
    Fuzzer --> RangeTracker
    Corpus --> MutatorEngine
    MutatorEngine --> SampleDelivery
    SampleDelivery --> Target
    Target --> Instrumentation
    Instrumentation --> Fuzzer
    Fuzzer --> Client
    Client --> Server
    Server --> Client
    Server --> Corpus
    Fuzzer --> Directory
    Fuzzer --> Thread
    Fuzzer --> Mutex
    Sample --> Minimizer
    Sample --> RunResult

    %% Click Events
    click Fuzzer "https://github.com/googleprojectzero/jackalope/blob/main/fuzzer.cpp"
    click Main "https://github.com/googleprojectzero/jackalope/blob/main/main.cpp"
    click MutatorEngine "https://github.com/googleprojectzero/jackalope/blob/main/mutator.cpp"
    click SampleDelivery "https://github.com/googleprojectzero/jackalope/blob/main/sampledelivery.cpp"
    click Instrumentation "https://github.com/googleprojectzero/jackalope/blob/main/instrumentation.cpp"
    click PRNG "https://github.com/googleprojectzero/jackalope/blob/main/prng.cpp"
    click RangeTracker "https://github.com/googleprojectzero/jackalope/blob/main/rangetracker.cpp"
    click Server "https://github.com/googleprojectzero/jackalope/blob/main/server.cpp"
    click Client "https://github.com/googleprojectzero/jackalope/blob/main/client.cpp"
    click Directory "https://github.com/googleprojectzero/jackalope/blob/main/directory.cpp"
    click Thread "https://github.com/googleprojectzero/jackalope/blob/main/thread.cpp"
    click Mutex "https://github.com/googleprojectzero/jackalope/blob/main/mutex.cpp"
    click Sample "https://github.com/googleprojectzero/jackalope/blob/main/sample.cpp"
    click RunResult "https://github.com/googleprojectzero/jackalope/blob/main/runresult.h"
    click Minimizer "https://github.com/googleprojectzero/jackalope/blob/main/minimizer.cpp"

    %% Grammar Mutators
    GrammarCore["Grammar Mutator Core"]:::core
    GrammarMin["Grammar Minimizer"]:::core
    GrammarMut["Grammar Mutator"]:::core

    Fuzzer --> GrammarCore
    Fuzzer --> GrammarMin
    Fuzzer --> GrammarMut

    click GrammarCore "https://github.com/googleprojectzero/jackalope/blob/main/mutators/grammar/grammar.cpp"
    click GrammarMin "https://github.com/googleprojectzero/jackalope/blob/main/mutators/grammar/grammarminimizer.cpp"
    click GrammarMut "https://github.com/googleprojectzero/jackalope/blob/main/mutators/grammar/grammarmutator.cpp"

    %% Third-party PRNG
    Mersenne["Mersenne Twister Impl"]:::core
    PRNG --> Mersenne
    click Mersenne "https://github.com/googleprojectzero/jackalope/blob/main/third_party/Mersenne/mersenne.cpp"

    %% SanitizerCoverage & TinyInst
    Sancov["Sancov Instrumentation"]:::inst
    TinyInst["TinyInst Instrumentation"]:::inst
    SancovClient["Sancov Client Hooks"]:::inst

    Instrumentation --> Sancov
    Instrumentation --> TinyInst
    Sancov --> SancovClient

    click Sancov "https://github.com/googleprojectzero/jackalope/blob/main/sancovinstrumentation.cpp"
    click TinyInst "https://github.com/googleprojectzero/jackalope/blob/main/tinyinstinstrumentation.cpp"
    click SancovClient "https://github.com/googleprojectzero/jackalope/blob/main/sancovclient.cpp"

    %% Styles
    classDef core fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef inst fill:#d4edda,stroke:#333,stroke-width:1px
    classDef network fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef util fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef external fill:#f8d7da,stroke:#333,stroke-width:1px
```
