Skip to content
 编辑

How to contribute to syzkaller

How to contribute to syzkaller

If you want to contribute to the project, feel free to send a pull request following the guidelines below.

In case this is your first pull request to syzkaller, you will need to sign Google CLA and add yourself to AUTHORS/CONTRIBUTORS files in the first commit.

What to work on

Extending/improving system call descriptions is always a good idea.

Unassigned issues from the bug tracker are worth doing, but some of them might be complicated.

To contribute code or syscall descriptions, at the very least you need to be able to build and run syzkaller, see the instructions here.

Guidelines

If you want to work on something non-trivial, please briefly describe it on the syzkaller@googlegroups.com mailing list first, so that there is an agreement on the high level approach/design and no duplication of work between contributors.

Split large changes into smaller, logically cohesive commits. Small commits are much easier and faster to review and iterate on.

Everything that can be reasonably tested should be tested.

Provide enough documentation for other users to use the new feature.

Keep the style of the code, tests, comments, docs, log/error messages consistent with the existing style.

Continuous Integration (CI) system runs a number of tests and some [opinionated] style checks. They need to pass. You can test locally with make presubmit, if you don’t have some prerequisites installed, you may use syz-env (see below).

Commits

Commit messages should follow the following template:

dir/path: one-line description
<empty line>
Extended multi-line description that includes
the problem you are solving and how it is solved.

dir/path is a relative path to the main dir this commit changes (look at examples in the commit history). If several packages/dirs are significantly affected, then the following format is allowed:

dir1/path1, dir2/path2: one-line description

Though, dirs should not be included if they have only minor changes. For pervasive changes the following format is allowed:

all: one-line description

Please pay attention to punctuation. In particular:

Commit message line length is limited to 120 characters.

Also:

Pull requests

How to create a pull request on Github

This adds git origin my-origin with your repository and checks out new branch my-branch based on master 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 provides a working hermetic development environment based on a Docker container. If you don’t yet have Docker installed, see documentation, in particular regarding enabling sudo-less 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=$(readlink -f ~/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.

To update syz-env container to the latest version do:

docker pull gcr.io/syzkaller/env

If you do not have access to the gcr.io registry, there is also a mirror in docker.pkg.github.com registry. In order to use it, you need to authenticate Docker with your Github account with:

docker login https://docker.pkg.github.com

and then pull the image and retag it to the name expacted by syz-env:

docker pull docker.pkg.github.com/google/syzkaller/env
docker tag docker.pkg.github.com/google/syzkaller/env gcr.io/syzkaller/env