]> git.bitcoin.ninja Git - rust-lightning/blob - fuzz/README.md
[router] Add and clarify comments describing router internals
[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 ### Execution
28
29 To run the Hongg fuzzer, do
30
31 ```shell
32 export CPU_COUNT=1 # replace as needed
33 export HFUZZ_BUILD_ARGS="--features honggfuzz_fuzz"
34 export HFUZZ_RUN_ARGS="-n $CPU_COUNT --exit_upon_crash"
35
36 export TARGET="msg_ping_target" # replace with the target to be fuzzed
37 cargo hfuzz run $TARGET 
38 ```
39
40 To see a list of available fuzzing targets, run:
41
42 ```shell
43 ls ./src/bin/
44 ```
45
46 ## A fuzz test failed on Travis, what do I do?
47
48 You're trying to create a PR, but need to find the underlying cause of that pesky fuzz failure blocking the merge?
49
50 Worry not, for this is easily traced.
51
52 If your Travis output log looks like this:
53
54 ```
55 Size:639 (i,b,hw,ed,ip,cmp): 0/0/0/0/0/1, Tot:0/0/0/2036/5/28604
56 Seen a crash. Terminating all fuzzing threads
57
58 … # a lot of lines in between
59
60 <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]
61 <0x0000000000000000> [func:UNKNOWN file: line:0 module:UNKNOWN]
62 =====================================================================
63 2d3136383734090101010101010101010101010101010101010101010101
64 010101010100040101010101010101010101010103010101010100010101
65 0069d07c319a4961
66 The command "if [ "$(rustup show | grep default | grep stable)" != "" ]; then cd fuzz && cargo test --verbose && ./travis-fuzz.sh; fi" exited with 1.
67 ```
68
69 Note that the penultimate stack trace line ends in `release/full_stack_target]`. That indicates that
70 the failing target was `full_stack`. To reproduce the error locally, simply copy the hex, 
71 and run the following from the `fuzz` directory:
72
73 ```shell
74 export TARGET="full_stack" # adjust for your output
75 export HEX="2d3136383734090101010101010101010101010101010101010101010101\
76 010101010100040101010101010101010101010103010101010100010101\
77 0069d07c319a4961" # adjust for your output
78
79 mkdir -p ./test_cases/$TARGET
80 echo $HEX | xxd -r -p > ./test_cases/$TARGET/any_filename_works
81
82 export RUST_BACKTRACE=1
83 cargo test
84 ```
85
86 This will reproduce the failing fuzz input and yield a usable stack trace.