| # Run a fuzzer | |
| Once you have [built your fuzzer](build-a-fuzzer.md#fx-set), there are a few ways to execute it. | |
| ## Run a fuzzer on a Fuchsia device {#run-on-device} | |
| You can use the `ffx fuzz` tool to run a fuzzer on your local device. This is the recommended way to | |
| run your fuzzer while you are developing it. The tool is useful in that it knows how to find | |
| fuzzing-related files and knows various common [options][options]{:.external}. | |
| When fuzzing locally, it is often convenient to use the interactive fuzzing shell, which can be | |
| started using `ffx fuzz shell`. This shell can maintain a connection to a fuzzer, and provides | |
| utilities such as tab-completion. It supports a number of commands: | |
| * To list available fuzzers: | |
| <pre class="devsite-terminal"> | |
| list [-p <pattern>] | |
| </pre> | |
| * To connect to a fuzzer, starting it if needed: | |
| <pre class="devsite-terminal"> | |
| attach <url> [-o <output>] | |
| </pre> | |
| * To get option(s) from a fuzzer: | |
| <pre class="devsite-terminal"> | |
| get [<name>] | |
| </pre> | |
| * To set options on a fuzzer: | |
| <pre class="devsite-terminal"> | |
| set <name> <value> | |
| </pre> | |
| * To add an input to a fuzzer's corpus: | |
| <pre class="devsite-terminal"> | |
| add <input> [--seed] | |
| </pre> | |
| * To test a specific input with a fuzzer: | |
| <pre class="devsite-terminal"> | |
| try <input> | |
| </pre> | |
| * To generate inputs and fuzz the target: | |
| <pre class="devsite-terminal"> | |
| run [--runs <runs>] [--time <time>] | |
| </pre> | |
| * To clear extraneous bytes from an error input: | |
| <pre class="devsite-terminal"> | |
| cleanse <input> | |
| </pre> | |
| * To reduce the size of an error input: | |
| <pre class="devsite-terminal"> | |
| minimize <input> [--runs <runs>] [--time <time>] | |
| </pre> | |
| * To compact the attached fuzzer's corpus: | |
| <pre class="devsite-terminal"> | |
| merge [--corpus <corpus>] | |
| </pre> | |
| * To get a fuzzer's execution status: | |
| <pre class="devsite-terminal"> | |
| status | |
| </pre> | |
| * To retrieve the attached fuzzer's corpus: | |
| <pre class="devsite-terminal"> | |
| fetch [--corpus <corpus>] [--seed] | |
| </pre> | |
| * To disconnect from a fuzzer without stopping it: | |
| <pre class="devsite-terminal"> | |
| detach | |
| </pre> | |
| * To stop the attached fuzzer: | |
| <pre class="devsite-terminal"> | |
| stop | |
| </pre> | |
| * To disconnect from a fuzzer and exit the shell: | |
| <pre class="devsite-terminal"> | |
| exit | |
| </pre> | |
| * To clear the screen: | |
| <pre class="devsite-terminal"> | |
| clear | |
| </pre> | |
| * To print the command history for the shell: | |
| <pre class="devsite-terminal"> | |
| history | |
| </pre> | |
| Most commands require a fuzzer to be attached to the shell using the fuzzer's | |
| [component URL][glossary.component-url]. Once attached, the fuzzer component | |
| remains alive until it is stopped, either by the `stop` command or by | |
| [Test Manager][test_manager]. You can detach from a fuzzer and reattach to it | |
| later. | |
| Note: if `attach` reports that the component cannot be found or cannot be resolved, check that the | |
| component is available to the [component resolver][component-resolvers]. Typically this means | |
| ensuring [`fx serve`][fx-serve] is running or including your fuzzer in the | |
| [base image][package-deployment-options]. | |
| Several of the commands represent long-running workflows. These include the most important command, | |
| `run`, which performs coverage-guided fuzzing. These also include `try`, `cleanse`, `minimize`, and | |
| `merge`. All of these may execute for an indefinite amount of time. | |
| Commands that take inputs accept both files and hexadecimal values. If the provided input is | |
| ambiguous, `ffx fuzz` will treat it as a hexadecimal value and print a warning. Treatment as a file | |
| can be forced by adding path elements, e.g. `./deadbeef` is a file while `deadbeef` is a value. | |
| Putting this all together, a typical workflow might look like the following, minus the comments: | |
| ```sh | |
| attach fuchsia-pkg://fuchsia.com/my-fuzzers#meta/my-fuzzer.cm # Connect to the fuzzer. | |
| run -t 60m # Run for up to one hour. | |
| try deadbeef # Try a specific input, e.g. reproduce an error found by the step above. | |
| merge -c my-local-dir # Shrink the corpus as much as possible and save it. | |
| stop | |
| exit | |
| ``` | |
| ## Run a fuzzer on a development host {#run-on-host} | |
| You can run host fuzzers built by the Fuchsia build system as host tools, although the extra tooling | |
| of `ffx fuzz` is not supported. This means you need to manually add any | |
| [libFuzzer options][options]{:external} to your `fx host-tool` invocation. | |
| For example: | |
| <pre class="devsite-terminal"> | |
| fx host-tool my_host_fuzzer -runs=1000 | |
| </pre> | |
| You can see all available options by using `-help=1`: | |
| <pre class="devsite-terminal"> | |
| fx host-tool my_host_fuzzer -help=1 | |
| </pre> | |
| ## Run a fuzzer on ClusterFuzz {#run-on-clusterfuzz} | |
| This is the easiest and most recommended way to run a fuzzer after initial development. To run your | |
| fuzzer on [ClusterFuzz][clusterfuzz]{:.external}, you simply need to ensure it is a [GN][fuchsia-gn] | |
| dependency of `//bundles/buildbot/core`. Practically, this means including it in your code's "tests" | |
| GN target. | |
| For example: | |
| ``` | |
| group("tests") { | |
| deps = [ | |
| ":existing-unittest-package", | |
| ":my-fuzzers", | |
| ] | |
| } | |
| ``` | |
| If you are unsure if your fuzzer is included in the dependency graph, you can check using `gn path`. | |
| For example: | |
| <pre class="devsite-terminal"> | |
| fx gn path out/default //bundles/buildbot/core <var>path-to-fuzzer</var> | |
| </pre> | |
| For `//examples/fuzzers`, this yields: | |
| <pre> | |
| //bundles/buildbot/core --[public]--> | |
| //examples:examples --[private]--> | |
| //examples/fuzzers:fuzzers | |
| 1 non-data path found. It is not public. | |
| </pre> | |
| All fuzzers in that dependency graph will be made available to ClusterFuzz to select and run. If | |
| ClusterFuzz opens bugs, you can use its outputs to reproduce its findings. | |
| See [Handling results found through fuzzing](handle-results.md#clusterfuzz-bugs). | |
| [component-resolvers]: /docs/concepts/components/v2/capabilities/resolver.md | |
| [clusterfuzz]: https://google.github.io/clusterfuzz/ | |
| [glossary.component-url]: /docs/glossary/README.md#component-url | |
| [fuchsia-gn]: /docs/development/build/gn_concepts/intro.md | |
| [fx-serve]: /tools/devshell/serve | |
| [options]: https://llvm.org/docs/LibFuzzer.html#options | |
| [package-deployment-options]: /docs/development/build/fx.md#package_deployment_options | |
| [test_manager]: /docs/development/testing/components/test_runner_framework.md#the_test_manager |