mirror of
https://github.com/reactos/syzkaller.git
synced 2024-11-23 03:19:51 +00:00
docs: various updates all over
This commit is contained in:
Andrey Konovalov
Dmitry Vyukov
parent
1913718f34
commit
fe4122c3bf
@ -1,8 +1,8 @@
|
||||
# How to contribute to syzkaller
|
||||
|
||||
## Guidelines
|
||||
If you want to contribute to the project, feel free to send a pull request following the guidelines below.
|
||||
|
||||
If you want to contribute to the project, feel free to send a pull request.
|
||||
## Guidelines
|
||||
|
||||
Before sending a pull request you need to [sign Google CLA](https://cla.developers.google.com/)
|
||||
(if you don't a bot will ask you to do that) and add yourself to
|
||||
@ -33,7 +33,7 @@ an issue without closing it, add `Update #NNN`.
|
||||
- Run `make presubmit` and ensure that it passes before sending a PR.
|
||||
It may require some additional packages to be installed (try `sudo make install_prerequisites`).
|
||||
- `*.const` files are checked-in with the `*.txt` changes in the same commit.
|
||||
- Rebase your pull request onto the master branch before submitting.
|
||||
- Rebase your working branch onto the master branch before sending a pull request.
|
||||
- If you're asked to add some fixes to your pull requested, please squash the new commits with the old ones.
|
||||
|
||||
## What to work on
|
||||
|
||||
@ -1,35 +1,6 @@
|
||||
# Coverage
|
||||
|
||||
Syzkaller uses [kcov](https://www.kernel.org/doc/html/latest/dev-tools/kcov.html) to collect coverage from the kernel. kcov exports the address of each executed basic block, and syzkaller runtime uses tools from `binutils` (`objdump`, `nm`, `addr2line` and `readelf`) to map these addresses to lines and functions in the source code.
|
||||
|
||||
## Binutils
|
||||
|
||||
Note that if you are fuzzing in cross-arch environment you need to provide correct `binutils` cross-tools to syzkaller before starting `syz-manager`:
|
||||
|
||||
``` bash
|
||||
mkdir -p ~/bin/mips64le
|
||||
ln -s `which mips64el-linux-gnuabi64-addr2line` ~/bin/mips64le/addr2line
|
||||
ln -s `which mips64el-linux-gnuabi64-nm` ~/bin/mips64le/nm
|
||||
ln -s `which mips64el-linux-gnuabi64-objdump` ~/bin/mips64le/objdump
|
||||
ln -s `which mips64el-linux-gnuabi64-readelf` ~/bin/mips64le/readelf
|
||||
export PATH=~/bin/mips64le:$PATH
|
||||
```
|
||||
|
||||
### objdump
|
||||
|
||||
`objdump` is used to parse PC value of each call to `__sanitizer_cov_trace_pc` in the kernel image. These PC values are representing all code that is built into kernel image. PC values exported by kcov are compared against these to determine coverage.
|
||||
|
||||
### nm
|
||||
|
||||
`nm` is used to parse address and size of each function in the kernel image. This information is used to map coverage data to functions. This is needed to find out whether certain functions are called at all.
|
||||
|
||||
### addr2line
|
||||
|
||||
`addr2line` is used for mapping PC values exported by kcov and parsed by `objdump` to source code files and lines.
|
||||
|
||||
### readelf
|
||||
|
||||
`readelf` is used to detect virtual memory offset. Executor truncates PC values into `uint32` before sending them to `syz-manager` and `syz-manager` has to detect the offset.
|
||||
See [this](linux/coverage.md) for Linux kernel specific coverage information.
|
||||
|
||||
## Web Interface
|
||||
|
||||
@ -71,13 +42,13 @@ PC values associated to the line are not instrumented or source line doesn't gen
|
||||
|
||||
## syz-cover
|
||||
|
||||
There is small utility in syzkaller repository to generate coverage report on kcov data. This is available in [syz-cover](/tools/syz-cover) and can be build by:
|
||||
There is small utility in syzkaller repository to generate coverage report based on raw coverage data. This is available in [syz-cover](/tools/syz-cover) and can be built by:
|
||||
|
||||
``` bash
|
||||
GOOS=linux GOARCH=amd64 go build "-ldflags=-s -w" -o ./bin/syz-cover github.com/google/syzkaller/tools/syz-cover
|
||||
```
|
||||
|
||||
kcov data can be obtained from running `syz-manager` by:
|
||||
Raw coverage data can be obtained from running `syz-manager` by:
|
||||
|
||||
``` bash
|
||||
wget http://localhost:<your syz-manager port>/rawcover
|
||||
|
||||
@ -1,7 +1,8 @@
|
||||
# How syzkaller works
|
||||
|
||||
Below is the generic descriptions of how syzkaller works.
|
||||
Check [this](linux/internals.md) for Linux kernel specific things.
|
||||
Generic description of how syzkaller works are [below](internals.md#overview).
|
||||
|
||||
Linux kernel specific internals can be found [here](linux/internals.md).
|
||||
|
||||
## Overview
|
||||
|
||||
@ -11,11 +12,11 @@ red labels indicate corresponding configuration options.
|
||||
|
||||
|
||||
The `syz-manager` process starts, monitors and restarts several VM instances, and starts a `syz-fuzzer` process inside of the VMs.
|
||||
It is responsible for persistent corpus and crash storage.
|
||||
As opposed to `syz-fuzzer` processes, it runs on a host with stable kernel which does not experience white-noise fuzzer load.
|
||||
`syz-manager` is responsible for persistent corpus and crash storage.
|
||||
It runs on a host with stable kernel which does not experience white-noise fuzzer load.
|
||||
|
||||
The `syz-fuzzer` process runs inside of presumably unstable VMs.
|
||||
The `syz-fuzzer` guides fuzzing process itself (input generation, mutation, minimization, etc) and sends inputs that trigger new coverage back to the `syz-manager` process via RPC.
|
||||
The `syz-fuzzer` guides fuzzing process (input generation, mutation, minimization, etc.) and sends inputs that trigger new coverage back to the `syz-manager` process via RPC.
|
||||
It also starts transient `syz-executor` processes.
|
||||
|
||||
Each `syz-executor` process executes a single input (a sequence of syscalls).
|
||||
@ -26,6 +27,10 @@ It is designed to be as simple as possible (to not interfere with fuzzing proces
|
||||
|
||||
The `syz-fuzzer` process generates programs to be executed by `syz-executor` based on syscall descriptions described [here](syscall_descriptions.md).
|
||||
|
||||
## Coverage
|
||||
|
||||
Syzkaller is a coverage-guided fuzzer. The details about coverage collection can be found [here](coverage.md).
|
||||
|
||||
## Crash reports
|
||||
|
||||
When `syzkaller` finds a crasher, it saves information about it into `workdir/crashes` directory.
|
||||
@ -48,7 +53,7 @@ and up to 100 `logN` and `reportN` files, one pair per test machine crash:
|
||||
...
|
||||
```
|
||||
|
||||
Descriptions are extracted using a set of [regular expressions](/pkg/report/report.go#L33).
|
||||
Descriptions are extracted using a set of [regular expressions](/pkg/report/).
|
||||
This set may need to be extended if you are using a different kernel architecture, or are just seeing a previously unseen kernel error messages.
|
||||
|
||||
`logN` files contain raw `syzkaller` logs and include kernel console output as well as programs executed before the crash.
|
||||
@ -69,7 +74,3 @@ However, frequently they mean a kernel lockup or something similarly bad (here a
|
||||
[1](https://groups.google.com/d/msg/syzkaller/zfuHHRXL7Zg/Tc5rK8bdCAAJ),
|
||||
[2](https://groups.google.com/d/msg/syzkaller/kY_ml6TCm9A/wDd5fYFXBQAJ),
|
||||
[3](https://groups.google.com/d/msg/syzkaller/OM7CXieBCoY/etzvFPX3AQAJ)).
|
||||
|
||||
## Coverage
|
||||
|
||||
Syzkaller coverage description can be found from [here](coverage.md).
|
||||
|
||||
32
docs/linux/coverage.md
Normal file
32
docs/linux/coverage.md
Normal file
@ -0,0 +1,32 @@
|
||||
# Coverage
|
||||
|
||||
Syzkaller uses [kcov](https://www.kernel.org/doc/html/latest/dev-tools/kcov.html) to collect coverage from the kernel. kcov exports the address of each executed basic block, and syzkaller runtime uses tools from `binutils` (`objdump`, `nm`, `addr2line` and `readelf`) to map these addresses to lines and functions in the source code.
|
||||
|
||||
## Binutils
|
||||
|
||||
Note that if you are fuzzing in cross-arch environment you need to provide correct `binutils` cross-tools to syzkaller before starting `syz-manager`:
|
||||
|
||||
``` bash
|
||||
mkdir -p ~/bin/mips64le
|
||||
ln -s `which mips64el-linux-gnuabi64-addr2line` ~/bin/mips64le/addr2line
|
||||
ln -s `which mips64el-linux-gnuabi64-nm` ~/bin/mips64le/nm
|
||||
ln -s `which mips64el-linux-gnuabi64-objdump` ~/bin/mips64le/objdump
|
||||
ln -s `which mips64el-linux-gnuabi64-readelf` ~/bin/mips64le/readelf
|
||||
export PATH=~/bin/mips64le:$PATH
|
||||
```
|
||||
|
||||
### objdump
|
||||
|
||||
`objdump` is used to parse PC value of each call to `__sanitizer_cov_trace_pc` in the kernel image. These PC values are representing all code that is built into kernel image. PC values exported by kcov are compared against these to determine coverage.
|
||||
|
||||
### nm
|
||||
|
||||
`nm` is used to parse address and size of each function in the kernel image. This information is used to map coverage data to functions. This is needed to find out whether certain functions are called at all.
|
||||
|
||||
### addr2line
|
||||
|
||||
`addr2line` is used for mapping PC values exported by kcov and parsed by `objdump` to source code files and lines.
|
||||
|
||||
### readelf
|
||||
|
||||
`readelf` is used to detect virtual memory offset. Executor truncates PC values into `uint32` before sending them to `syz-manager` and `syz-manager` has to detect the offset.
|
||||
@ -1,14 +1,15 @@
|
||||
# How to set up syzkaller
|
||||
|
||||
Below are the generic instructions for how to set up syzkaller to fuzz the Linux kernel.
|
||||
Instructions for a particular VM type or kernel arch can be found on these pages:
|
||||
Generic instructions on how to set up Linux kernel fuzzing with syzkaller are [below](setup.md#install).
|
||||
|
||||
Instructions for a particular VM type or kernel architecture can be found on these pages:
|
||||
|
||||
- [Setup: Ubuntu host, QEMU vm, x86-64 kernel](setup_ubuntu-host_qemu-vm_x86-64-kernel.md)
|
||||
- [Setup: Linux host, QEMU vm, arm64 kernel](setup_linux-host_qemu-vm_arm64-kernel.md)
|
||||
- [Setup: Linux host, QEMU vm, arm kernel](setup_linux-host_qemu-vm_arm-kernel.md)
|
||||
- [Setup: Linux host, Android device, arm32/64 kernel](setup_linux-host_android-device_arm-kernel.md)
|
||||
- [Setup: Linux isolated host](setup_linux-host_isolated.md)
|
||||
- [Setup: Ubuntu host, Odroid C2 board, arm64 kernel](setup_ubuntu-host_odroid-c2-board_arm64-kernel.md)
|
||||
- [Setup: Ubuntu host, Odroid C2 board, arm64 kernel](setup_ubuntu-host_odroid-c2-board_arm64-kernel.md) [outdated]
|
||||
|
||||
## Install
|
||||
|
||||
@ -57,6 +58,10 @@ Note: older versions of Go toolchain formatted code in a slightly
|
||||
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](coverage.md#binutils).
|
||||
|
||||
### 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.
|
||||
|
||||
@ -1,5 +1,7 @@
|
||||
# Setup: Ubuntu host, Odroid C2 board, arm64 kernel
|
||||
|
||||
Note: these instructions are currently outdated, but can still be used as a reference.
|
||||
|
||||
These are the instructions on how to fuzz the kernel on an [Odroid C2](http://www.hardkernel.com/main/products/prdt_info.php) board using Ubuntu 14.04 on the host machine and Ubuntu on the Odroid.
|
||||
|
||||
## Hardware setup
|
||||
|
||||
@ -3,14 +3,15 @@
|
||||
Generic setup instructions for fuzzing Linux kernel are outlined [here](linux/setup.md).
|
||||
|
||||
For other kernels see:
|
||||
[Akaros](/docs/akaros/README.md),
|
||||
[FreeBSD](/docs/freebsd/README.md),
|
||||
[Fuchsia](/docs/fuchsia/README.md),
|
||||
[NetBSD](/docs/netbsd/README.md),
|
||||
[OpenBSD](/docs/openbsd/setup.md),
|
||||
[Windows](/docs/windows/README.md).
|
||||
[Akaros](akaros/README.md),
|
||||
[FreeBSD](freebsd/README.md),
|
||||
[Fuchsia](fuchsia/README.md),
|
||||
[NetBSD](netbsd/README.md),
|
||||
[OpenBSD](openbsd/setup.md),
|
||||
[Windows](windows/README.md).
|
||||
|
||||
After following these instructions you should be able to run `syz-manager`, see it executing programs and be able to access statistics exposed at `http://127.0.0.1:56741`:
|
||||
After following these instructions you should be able to run `syz-manager`, see it executing programs, and be able to access statistics exposed at `http://127.0.0.1:56741` (or whatever address you've specified in the manager config).
|
||||
If everything is working properly, a typical execution log would look like:
|
||||
|
||||
```
|
||||
$ ./bin/syz-manager -config=my.cfg
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
|
||||
`syzkaller` uses declarative description of syscall interfaces to manipulate
|
||||
programs (sequences of syscalls). Below you can see (hopefully self-explanatory)
|
||||
excerpt from the description:
|
||||
excerpt from the descriptions:
|
||||
|
||||
```
|
||||
open(file filename, flags flags[open_flags], mode flags[open_mode]) fd
|
||||
@ -11,7 +11,7 @@ close(fd fd)
|
||||
open_mode = S_IRUSR, S_IWUSR, S_IXUSR, S_IRGRP, S_IWGRP, S_IXGRP, S_IROTH, S_IWOTH, S_IXOTH
|
||||
```
|
||||
|
||||
The description is contained in `sys/OS/*.txt` files.
|
||||
The descriptions are contained in `sys/$OS/*.txt` files.
|
||||
For example see the [sys/linux/dev_snd_midi.txt](/sys/linux/dev_snd_midi.txt) file
|
||||
for descriptions of the Linux MIDI interfaces.
|
||||
|
||||
@ -43,31 +43,43 @@ and is used for actual execution (interpretation) of programs by [executor](/exe
|
||||
|
||||
## Describing new system calls
|
||||
|
||||
This section describes how to extend syzkaller to allow fuzz testing of a new system call;
|
||||
this is particularly useful for kernel developers who are proposing new system calls.
|
||||
This section describes how to extend syzkaller to allow fuzz testing of more kernel interfaces.
|
||||
This is particularly useful for kernel developers who are proposing new system calls.
|
||||
|
||||
Syscall interfaces are manually-written. There is an
|
||||
Currently all syscall descriptions are manually-written. There is an
|
||||
[open issue](https://github.com/google/syzkaller/issues/590) to provide some aid
|
||||
for this process and some ongoing work, but we are yet there.
|
||||
There is also [headerparser](headerparser_usage.md) utility that can auto-generate
|
||||
for this process and some ongoing work, but we are not there yet to have a
|
||||
fully-automated way to generate descriptions.
|
||||
There is a helper [headerparser](headerparser_usage.md) utility that can auto-generate
|
||||
some parts of descriptions from header files.
|
||||
|
||||
First, add a declarative description of the new system call to the appropriate file:
|
||||
- Various `sys/linux/<subsystem>.txt` files hold system calls for particular kernel
|
||||
subsystems, for example `bpf` or `socket`.
|
||||
- [sys/linux/sys.txt](/sys/linux/sys.txt) holds descriptions for more general system calls.
|
||||
- An entirely new subsystem can be added as a new `sys/linux/<new>.txt` file.
|
||||
To enable fuzzing of a new kernel interface:
|
||||
|
||||
The description of the syntax can be found [here](syscall_descriptions_syntax.md).
|
||||
1. Study the interface, find out which syscalls are required to use it.
|
||||
|
||||
After adding/changing descriptions run:
|
||||
```
|
||||
make extract TARGETOS=linux SOURCEDIR=$KSRC
|
||||
make generate
|
||||
make
|
||||
```
|
||||
2. Using [syntax documentation](syscall_descriptions_syntax.md) and
|
||||
[existing descriptions](/sys/linux/) as an example, add a declarative
|
||||
description of this interface to the appropriate file:
|
||||
|
||||
Here `make extract` generates/updates the `*.const` files.
|
||||
- `sys/linux/<subsystem>.txt` files hold system calls for particular kernel
|
||||
subsystems, for example [bpf.txt](/sys/linux/bpf.txt) or [socket.txt](/sys/linux/socket.txt).
|
||||
- [sys/linux/sys.txt](/sys/linux/sys.txt) holds descriptions for more general system calls.
|
||||
- An entirely new subsystem can be added as a new `sys/linux/<new>.txt` file.
|
||||
- Use `dev_*.txt` filename format for descriptions of `/dev/` devices.
|
||||
- Similarly, use `socket_*.txt` for sockets.
|
||||
|
||||
3. After adding/changing descriptions run:
|
||||
|
||||
``` bash
|
||||
make extract TARGETOS=linux SOURCEDIR=$KSRC
|
||||
make generate
|
||||
make
|
||||
```
|
||||
|
||||
4. Run syzkaller. Make sure that the newly added interface in being reached by
|
||||
syzkaller using the [coverage](coverage.md) information page.
|
||||
|
||||
In the instructions above `make extract` generates/updates the `*.const` files.
|
||||
`$KSRC` should point to the _latest_ kernel checkout.\
|
||||
_Note_: for Linux the _latest_ kernel checkout generally means the
|
||||
[mainline](https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git/log/) tree.\
|
||||
@ -92,8 +104,8 @@ Note: `sudo make install_prerequisites` will success even with some package fail
|
||||
install, `sudo apt-get update && sudo apt-get upgrade` might be required to make this
|
||||
more efficient.
|
||||
|
||||
If you want to fuzz the new subsystem that you described locally, you may find
|
||||
the `enable_syscalls` configuration parameter useful to specifically target
|
||||
If you want to fuzz only the new subsystem that you described locally, you may
|
||||
find the `enable_syscalls` configuration parameter useful to specifically target
|
||||
the new system calls.
|
||||
|
||||
When updating existing syzkaller descriptions, note, that unless there's a drastic
|
||||
|
||||
@ -8,7 +8,7 @@ Start the `syz-manager` process as:
|
||||
```
|
||||
|
||||
The `syz-manager` process will wind up VMs and start fuzzing in them.
|
||||
The `-config` command line option gives the location of the configuration file, which is [described here](configuration.md).
|
||||
The `-config` command line option gives the location of the configuration file, which is described [here](configuration.md).
|
||||
Found crashes, statistics and other information is exposed on the HTTP address specified in the manager config.
|
||||
|
||||
## Crashes
|
||||
@ -24,10 +24,10 @@ If a reproducer is successfully found, it can be generated in one of the two for
|
||||
Syzkaller always tries to generate a more user-friendly C reproducer, but sometimes fails for various reasons (for example slightly different timings).
|
||||
In case syzkaller only generated a syzkaller program, there's [a way to execute them](reproducing_crashes.md) to reproduce and debug the crash manually.
|
||||
|
||||
## Hub
|
||||
|
||||
In case you're running multiple `syz-manager` instances, there's a way connect them together and allow to exchange programs and reproducers, see the details [here](hub.md).
|
||||
|
||||
## Reporting bugs
|
||||
|
||||
Check [here](linux/reporting_kernel_bugs.md) for the instructions on how to report Linux kernel bugs.
|
||||
|
||||
## Other
|
||||
|
||||
[How to connect several managers via Hub](hub.md)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user