github.com/lzhfromustc/gofuzz@v0.0.0-20211116160056-151b3108bbd1/README.md (about) 1 - [Go Fuzz Project](#go-fuzz-project) 2 - [Project Structure](#project-structure) 3 - [Prerequisite](#prerequisite) 4 - [Dev Setup](#dev-setup) 5 - [Helper Scripts](#helper-scripts) 6 - [fuzz.sh](#fuzzsh) 7 8 # Go Fuzz Project 9 10 `Go Fuzz` aims find concurrency bugs in Golang program at runtime. 11 12 ## Project Structure 13 - goFuzz: contains packages/utilities that used to/in instrument/instrumented program. 14 - runtime: patched Golang runtime (1.14) for recording necessary information to find bugs. 15 16 ## Prerequisite 17 - Python 3.6+ 18 - Golang 1.14+ 19 20 ## Dev Setup 21 22 1. Copy gooracle 23 - Go Module: Put `goFuzz/gooracle` under the same root of go module of the target application 24 - Without Go Module: Put `goFuzz/gooracle` to $GOPATH/src/gooracle 25 26 2. Use goFuzz/runtime to overwrite the original runtime 27 Note: goFuzz/runtime is based on the runtime of go-1.14.2 28 Remember to have a backup of the original runtime. 29 30 3. Build utilities 31 32 ```bash 33 $ cd goFuzz 34 35 # This step will 36 # 1. Download dependencies by go mod tidy 37 # 2. Generate binary program 'instrument' 38 # 3. Generate binary program 'fuzz' 39 $ make build 40 ``` 41 42 4. Overwrite your runtime 43 44 ```bash 45 cd ./goFuzz/scripts 46 sudo ./editRuntime.sh 47 ``` 48 49 5. Instrument target application 50 ```bash 51 # Shihao's tool 52 $ ./goFuzz/scripts/instrument.py [folder contains Golang source code] 53 # Ziheng's way 54 cd ./goFuzz/cmd/instrument 55 go install 56 cd $GOPATH/bin 57 ./instrument -file=/Full/Path/Of/The/File/You/Want/To/Instrument 58 ``` 59 60 6. Run goFuzz/cmd/fuzz 61 62 For example: 63 `./fuzz -path=/data/ziheng/shared/gotest/stubs/grpc/grpc-last/src/google.golang.org/grpc -GOPATH=/data/ziheng/shared/gotest/stubs/grpc/grpc-last -output=/data/ziheng/shared/gotest/stubs/grpc/grpc-last/src/google.golang.org/grpc/myoutput.txt -test=TestStateTransitions_MultipleAddrsEntersReady` 64 65 This indicates: 66 67 run fuzzer on unit test "TestStateTransitions_MultipleAddrsEntersReady()", 68 69 which is in "/data/ziheng/shared/gotest/stubs/grpc/grpc-last/src/google.golang.org/grpc", 70 71 and its GOPATH is "/data/ziheng/shared/gotest/stubs/grpc/grpc-last". 72 73 Print the output to "/data/ziheng/shared/gotest/stubs/grpc/grpc-last/src/google.golang.org/grpc/myoutput.txt". 74 75 And use global tuple strategy 76 77 BTW, we need to remove "(s)" before "TestStateTransitions_MultipleAddrsEntersReady()" manually. This is a special problem with grpc 78 79 80 -path=/Users/xsh/code/goFuzz/goFuzz/example/simple1 -GOPATH=/Users/xsh/code/goFuzz/goFuzz/example -output=/Users/xsh/code/goFuzz/goFuzz/example/simple1/myoutput.txt -test=TestHello 81 82 83 ## Helper Scripts 84 85 ### fuzz.sh 86 87 Usage: 88 ```bash 89 ./fuzz.sh <target dir contains go.mod> <output dir> <parallel> [...optional flags passed to fuzz binary] 90 91 Reminder: Optional flags cannot be -goModDir, -chCover, -outputDir and -parallel since they are already filled by the script. 92 93 ``` 94 95 Usage: 96 ```bash 97 ./fuzz-git.sh <target git> <commit> <output> [...optional flags passed to fuzz binary] 98 99 Reminder: Optional flags cannot be -goModDir, -chCover, -outputDir and -parallel since they are already filled by the script. 100 101 // Example: 102 // ./fuzz-git.sh https://github.com/etcd-io/etcd.git bbe1e78e6242a57d54c4b96d8c49ea1e094c3cbb ~/out/etcd 103 ```