github.com/google/syzkaller@v0.0.0-20240517125934-c0f1611a36d6/docs/fuchsia/README.md (about) 1 # Fuchsia support 2 3 For information about checking out and building Fuchsia see [Get started with 4 Fuchsia](https://fuchsia.dev/fuchsia-src/get-started) and [Download the Fuchsia 5 source code](https://fuchsia.dev/fuchsia-src/get-started/get_fuchsia_source). 6 7 ## Caveat 8 9 Please note that Fuchsia support is currently incomplete, and may break at any 10 time due to changes in Fuchsia and/or Syzkaller. 11 12 Some known issues include: 13 14 * System call definitions require manual updates. 15 * Crash parsing does not work reliably. 16 * Coverage feedback is not supported. 17 18 ## Prerequisites 19 20 To run Syzkaller with a Fuchsia target, you will need a checkout of the Fuchsia 21 source repository. 22 23 The rest of this document will use the environment variable `SOURCEDIR` to 24 identify the path to your Fuchsia checkout (e.g. `/home/you/fuchsia`). The 25 commands below assume you have set `SOURCEDIR`, like so: 26 27 ```bash 28 export SOURCEDIR=/home/you/fuchsia 29 ``` 30 31 ## Quick and easy version 32 33 The shell script [setup.sh](setup.sh) automates the building and running 34 `syz-manager` steps described below. Give it a try, and see if it works for you. 35 For usage help, invoke it with no arguments. 36 37 ## Building Fuchsia 38 39 To build Fuchsia for x64, run: 40 41 ```bash 42 fx --dir "out/x64" set core.x64 \ 43 --with-base "//bundles/tools" \ 44 --with-base "//src/testing/fuzzing/syzkaller" \ 45 --args=syzkaller_dir='"/full/path/to/syzkaller"' \ 46 --variant=kasan 47 fx build 48 ``` 49 50 Alternatively, for arm64, run: 51 52 ```bash 53 fx --dir "out/arm64" set core.arm64 \ 54 --with-base "//bundles/tools" \ 55 --with-base "//src/testing/fuzzing/syzkaller" \ 56 --args=syzkaller_dir='"/full/path/to/syzkaller"' \ 57 --variant=kasan 58 fx clean-build 59 ``` 60 61 ## Building binaries for Fuchsia 62 63 To build all the binaries required for running Syzkaller in Fuchsia, run this 64 from inside your Syzkaller checkout (assuming you built Fuchsia for x64): 65 66 ```bash 67 make TARGETOS=fuchsia TARGETARCH=amd64 SOURCEDIR=${SOURCEDIR} 68 ``` 69 70 ## Running syz-manager 71 72 Running syz-manager requires you to have built Fuchsia previously, and added the 73 ssh keys to the fuchsia.zbi image: 74 75 The output of the Fuchsia build is a _product bundle_. Look up the image files needed 76 via `ffx product get-image-path`: 77 78 ```bash 79 product_bundle_path="$(ffx config get product.path | tr -d '"')" 80 fxfs_path="$(ffx product get-image-path "$product_bundle_path" --slot a --image-type fxfs)" 81 zbi_path="$(ffx product get-image-path "$product_bundle_path" --slot a --image-type zbi)" 82 multiboot_path="$(ffx product get-image-path "$product_bundle_path" --slot a --image-type qemu-kernel)" 83 ``` 84 85 Make sure the ssh keys exist and are properly configured: 86 87 ```bash 88 # Make sure there are ssh keys available 89 ffx config check-ssh-keys 90 auth_keys_path="$(ffx config get ssh.pub | tr -d '"')" 91 priv_key_path="$(ffx config get ssh.priv | tr -d '"')" 92 ``` 93 94 Add the authorized keys to the zbi. 95 ```bash 96 fx host-tool zbi -o "${SOURCEDIR}/out/x64/fuchsia-ssh.zbi" \ 97 "${zbi_path}" \ 98 --entry "data/ssh/authorized_keys=${auth_keys_path}" 99 ``` 100 101 Note: This needs to be repeated after each `fx build`. 102 103 Create a `syz-manager` configuration file, using this as a starting point: 104 105 ```json 106 { 107 "name": "fuchsia", 108 "target": "fuchsia/amd64", 109 "http": ":12345", 110 "workdir": "/workdir.fuchsia", 111 "kernel_obj": "/fuchsia/out/syz/kernel_x64-kasan/obj/zircon/kernel", 112 "syzkaller": "/syzkaller", 113 "image": "$fxfs_path", 114 "sshkey": "$priv_key_path", 115 "reproduce": false, 116 "cover": false, 117 "procs": 8, 118 "type": "qemu", 119 "vm": { 120 "count": 10, 121 "cpu": 4, 122 "mem": 2048, 123 "kernel": "${multiboot_path}", 124 "initrd": " ${SOURCEDIR}/out/x64/fuchsia-ssh.zbi" 125 } 126 } 127 ``` 128 129 Run `syz-manager` with that config: 130 131 ```bash 132 bin/syz-manager -config manager.cfg 133 ``` 134 135 Note: You may need to modify your `PATH` so that qemu can be found, e.g. 136 137 ```bash 138 export `PATH="$SOURCEDIR/prebuilt/third_party/qemu/linux-x64/bin:$PATH"` 139 ``` 140 141 ## Update syscall and FIDL definitions 142 143 Syscall descriptions live in the `sys/fuchsia` folder. To update a syscall, you 144 need to modify the `.txt` file that contains it, make sure your new definition 145 matches the one in Zircon's 146 [syscalls.abigen](https://fuchsia.googlesource.com/fuchsia/+/master/zircon/system/public/zircon/syscalls.abigen) 147 file. **If the syscall was used in `executor/common_fuchsia.h`, you need to 148 update the usages there as well.** FIDL definitions do not need manual updating 149 because they are extracted automatically when you run `make extract`, but they 150 require Fuchsia to be rebuilt for each architecture (see [Building 151 Fuchsia](#building-fuchsia) above). 152 153 Once you updated the syscall definitions, everything can be regenerated by 154 running (in your Syzkaller checkout): 155 156 ```bash 157 make extract TARGETOS=fuchsia SOURCEDIR=${SOURCEDIR} 158 make generate 159 ``` 160 161 **Caveat:** This command does not currently work. 162 163 ## How to generate syscall definitions from FIDL 164 165 TODO: This section is out of date. 166 167 Syscall descriptions for FIDL are automatically generated as part of `make 168 extract` as described above. 169 170 However, if you wish to manually generate syscall descriptions for a given 171 `.fidl` file, do the following. 172 173 FIDL files should first be compiled into FIDL intermediate representation (JSON) 174 files using `fidlc`: 175 176 ```bash 177 ${SOURCEDIR}/out/x64/host_x64/fidlc --json /tmp/io.json --files ${SOURCEDIR}/zircon/system/fidl/fuchsia-io/io.fidl 178 ``` 179 180 Then run the FIDL compiler backend `fidlgen` with the syzkaller generator, which 181 compiles a FIDL IR file into a syscall description file: 182 183 ```bash 184 ${SOURCEDIR}/out/x64/host_x64/fidlgen -generators syzkaller -json /tmp/io.json -output-base fidl_io -include-base fidl_io 185 ``` 186 187 ## Running syz-ci locally 188 189 To run `syz-ci` locally for Fuchsia, you need: 190 191 - bootstrapped Fuchsia checkout (in `/bootstrap/fuchsia` dir in the example below) 192 - bootstrap `syz-ci` binary (in the current dir, build with `make ci`) 193 - `syz-ci` config similar to the one below (in `ci.cfg` file in the current dir) 194 195 ```json 196 { 197 "name": "testci", 198 "http": ":50000", 199 "manager_port_start": 50001, 200 "syzkaller_repo": "https://github.com/google/syzkaller.git", 201 "managers": [ 202 { 203 "name": "fuchsia", 204 "repo": "https://fuchsia.googlesource.com", 205 "manager_config": { 206 "target": "fuchsia/amd64", 207 "type": "qemu", 208 "cover": false, 209 "procs": 8, 210 "vm": { 211 "count": 4, 212 "cpu": 4, 213 "mem": 1024 214 } 215 } 216 } 217 ] 218 } 219 ``` 220 221 Run `syz-ci` as: 222 223 ```bash 224 SOURCEDIR=/bootstrap/fuchsia ./syz-ci -config ci.cfg 225 ``` 226 227 ## Troubleshooting 228 229 While running the `make extract` step, it's possible that the FIDL definitions 230 are not up to date. It could happen that they have been removed or renamed. 231 232 If this is the case, you would see an error mentioning that the fidl.json file 233 could not be found: 234 235 ```bash 236 go generate ./sys/fuchsia 237 cannot find /path-to-fuchsia/out/x64/fidling/gen/zircon/public/fidl/zircon-ethernet/zircon-ethernet.fidl.json 238 exit status 1 239 ``` 240 241 You can search for the string in [the Fuchsia code search 242 interface](https://cs.opensource.google/fuchsia/fuchsia/+/main:) or in [the 243 Gerrit code-review tool](https://fuchsia-review.googlesource.com/) to see what 244 happened to it. If the FIDL interface was renamed or removed, you should update 245 `sys/fuchsia/fidlgen/main.go` to reflect this change, and remove the stale 246 autogenerated files.