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  ```