github.com/google/syzkaller@v0.0.0-20251211124644-a066d2bc4b02/docs/bisect.md (about)

     1  # Syz-bisect
     2  
     3  `syz-bisect` program can be used to bisect culprit and fix commits for
     4  crashes found by syzkaller. It can also identify configuration options
     5  that are triggers for the crash.
     6  
     7  ## Usage
     8  
     9  Build `syz-bisect` with `make bisect`.
    10  
    11  During bisection different compilers depending on kernel revision are
    12  used. These compilers are available
    13  [here](https://storage.googleapis.com/syzkaller/bisect_bin.tar.gz).
    14  
    15  Install ccache to speed up kernel compilations during bisecton.
    16  
    17  Create user-space (chroot) using [create-image.sh](../tools/create-image.sh)
    18  
    19  Create a config file with following lines adjusted for your environment:
    20  
    21  ```
    22  {
    23  	"bin_dir": "/home/syzkaller/bisect_bin",
    24  	"ccache": "/usr/bin/ccache",
    25  	"compiler_type": "gcc",
    26  	"kernel_repo": "git://git.kernel.org/pub/scm/linux/kernel/git/next/linux-next.git",
    27  	"kernel_branch": "master",
    28  	"syzkaller_repo": "https://github.com/google/syzkaller",
    29  	"userspace": "/home/syzkaller/image/chroot",
    30  	"kernel_config": "/home/syzkaller/go/src/github.com/google/syzkaller/dashboard/config/linux/upstream-apparmor-kasan.config",
    31  	"kernel_baseline_config": "/home/syzkaller/go/src/github.com/google/syzkaller/dashboard/config/linux/upstream-apparmor-kasan-base.config",
    32  	"syzctl": /home/syzkaller/go/src/github.com/google/syzkaller/dashboard/config/linux/upstream.sysctl,
    33  	"cmdline": /home/syzkaller/go/src/github.com/google/syzkaller/dashboard/config/linux/upstream.cmdline,
    34  	"manager":
    35  	{
    36  		"name" : "bisect",
    37  		"target": "linux/amd64",
    38  		"http": "127.0.0.1:56741",
    39  		"workdir": "/home/syzkaller/workdir",
    40  		"kernel_obj": "/home/syzkaller/linux",
    41  		"image": "/home/syzkaller/workdir/image/image",
    42  		"sshkey": "/home/syzkaller/workdir/image/key",
    43  		"syzkaller": "/home/syzkaller/go/src/github.com/google/syzkaller_bisect",
    44  		"procs": 8,
    45  		"type": "qemu",
    46  		"kernel_src": "/syzkaller/linux",
    47  		"vm": {
    48  		      "count": 4,
    49  		      "kernel": "/home/syzkaller/linux/arch/x86/boot/bzImage",
    50  		      "cpu": 2,
    51  		      "mem": 2048,
    52  		      "cmdline": "root=/dev/sda1 rw console=ttyS0 kaslr crashkernel=512M minnowboard_1:eth0::: security=none"
    53  		}
    54  	}
    55  }
    56  ```
    57  
    58  And run bisection with `bin/syz-bisect -config vm_bisect.cfg -crash
    59  /syzkaller/workdir/crashes/03ee30ae11dfd0ddd062af26566c34a8c853698d`.
    60  
    61  `Syz-bisect` is expecting finding repro.cprog or repro.prog in given
    62  crash directory. It will also utilize repro.opts, but it's not
    63  mandatory.
    64  
    65  ## Additional Arguments
    66  
    67  `-syzkaller_commit` use this if you want to use specific version of syzkaller
    68  
    69  `-kernel_commit` kernel commit where crash is known to reproduce. You
    70  want to use this when bisecting fixing commit
    71  
    72  `-fix` use this if you want to bisect a fixing commit.
    73  
    74  ## Output
    75  
    76  It takes some time, but after `syz-bisect` completes it dumps out it's
    77  results into console It also stores results into files in given crash
    78  directory:
    79  
    80  `cause.commit` commit identified causing the crash or text "the crash
    81  already happened on the oldest tested release"
    82  
    83  `fix.commit` commit identified fixing the crash or text "the crash
    84  still happens on HEAD"
    85  
    86  `cause.config` config options identified working as one trigger for the crash
    87  
    88  `original.config, baseline.config, minimized.config` config files used
    89  in config bisection