diff options
Diffstat (limited to 'nyx_mode/README.md')
| -rw-r--r-- | nyx_mode/README.md | 47 |
1 files changed, 42 insertions, 5 deletions
diff --git a/nyx_mode/README.md b/nyx_mode/README.md index 11698df9..eee7d363 100644 --- a/nyx_mode/README.md +++ b/nyx_mode/README.md @@ -15,6 +15,7 @@ Underneath it is built upon KVM and QEMU and requires a modern Linux kernel requires an Intel processor (6th generation onwards) and a special 5.10 kernel (see [KVM-Nyx](https://github.com/nyx-fuzz/KVM-Nyx)). + ## Building Nyx mode 1. Install all the packages from [docs/INSTALL.md](../docs/INSTALL.md). @@ -41,6 +42,7 @@ requires an Intel processor (6th generation onwards) and a special 5.10 kernel 5. Optionally, for binary-only fuzzing: set up the required 5.10 kernel, see [KVM-Nyx](https://github.com/nyx-fuzz/KVM-Nyx). + ## Preparing to fuzz a target with Nyx mode For source instrumented fuzzing you can use any afl-cc mode, with LTO even @@ -68,12 +70,21 @@ This will create a directory with all necessary files and the Nyx configuration. The name of the directory will be whatever you choose for `PACKAGE-DIRECTORY` above. -In the final step for the packaging we generate the Nyx configuration: +Note that if the target reads from a file then use the `-file /path/to/file` +parameter to the above command. + +Note that Nyx does **not** support the afl `@@` argument. Instead pass +something like `-file /foo.file -args "--file /foo.file --other-args"` to +the above command. + + +Then the final step: we generate the Nyx package configuration: ```shell python3 nyx_mode/packer/packer/nyx_config_gen.py PACKAGE-DIRECTORY Kernel ``` + ## Fuzzing with Nyx mode All the hard parts are done, fuzzing with Nyx mode is easy - just supply the @@ -114,13 +125,39 @@ afl-fuzz -i in -o out -Y -S 1 -- ./PACKAGE-DIRECTORY afl-fuzz -i in -o out -Y -S 2 -- ./PACKAGE-DIRECTORY ``` + ## AFL++ companion tools (afl-showmap etc.) -Please note that AFL++ companion tools like afl-cmin, afl-showmap, etc. are -not supported with Nyx mode, only afl-fuzz. +AFL++ companion tools support Nyx mode and can be used to analyze or minimize one specific input or an entire output corpus. These tools work similarly to `afl-fuzz`. + +To run a target with one of these tools, add the `-X` parameter to the command line to enable Nyx mode, and pass the path to a Nyx package directory: + +```shell +afl-tmin -i in_file -o out_file -X -- ./PACKAGE-DIRECTORY +``` + +```shell +afl-analyze -i in_file -X -- ./PACKAGE-DIRECTORY +``` + +```shell +afl-showmap -i in_dir -o out_file -X -- ./PACKAGE-DIRECTORY +``` + +```shell +afl-cmin -i in_dir -o out_dir -X -- ./PACKAGE-DIRECTORY +``` + +On each program startup of one the AFL++ tools in Nyx mode, a Nyx VM is spawned, and a bootstrapping procedure is performed inside the VM to prepare the target environment. As a consequence, due to the bootstrapping procedure, the launch performance is much slower compared to other modes. However, this can be optimized by reusing an existing fuzzing snapshot to avoid the slow re-execution of the bootstrap procedure. + +A fuzzing snapshot is automatically created and stored in the output directory at `out_dir/workdir/snapshot/` by the first parent process of `afl-fuzz` if parallel mode is used. To enable this feature, set the path to an existing snapshot directory in the `NYX_REUSE_SNAPSHOT` environment variable and use the tools as usual: + +```shell +afl-fuzz -i ./in_dir -o ./out_dir -Y -M 0 ./PACKAGE-DIRECTORY + +NYX_REUSE_SNAPSHOT=./out_dir/workdir/snapshot/ afl-analyze -i in_file -X -- ./PACKAGE-DIRECTORY +``` -For source based instrumentation just use these tools normally, for -binary-only targets use with -Q for qemu_mode. ## Real-world examples |