_ Git - rust-lightning/blob - fuzz/README.md

   1 # Fuzzing
   2
   3 Fuzz tests generate a ton of random parameter arguments to the program and then validate that none
   4 cause it to crash.
   5
   6 ## How does it work?
   7
   8 Typically, CI will run `ci-fuzz.sh` on one of the environments the automated tests are
   9 configured for. Fuzzing is further only effective with a lot of CPU time, indicating that if crash
  10 scenarios are discovered on CI with its low runtime constraints, the crash is caused relatively
  11 easily.
  12
  13 ## How do I run fuzz tests locally?
  14
  15 We support multiple fuzzing engines such as `honggfuzz`, `libFuzzer` and `AFL`. You typically won't
  16 need to run the entire suite of different fuzzing tools. For local execution, `honggfuzz`should be
  17 more than sufficient.
  18
  19 ### Setup
  20 #### Honggfuzz
  21 To install `honggfuzz`, simply run
  22
  23 ```shell
  24 cargo update
  25 cargo install --force honggfuzz
  26 ```
  27
  28 In some environments, you may want to pin the honggfuzz version to `0.5.52`:
  29
  30 ```shell
  31 cargo update -p honggfuzz --precise "0.5.52"
  32 cargo install --force honggfuzz --version "0.5.52"
  33 ```
  34
  35 #### cargo-fuzz / libFuzzer
  36 To install `cargo-fuzz`, simply run
  37
  38 ```shell
  39 cargo update
  40 cargo install --force cargo-fuzz
  41 ```
  42
  43 ### Execution
  44
  45 #### Honggfuzz
  46 To run fuzzing using `honggfuzz`, do
  47
  48 ```shell
  49 export CPU_COUNT=1 # replace as needed
  50 export HFUZZ_BUILD_ARGS="--features honggfuzz_fuzz"
  51 export HFUZZ_RUN_ARGS="-n $CPU_COUNT --exit_upon_crash"
  52
  53 export TARGET="msg_ping_target" # replace with the target to be fuzzed
  54 cargo hfuzz run $TARGET
  55 ```
  56
  57 (Or, for a prettier output, replace the last line with `cargo --color always hfuzz run $TARGET`.)
  58
  59 #### cargo-fuzz / libFuzzer
  60 To run fuzzing using `cargo-fuzz / libFuzzer`, run
  61
  62 ```shell
  63 rustup install nightly # Note: libFuzzer requires a nightly version of rust.
  64 cargo +nightly fuzz run --features "libfuzzer_fuzz" msg_ping_target
  65 ```
  66 Note: If you encounter a `SIGKILL` during run/build check for OOM in kernel logs and consider
  67 increasing RAM size for VM.
  68
  69 If you wish to just generate fuzzing binary executables for `libFuzzer` and not run them:
  70 ```shell
  71 cargo +nightly fuzz build --features "libfuzzer_fuzz" msg_ping_target
  72 # Generates binary artifact in path ./target/aarch64-unknown-linux-gnu/release/msg_ping_target
  73 # Exact path depends on your system architecture.
  74 ```
  75 You can upload the build artifact generated above to `ClusterFuzz` for distributed fuzzing.
  76
  77 ### List Fuzzing Targets
  78 To see a list of available fuzzing targets, run:
  79
  80 ```shell
  81 ls ./src/bin/
  82 ```
  83
  84 ## A fuzz test failed, what do I do?
  85
  86 You're trying to create a PR, but need to find the underlying cause of that pesky fuzz failure
  87 blocking the merge?
  88
  89 Worry not, for this is easily traced.
  90
  91 If your output log looks like this:
  92
  93 ```
  94 Size:639 (i,b,hw,ed,ip,cmp): 0/0/0/0/0/1, Tot:0/0/0/2036/5/28604
  95 Seen a crash. Terminating all fuzzing threads
  96
  97 … # a lot of lines in between
  98
  99 <0x0000555555565559> [func:UNKNOWN file: line:0 module:./rust-lightning/fuzz/hfuzz_target/x86_64-unknown-linux-gnu/release/full_stack_target]
 100 <0x0000000000000000> [func:UNKNOWN file: line:0 module:UNKNOWN]
 101 =====================================================================
 102 2d3136383734090101010101010101010101010101010101010101010101
 103 010101010100040101010101010101010101010103010101010100010101
 104 0069d07c319a4961
 105 The command "if [ "$(rustup show | grep default | grep stable)" != "" ]; then cd fuzz && cargo test --verbose && ./ci-fuzz.sh; fi" exited with 1.
 106 ```
 107
 108 Note that the penultimate stack trace line ends in `release/full_stack_target]`. That indicates that
 109 the failing target was `full_stack`. To reproduce the error locally, simply copy the hex,
 110 and run the following from the `fuzz` directory:
 111
 112 ```shell
 113 export TARGET="full_stack" # adjust for your output
 114 export HEX="2d3136383734090101010101010101010101010101010101010101010101\
 115 010101010100040101010101010101010101010103010101010100010101\
 116 0069d07c319a4961" # adjust for your output
 117
 118 mkdir -p ./test_cases/$TARGET
 119 echo $HEX | xxd -r -p > ./test_cases/$TARGET/any_filename_works
 120
 121 export RUST_BACKTRACE=1
 122 export RUSTFLAGS="--cfg=fuzzing"
 123 cargo test
 124 ```
 125
 126 Note that if the fuzz test failed locally, moving the offending run's trace
 127 to the `test_cases` folder should also do the trick; simply replace the `echo $HEX |` line above
 128 with (the trace file name is of course a bit longer than in the example):
 129
 130 ```shell
 131 mv hfuzz_workspace/fuzz_target/SIGABRT.PC.7ffff7e21ce1.STACK.[…].fuzz ./test_cases/$TARGET/
 132 ```
 133
 134 This will reproduce the failing fuzz input and yield a usable stack trace.
 135
 136
 137 ## How do I add a new fuzz test?
 138
 139 1. The easiest approach is to take one of the files in `fuzz/src/`, such as
 140 `process_network_graph.rs`, and duplicate it, renaming the new file to something more
 141 suitable. For the sake of example, let's call the new fuzz target we're creating
 142 `my_fuzzy_experiment`.
 143
 144 2. In the newly created file `fuzz/src/my_fuzzy_experiment.rs`, run a string substitution
 145 of `process_network_graph` to `my_fuzzy_experiment`, such that the three methods in the
 146 file are `do_test`, `my_fuzzy_experiment_test`, and `my_fuzzy_experiment_run`.
 147
 148 3. Adjust the body (not the signature!) of `do_test` as necessary for the new fuzz test.
 149
 150 4. In `fuzz/src/bin/gen_target.sh`, add a line reading `GEN_TEST my_fuzzy_experiment` to the
 151 first group of `GEN_TEST` lines (starting in line 9).
 152
 153 5. If your test relies on a new local crate, add that crate as a dependency to `fuzz/Cargo.toml`.
 154
 155 6. In `fuzz/src/lib.rs`, add the line `pub mod my_fuzzy_experiment`. Additionally, if
 156 you added a new crate dependency, add the `extern crate […]` import line.
 157
 158 7. Run `fuzz/src/bin/gen_target.sh`.
 159
 160 8. There is no step eight: happy fuzzing!