# google/syzkaller architecture

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

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

## Overview

##### Project’s Main Components
- Core Fuzzer Engine:
– The program generation layer (found in the “prog” directory) builds the test programs.
– The “pkg/fuzzer” package includes the logic that interprets coverage feedback and schedules tests.
- Executor and Runtime Environment:
– The “executor” folder contains the executor code that runs the generated tests on the target kernel.
– The “vm” directory shows virtualization and isolated execution components (for QEMU, GCE, etc.).
- API & Communication Layers:
– The “dashboard” package (with “dashboard/api” and “dashboard/app”) and related syz-hub, syz-manager, and syz-cluster modules provide interfaces for job management, reporting, and user interactions.
– “pkg/rpcserver” and “pkg/rpctype” reveal the RPC mechanisms that allow different services to communicate.
- Data Storage & Coverage Databases:
– Modules such as “pkg/coveragedb”, “pkg/cover”, “pkg/covermerger”, and “pkg/db” handle storage, merging of coverage data, and repository management.
- Auxiliary & Supporting Tools:
– The “tools” directory contains various utilities for building, debugging, formatting, triaging, and analyzing outputs.
– There are CI/CD configurations (in .github/workflows) and syz-ci components that support continuous integration.
– The “sys” tree provides system call descriptions and OS-specific definitions for different targets.

##### Relationships and Interactions
- How the Engine communicates with the Executor: the Executor receives generated test cases and returns execution results (coverage data, crashes, etc.) back to the Engine.
- A flow where the Executor is hosted within a virtual machine or container (as shown in the “vm” directories), making use of platform-specific code.
- That the API and dashboard components (“dashboard”, “syz-hub”, “syz-manager”, “syz-cluster”) interact with the core engine: they display job statuses, statistics and reporting information that is collected from the fuzzer and executor.
- Auxiliary tools to the main system as having roles in artifact creation (e.g., syz-build, syz-testbed) and quality checks (like syz-fmt and syz-linter).

##### Architectural Patterns and Design Principles
- Microservice-style Components: In the syz-cluster module, for example, you see separate services (dashboard, controller, DB management, reporter, workflow) that communicate via APIs and configurations. Indicate these as individual sub-components with clearly defined interfaces.
- Multi-OS and Multi-Platform Support: Include a note that the “sys” and “pkg” directories provide OS-specific modules (Linux, FreeBSD, Windows, etc.), suggesting a plug-in style architecture for kernel-specific adaptations.

##### Relevant Technologies, Frameworks, and Libraries
- Go is the primary language for most components, as seen from the .go files.
- The system uses RPC (over HTTP or custom protocols) for communication between components.
- Virtualization modules and container orchestration are seen in directories like “vm”, “syz-cluster”, and CI configurations.
- External tools (such as Docker, Kubernetes manifests from the syz-cluster overlays and workflows) are integral to how syzkaller is deployed and scaled.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Fuzzing Engine
    subgraph "Core Fuzzing Engine"
        P1["Test Program Generator (prog)"]:::coreEngine
        P2["Scheduling Engine (pkg/fuzzer)"]:::coreEngine
        P1 -->|"generates"| P2
    end

    %% Execution Environment
    subgraph "Execution Environment"
        E1["Executor (executor)"]:::runtime
        E2["VM/Isolation (vm)"]:::runtime
        P2 -->|"sends_tests"| E1
        E1 -->|"runs_in"| E2
        E1 -->|"feedback"| P2
    end

    %% API & Communication Layers
    subgraph "API & Communication"
        A1["Dashboard API (dashboard/api)"]:::api
        A2["Dashboard App (dashboard/app)"]:::api
        R1["RPC Server (pkg/rpcserver)"]:::api
        R2["RPC Type (pkg/rpctype)"]:::api
        H1["Syz-hub (syz-hub)"]:::api
        M1["Syz-manager (syz-manager)"]:::api
        C1["Syz-cluster (syz-cluster)"]:::api
        P2 -->|"updates"| A1
        P2 -->|"updates"| A2
        P2 -->|"communicates"| R1
        R1 -->|"uses"| R2
        P2 -->|"notifies"| H1
        P2 -->|"notifies"| M1
        P2 -->|"notifies"| C1
    end

    %% Data Storage & Coverage Databases
    subgraph "Data Storage & Coverage Databases"
        D1["Coverage DB (pkg/coveragedb)"]:::storage
        D2["Coverage Processing (pkg/cover)"]:::storage
        D3["Coverage Merging (pkg/covermerger)"]:::storage
        D4["Repo/Database (pkg/db)"]:::storage
        E1 -->|"reports"| D1
        D1 -->|"processes"| D2
        D2 -->|"merges"| D3
        D1 -->|"stores"| D4
    end

    %% Auxiliary & Supporting Tools
    subgraph "Auxiliary & Supporting Tools"
        T1["Utilities (tools)"]:::aux
        T2["CI/CD Config (.github/workflows)"]:::aux
        T3["Sys Definitions (sys)"]:::aux
        T1 ---|"supports"| P2
        T2 ---|"supports"| P2
        T3 ---|"plugin_support"| P2
    end

    %% Class definitions for colour styling
    classDef coreEngine fill:#ffcc00,stroke:#333,stroke-width:2px;
    classDef runtime fill:#add8e6,stroke:#333,stroke-width:2px;
    classDef api fill:#90ee90,stroke:#333,stroke-width:2px;
    classDef storage fill:#ffb6c1,stroke:#333,stroke-width:2px;
    classDef aux fill:#d3d3d3,stroke:#333,stroke-width:2px;

    %% Click Events
    click P1 "https://github.com/google/syzkaller/tree/master/prog/"
    click P2 "https://github.com/google/syzkaller/tree/master/pkg/fuzzer/"
    click E1 "https://github.com/google/syzkaller/tree/master/executor/"
    click E2 "https://github.com/google/syzkaller/tree/master/vm/"
    click A1 "https://github.com/google/syzkaller/tree/master/dashboard/api/"
    click A2 "https://github.com/google/syzkaller/tree/master/dashboard/app/"
    click R1 "https://github.com/google/syzkaller/tree/master/pkg/rpcserver/"
    click R2 "https://github.com/google/syzkaller/tree/master/pkg/rpctype/"
    click H1 "https://github.com/google/syzkaller/tree/master/syz-hub/"
    click M1 "https://github.com/google/syzkaller/tree/master/syz-manager/"
    click C1 "https://github.com/google/syzkaller/tree/master/syz-cluster/"
    click D1 "https://github.com/google/syzkaller/tree/master/pkg/coveragedb/"
    click D2 "https://github.com/google/syzkaller/tree/master/pkg/cover/"
    click D3 "https://github.com/google/syzkaller/tree/master/pkg/covermerger/"
    click D4 "https://github.com/google/syzkaller/tree/master/pkg/db/"
    click T1 "https://github.com/google/syzkaller/tree/master/tools/"
    click T2 "https://github.com/google/syzkaller/tree/master/.github/workflows/"
    click T3 "https://github.com/google/syzkaller/tree/master/sys/"
```
