1 files changed, 106 insertions, 0 deletions
diff --git a/docs/syz-kfuzztest.md b/docs/syz-kfuzztest.md
new file mode 100644
index 000000000..4df0248c5
--- /dev/null
+++ b/docs/syz-kfuzztest.md
@@ -0,0 +1,106 @@
+# `syz-kfuzztest`
+
+`syz-kfuzztest` is a standalone tool for fuzzing KFuzzTest targets from within
+the kernel being fuzzed (e.g., a VM).
+
+It is intended to be used for development-time fuzzing rather than continuous
+fuzzing like `syz-manager`.
+
+For more information on KFuzzTest, consult the [dedicated readme](kfuzztest.md)
+or the Kernel documentation.
+
+## Usage (in-VM fuzzing)
+
+### Getting the Kernel Ready
+
+It is important that the target Kernel image has the correct KConfig options
+enabled. Namely
+
+- `CONFIG_KFUZZTEST`
+- `CONFIG_DEBUG_FS`
+- `CONFIG_DEBUG_KERNEL`
+- `CONFIG_KCOV`
+- `CONFIG_DWARF4` or `CONFIG_DWARF5`
+- `CONFIG_KASAN` _(optional, choose your favorite sanitizers for a better shot
+  at finding bugs!)_
+
+Furthermore, as you will need to connect to the VM being tested through SSH and
+launch `syz-kfuzztest` _(a Go binary with LIBC dependencies)_, it is recommended
+to create an image for the kernel being fuzzed (e.g., a Debian Bullseye image).
+Detailed instructions on how to do this can be found in
+[this setup guide](linux/setup_ubuntu-host_qemu-vm_x86-64-kernel.md).
+
+### Building and Launching the Binary
+
+The `syz-kfuzztest` binary is built with `make syz-kfuzztest`, and is intended
+to run on the Kernel fuzzed. The common case for this is within a VM _(after
+all, the tool is trying to make the Kernel crash)_.
+
+Then, ensure that the `syz-kfuzztest` binary and `vmlinux` image are copied
+over into the VM. E.g.,
+
+```sh
+scp $KERNEL/vmlinux root@my-vm:~/syz-kfuzztest/vmlinux
+scp $SYZKALLER/bin/syz-kfuzztest root@lmy-vm:~/syz-kfuzztest/syz-kfuzztest
+```
+
+Then launched like this:
+
+```
+usage: ./bin/syz-kfuzztest [flags] [enabled targets]
+
+Args:
+  One fuzz test name per enabled fuzz test arg. If empty, defaults to
+  all discovered targets.
+Example:
+  ./syz-kfuzztest -vmlinux ~/kernel/vmlinux fuzz_target_0 fuzz_target_1
+Flags:
+  -display int
+        Number of seconds between console outputs (default 5)
+  -threads int
+        Number of threads (default 2)
+  -timeout int
+        Timeout between program executions in seconds (default 0)
+  -vmlinux string
+        Path to vmlinux binary (default "vmlinux")
+  -vv int
+        verbosity
+```
+
+The enabled targets, which are listed after the flag arguments, are the names of
+the enabled fuzz targets. For example given some KFuzzTest targets:
+
+```c
+FUZZ_TEST(kfuzztest_target_1, struct input_arg_type)
+{
+    /* ... */
+}
+
+FUZZ_TEST(kfuzztest_target_2, struct input_arg_type)
+{
+    /* ... */
+}
+
+```
+
+Can be fuzzed with:
+
+```bash
+./syz-kfuzztest -vmlinux path/to/vmlinux -threads 4 kfuzztest_target_1 kfuzztest_target_2
+```
+
+If the enabled targets list is left empty, `syz-kfuzztest` will fuzz all
+discovered targets in the kernel.
+
+On exit, `syz-kfuzztest` will write the collected program counters (which are
+collected with KCOV) into a file called `pcs.out`. These program counters can
+be fed into [`syz-cover`](../tools/syz-cover/syz-cover.go) to generate an HTML
+visualization of the lines that were covered during fuzzing. It is recommended
+to do this on the host machine rather than the VM.
+
+For example:
+
+```sh
+scp root@my-vm:~/syz-kfuzztest/pcs.out .
+go run tools/syz-cover -config my.cfg pcs.out # May require the -force flag.
+```