syzkaller Documentation

syz-cluster is a distributed patch series fuzzing system built on top of syzkaller. It is designed to be deployed on a Kubernetes (K8S) cluster.

Core Services

• dashboard: A read-only web interface.
• controller: Manages system state, schedules fuzzing sessions, and provides an API for other components.
• series-tracker: Polls LKML git archives for new series.
• reporter-server: Generates new reports and provides an API for reporter implementations.
• email-reporter: Sends reports via email and handles incoming email commands.

Patch Processing Workflow

Patch processing is orchestrated by Argo Workflows using the following steps (defined in pkg/workflow/template.yaml):

1. workflow/triage
2. workflow/build
3. workflow/boot
4. workflow/fuzz

Note: Triage and build steps require kernel checkouts. The base kernel repository is hosted on a shared network disk and updated via kernel-disk scripts.

Deployment and Configuration

The system uses Kustomize to support multiple environments:

• overlays/local/minikube: Local development environment.
• overlays/gke/staging: Staging production environment.
• overlays/gke/prod: Production environment (deployed at https://ci.syzbot.org).

global-config.yaml is the primary configuration file used to determine mailing lists to poll, resource usage, and reporting settings.

Syzkaller uses a pseudo-formal grammar called syzlang to describe system calls. A syscall description follows this general syntax:

syscallname "(" [arg ["," arg]*] ")" [type] "(" attribute* ")"

Where:

• arg is defined as argname type.
• type is a typename optionally followed by type-options in brackets [].
• attribute refers to call attributes (like timeout or no_generate).

Basic components include:

• Arguments: Named identifiers followed by a type.
• Types: Includes primitives like intN, ptr, string, array, and complex types like vma or proc.
• Type Options: Specific modifiers for types, such as opt for optional parameters, or range constraints for integers.

syscallname "(" [arg ["," arg]*] ")" [type] "(" attribute* ")"
arg = argname type
argname = identifier
type = typename ["[" type-options "]"]
typename = "const" | "intN" | "intptr" | "flags" | "array" | "ptr" |
	   "string" | "strconst" | "filename" | "glob" | "len" |
	   "bytesize" | "bytesizeN" | "bitsize" | "vma" | "proc" |
	   "compressed_image"
type-options = [type-opt ["," type-opt]]

Linux kernel configurations used by syzbot are auto-generated using the syz-kconf utility. The process uses a central declaration file main.yml and various configuration fragments located in the bits/ directory.

Core Concepts

• Instances: Defined in main.yml, these represent target configuration files. Each instance has a list of features (e.g., x86_64, gcc, upstream).
• Fragments: Files in bits/ that contain configuration logic. A fragment is included in an instance if all its constraints are met and no negative constraints (prefixed with -) are present in the instance's features.
• Includes: The includes section in main.yml defines the order and conditions for applying fragments to instances.

Fragment Capabilities

Fragments can specify:

• Kernel Repository: The git URL and tag/revision to use.
• Shell Commands: Kernel make commands (e.g., make x86_64_defconfig) to create base configs. Commands can have constraints (e.g., make defconfig: [-nodefconfig]).
• Verbatim Text: Strings appended to the end of the resulting config.
• Config Options: Specific kernel options to enable (CONFIG_FOO), disable (CONFIG_FOO: n), or set to specific values (CONFIG_FOO: 10 or CONFIG_FOO: "string").

The docs/research.md file maintains a curated list of academic papers, source code repositories, and tools that build upon or extend the syzkaller kernel fuzzer. This includes research on:

• Syscall Generation & Description: Tools like SyzDescribe and SyzGen for automated syscall specification.
• Exploit Generation: Research into automating the generation of Proof-of-Concept (PoC) exploits (e.g., SemFuzz, KOOBE).
• Concurrency & Race Detection: Methods for finding kernel data races and concurrency bugs (e.g., RAZZER, Snowboard).
• Specialized Fuzzing: Research targeting specific subsystems like macOS drivers, Android drivers, or RTOS (e.g., Rtkaller).
• Efficiency & Optimization: Techniques for improving fuzzing speed and configuration selection (e.g., FastSyzkaller, MoonShine).

For a comprehensive list, refer to the full bibliography in the repository's documentation.

The aflow framework provides an AI agent workflow (implemented in pkg/aflow/flow/repro/repro.go) designed to automatically convert kernel crash reports and execution logs into reliable syzkaller reproducers (.syz files).

The Agent Loop follows these steps:

1. Context Initialization: Ingests kernel crash logs, stack traces, target kernel info (.config, kernel repo, commit), and execution logs (using a Bug ID from the syzbot dashboard).
2. Subsystem Analysis: Identifies the vulnerable subsystem (e.g., io_uring, bpf) from the stack trace.
3. Syzlang Contextualization: Uses the read-description tool to look up relevant syscall signatures, structs, and flags from sys/linux/*.txt.
4. Draft Generation: The LLM generates a candidate .syz program.
5. Execution & Verification: The reproduce-crash tool compiles and runs the program in an instrumented VM. The agent verifies if the resulting crash is "very close" to the original (e.g., same function/root cause).
6. Iterative Refinement: If compilation fails or the crash doesn't reproduce, the agent analyzes the error and retries until a limit is reached.