From f900b48c62114547e55ef3513b9333196ebbb5ca Mon Sep 17 00:00:00 2001 From: Jouni Hogander Date: Sun, 22 Nov 2020 15:56:13 +0200 Subject: docs: add document for syz-bisect tool --- docs/bisect.md | 88 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 88 insertions(+) create mode 100644 docs/bisect.md (limited to 'docs') diff --git a/docs/bisect.md b/docs/bisect.md new file mode 100644 index 000000000..4c87a98c5 --- /dev/null +++ b/docs/bisect.md @@ -0,0 +1,88 @@ +# Syz-bisect + +`syz-bisect` program can be used to bisect culprit and fix commits for +crashes found by syzkaller. It can also identify configuration options +that are triggers for the crash. + +## Usage + +Build `syz-bisect` with `make bisect`. + +During bisection different compilers depending on kernel revision are +used. These compilers are available +[here](https://storage.googleapis.com/syzkaller/bisect_bin.tar.gz). + +Install ccache to speed up kernel compilations during bisecton. + +Create user-space (chroot) using [create-image.sh](../tools/create-image.sh) + +Create a config file with following lines adjusted for your environment: + +``` +{ + "bin_dir": "/home/syzkaller/bisect_bin", + "ccache": "/usr/bin/ccache", + "kernel_repo": "git://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git", + "kernel_branch": "master", + "syzkaller_repo": "https://github.com/google/syzkaller", + "userspace": "/home/syzkaller/image/chroot", + "kernel_config": "/home/syzkaller/go/src/github.com/google/syzkaller/dashboard/config/linux/upstream-apparmor-kasan.config", + "kernel_baseline_config": "/home/syzkaller/go/src/github.com/google/syzkaller/dashboard/config/linux/upstream-apparmor-kasan-base.config", + "syzctl": /home/syzkaller/go/src/github.com/google/syzkaller/dashboard/config/linux/upstream.sysctl, + "cmdline": /home/syzkaller/go/src/github.com/google/syzkaller/dashboard/config/linux/upstream.cmdline, + "manager": + { + "name" : "bisect", + "target": "linux/amd64", + "http": "127.0.0.1:56741", + "workdir": "/home/syzkaller/workdir", + "kernel_obj": "/home/syzkaller/linux", + "image": "/home/syzkaller/workdir/image/image", + "sshkey": "/home/syzkaller/workdir/image/key", + "syzkaller": "/home/syzkaller/go/src/github.com/google/syzkaller_bisect", + "procs": 8, + "type": "qemu", + "kernel_src": "/syzkaller/linux", + "vm": { + "count": 4, + "kernel": "/home/syzkaller/linux/arch/x86/boot/bzImage", + "cpu": 2, + "mem": 2048, + "cmdline": "root=/dev/sda1 rw console=ttyS0 kaslr crashkernel=512M minnowboard_1:eth0::: security=none" + } + } +} +``` + +And run bisection with `bin/syz-bisect -config vm_bisect.cfg -crash +/syzkaller/workdir/crashes/03ee30ae11dfd0ddd062af26566c34a8c853698d`. + +`Syz-bisect` is expecting finding repro.cprog or repro.prog in given +crash directory. It will also utilize repro.opts, but it's not +mandatory. + +## Additional Arguments + +`-syzkaller_commit` use this if you want to use specific version of syzkaller + +`-kernel_commit` kernel commit where crash is known to reproduce. You +want to use this when bisecting fixing commit + +`-fix` use this if you want to bisect a fixing commit. + +## Output + +It takes some time, but after `syz-bisect` completes it dumps out it's +results into console It also stores results into files in given crash +directory: + +`cause.commit` commit identified causing the crash or text "the crash +already happened on the oldest tested release" + +`fix.commit` commit identified fixing the crash or text "the crash +still happens on HEAD" + +`cause.config` config options identified working as one trigger for the crash + +`original.config, baseline.config, minimized.config` config files used +in config bisection -- cgit mrf-deployment