diff options
| -rw-r--r-- | Makefile | 4 | ||||
| -rw-r--r-- | docs/contributing.md | 25 | ||||
| -rw-r--r-- | tools/Dockerfile | 58 | ||||
| -rwxr-xr-x | tools/syz-env | 65 |
4 files changed, 150 insertions, 2 deletions
@@ -357,8 +357,8 @@ clean: rm -rf ./bin .descriptions sys/*/gen executor/defs.h executor/syscalls.h # For a tupical Ubuntu/Debian distribution. -# We use "|| true" for apt-get install because packages are all different on different distros, -# and we want to install at least golangci-lint on Travis CI. +# We use "|| true" for apt-get install because packages are all different on different distros. +# Also see tools/syz-env for container approach. install_prerequisites: uname -a sudo apt-get update diff --git a/docs/contributing.md b/docs/contributing.md index 6d5a1f321..fae689f6e 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -85,3 +85,28 @@ This adds git origin `my-origin` with your repository and checks out new branch - Nagivate to [github.com/google/syzkaller](https://github.com/google/syzkaller) and you should see green `Compare & pull request` button, press it. Then press `Create pull request`. Now your pull request should show up on [pull requests page](https://github.com/google/syzkaller/pulls). - If you don't see `Create pull request` button for any reason, you can create pull request manually. For that nagivate to [pull requests page](https://github.com/google/syzkaller/pulls), press `New pull request`, then `compare across forks` and choose `google/syzkaller`/`master` as base and `YOUR_GITHUB_USERNAME/syzkaller`/`my-branch` as compare and press `Create pull request`. - If you decided to rebase commits in `my-branch` (e.g. to rebase them onto updated master) after you created a pull-request, you will need to do a force push: `git push -f my-origin my-branch`. + +### Using syz-env + +Developing syzkaller requires a number of tools installed (Go toolchain, C/C++ cross-compilers, golangci-lint, etc). +Installing all of them may be cumbersome, e.g. due broken/missing packages. +[syz-env](/tools/syz-env) provides a working hermetic development environment based on a Docker container. +If you don't yet have Docker installed, see [documentation](https://docs.docker.com/engine/install), +in particular regarding enabling [sudo-less](https://docs.docker.com/engine/install/linux-postinstall) +Docker (Googlers see go/docker). + +It's recommended to create an alias for `syz-env` script: +``` +alias syz-env="$(go env GOPATH)/src/github.com/google/syzkaller/tools/syz-env" +``` +Then it can be used to wrap almost any make invocation as: +``` +syz-env make format +syz-env make presubmit +syz-env make extract SOURCEDIR=~/linux +``` +Or other commands/scripts, e.g.: +``` +syz-env go test -short ./pkg/csource +``` +Or you may run the shell inside of the container with just `syz-env` and look around. diff --git a/tools/Dockerfile b/tools/Dockerfile new file mode 100644 index 000000000..fb1214e4c --- /dev/null +++ b/tools/Dockerfile @@ -0,0 +1,58 @@ +# Copyright 2020 syzkaller project authors. All rights reserved. +# Use of this source code is governed by Apache 2 LICENSE that can be found in the LICENSE file. + +# The image provides dev environment suitable for syzkaller development/testing. +# It includes Go toolchain, C/C++ cross-compilers, go-fuzz and golangci-lint. + +# The image is available as gcr.io/syzkaller/env. + +# To download and run locally: +# docker pull gcr.io/syzkaller/env +# docker run -it gcr.io/syzkaller/env + +# To build and push new version: +# docker build -t gcr.io/syzkaller/env tools +# gcloud auth login && gcloud auth configure-docker +# docker push gcr.io/syzkaller/env + +FROM debian:buster + +LABEL homepage="https://github.com/google/syzkaller" + +RUN dpkg --add-architecture i386 && \ + apt-get update && \ + DEBIAN_FRONTEND=noninteractive apt-get install -y -q --no-install-recommends \ + sudo make nano git curl ca-certificates clang-format binutils g++ clang \ + g++-arm-linux-gnueabi g++-aarch64-linux-gnu g++-powerpc64le-linux-gnu g++-mips64el-linux-gnuabi64 \ + libc6-dev:i386 linux-libc-dev:i386 lib32gcc-8-dev lib32stdc++-8-dev \ + # These are needed to build Linux kernel: + flex bison bc libelf-dev libssl-dev && \ + apt-get -y autoremove && \ + apt-get clean autoclean && \ + rm -rf /var/lib/apt/lists/{apt,dpkg,cache,log} /tmp/* /var/tmp/* + +RUN curl https://dl.google.com/go/go1.14.2.linux-amd64.tar.gz | tar -C /usr/local -xz +ENV PATH /usr/local/go/bin:/gopath/bin:$PATH +ENV GOPATH /gopath + +# For golangci-lint we need only the binary. +RUN GO111MODULE=on go get github.com/golangci/golangci-lint/cmd/golangci-lint@v1.26.0 && \ + mv /gopath/bin/* /usr/local/bin/ && \ + rm -rf /gopath + +# For go-fuzz we also need sources (go-fuzz-dep). +RUN go get github.com/dvyukov/go-fuzz/go-fuzz github.com/dvyukov/go-fuzz/go-fuzz-build + +# Pre-create dirs for syz-dock. +# This is necessary to make docker work with the current user, +# otherwise --volume will create these dirs under root and then +# the current user won't have access to them. +RUN mkdir -p /syzkaller/gopath/src/github.com/google/syzkaller && \ + mkdir -p /syzkaller/.cache && \ + chmod -R 0777 /syzkaller + +# The default Docker prompt is too ugly and takes the whole line: +# I have no name!@0f3331d2fb54:~/gopath/src/github.com/google/syzkaller$ +RUN echo "export PS1='syz-env🈴 '" > /syzkaller/.bashrc + +ENTRYPOINT ["bash"] diff --git a/tools/syz-env b/tools/syz-env new file mode 100755 index 000000000..e8686cf6c --- /dev/null +++ b/tools/syz-env @@ -0,0 +1,65 @@ +#!/usr/bin/env bash +# Copyright 2020 syzkaller project authors. All rights reserved. +# Use of this source code is governed by Apache 2 LICENSE that can be found in the LICENSE file. + +# syz-env is a wrapper around gcr.io/syzkaller/env container, +# which includes all tools necessary to develop/test syzkaller. +# It's recommended to create an alias for this script: +# +# alias syz-env="$(go env GOPATH)/src/github.com/google/syzkaller/tools/syz-env" +# +# Then it can be used to wrap almost any make invocation as: +# +# syz-env make format +# syz-env make presubmit +# syz-env make extract SOURCEDIR=~/linux +# +# Or you may run the shell inside of the container with just syz-env. +# +# Note: this way everything runs inside of the container +# and uses all tools bundled in the container rather than host tools. +# +# Note: syz-env assumes a sudo-less Docker is installed, see: +# https://docs.docker.com/engine/install +# https://docs.docker.com/engine/install/linux-postinstall +# (Googlers see go/docker). + +COMMAND="" +DOCKERARGS=() +for ARG in "$@"; do + while IFS='=' read KEY VAL; do + # If we have a kernel path passed in, we mount it in the container + # at /syzkaller/kernel and fix up SOURCEDIR argument. + if [ "$KEY" == "SOURCEDIR" ]; then + DOCKERARGS+=" --volume $VAL:/syzkaller/kernel" + COMMAND+=" SOURCEDIR=/syzkaller/kernel" + else + COMMAND+=" $ARG" + fi + done <<< "$ARG" +done +if [ "$CI" == "" ]; then + # This gives interactive shell and allows to abort commands with Ctrl+C. + DOCKERARGS+=" -it" +fi +if [ "$COMMAND" == "" ]; then + COMMAND="bash" +fi + +SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)" + +# Run everything as the host user, this is important for created/modified files. +docker run \ + --user $(id -u ${USER}):$(id -g ${USER}) \ + --volume "$SCRIPT_DIR/..:/syzkaller/gopath/src/github.com/google/syzkaller" \ + --volume "$HOME/.cache:/syzkaller/.cache" \ + --volume "/var/run/docker.sock":"/var/run/docker.sock" \ + --workdir /syzkaller/gopath/src/github.com/google/syzkaller \ + --env HOME=/syzkaller \ + --env GOPATH=/syzkaller/gopath:/gopath \ + --env FUZZIT_API_KEY \ + --env GITHUB_REF \ + --env GITHUB_SHA \ + --env CI \ + ${DOCKERARGS[@]} \ + gcr.io/syzkaller/env -c "$COMMAND" |