_ 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 cause it to crash.
   4
   5 ## How does it work?
   6
   7 Typically, Travis CI will run `travis-fuzz.sh` on one of the environments the automated tests are configured for.
   8 This is the most time-consuming component of the continuous integration workflow, so it is recommended that you detect
   9 issues locally, and Travis merely acts as a sanity check.
  10
  11 ## How do I run fuzz tests locally?
  12
  13 You typically won't need to run the entire combination of different fuzzing tools. For local execution, `honggfuzz`
  14 should be more than sufficient.
  15
  16 ### Setup
  17
  18 To install `honggfuzz`, simply run
  19
  20 ```shell
  21 cargo update
  22 cargo install honggfuzz --force
  23 ```
  24
  25 ### Execution
  26
  27 To run the Hongg fuzzer, do
  28
  29 ```shell
  30 export CPU_COUNT=1 # replace as needed
  31 export HFUZZ_BUILD_ARGS="--features honggfuzz_fuzz"
  32 export HFUZZ_RUN_ARGS="-n $CPU_COUNT --exit_upon_crash"
  33
  34 export TARGET="msg_ping_target" # replace with the target to be fuzzed
  35 cargo hfuzz run $TARGET
  36 ```
  37
  38 To see a list of available fuzzing targets, run:
  39
  40 ```shell
  41 ls ./src/bin/
  42 ```
  43
  44 ## A fuzz test failed on Travis, what do I do?
  45
  46 You're trying to create a PR, but need to find the underlying cause of that pesky fuzz failure blocking the merge?
  47
  48 Worry not, for this is easily traced.
  49
  50 If your Travis output log looks like this:
  51
  52 ```
  53 Size:639 (i,b,hw,ed,ip,cmp): 0/0/0/0/0/1, Tot:0/0/0/2036/5/28604
  54 Seen a crash. Terminating all fuzzing threads
  55
  56 … # a lot of lines in between
  57
  58 <0x0000000000000000> [func:UNKNOWN file: line:0 module:UNKNOWN]
  59 =====================================================================
  60 2d3136383734090101010101010101010101010101010101010101010101
  61 010101010100040101010101010101010101010103010101010100010101
  62 0069d07c319a4961
  63 The command "if [ "$(rustup show | grep default | grep stable)" != "" ]; then cd fuzz && cargo test --verbose && ./travis-fuzz.sh; fi" exited with 1.
  64 ```
  65
  66 Simply copy the hex, and run the following from the `fuzz` directory:
  67
  68 ```shell
  69 export HEX="2d3136383734090101010101010101010101010101010101010101010101\
  70 010101010100040101010101010101010101010103010101010100010101\
  71 0069d07c319a4961" # adjust for your output
  72 echo $HEX | xxd -r -p > ./test_cases/full_stack/your_test_case_name
  73
  74 export RUST_BACKTRACE=1
  75 cargo test
  76 ```
  77
  78 This will reproduce the failing fuzz input and yield a usable stack trace.