1--- 2layout: default 3title: Integrating a Go project 4parent: Setting up a new project 5grand_parent: Getting started 6nav_order: 1 7permalink: /getting-started/new-project-guide/go-lang/ 8--- 9 10# Integrating a Go project 11{: .no_toc} 12 13- TOC 14{:toc} 15--- 16 17The process of integrating a project written in Go with OSS-Fuzz is very similar 18to the general 19[Setting up a new project]({{ site.baseurl }}/getting-started/new-project-guide/) 20process. The key specifics of integrating a Go project are outlined below. 21 22## Go-fuzz support 23 24OSS-Fuzz supports **go-fuzz** in the 25[libFuzzer compatible mode](https://github.com/mdempsky/go114-fuzz-build) 26only. In that mode, fuzz targets for Go use the libFuzzer engine with native Go 27coverage instrumentation. Binaries compiled in this mode provide the same 28libFuzzer command line interface as non-Go fuzz targets. 29 30## Project files 31 32First, you need to write a Go fuzz target that accepts a stream of bytes and 33calls the program API with that. This fuzz target should reside in your project 34repository 35([example](https://github.com/golang/go/blob/4ad13555184eb0697c2e92c64c1b0bdb287ccc10/src/html/fuzz.go#L13)). 36 37The structure of the project directory in OSS-Fuzz repository doesn't differ for 38projects written in Go. The project files have the following Go specific 39aspects. 40 41### project.yaml 42 43The `language` attribute must be specified. 44 45```yaml 46language: go 47``` 48 49The only supported fuzzing engine and sanitizer are `libfuzzer` and `address`, 50respectively. 51[Example](https://github.com/google/oss-fuzz/blob/356f2b947670b7eb33a1f535c71bc5c87a60b0d1/projects/syzkaller/project.yaml#L7): 52 53```yaml 54fuzzing_engines: 55 - libfuzzer 56sanitizers: 57 - address 58``` 59 60### Dockerfile 61 62The Dockerfile should start by `FROM gcr.io/oss-fuzz-base/base-builder-go` 63 64The OSS-Fuzz builder image has the latest stable release of Golang installed. In 65order to install dependencies of your project, add `RUN git clone ...` command to 66your Dockerfile. 67[Example](https://github.com/google/oss-fuzz/blob/356f2b947670b7eb33a1f535c71bc5c87a60b0d1/projects/syzkaller/Dockerfile#L23): 68 69```dockerfile 70# Dependency for one of the fuzz targets. 71RUN git clone --depth 1 https://github.com/ianlancetaylor/demangle 72``` 73 74go-fuzz will then automatically download the dependencies based on the go.mod file 75 76### build.sh 77 78In order to build a Go fuzz target, you need to call `go-fuzz` 79command first, and then link the resulting `.a` file against 80`$LIB_FUZZING_ENGINE` using the `$CXX $CXXFLAGS ...` command. 81 82The best way to do this is by using a `compile_go_fuzzer` script, 83as it also supports coverage builds. 84 85A usage example from go-dns project is 86 87```sh 88compile_go_fuzzer github.com/miekg/dns FuzzNewRR fuzz_newrr fuzz 89``` 90 91Arguments are : 92* path of the package with the fuzz target 93* name of the fuzz function 94* name of the fuzzer to be built 95* optional tag to be used by `go build` and such 96