From 3b8291bd1a368667df02bcf7cbf09b8a6a0e7dbb Mon Sep 17 00:00:00 2001 From: Dmitry Vyukov Date: Tue, 26 Feb 2019 13:38:57 +0100 Subject: docs: move OS-specific docs to subdirs Move freebsd, fuchsia, gvisor docs into own subdirs as we do for all other OSes. Add freebsd found_bugs.md. --- docs/freebsd.md | 101 --------------- docs/freebsd/README.md | 101 +++++++++++++++ docs/freebsd/found_bugs.md | 7 ++ docs/fuchsia.md | 134 -------------------- docs/fuchsia/README.md | 134 ++++++++++++++++++++ docs/gvisor.md | 303 --------------------------------------------- docs/gvisor/README.md | 303 +++++++++++++++++++++++++++++++++++++++++++++ docs/setup.md | 8 +- 8 files changed, 552 insertions(+), 539 deletions(-) delete mode 100644 docs/freebsd.md create mode 100644 docs/freebsd/README.md create mode 100644 docs/freebsd/found_bugs.md delete mode 100644 docs/fuchsia.md create mode 100644 docs/fuchsia/README.md delete mode 100644 docs/gvisor.md create mode 100644 docs/gvisor/README.md (limited to 'docs') diff --git a/docs/freebsd.md b/docs/freebsd.md deleted file mode 100644 index d15689ac5..000000000 --- a/docs/freebsd.md +++ /dev/null @@ -1,101 +0,0 @@ -# FreeBSD - -## How to run syzkaller on FreeBSD using qemu - -So far the process is tested only on linux/amd64 host. To build Go binaries do: -``` -make manager fuzzer execprog TARGETOS=freebsd -``` -To build C `syz-executor` binary, copy `executor/*` files to a FreeBSD machine and build there with: -``` -c++ executor/executor_freebsd.cc -o syz-executor -O1 -lpthread -DGOOS=\"freebsd\" -DGIT_REVISION=\"CURRENT_GIT_REVISION\" -``` -Then, copy out the binary back to host into `bin/freebsd_amd64` dir. - -Building/running on a FreeBSD host should work as well, but currently our `Makefile` does not work there, so you will need to do its work manually. - -Then, you need a FreeBSD image with root ssh access with a key. General instructions can be found here [qemu instructions](https://wiki.qemu.org/Hosts/BSD). I used `FreeBSD-11.0-RELEASE-amd64.qcow2` image, and it required a freashly built `qemu-system-x86_64` (networking did not work in the system-provided one). After booting add the following to `/boot/loader.conf`: -``` -autoboot_delay="-1" -console="comconsole" -``` -and the following to `/etc/rc.conf`: -``` -sshd_enable="YES" -ifconfig_em0="inet 10.0.0.1 netmask 255.255.255.0" -``` -Here is `/etc/ssh/sshd_config` that I used: -``` -Port 22 -AddressFamily any -ListenAddress 0.0.0.0 -ListenAddress :: -Protocol 2 -HostKey /etc/ssh/ssh_host_rsa_key -SyslogFacility AUTH -LogLevel INFO -AuthenticationMethods publickey password -PermitRootLogin yes -PubkeyAuthentication yes -AuthorizedKeysFile .ssh/authorized_keys .ssh/authorized_keys2 -PasswordAuthentication yes -PermitEmptyPasswords yes -Subsystem sftp /usr/libexec/sftp-server -``` - -Check that you can run the VM with: -``` -qemu-system-x86_64 -m 2048 -hda FreeBSD-11.0-RELEASE-amd64.qcow2 -enable-kvm -netdev user,id=mynet0,host=10.0.2.10,hostfwd=tcp::10022-:22 -device e1000,netdev=mynet0 -nographic -``` -and ssh into it with a key. - -If all of the above worked, create `freebsd.cfg` config file with the following contents (alter paths as necessary): -``` -{ - "name": "freebsd", - "target": "freebsd/amd64", - "http": ":10000", - "workdir": "/workdir", - "syzkaller": "/gopath/src/github.com/google/syzkaller", - "image": "/FreeBSD-11.1-RELEASE-amd64.qcow2", - "sshkey": "/freebsd_id_rsa", - "sandbox": "none", - "procs": 8, - "type": "qemu", - "vm": { - "qemu": "/qemu/build/x86_64-softmmu/qemu-system-x86_64", - "count": 10, - "cpu": 4, - "mem": 2048 - } -} -``` - -Then, start `syz-manager` with: -``` -bin/syz-manager -config freebsd.cfg -``` -It should start printing output along the lines of: -``` -booting test machines... -wait for the connection from test machine... -machine check: 253 calls enabled, kcov=true, kleakcheck=false, faultinjection=false, comps=false -executed 3622, cover 1219, crashes 0, repro 0 -executed 7921, cover 1239, crashes 0, repro 0 -executed 32807, cover 1244, crashes 0, repro 0 -executed 35803, cover 1248, crashes 0, repro 0 -``` -If something does not work, add `-debug` flag to `syz-manager`. - -## Missing things - -- Coverage. `executor/executor_freebsd.cc` uses a very primitive fallback for coverage. We need KCOV for FreeBSD. It will also help to assess what's covered and what's missing. -- System call descriptions. `sys/freebsd/*.txt` is a dirty copy from `sys/linux/*.txt` with everything that does not compile dropped. We need to go through syscalls and verify/fix/extend them, including devices/ioctls/etc. -- Currently only `amd64` arch is supported. Supporting `386` would be useful, because it should cover compat paths. Also, we could do testing of the linux-compatibility subsystem. -- `pkg/csource` needs to be taught how to generate/build C reproducers. -- `pkg/host` needs to be taught how to detect supported syscalls/devices. -- `pkg/report`/`pkg/symbolizer` need to be taught how to extract/symbolize kernel crash reports. -- We need to learn how to build/use debug version of kernel. -- KASAN for FreeBSD would be useful. -- On Linux we have emission of exernal networking/USB traffic into kernel using tun/gadgetfs. Implementing these for FreeBSD could uncover a number of high-profile bugs. -- Last but not least, we need to support FreeBSD in `syz-ci` command (including building kernel/image continuously from git). diff --git a/docs/freebsd/README.md b/docs/freebsd/README.md new file mode 100644 index 000000000..d15689ac5 --- /dev/null +++ b/docs/freebsd/README.md @@ -0,0 +1,101 @@ +# FreeBSD + +## How to run syzkaller on FreeBSD using qemu + +So far the process is tested only on linux/amd64 host. To build Go binaries do: +``` +make manager fuzzer execprog TARGETOS=freebsd +``` +To build C `syz-executor` binary, copy `executor/*` files to a FreeBSD machine and build there with: +``` +c++ executor/executor_freebsd.cc -o syz-executor -O1 -lpthread -DGOOS=\"freebsd\" -DGIT_REVISION=\"CURRENT_GIT_REVISION\" +``` +Then, copy out the binary back to host into `bin/freebsd_amd64` dir. + +Building/running on a FreeBSD host should work as well, but currently our `Makefile` does not work there, so you will need to do its work manually. + +Then, you need a FreeBSD image with root ssh access with a key. General instructions can be found here [qemu instructions](https://wiki.qemu.org/Hosts/BSD). I used `FreeBSD-11.0-RELEASE-amd64.qcow2` image, and it required a freashly built `qemu-system-x86_64` (networking did not work in the system-provided one). After booting add the following to `/boot/loader.conf`: +``` +autoboot_delay="-1" +console="comconsole" +``` +and the following to `/etc/rc.conf`: +``` +sshd_enable="YES" +ifconfig_em0="inet 10.0.0.1 netmask 255.255.255.0" +``` +Here is `/etc/ssh/sshd_config` that I used: +``` +Port 22 +AddressFamily any +ListenAddress 0.0.0.0 +ListenAddress :: +Protocol 2 +HostKey /etc/ssh/ssh_host_rsa_key +SyslogFacility AUTH +LogLevel INFO +AuthenticationMethods publickey password +PermitRootLogin yes +PubkeyAuthentication yes +AuthorizedKeysFile .ssh/authorized_keys .ssh/authorized_keys2 +PasswordAuthentication yes +PermitEmptyPasswords yes +Subsystem sftp /usr/libexec/sftp-server +``` + +Check that you can run the VM with: +``` +qemu-system-x86_64 -m 2048 -hda FreeBSD-11.0-RELEASE-amd64.qcow2 -enable-kvm -netdev user,id=mynet0,host=10.0.2.10,hostfwd=tcp::10022-:22 -device e1000,netdev=mynet0 -nographic +``` +and ssh into it with a key. + +If all of the above worked, create `freebsd.cfg` config file with the following contents (alter paths as necessary): +``` +{ + "name": "freebsd", + "target": "freebsd/amd64", + "http": ":10000", + "workdir": "/workdir", + "syzkaller": "/gopath/src/github.com/google/syzkaller", + "image": "/FreeBSD-11.1-RELEASE-amd64.qcow2", + "sshkey": "/freebsd_id_rsa", + "sandbox": "none", + "procs": 8, + "type": "qemu", + "vm": { + "qemu": "/qemu/build/x86_64-softmmu/qemu-system-x86_64", + "count": 10, + "cpu": 4, + "mem": 2048 + } +} +``` + +Then, start `syz-manager` with: +``` +bin/syz-manager -config freebsd.cfg +``` +It should start printing output along the lines of: +``` +booting test machines... +wait for the connection from test machine... +machine check: 253 calls enabled, kcov=true, kleakcheck=false, faultinjection=false, comps=false +executed 3622, cover 1219, crashes 0, repro 0 +executed 7921, cover 1239, crashes 0, repro 0 +executed 32807, cover 1244, crashes 0, repro 0 +executed 35803, cover 1248, crashes 0, repro 0 +``` +If something does not work, add `-debug` flag to `syz-manager`. + +## Missing things + +- Coverage. `executor/executor_freebsd.cc` uses a very primitive fallback for coverage. We need KCOV for FreeBSD. It will also help to assess what's covered and what's missing. +- System call descriptions. `sys/freebsd/*.txt` is a dirty copy from `sys/linux/*.txt` with everything that does not compile dropped. We need to go through syscalls and verify/fix/extend them, including devices/ioctls/etc. +- Currently only `amd64` arch is supported. Supporting `386` would be useful, because it should cover compat paths. Also, we could do testing of the linux-compatibility subsystem. +- `pkg/csource` needs to be taught how to generate/build C reproducers. +- `pkg/host` needs to be taught how to detect supported syscalls/devices. +- `pkg/report`/`pkg/symbolizer` need to be taught how to extract/symbolize kernel crash reports. +- We need to learn how to build/use debug version of kernel. +- KASAN for FreeBSD would be useful. +- On Linux we have emission of exernal networking/USB traffic into kernel using tun/gadgetfs. Implementing these for FreeBSD could uncover a number of high-profile bugs. +- Last but not least, we need to support FreeBSD in `syz-ci` command (including building kernel/image continuously from git). diff --git a/docs/freebsd/found_bugs.md b/docs/freebsd/found_bugs.md new file mode 100644 index 000000000..5de46cce4 --- /dev/null +++ b/docs/freebsd/found_bugs.md @@ -0,0 +1,7 @@ +# Found Bugs + +Newer bugs come first + +- [Fix a locking bug in the IPPROTO_SCTP level SCTP_EVENT socket option.](https://reviews.freebsd.org/rS343954) +- [Fix a locking issue in the IPPROTO_SCTP level SCTP_PEER_ADDR_THLDS socket](https://reviews.freebsd.org/rS343960) +- [Check the index hasn't changed after writing the cmp entry.](https://reviews.freebsd.org/rS344517) diff --git a/docs/fuchsia.md b/docs/fuchsia.md deleted file mode 100644 index dd5243f91..000000000 --- a/docs/fuchsia.md +++ /dev/null @@ -1,134 +0,0 @@ -# Fuchsia support - -For information about checking out and building Fuchsia see -[Getting Started](https://fuchsia.googlesource.com/docs/+/master/getting_started.md) -and [Soure Code](https://fuchsia.googlesource.com/docs/+/master/development/source_code/README.md). -Image needs to be configured with sshd support: -``` -fx set x64 --packages garnet/packages/products/sshd -fx full-build -``` - -You need to build fuchsia for both arm64 and amd64: - -``` -fx set arm64 --packages garnet/packages/products/sshd -fx full-build -``` - -Syscall descriptions live in the `sys/fuchsia` folder. To update a syscall, you need to modify the `.txt` file that contains it, make sure your new definition matches the one in zircon's [syscalls.abigen](https://fuchsia.googlesource.com/zircon/+/HEAD/system/public/zircon/syscalls.abigen) file. **If the syscall was used in `executor/common_fuchsia.h`, you need to update the usages there as well**. FIDL definitions do not need manual updating because they are extracted automatically with the commands below. - -Once you updated the syscalls definitions, everything can be regenerated by running: - -``` -make extract TARGETOS=fuchsia SOURCEDIR=/path/to/fuchsia/checkout -make generate -``` - -To build binaries: -``` -make TARGETOS=fuchsia TARGETARCH=amd64 SOURCEDIR=/path/to/fuchsia/checkout -``` - -Run `syz-manager` with a config along the lines of: -``` -{ - "name": "fuchsia", - "target": "fuchsia/amd64", - "http": ":12345", - "workdir": "/workdir.fuchsia", - "kernel_obj": "/fuchsia/out/build-zircon/build-x64", - "syzkaller": "/syzkaller", - "image": "/fuchsia/out/x64/out/build/images/fvm.blk", - "sshkey": "/fuchsia/out/x64/ssh-keys/id_ed25519", - "reproduce": false, - "cover": false, - "procs": 8, - "type": "qemu", - "vm": { - "count": 10, - "cpu": 4, - "mem": 2048, - "kernel": "/fuchsia/out/build-zircon/build-x64/zircon.bin", - "initrd": "/fuchsia/out/x64/bootdata-blob.bin" - } -} -``` - - -## How to generate syscall description for FIDL - -Syscall descriptions for FIDL are automatically generated as part of `make extract` as described above. - -However, if you wish to manually generate syscall descriptions for a given `.fidl` file, do the following. - -FIDL files should first be compiled into FIDL intermediate representation (JSON) files using `fidlc`: - -```bash -/fuchsia/out/x64/host_x64/fidlc --json /tmp/io.json --files /fuchsia/zircon/system/fidl/fuchsia-io/io.fidl -``` - -Then run FIDL compiler backend `fidlgen` with syzkaller generator, which compiles a FIDL IR file into a syscall description file: - -```bash -/fuchsia/out/x64/host_x64/fidlgen -generators syzkaller -json /tmp/io.json -output-base fidl_io -include-base fidl_io -``` -## Running syz-ci locally - -To run `syz-ci` locally for Fuchsia, you need: - -- Go 1.10 toolchain (in `/go1.10` dir in the example below) -- bootstrapped Fuchsia checkout (in `/bootstrap/fuchsia` dir in the example below) -- bootstrap `syz-ci` binary (in the current dir, build with `make ci`) -- `syz-ci` config similar to the one below (in `ci.cfg` file in the current dir) - -``` -{ - "name": "testci", - "http": ":50000", - "manager_port_start": 50001, - "goroot": "/go1.10", - "syzkaller_repo": "https://github.com/google/syzkaller.git", - "managers": [ - { - "name": "fuchsia", - "repo": "https://fuchsia.googlesource.com", - "manager_config": { - "target": "fuchsia/amd64", - "type": "qemu", - "cover": false, - "procs": 8, - "vm": { - "count": 4, - "cpu": 4, - "mem": 1024 - } - } - } - ] -} -``` - -Run `syz-ci` as: -``` -SOURCEDIR=/bootstrap/fuchsia ./syz-ci -config ci.cfg -``` - -## Troubleshooting - -While running the `make extract` step, it's possible that the fidl definitions -are not up to date. It could happen that they have been removed or renamed. - -If this is the case, you would see an error mentioning that the fidl.json file -could not be found: - -``` -go generate ./sys/fuchsia -cannot find /path-to-fuchsia/out/x64/fidling/gen/zircon/public/fidl/zircon-ethernet/zircon-ethernet.fidl.json -exit status 1 -``` - -You can search for the string in the fuchsia repos or in the code-review tool to -see what happened to it. If the fidl interface was renamed or removed, you -should update `sys/fuchsia/fidlgen/main.go` to reflect this change, and remove the -stale autogenerated files. diff --git a/docs/fuchsia/README.md b/docs/fuchsia/README.md new file mode 100644 index 000000000..dd5243f91 --- /dev/null +++ b/docs/fuchsia/README.md @@ -0,0 +1,134 @@ +# Fuchsia support + +For information about checking out and building Fuchsia see +[Getting Started](https://fuchsia.googlesource.com/docs/+/master/getting_started.md) +and [Soure Code](https://fuchsia.googlesource.com/docs/+/master/development/source_code/README.md). +Image needs to be configured with sshd support: +``` +fx set x64 --packages garnet/packages/products/sshd +fx full-build +``` + +You need to build fuchsia for both arm64 and amd64: + +``` +fx set arm64 --packages garnet/packages/products/sshd +fx full-build +``` + +Syscall descriptions live in the `sys/fuchsia` folder. To update a syscall, you need to modify the `.txt` file that contains it, make sure your new definition matches the one in zircon's [syscalls.abigen](https://fuchsia.googlesource.com/zircon/+/HEAD/system/public/zircon/syscalls.abigen) file. **If the syscall was used in `executor/common_fuchsia.h`, you need to update the usages there as well**. FIDL definitions do not need manual updating because they are extracted automatically with the commands below. + +Once you updated the syscalls definitions, everything can be regenerated by running: + +``` +make extract TARGETOS=fuchsia SOURCEDIR=/path/to/fuchsia/checkout +make generate +``` + +To build binaries: +``` +make TARGETOS=fuchsia TARGETARCH=amd64 SOURCEDIR=/path/to/fuchsia/checkout +``` + +Run `syz-manager` with a config along the lines of: +``` +{ + "name": "fuchsia", + "target": "fuchsia/amd64", + "http": ":12345", + "workdir": "/workdir.fuchsia", + "kernel_obj": "/fuchsia/out/build-zircon/build-x64", + "syzkaller": "/syzkaller", + "image": "/fuchsia/out/x64/out/build/images/fvm.blk", + "sshkey": "/fuchsia/out/x64/ssh-keys/id_ed25519", + "reproduce": false, + "cover": false, + "procs": 8, + "type": "qemu", + "vm": { + "count": 10, + "cpu": 4, + "mem": 2048, + "kernel": "/fuchsia/out/build-zircon/build-x64/zircon.bin", + "initrd": "/fuchsia/out/x64/bootdata-blob.bin" + } +} +``` + + +## How to generate syscall description for FIDL + +Syscall descriptions for FIDL are automatically generated as part of `make extract` as described above. + +However, if you wish to manually generate syscall descriptions for a given `.fidl` file, do the following. + +FIDL files should first be compiled into FIDL intermediate representation (JSON) files using `fidlc`: + +```bash +/fuchsia/out/x64/host_x64/fidlc --json /tmp/io.json --files /fuchsia/zircon/system/fidl/fuchsia-io/io.fidl +``` + +Then run FIDL compiler backend `fidlgen` with syzkaller generator, which compiles a FIDL IR file into a syscall description file: + +```bash +/fuchsia/out/x64/host_x64/fidlgen -generators syzkaller -json /tmp/io.json -output-base fidl_io -include-base fidl_io +``` +## Running syz-ci locally + +To run `syz-ci` locally for Fuchsia, you need: + +- Go 1.10 toolchain (in `/go1.10` dir in the example below) +- bootstrapped Fuchsia checkout (in `/bootstrap/fuchsia` dir in the example below) +- bootstrap `syz-ci` binary (in the current dir, build with `make ci`) +- `syz-ci` config similar to the one below (in `ci.cfg` file in the current dir) + +``` +{ + "name": "testci", + "http": ":50000", + "manager_port_start": 50001, + "goroot": "/go1.10", + "syzkaller_repo": "https://github.com/google/syzkaller.git", + "managers": [ + { + "name": "fuchsia", + "repo": "https://fuchsia.googlesource.com", + "manager_config": { + "target": "fuchsia/amd64", + "type": "qemu", + "cover": false, + "procs": 8, + "vm": { + "count": 4, + "cpu": 4, + "mem": 1024 + } + } + } + ] +} +``` + +Run `syz-ci` as: +``` +SOURCEDIR=/bootstrap/fuchsia ./syz-ci -config ci.cfg +``` + +## Troubleshooting + +While running the `make extract` step, it's possible that the fidl definitions +are not up to date. It could happen that they have been removed or renamed. + +If this is the case, you would see an error mentioning that the fidl.json file +could not be found: + +``` +go generate ./sys/fuchsia +cannot find /path-to-fuchsia/out/x64/fidling/gen/zircon/public/fidl/zircon-ethernet/zircon-ethernet.fidl.json +exit status 1 +``` + +You can search for the string in the fuchsia repos or in the code-review tool to +see what happened to it. If the fidl interface was renamed or removed, you +should update `sys/fuchsia/fidlgen/main.go` to reflect this change, and remove the +stale autogenerated files. diff --git a/docs/gvisor.md b/docs/gvisor.md deleted file mode 100644 index 63e353bda..000000000 --- a/docs/gvisor.md +++ /dev/null @@ -1,303 +0,0 @@ -# gVisor - -[gVisor](https://github.com/google/gvisor) is a user-space kernel, written in -Go, that implements a substantial portion of the Linux system surface. - -`gVisor` uses `linux` OS, but the special `gvisor` VM type. There is nothing -special regarding `gVisor` besides that. Here is an example manager config: - -``` -{ - "name": "gvisor", - "target": "linux/amd64", - "http": ":12345", - "workdir": "/workdir", - "image": "/usr/local/bin/runsc", - "syzkaller": "/gopath/src/github.com/google/syzkaller", - "cover": false, - "procs": 8, - "type": "gvisor", - "vm": { - "count": 5, - "runsc_args": "-platform=kvm" - } -} -``` - -## Reproducing crashes - -`syz-execprog` can be used inside gVisor to (hopefully) reproduce crashes. - -To run a single program inside a minimal gVisor sandbox, do the following. - -1. Build all of the syzkaller tools: - -```bash -$ cd $SYZKALLER_DIR -$ make -``` - -2. Build runsc: - -```bash -$ cd $GVISOR_DIR -$ bazel build //runsc -``` - -3. Create a `bundle/` directory with a config like the one below. Be sure to - update the paths to the `linux_amd64` directory and input log/program file. - -```bash -$ mkdir bundle -$ $EDITOR bundle/config.json -``` - -4. Run gVisor: - -```bash -$ sudo bazel-bin/runsc/linux_amd64_pure_stripped/runsc \ - -platform=ptrace \ - -file-access=shared \ - -network=host \ - run \ - -bundle /PATH/TO/bundle/ \ - syzkaller -``` - -5. Remove container: - -```bash -$ sudo bazel-bin/runsc/linux_amd64_pure_stripped/runsc delete -force syzkaller -``` - -Note that you'll want to adjust the `runsc` args to match the config in which -the crash was discovered. You may also want to add `-debug -strace` for more -debugging information. - -You can also adjust the args to `syz-execprog` in `config.json`. e.g., add -`-repeat` to repeat the program. - -### config.json - -```json -{ - "root": { - "path": "/PATH/TO/syzkaller/bin/linux_amd64", - "readonly": true - }, - "mounts": [ - { - "destination": "/input", - "source": "/PATH/TO/INPUT/LOG", - "type": "bind", - "options": ["ro"] - } - ], - "process":{ - "args": ["/syz-execprog", "-executor=/syz-executor", "-cover=false", "-sandbox=none", "/input"], - "cwd": "/tmp", - "capabilities": { - "bounding": [ - "CAP_CHOWN", - "CAP_DAC_OVERRIDE", - "CAP_DAC_READ_SEARCH", - "CAP_FOWNER", - "CAP_FSETID", - "CAP_KILL", - "CAP_SETGID", - "CAP_SETUID", - "CAP_SETPCAP", - "CAP_LINUX_IMMUTABLE", - "CAP_NET_BIND_SERVICE", - "CAP_NET_BROADCAST", - "CAP_NET_ADMIN", - "CAP_NET_RAW", - "CAP_IPC_LOCK", - "CAP_IPC_OWNER", - "CAP_SYS_MODULE", - "CAP_SYS_RAWIO", - "CAP_SYS_CHROOT", - "CAP_SYS_PTRACE", - "CAP_SYS_PACCT", - "CAP_SYS_ADMIN", - "CAP_SYS_BOOT", - "CAP_SYS_NICE", - "CAP_SYS_RESOURCE", - "CAP_SYS_TIME", - "CAP_SYS_TTY_CONFIG", - "CAP_MKNOD", - "CAP_LEASE", - "CAP_AUDIT_WRITE", - "CAP_AUDIT_CONTROL", - "CAP_SETFCAP", - "CAP_MAC_OVERRIDE", - "CAP_MAC_ADMIN", - "CAP_SYSLOG", - "CAP_WAKE_ALARM", - "CAP_BLOCK_SUSPEND", - "CAP_AUDIT_READ" - ], - "effective": [ - "CAP_CHOWN", - "CAP_DAC_OVERRIDE", - "CAP_DAC_READ_SEARCH", - "CAP_FOWNER", - "CAP_FSETID", - "CAP_KILL", - "CAP_SETGID", - "CAP_SETUID", - "CAP_SETPCAP", - "CAP_LINUX_IMMUTABLE", - "CAP_NET_BIND_SERVICE", - "CAP_NET_BROADCAST", - "CAP_NET_ADMIN", - "CAP_NET_RAW", - "CAP_IPC_LOCK", - "CAP_IPC_OWNER", - "CAP_SYS_MODULE", - "CAP_SYS_RAWIO", - "CAP_SYS_CHROOT", - "CAP_SYS_PTRACE", - "CAP_SYS_PACCT", - "CAP_SYS_ADMIN", - "CAP_SYS_BOOT", - "CAP_SYS_NICE", - "CAP_SYS_RESOURCE", - "CAP_SYS_TIME", - "CAP_SYS_TTY_CONFIG", - "CAP_MKNOD", - "CAP_LEASE", - "CAP_AUDIT_WRITE", - "CAP_AUDIT_CONTROL", - "CAP_SETFCAP", - "CAP_MAC_OVERRIDE", - "CAP_MAC_ADMIN", - "CAP_SYSLOG", - "CAP_WAKE_ALARM", - "CAP_BLOCK_SUSPEND", - "CAP_AUDIT_READ" - ], - "inheritable": [ - "CAP_CHOWN", - "CAP_DAC_OVERRIDE", - "CAP_DAC_READ_SEARCH", - "CAP_FOWNER", - "CAP_FSETID", - "CAP_KILL", - "CAP_SETGID", - "CAP_SETUID", - "CAP_SETPCAP", - "CAP_LINUX_IMMUTABLE", - "CAP_NET_BIND_SERVICE", - "CAP_NET_BROADCAST", - "CAP_NET_ADMIN", - "CAP_NET_RAW", - "CAP_IPC_LOCK", - "CAP_IPC_OWNER", - "CAP_SYS_MODULE", - "CAP_SYS_RAWIO", - "CAP_SYS_CHROOT", - "CAP_SYS_PTRACE", - "CAP_SYS_PACCT", - "CAP_SYS_ADMIN", - "CAP_SYS_BOOT", - "CAP_SYS_NICE", - "CAP_SYS_RESOURCE", - "CAP_SYS_TIME", - "CAP_SYS_TTY_CONFIG", - "CAP_MKNOD", - "CAP_LEASE", - "CAP_AUDIT_WRITE", - "CAP_AUDIT_CONTROL", - "CAP_SETFCAP", - "CAP_MAC_OVERRIDE", - "CAP_MAC_ADMIN", - "CAP_SYSLOG", - "CAP_WAKE_ALARM", - "CAP_BLOCK_SUSPEND", - "CAP_AUDIT_READ" - ], - "permitted": [ - "CAP_CHOWN", - "CAP_DAC_OVERRIDE", - "CAP_DAC_READ_SEARCH", - "CAP_FOWNER", - "CAP_FSETID", - "CAP_KILL", - "CAP_SETGID", - "CAP_SETUID", - "CAP_SETPCAP", - "CAP_LINUX_IMMUTABLE", - "CAP_NET_BIND_SERVICE", - "CAP_NET_BROADCAST", - "CAP_NET_ADMIN", - "CAP_NET_RAW", - "CAP_IPC_LOCK", - "CAP_IPC_OWNER", - "CAP_SYS_MODULE", - "CAP_SYS_RAWIO", - "CAP_SYS_CHROOT", - "CAP_SYS_PTRACE", - "CAP_SYS_PACCT", - "CAP_SYS_ADMIN", - "CAP_SYS_BOOT", - "CAP_SYS_NICE", - "CAP_SYS_RESOURCE", - "CAP_SYS_TIME", - "CAP_SYS_TTY_CONFIG", - "CAP_MKNOD", - "CAP_LEASE", - "CAP_AUDIT_WRITE", - "CAP_AUDIT_CONTROL", - "CAP_SETFCAP", - "CAP_MAC_OVERRIDE", - "CAP_MAC_ADMIN", - "CAP_SYSLOG", - "CAP_WAKE_ALARM", - "CAP_BLOCK_SUSPEND", - "CAP_AUDIT_READ" - ], - "ambient": [ - "CAP_CHOWN", - "CAP_DAC_OVERRIDE", - "CAP_DAC_READ_SEARCH", - "CAP_FOWNER", - "CAP_FSETID", - "CAP_KILL", - "CAP_SETGID", - "CAP_SETUID", - "CAP_SETPCAP", - "CAP_LINUX_IMMUTABLE", - "CAP_NET_BIND_SERVICE", - "CAP_NET_BROADCAST", - "CAP_NET_ADMIN", - "CAP_NET_RAW", - "CAP_IPC_LOCK", - "CAP_IPC_OWNER", - "CAP_SYS_MODULE", - "CAP_SYS_RAWIO", - "CAP_SYS_CHROOT", - "CAP_SYS_PTRACE", - "CAP_SYS_PACCT", - "CAP_SYS_ADMIN", - "CAP_SYS_BOOT", - "CAP_SYS_NICE", - "CAP_SYS_RESOURCE", - "CAP_SYS_TIME", - "CAP_SYS_TTY_CONFIG", - "CAP_MKNOD", - "CAP_LEASE", - "CAP_AUDIT_WRITE", - "CAP_AUDIT_CONTROL", - "CAP_SETFCAP", - "CAP_MAC_OVERRIDE", - "CAP_MAC_ADMIN", - "CAP_SYSLOG", - "CAP_WAKE_ALARM", - "CAP_BLOCK_SUSPEND", - "CAP_AUDIT_READ" - ] - } - } -} -``` diff --git a/docs/gvisor/README.md b/docs/gvisor/README.md new file mode 100644 index 000000000..63e353bda --- /dev/null +++ b/docs/gvisor/README.md @@ -0,0 +1,303 @@ +# gVisor + +[gVisor](https://github.com/google/gvisor) is a user-space kernel, written in +Go, that implements a substantial portion of the Linux system surface. + +`gVisor` uses `linux` OS, but the special `gvisor` VM type. There is nothing +special regarding `gVisor` besides that. Here is an example manager config: + +``` +{ + "name": "gvisor", + "target": "linux/amd64", + "http": ":12345", + "workdir": "/workdir", + "image": "/usr/local/bin/runsc", + "syzkaller": "/gopath/src/github.com/google/syzkaller", + "cover": false, + "procs": 8, + "type": "gvisor", + "vm": { + "count": 5, + "runsc_args": "-platform=kvm" + } +} +``` + +## Reproducing crashes + +`syz-execprog` can be used inside gVisor to (hopefully) reproduce crashes. + +To run a single program inside a minimal gVisor sandbox, do the following. + +1. Build all of the syzkaller tools: + +```bash +$ cd $SYZKALLER_DIR +$ make +``` + +2. Build runsc: + +```bash +$ cd $GVISOR_DIR +$ bazel build //runsc +``` + +3. Create a `bundle/` directory with a config like the one below. Be sure to + update the paths to the `linux_amd64` directory and input log/program file. + +```bash +$ mkdir bundle +$ $EDITOR bundle/config.json +``` + +4. Run gVisor: + +```bash +$ sudo bazel-bin/runsc/linux_amd64_pure_stripped/runsc \ + -platform=ptrace \ + -file-access=shared \ + -network=host \ + run \ + -bundle /PATH/TO/bundle/ \ + syzkaller +``` + +5. Remove container: + +```bash +$ sudo bazel-bin/runsc/linux_amd64_pure_stripped/runsc delete -force syzkaller +``` + +Note that you'll want to adjust the `runsc` args to match the config in which +the crash was discovered. You may also want to add `-debug -strace` for more +debugging information. + +You can also adjust the args to `syz-execprog` in `config.json`. e.g., add +`-repeat` to repeat the program. + +### config.json + +```json +{ + "root": { + "path": "/PATH/TO/syzkaller/bin/linux_amd64", + "readonly": true + }, + "mounts": [ + { + "destination": "/input", + "source": "/PATH/TO/INPUT/LOG", + "type": "bind", + "options": ["ro"] + } + ], + "process":{ + "args": ["/syz-execprog", "-executor=/syz-executor", "-cover=false", "-sandbox=none", "/input"], + "cwd": "/tmp", + "capabilities": { + "bounding": [ + "CAP_CHOWN", + "CAP_DAC_OVERRIDE", + "CAP_DAC_READ_SEARCH", + "CAP_FOWNER", + "CAP_FSETID", + "CAP_KILL", + "CAP_SETGID", + "CAP_SETUID", + "CAP_SETPCAP", + "CAP_LINUX_IMMUTABLE", + "CAP_NET_BIND_SERVICE", + "CAP_NET_BROADCAST", + "CAP_NET_ADMIN", + "CAP_NET_RAW", + "CAP_IPC_LOCK", + "CAP_IPC_OWNER", + "CAP_SYS_MODULE", + "CAP_SYS_RAWIO", + "CAP_SYS_CHROOT", + "CAP_SYS_PTRACE", + "CAP_SYS_PACCT", + "CAP_SYS_ADMIN", + "CAP_SYS_BOOT", + "CAP_SYS_NICE", + "CAP_SYS_RESOURCE", + "CAP_SYS_TIME", + "CAP_SYS_TTY_CONFIG", + "CAP_MKNOD", + "CAP_LEASE", + "CAP_AUDIT_WRITE", + "CAP_AUDIT_CONTROL", + "CAP_SETFCAP", + "CAP_MAC_OVERRIDE", + "CAP_MAC_ADMIN", + "CAP_SYSLOG", + "CAP_WAKE_ALARM", + "CAP_BLOCK_SUSPEND", + "CAP_AUDIT_READ" + ], + "effective": [ + "CAP_CHOWN", + "CAP_DAC_OVERRIDE", + "CAP_DAC_READ_SEARCH", + "CAP_FOWNER", + "CAP_FSETID", + "CAP_KILL", + "CAP_SETGID", + "CAP_SETUID", + "CAP_SETPCAP", + "CAP_LINUX_IMMUTABLE", + "CAP_NET_BIND_SERVICE", + "CAP_NET_BROADCAST", + "CAP_NET_ADMIN", + "CAP_NET_RAW", + "CAP_IPC_LOCK", + "CAP_IPC_OWNER", + "CAP_SYS_MODULE", + "CAP_SYS_RAWIO", + "CAP_SYS_CHROOT", + "CAP_SYS_PTRACE", + "CAP_SYS_PACCT", + "CAP_SYS_ADMIN", + "CAP_SYS_BOOT", + "CAP_SYS_NICE", + "CAP_SYS_RESOURCE", + "CAP_SYS_TIME", + "CAP_SYS_TTY_CONFIG", + "CAP_MKNOD", + "CAP_LEASE", + "CAP_AUDIT_WRITE", + "CAP_AUDIT_CONTROL", + "CAP_SETFCAP", + "CAP_MAC_OVERRIDE", + "CAP_MAC_ADMIN", + "CAP_SYSLOG", + "CAP_WAKE_ALARM", + "CAP_BLOCK_SUSPEND", + "CAP_AUDIT_READ" + ], + "inheritable": [ + "CAP_CHOWN", + "CAP_DAC_OVERRIDE", + "CAP_DAC_READ_SEARCH", + "CAP_FOWNER", + "CAP_FSETID", + "CAP_KILL", + "CAP_SETGID", + "CAP_SETUID", + "CAP_SETPCAP", + "CAP_LINUX_IMMUTABLE", + "CAP_NET_BIND_SERVICE", + "CAP_NET_BROADCAST", + "CAP_NET_ADMIN", + "CAP_NET_RAW", + "CAP_IPC_LOCK", + "CAP_IPC_OWNER", + "CAP_SYS_MODULE", + "CAP_SYS_RAWIO", + "CAP_SYS_CHROOT", + "CAP_SYS_PTRACE", + "CAP_SYS_PACCT", + "CAP_SYS_ADMIN", + "CAP_SYS_BOOT", + "CAP_SYS_NICE", + "CAP_SYS_RESOURCE", + "CAP_SYS_TIME", + "CAP_SYS_TTY_CONFIG", + "CAP_MKNOD", + "CAP_LEASE", + "CAP_AUDIT_WRITE", + "CAP_AUDIT_CONTROL", + "CAP_SETFCAP", + "CAP_MAC_OVERRIDE", + "CAP_MAC_ADMIN", + "CAP_SYSLOG", + "CAP_WAKE_ALARM", + "CAP_BLOCK_SUSPEND", + "CAP_AUDIT_READ" + ], + "permitted": [ + "CAP_CHOWN", + "CAP_DAC_OVERRIDE", + "CAP_DAC_READ_SEARCH", + "CAP_FOWNER", + "CAP_FSETID", + "CAP_KILL", + "CAP_SETGID", + "CAP_SETUID", + "CAP_SETPCAP", + "CAP_LINUX_IMMUTABLE", + "CAP_NET_BIND_SERVICE", + "CAP_NET_BROADCAST", + "CAP_NET_ADMIN", + "CAP_NET_RAW", + "CAP_IPC_LOCK", + "CAP_IPC_OWNER", + "CAP_SYS_MODULE", + "CAP_SYS_RAWIO", + "CAP_SYS_CHROOT", + "CAP_SYS_PTRACE", + "CAP_SYS_PACCT", + "CAP_SYS_ADMIN", + "CAP_SYS_BOOT", + "CAP_SYS_NICE", + "CAP_SYS_RESOURCE", + "CAP_SYS_TIME", + "CAP_SYS_TTY_CONFIG", + "CAP_MKNOD", + "CAP_LEASE", + "CAP_AUDIT_WRITE", + "CAP_AUDIT_CONTROL", + "CAP_SETFCAP", + "CAP_MAC_OVERRIDE", + "CAP_MAC_ADMIN", + "CAP_SYSLOG", + "CAP_WAKE_ALARM", + "CAP_BLOCK_SUSPEND", + "CAP_AUDIT_READ" + ], + "ambient": [ + "CAP_CHOWN", + "CAP_DAC_OVERRIDE", + "CAP_DAC_READ_SEARCH", + "CAP_FOWNER", + "CAP_FSETID", + "CAP_KILL", + "CAP_SETGID", + "CAP_SETUID", + "CAP_SETPCAP", + "CAP_LINUX_IMMUTABLE", + "CAP_NET_BIND_SERVICE", + "CAP_NET_BROADCAST", + "CAP_NET_ADMIN", + "CAP_NET_RAW", + "CAP_IPC_LOCK", + "CAP_IPC_OWNER", + "CAP_SYS_MODULE", + "CAP_SYS_RAWIO", + "CAP_SYS_CHROOT", + "CAP_SYS_PTRACE", + "CAP_SYS_PACCT", + "CAP_SYS_ADMIN", + "CAP_SYS_BOOT", + "CAP_SYS_NICE", + "CAP_SYS_RESOURCE", + "CAP_SYS_TIME", + "CAP_SYS_TTY_CONFIG", + "CAP_MKNOD", + "CAP_LEASE", + "CAP_AUDIT_WRITE", + "CAP_AUDIT_CONTROL", + "CAP_SETFCAP", + "CAP_MAC_OVERRIDE", + "CAP_MAC_ADMIN", + "CAP_SYSLOG", + "CAP_WAKE_ALARM", + "CAP_BLOCK_SUSPEND", + "CAP_AUDIT_READ" + ] + } + } +} +``` diff --git a/docs/setup.md b/docs/setup.md index 98184c221..81b001c97 100644 --- a/docs/setup.md +++ b/docs/setup.md @@ -1,7 +1,13 @@ # How to set up syzkaller Generic setup instructions for fuzzing Linux kernel are outlined [here](linux/setup.md). -For other OS kernels check: [Akaros](/docs/akaros/README.md), [FreeBSD](/docs/freebsd.md), [Fuchsia](/docs/fuchsia.md), [NetBSD](/docs/netbsd/README.md), [OpenBSD](/docs/openbsd/setup.md), [Windows](/docs/windows/README.md). +For other OS kernels check: +[Akaros](/docs/akaros/README.md), +[FreeBSD](/docs/freebsd/README.md), +[Fuchsia](/docs/fuchsia/README.md), +[NetBSD](/docs/netbsd/README.md), +[OpenBSD](/docs/openbsd/setup.md), +[Windows](/docs/windows/README.md). After following these instructions you should be able to run `syz-manager`, see it executing programs and be able to access statistics exposed at `http://127.0.0.1:56741`: -- cgit mrf-deployment