# googleprojectzero/fuzzilli architecture

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

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

## Overview

##### Main components
- Fuzzilli CLI (Sources/FuzzilliCli)
- Core library (Sources/Fuzzilli)
– Fuzzer instance (Fuzzer.swift)
– Engines (MutationEngine, HybridEngine, etc.)
– Mutators, Corpus, Minimizer, Evaluator, Lifter, Environment, ScriptRunner/REPRL
– Event system (Events.swift)
- Intermediate Language (FuzzIL)
- C helper libs (libcoverage, libreprl, libsocket)
- Target engine processes (JS shells instrumented via patches in Targets/)
- Optional modules: Storage, NetworkSync, ThreadSync, Statistics
- Deployment: Docker builders, Cloud-GCE scripts

##### Relationships and data flows
a. CLI → config → instantiate one or more Fuzzer instances
b. Fuzzer loop:
– Corpus supplies seed programs
– MutationEngine applies Mutators → new FuzzIL programs
– Lifter translates IR to JavaScript
– ScriptRunner (via REPRL) sends code over socket/shared memory to target engine process
– libcoverage collects coverage feedback
– Evaluator grades program (coverage gain, crash)
– Corpus & Minimizer update stored programs/crashes
– Events propagate between components (decoupled via EventDispatcher)
c. Modules can subscribe to events to:
– Store crashes to disk (Storage)
– Sync corpora across threads/processes (ThreadSync)
– Sync corpora over network (NetworkSync)
– Gather stats (Statistics)
d. For distributed fuzzing: multiple Fuzzer instances form a tree hierarchy; parent/child sync via modules

##### Architectural patterns
- Event-driven, modular design: components decoupled by Events
- Pipeline pattern: IR generation → translation → execution → feedback
- Reader–Eval–Print–Reset loop (REPRL) for efficient reuse of target engine
- Tree-based distribution for scalability
- Platform abstraction layers: Swift code for core logic; C for low-level IPC & coverage

##### Technologies & frameworks
- Swift (fuzzer logic, CLI, lifting, engines, mutators)
- C (libcoverage, libreprl, libsocket)
- Docker (Cloud/Docker builders for Fuzzilli and JS engines)
- Google Compute Engine scripts (Cloud/GCE)
- Protobuf for sync protocol (Sources/Fuzzilli/Protobuf)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CLI Layer
    subgraph "CLI Layer"
        direction TB
        CLI["Fuzzilli CLI"]:::swift
    end

    %% Core Library
    subgraph "Core Library" 
        direction TB
        Fuzzer["Fuzzer Instance"]:::swift
        subgraph "Pipeline Components"
            direction TB
            Corpus["Corpus"]:::swift
            Engines["Engines"]:::swift
            Mutators["Mutators"]:::swift
            Lifter["Lifter"]:::swift
            ScriptRunner["ScriptRunner/REPRL"]:::swift
            Evaluator["Evaluator"]:::swift
        end
        EventSys["Event System"]:::swift
    end

    %% IR
    FuzzIL["Intermediate Language (FuzzIL)"]:::swift

    %% C Libraries
    subgraph "C Helper Libraries"
        direction TB
        Coverage["libcoverage"]:::c
        REPRLLib["libreprl"]:::c
        SocketIPC["libsocket"]:::c
    end

    %% Targets
    subgraph "Target Engine Processes"
        direction TB
        Targets["JS Engines"]:::external
    end

    %% Optional Modules
    subgraph "Optional Modules"
        direction TB
        Storage["Storage"]:::swift
        NetworkSync["NetworkSync"]:::swift
        ThreadSync["ThreadSync"]:::swift
        Statistics["Statistics"]:::swift
    end

    %% Deployment
    subgraph "Deployment Infrastructure"
        direction TB
        Docker["Docker Builders"]:::infra
        GCE["GCE Scripts"]:::infra
    end

    %% Data Flows
    CLI -->|"config & start"| Fuzzer
    Fuzzer -->|seeds| Corpus
    Corpus -->|programs| Engines
    Engines -->|mutate| Mutators
    Mutators -->|FuzzIL program| FuzzIL
    FuzzIL -->|IR to JS| Lifter
    Lifter -->|JavaScript| ScriptRunner
    ScriptRunner -->|execute via REPRL| Targets
    Targets -->|coverage data| Coverage
    Coverage -->|coverage metrics| Evaluator
    Targets -->|crash report| Evaluator
    Evaluator -->|results| Fuzzer

    %% Events and Modules
    Fuzzer --> EventSys
    EventSys -->|events| Storage
    EventSys -->|events| NetworkSync
    EventSys -->|events| ThreadSync
    EventSys -->|events| Statistics

    %% IPC connections
    ScriptRunner --> REPRLLib
    ScriptRunner --> SocketIPC

    %% Deployment hosting
    Docker -->|hosts| Fuzzer
    Docker -->|hosts| Targets
    GCE -->|orchestrates| Docker

    %% Distribution sync protocol
    NetworkSync --> Protobuf
    ThreadSync --> Protobuf

    subgraph "Protobuf Protocol"
        direction TB
        Protobuf["Protobuf Sync Protocol"]:::swift
    end

    %% Click Events
    click CLI "https://github.com/googleprojectzero/fuzzilli/tree/main/Sources/FuzzilliCli"
    click Fuzzer "https://github.com/googleprojectzero/fuzzilli/blob/main/Sources/Fuzzilli/Fuzzer.swift"
    click Engines "https://github.com/googleprojectzero/fuzzilli/tree/main/Sources/Fuzzilli/Engines"
    click Mutators "https://github.com/googleprojectzero/fuzzilli/tree/main/Sources/Fuzzilli/Mutators"
    click Corpus "https://github.com/googleprojectzero/fuzzilli/tree/main/Sources/Fuzzilli/Corpus"
    click Lifter "https://github.com/googleprojectzero/fuzzilli/tree/main/Sources/Fuzzilli/Lifting"
    click ScriptRunner "https://github.com/googleprojectzero/fuzzilli/tree/main/Sources/Fuzzilli/Execution"
    click EventSys "https://github.com/googleprojectzero/fuzzilli/blob/main/Sources/Fuzzilli/Base/Events.swift"
    click FuzzIL "https://github.com/googleprojectzero/fuzzilli/tree/main/Sources/Fuzzilli/FuzzIL"
    click Coverage "https://github.com/googleprojectzero/fuzzilli/tree/main/Sources/libcoverage"
    click REPRLLib "https://github.com/googleprojectzero/fuzzilli/tree/main/Sources/libreprl"
    click SocketIPC "https://github.com/googleprojectzero/fuzzilli/tree/main/Sources/libsocket"
    click Storage "https://github.com/googleprojectzero/fuzzilli/blob/main/Sources/Fuzzilli/Modules/Storage.swift"
    click NetworkSync "https://github.com/googleprojectzero/fuzzilli/blob/main/Sources/Fuzzilli/Modules/NetworkSync.swift"
    click ThreadSync "https://github.com/googleprojectzero/fuzzilli/blob/main/Sources/Fuzzilli/Modules/ThreadSync.swift"
    click Statistics "https://github.com/googleprojectzero/fuzzilli/blob/main/Sources/Fuzzilli/Modules/Statistics.swift"
    click Protobuf "https://github.com/googleprojectzero/fuzzilli/tree/main/Sources/Fuzzilli/Protobuf"
    click Targets "https://github.com/googleprojectzero/fuzzilli/tree/main/Targets"
    click Docker "https://github.com/googleprojectzero/fuzzilli/tree/main/Cloud/Docker"
    click GCE "https://github.com/googleprojectzero/fuzzilli/tree/main/Cloud/GCE"

    %% Styles
    classDef swift fill:#cde5ff,stroke:#339,stroke-width:1px
    classDef c fill:#e0f7e9,stroke:#073,stroke-width:1px
    classDef external fill:#ffe0b2,stroke:#e65100,stroke-width:1px
    classDef infra fill:#e0e0e0,stroke:#616161,stroke-width:1px
```
