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

     1  # `syz-kfuzztest`
     2  
     3  `syz-kfuzztest` is a standalone tool for fuzzing KFuzzTest targets from within
     4  the kernel being fuzzed (e.g., a VM).
     5  
     6  It is intended to be used for development-time fuzzing rather than continuous
     7  fuzzing like `syz-manager`.
     8  
     9  For more information on KFuzzTest, consult the [dedicated readme](kfuzztest.md)
    10  or the Kernel documentation.
    11  
    12  ## Usage (in-VM fuzzing)
    13  
    14  ### Getting the Kernel Ready
    15  
    16  It is important that the target Kernel image has the correct KConfig options
    17  enabled. Namely
    18  
    19  - `CONFIG_KFUZZTEST`
    20  - `CONFIG_DEBUG_FS`
    21  - `CONFIG_DEBUG_KERNEL`
    22  - `CONFIG_KCOV`
    23  - `CONFIG_DWARF4` or `CONFIG_DWARF5`
    24  - `CONFIG_KASAN` _(optional, choose your favorite sanitizers for a better shot
    25    at finding bugs!)_
    26  
    27  Furthermore, as you will need to connect to the VM being tested through SSH and
    28  launch `syz-kfuzztest` _(a Go binary with LIBC dependencies)_, it is recommended
    29  to create an image for the kernel being fuzzed (e.g., a Debian Trixie image).
    30  Detailed instructions on how to do this can be found in
    31  [this setup guide](linux/setup_ubuntu-host_qemu-vm_x86-64-kernel.md).
    32  
    33  ### Building and Launching the Binary
    34  
    35  The `syz-kfuzztest` binary is built with `make syz-kfuzztest`, and is intended
    36  to run on the Kernel fuzzed. The common case for this is within a VM _(after
    37  all, the tool is trying to make the Kernel crash)_.
    38  
    39  Then, ensure that the `syz-kfuzztest` binary and `vmlinux` image are copied
    40  over into the VM. E.g.,
    41  
    42  ```sh
    43  scp $KERNEL/vmlinux root@my-vm:~/syz-kfuzztest/vmlinux
    44  scp $SYZKALLER/bin/syz-kfuzztest root@lmy-vm:~/syz-kfuzztest/syz-kfuzztest
    45  ```
    46  
    47  Then launched like this:
    48  
    49  ```
    50  usage: ./bin/syz-kfuzztest [flags] [enabled targets]
    51  
    52  Args:
    53    One fuzz test name per enabled fuzz test arg. If empty, defaults to
    54    all discovered targets.
    55  Example:
    56    ./syz-kfuzztest -vmlinux ~/kernel/vmlinux fuzz_target_0 fuzz_target_1
    57  Flags:
    58    -display int
    59          Number of seconds between console outputs (default 5)
    60    -threads int
    61          Number of threads (default 2)
    62    -timeout int
    63          Timeout between program executions in seconds (default 0)
    64    -vmlinux string
    65          Path to vmlinux binary (default "vmlinux")
    66    -vv int
    67          verbosity
    68  ```
    69  
    70  The enabled targets, which are listed after the flag arguments, are the names of
    71  the enabled fuzz targets. For example given some KFuzzTest targets:
    72  
    73  ```c
    74  FUZZ_TEST(kfuzztest_target_1, struct input_arg_type)
    75  {
    76      /* ... */
    77  }
    78  
    79  FUZZ_TEST(kfuzztest_target_2, struct input_arg_type)
    80  {
    81      /* ... */
    82  }
    83  
    84  ```
    85  
    86  Can be fuzzed with:
    87  
    88  ```bash
    89  ./syz-kfuzztest -vmlinux path/to/vmlinux -threads 4 kfuzztest_target_1 kfuzztest_target_2
    90  ```
    91  
    92  If the enabled targets list is left empty, `syz-kfuzztest` will fuzz all
    93  discovered targets in the kernel.
    94  
    95  On exit, `syz-kfuzztest` will write the collected program counters (which are
    96  collected with KCOV) into a file called `pcs.out`. These program counters can
    97  be fed into [`syz-cover`](../tools/syz-cover/syz-cover.go) to generate an HTML
    98  visualization of the lines that were covered during fuzzing. It is recommended
    99  to do this on the host machine rather than the VM.
   100  
   101  For example:
   102  
   103  ```sh
   104  scp root@my-vm:~/syz-kfuzztest/pcs.out .
   105  go run tools/syz-cover -config my.cfg pcs.out # May require the -force flag.
   106  ```