diff options
author | Max Moroz <mmoroz@chromium.org> | 2019-09-17 07:15:22 -0700 |
---|---|---|
committer | GitHub <noreply@github.com> | 2019-09-17 07:15:22 -0700 |
commit | d1ed6b87a740878117ce804734b92e65313d6b3c (patch) | |
tree | 60370890d81e6dd335a94d317bfaa4d9a27fb084 /docs | |
parent | 8b911bf10c9249f653747a022c73e923ffbd5b28 (diff) | |
download | oss-fuzz-d1ed6b87a740878117ce804734b92e65313d6b3c.tar.gz |
[docs] Add "Integrating a Go project" documentation page (#2714). (#2837)
* [docs] Add "Integrating a Go project" documentation page (#2714).
* rephrase go-fuzz mode description
Diffstat (limited to 'docs')
-rw-r--r-- | docs/getting-started/new-project-guide/go_lang.md | 82 | ||||
-rw-r--r-- | docs/getting-started/new_project_guide.md | 34 |
2 files changed, 101 insertions, 15 deletions
diff --git a/docs/getting-started/new-project-guide/go_lang.md b/docs/getting-started/new-project-guide/go_lang.md new file mode 100644 index 000000000..800485ca5 --- /dev/null +++ b/docs/getting-started/new-project-guide/go_lang.md @@ -0,0 +1,82 @@ +--- +layout: default +title: Integrating a Go project +parent: Setting up a new project +grand_parent: Getting started +nav_order: 1 +permalink: /getting-started/new-project-guide/go-lang/ +--- + +# Integrating a Go project +{: .no_toc} + +- TOC +{:toc} +--- + +The process of integrating a project written in Go with OSS-Fuzz is very similar +to the general +[Setting up a new project]({{ site.baseurl }}/getting-started/new-project-guide/) +process. The key specifics of integrating a Go project are outlined below. + +## Go-fuzz support + +OSS-Fuzz supports **go-fuzz** in the +[libFuzzer compatible mode](https://github.com/dvyukov/go-fuzz#libfuzzer-support) +only. In that mode, fuzz targets for Go use the libFuzzer engine with native Go +coverage instrumentation. Binaries compiled in this mode provide the same +libFuzzer command line interface as non-Go fuzz targets. + +## Project files + +The structure of the project directory in OSS-Fuzz repository doesn't differ for +projects written in Go. The project files have the following Go specific aspects. + +### project.yaml + +For projects written in Go, we use only `libfuzzer` fuzzing engine and `address` +sanitizer. +[Example](https://github.com/google/oss-fuzz/blob/356f2b947670b7eb33a1f535c71bc5c87a60b0d1/projects/syzkaller/project.yaml#L7): + +```yaml +fuzzing_engines: + - libfuzzer +sanitizers: + - address +``` + +### Dockerfile + +The OSS-Fuzz builder image has the latest stable release of Golang installed. In +order to install dependencies of your project, add `RUN go get ...` command to +your Dockerfile. +[Example](https://github.com/google/oss-fuzz/blob/356f2b947670b7eb33a1f535c71bc5c87a60b0d1/projects/syzkaller/Dockerfile#L23): + +```dockerfile +# Dependency for one of the fuzz targets. +RUN go get github.com/ianlancetaylor/demangle +``` + +### build.sh + +In order to build a Go fuzz target, you need to call `go-fuzz-build -libfuzzer` +command first, and then link the resulting `.a` file against +`$LIB_FUZZING_ENGINE` using the `$CXX $CXXFLAGS ...` command. +[Example](https://github.com/google/oss-fuzz/blob/356f2b947670b7eb33a1f535c71bc5c87a60b0d1/projects/syzkaller/build.sh#L19): + +```sh +function compile_fuzzer { + path=$1 + function=$2 + fuzzer=$3 + + # Instrument all Go files relevant to this fuzzer + go-fuzz-build -libfuzzer -func $function -o $fuzzer.a $path + + # Instrumented, compiled Go ($fuzzer.a) + fuzzing engine = fuzzer binary + $CXX $CXXFLAGS $LIB_FUZZING_ENGINE $fuzzer.a -lpthread -o $OUT/$fuzzer +} + +compile_fuzzer ./pkg/compiler Fuzz compiler_fuzzer +compile_fuzzer ./prog/test FuzzDeserialize prog_deserialize_fuzzer +``` diff --git a/docs/getting-started/new_project_guide.md b/docs/getting-started/new_project_guide.md index 317025ada..8018c6052 100644 --- a/docs/getting-started/new_project_guide.md +++ b/docs/getting-started/new_project_guide.md @@ -2,6 +2,7 @@ layout: default title: Setting up a new project parent: Getting started +has_children: true nav_order: 2 permalink: /getting-started/new-project-guide/ --- @@ -21,15 +22,11 @@ Before you can start setting up your new project for fuzzing, you must do the fo with the project you want to fuzz. For examples, see -[boringssl](https://github.com/google/boringssl/tree/master/fuzz), -[SQLite](https://www.sqlite.org/src/artifact/ad79e867fb504338), -[s2n](https://github.com/awslabs/s2n/tree/master/tests/fuzz), -[openssl](https://github.com/openssl/openssl/tree/master/fuzz), -[FreeType](http://git.savannah.gnu.org/cgit/freetype/freetype2.git/tree/src/tools/ftfuzzer), -[re2](https://github.com/google/re2/tree/master/re2/fuzzing), -[harfbuzz](https://github.com/behdad/harfbuzz/tree/master/test/fuzzing), -[pcre2](http://vcs.pcre.org/pcre2/code/trunk/src/pcre2_fuzzsupport.c?view=markup), and -[ffmpeg](https://github.com/FFmpeg/FFmpeg/blob/master/tools/target_dec_fuzzer.c). +[boringssl](https://github.com/google/boringssl/tree/master/fuzz) or +[SQLite](https://www.sqlite.org/src/artifact/ad79e867fb504338) (C/C++), +[go-fuzz](https://github.com/dvyukov/go-fuzz-corpus/tree/86a5af9d6842f80b205a082538ea28f61bbb8ccb) or +[syzkaller](https://github.com/google/syzkaller/tree/7c7ded697e6322b0975f061b7e268fe44f585dab/prog/test) +(Go). - [Install Docker](https://docs.docker.com/engine/installation) (Googlers can visit [go/installdocker](https://goto.google.com/installdocker)). @@ -164,16 +161,20 @@ reproducing and fixing bugs than the standard one outlined in the reproducing gu This configuration file defines the Docker image for your project. Your [build.sh](#build.sh) script will be executed in inside the container you define. For most projects, the image is simple: ```docker -FROM gcr.io/oss-fuzz-base/base-builder # base image with clang toolchain -MAINTAINER YOUR_EMAIL # maintainer for this file +FROM gcr.io/oss-fuzz-base/base-builder # base image with clang toolchain +MAINTAINER YOUR_EMAIL # maintainer for this file RUN apt-get update && apt-get install -y ... # install required packages to build your project -RUN git clone <git_url> <checkout_dir> # checkout all sources needed to build your project -WORKDIR <checkout_dir> # current directory for build script -COPY build.sh fuzzer.cc $SRC/ # copy build script and other fuzzer files in src dir +RUN go get ... # install dependencies to build your Go project +RUN git clone <git_url> <checkout_dir> # checkout all sources needed to build your project +WORKDIR <checkout_dir> # current directory for the build script +COPY build.sh fuzzer.cc $SRC/ # copy build script and other fuzzer files in src dir ``` In the above example, the git clone will check out the source to `$SRC/<checkout_dir>`. -For an example in Expat, see [expat/Dockerfile](https://github.com/google/oss-fuzz/tree/master/projects/expat/Dockerfile) +For an example, see +[expat/Dockerfile](https://github.com/google/oss-fuzz/tree/master/projects/expat/Dockerfile) +or +[syzkaller/Dockerfile](https://github.com/google/oss-fuzz/blob/master/projects/syzkaller/Dockerfile). ## build.sh @@ -206,6 +207,9 @@ $CXX $CXXFLAGS -std=c++11 -Ilib/ \ cp $SRC/*.dict $SRC/*.options $OUT/ ``` + +If your project is written in Go, check out the [Integrating a Go project]({{ site.baseurl }}//getting-started/new-project-guide/go-lang/) page. + **Notes:** 1. Don't assume the fuzzing engine is libFuzzer by default, because we generate builds for both libFuzzer and AFL fuzzing engine configurations. Instead, link the fuzzing engine using $LIB_FUZZING_ENGINE. |