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 OSS-Fuzz builder image has the latest stable release of Golang installed. In 63order to install dependencies of your project, add `RUN git clone ...` command to 64your Dockerfile. 65[Example](https://github.com/google/oss-fuzz/blob/356f2b947670b7eb33a1f535c71bc5c87a60b0d1/projects/syzkaller/Dockerfile#L23): 66 67```dockerfile 68# Dependency for one of the fuzz targets. 69RUN git clone --depth 1 https://github.com/ianlancetaylor/demangle 70``` 71 72go-fuzz will then automatically download the dependencies based on the go.mod file 73 74### build.sh 75 76In order to build a Go fuzz target, you need to call `go-fuzz` 77command first, and then link the resulting `.a` file against 78`$LIB_FUZZING_ENGINE` using the `$CXX $CXXFLAGS ...` command. 79 80The best way to do this is by using a `compile_go_fuzzer` script, 81as it also supports coverage builds. 82 83A usage example from go-dns project is 84 85```sh 86compile_go_fuzzer github.com/miekg/dns FuzzNewRR fuzz_newrr fuzz 87``` 88 89Arguments are : 90* path of the package with the fuzz target 91* name of the fuzz function 92* name of the fuzzer to be built 93* optional tag to be used by `go build` and such 94