Skip to content

Latest commit

 

History

History
104 lines (75 loc) · 4.78 KB

setup.md

File metadata and controls

104 lines (75 loc) · 4.78 KB
Raw

How to set up syzkaller

Generic instructions on how to set up Linux kernel fuzzing with syzkaller are below.

Instructions for a particular VM type or kernel architecture can be found on these pages:

Install

The following components are needed to use syzkaller:

  • Go compiler and syzkaller itself
  • C compiler with coverage support
  • Linux kernel with coverage additions
  • Virtual machine or a physical device

If you encounter any troubles, check the troubleshooting page.

Go and syzkaller

syzkaller is written in Go, and Go 1.13+ toolchain is required for build. The toolchain can be installed with:

wget https://dl.google.com/go/go1.14.2.linux-amd64.tar.gz
tar -xf go1.14.2.linux-amd64.tar.gz
mv go goroot
mkdir gopath
export GOPATH=`pwd`/gopath
export GOROOT=`pwd`/goroot
export PATH=$GOPATH/bin:$PATH
export PATH=$GOROOT/bin:$PATH

To download and build syzkaller:

go get -u -d github.com/google/syzkaller/prog
cd gopath/src/github.com/google/syzkaller/
make

As the result compiled binaries should appear in the bin/ dir.

Also see Go Getting Started for more details.

Note: if you want to do cross-OS/arch testing, you need to specify TARGETOS, TARGETVMARCH and TARGETARCH arguments to make. See the Makefile for details.

Note: older versions of Go toolchain formatted code in a slightly different way. So if you are seeing unrelated code formatting diffs after running make generate or make format, you may be using Go 1.10 or older. In such case update to Go 1.13+.

Environment

You might need to properly setup binutils if you're fuzzing in a cross-arch environment as described here.

C Compiler

Syzkaller is a coverage-guided fuzzer and therefore it needs the kernel to be built with coverage support, which requires a recent GCC version. Coverage support was submitted to GCC, released in GCC 6.1.0 or later. Make sure that your GCC meets this requirement, or get a GCC that syzbot uses here.

Linux Kernel

Besides coverage support in GCC, you also need support for it on the kernel side. KCOV was added into mainline Linux kernel in version 4.6 and is be enabled by CONFIG_KCOV=y kernel configation option. For older kernels you need to at least backport commit kernel: add kcov code coverage. Besides that, it's recomended to backport all kernel patches that touch kernel/kcov.c.

To enable more syzkaller features and improve bug detection abilities, it's recommended to use additional config options. See this page for details.

VM Setup

Syzkaller performs kernel fuzzing on slave virtual machines or physical devices. These slave enviroments are referred to as VMs. Out-of-the-box syzkaller supports QEMU, kvmtool and GCE virtual machines, Android devices and Odroid C2 boards.

These are the generic requirements for a syzkaller VM:

  • The fuzzing processes communicate with the outside world, so the VM image needs to include networking support.
  • The program files for the fuzzer processes are transmitted into the VM using SSH, so the VM image needs a running SSH server.
  • The VM's SSH configuration should be set up to allow root access for the identity that is included in the syz-manager's configuration. In other words, you should be able to do ssh -i $SSHID -p $PORT root@localhost without being prompted for a password (where SSHID is the SSH identification file and PORT is the port that are specified in the syz-manager configuration file).
  • The kernel exports coverage information via a debugfs entry, so the VM image needs to mount the debugfs filesystem at /sys/kernel/debug.

To use QEMU syzkaller VMs you have to install QEMU on your host system, see QEMU docs for details. The create-image.sh script can be used to create a suitable Linux image.

See the links at the top of the document for instructions on setting up syzkaller for QEMU, Android and some other types of VMs.