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

     1  # KFuzzTest Integration With syzkaller
     2  
     3  KFuzzTest, introduced initially in [this RFC](https://lore.kernel.org/all/20250813133812.926145-1-ethan.w.s.graham@gmail.com/)
     4  is a framework for exposing internal kernel functions to a userspace fuzzing
     5  engine like syzkaller. As the kernel docs put it:
     6  
     7  > The Kernel Fuzz Testing Framework (KFuzzTest) is a framework designed to
     8  > expose internal kernel functions to a userspace fuzzing engine.
     9  >
    10  > It is intended for testing stateless or low-state functions that are difficult
    11  > to reach from the system call interface, such as routines involved in file
    12  > format parsing or complex data transformations. This provides a method for
    13  > in-situ fuzzing of kernel code without requiring that it be built as a
    14  > separate userspace library or that its dependencies be stubbed out.
    15  
    16  This document introduces how syzkaller integrates with KFuzzTest.
    17  
    18  ## Getting Started
    19  
    20  Firstly, ensure that the KFuzzTest patch series has been applied to your Linux
    21  tree.
    22  
    23  As of the 26th of Semptember 2025, the most up-to-date version can be found in
    24  [this Linux Kernel patch series](https://lore.kernel.org/all/20250919145750.3448393-1-ethan.w.s.graham@gmail.com/).
    25  
    26  Once this is done, KFuzzTest targets can be defined on arbitrary kernel
    27  functions using the `FUZZ_TEST` macro as described in the kernel docs in
    28  `Documentation/dev-tools/kfuzztest.rst`.
    29  
    30  ### Configuration Options
    31  
    32  Ensure that the following KConfig options are enabled for your kernel image:
    33  
    34  - `CONFIG_DEBUG_FS` (used as a communication interface by KFuzzTest).
    35  - `CONFIG_DEBUG_KERNEL`.
    36  - `CONFIG_KFUZZTEST`.
    37  
    38  It is also **highly** recommended to enable the following KConfig options for
    39  more effective fuzzing.
    40  
    41  - `CONFIG_KASAN` (catch memory bugs such as out-of-bounds-accesses).
    42  - `CONFIG_KCOV` (to enable coverage guided fuzzing).
    43  
    44  ## Fuzzing KFuzzTest Targets
    45  
    46  Syzkaller implements three ways to fuzz KFuzzTest targets:
    47  
    48  1. `syz-manager` integration with static targets
    49  2. `syz-manager` with dynamic targets
    50  3. `syz-kfuzztest`: a standalone tool that runs inside a VM, discovers KFuzzTest
    51      targets dynamically, and fuzzes them.
    52  
    53  ### 1. `syz-manager` with static targets
    54  
    55  Configuration for this method is identical to `syz-manager`, and is designed to
    56  make it easy to integrate KFuzzTest fuzzing into existing continuous fuzzing
    57  deployments.
    58  
    59  One must first write a syzlang description for the KFuzzTest target(s) of
    60  interest, for example in `/sys/linux/my_kfuzztest_target.txt`. Each target
    61  should have the following format:
    62  
    63  ```
    64  some_buffer {
    65          buf     ptr[inout, array[int8]]
    66          buflen  len[buf, int64]
    67  }
    68  
    69  kfuzztest_underflow_on_buffer(name ptr[in, string["test_underflow_on_buffer"]], data ptr[in, some_buffer], len bytesize[data], buf ptr[in, array[int8, 65536]]) (kfuzz_test)
    70  ```
    71  
    72  Where:
    73  
    74  - The first argument should be a string pointer to the name of the fuzz target,
    75    i.e,. the name of its `debugfs` input directory in the kernel.
    76  - The second should be a pointer to a struct of the type that the fuzz
    77    target accepts as input.
    78  - The third should be the size in bytes of the input argument.
    79  - The call is annotated with attribute `kfuzz_test`.
    80  
    81  The final `buf` argument is a buffer of size
    82  `KFUZZTEST_MAX_INPUT_SIZE = 16 * PAGE_SIZE` and is used internally to ensure
    83  that enough space is available in a program for the entire flattened input that
    84  is sent into a KFuzzTest target.
    85  
    86  For more information on writing syzkaller descriptions attributes, consult the
    87  [syscall description](syscall_descriptions.md) and [syscall description syntax](syscall_descriptions_syntax.md)
    88  documentation files.
    89  
    90  To facilitate the tedious task of writing  `syz_kfuzztest_run` descriptions, a
    91  tool (`tools/kfuzztest-gen`) is provided to automatically generate these from a
    92  `vmlinux` binary. One can run the tool and paste the output into a syzlang file.
    93  
    94  ```sh
    95  go run ./tools/kfuzztest-gen --vmlinux=path/to/vmlinux
    96  ```
    97  
    98  After writing these descriptions to a file under the `/sys/linux/` directory
    99  (for example, `/sys/linux/my_fuzz_targets.txt`), they need to be compiled with
   100  `make descriptions`.
   101  
   102  Finally, the targets can be enabled in `syz-manager` config file in the
   103  `enable_syscalls` field, e.g.
   104  
   105  ```json
   106  {
   107      "enable_syscalls": [ "syz_kfuzztest_run$test_underflow_on_buffer" ]
   108  }
   109  ```
   110  
   111  ### 2. `syz-manager` with dynamic discovery
   112  
   113  This feature greatly reduces the amount of setup needed for fuzzing KFuzzTest
   114  targets, by discovering them all dynamically at launch.
   115  
   116  This approach is considered less stable than the previous as it involves
   117  generating descriptions for KFuzzTest targets without human input and then
   118  immediately fuzzing them. It does, however, better reflect our intentions for
   119  KFuzzTest: continuously fuzzing the kernel with a dynamically changing set of
   120  targets with little intervention from syzkaller maintainers.
   121  
   122  To enable this feature, configure the experimental `enable_kfuzztest` option in
   123  the manager configuration, which enables all discovered KFuzzTest targets by
   124  default.
   125  
   126  ```json
   127  {
   128      "enable_kfuzztest": true
   129  }
   130  ```
   131  
   132  You must also enable pseudo-syscall `syz_kfuzztest_run`, like so:
   133  
   134  ```json
   135  {
   136      "enable_syscalls": [
   137          "syz_kfuzztest_run"
   138      ],
   139  }
   140  ```
   141  
   142  **IMPORTANT:** for dynamic discovery to work, it is essential for the kernel
   143  image pointed to by the manager configuration is built with `CONFIG_DWARF4` or
   144  `CONFIG_DWARF5` enabled, as dynamic target discovery depends on these symbols
   145  being emitted.
   146  
   147  ### 3. `syz-kfuzztest`, an in-VM standalone tool
   148  
   149  In contrast with `syz-manager`, `syz-kfuzztest` is designed to perform coverage
   150  guided fuzzing from within a VM directly rather than orchestrating a fleet of
   151  VMs. It is primarily targetted at development-time fuzzing, rather than longterm
   152  continuous fuzzing.
   153  
   154  For more information, consult [the `syz-kfuzztest` documentation](syz-kfuzztest.md).