]> git.bitcoin.ninja Git - rust-lightning/blob - fuzz/README.md
Fix new unused variable warning in `test_utils.rs`
[rust-lightning] / 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. Fuzzing is further only effective with
10 a lot of CPU time, indicating that if crash scenarios are discovered on Travis with its low
11 runtime constraints, the crash is caused relatively easily.
12
13 ## How do I run fuzz tests locally?
14
15 You typically won't need to run the entire combination of different fuzzing tools. For local execution, `honggfuzz`
16 should be more than sufficient. 
17
18 ### Setup
19
20 To install `honggfuzz`, simply run
21
22 ```shell
23 cargo update
24 cargo install --force honggfuzz
25 ```
26
27 In some environments, you may want to pin the honggfuzz version to `0.5.52`:
28
29 ```shell
30 cargo update -p honggfuzz --precise "0.5.52"
31 cargo install --force honggfuzz --version "0.5.52"
32 ```
33
34 ### Execution
35
36 To run the Hongg fuzzer, do
37
38 ```shell
39 export CPU_COUNT=1 # replace as needed
40 export HFUZZ_BUILD_ARGS="--features honggfuzz_fuzz"
41 export HFUZZ_RUN_ARGS="-n $CPU_COUNT --exit_upon_crash"
42
43 export TARGET="msg_ping_target" # replace with the target to be fuzzed
44 cargo hfuzz run $TARGET
45 ```
46
47 (Or, for a prettier output, replace the last line with `cargo --color always hfuzz run $TARGET`.)
48
49 To see a list of available fuzzing targets, run:
50
51 ```shell
52 ls ./src/bin/
53 ```
54
55 ## A fuzz test failed on Travis, what do I do?
56
57 You're trying to create a PR, but need to find the underlying cause of that pesky fuzz failure blocking the merge?
58
59 Worry not, for this is easily traced.
60
61 If your Travis output log looks like this:
62
63 ```
64 Size:639 (i,b,hw,ed,ip,cmp): 0/0/0/0/0/1, Tot:0/0/0/2036/5/28604
65 Seen a crash. Terminating all fuzzing threads
66
67 … # a lot of lines in between
68
69 <0x0000555555565559> [func:UNKNOWN file: line:0 module:/home/travis/build/rust-bitcoin/rust-lightning/fuzz/hfuzz_target/x86_64-unknown-linux-gnu/release/full_stack_target]
70 <0x0000000000000000> [func:UNKNOWN file: line:0 module:UNKNOWN]
71 =====================================================================
72 2d3136383734090101010101010101010101010101010101010101010101
73 010101010100040101010101010101010101010103010101010100010101
74 0069d07c319a4961
75 The command "if [ "$(rustup show | grep default | grep stable)" != "" ]; then cd fuzz && cargo test --verbose && ./travis-fuzz.sh; fi" exited with 1.
76 ```
77
78 Note that the penultimate stack trace line ends in `release/full_stack_target]`. That indicates that
79 the failing target was `full_stack`. To reproduce the error locally, simply copy the hex, 
80 and run the following from the `fuzz` directory:
81
82 ```shell
83 export TARGET="full_stack" # adjust for your output
84 export HEX="2d3136383734090101010101010101010101010101010101010101010101\
85 010101010100040101010101010101010101010103010101010100010101\
86 0069d07c319a4961" # adjust for your output
87
88 mkdir -p ./test_cases/$TARGET
89 echo $HEX | xxd -r -p > ./test_cases/$TARGET/any_filename_works
90
91 export RUST_BACKTRACE=1
92 export RUSTFLAGS="--cfg=fuzzing"
93 cargo test
94 ```
95
96 Note that if the fuzz test failed locally, moving the offending run's trace 
97 to the `test_cases` folder should also do the trick; simply replace the `echo $HEX |` line above
98 with (the trace file name is of course a bit longer than in the example):
99
100 ```shell
101 mv hfuzz_workspace/fuzz_target/SIGABRT.PC.7ffff7e21ce1.STACK.[…].fuzz ./test_cases/$TARGET/
102 ```
103
104 This will reproduce the failing fuzz input and yield a usable stack trace.
105
106
107 ## How do I add a new fuzz test?
108
109 1. The easiest approach is to take one of the files in `fuzz/src/`, such as 
110 `process_network_graph.rs`, and duplicate it, renaming the new file to something more 
111 suitable. For the sake of example, let's call the new fuzz target we're creating 
112 `my_fuzzy_experiment`.
113
114 2. In the newly created file `fuzz/src/my_fuzzy_experiment.rs`, run a string substitution
115 of `process_network_graph` to `my_fuzzy_experiment`, such that the three methods in the
116 file are `do_test`, `my_fuzzy_experiment_test`, and `my_fuzzy_experiment_run`.
117
118 3. Adjust the body (not the signature!) of `do_test` as necessary for the new fuzz test.
119
120 4. In `fuzz/src/bin/gen_target.sh`, add a line reading `GEN_TEST my_fuzzy_experiment` to the 
121 first group of `GEN_TEST` lines (starting in line 9).
122
123 5. If your test relies on a new local crate, add that crate as a dependency to `fuzz/Cargo.toml`.
124
125 6. In `fuzz/src/lib.rs`, add the line `pub mod my_fuzzy_experiment`. Additionally, if 
126 you added a new crate dependency, add the `extern crate […]` import line.
127
128 7. Run `fuzz/src/bin/gen_target.sh`.
129
130 8. There is no step eight: happy fuzzing!