Skip to content

Commit

Permalink
Move docs/tutorial to the Rust Fuzz Book.
Browse files Browse the repository at this point in the history
Fixes #41

Associated book PR: rust-fuzz/book#11
  • Loading branch information
frewsxcv committed Apr 11, 2018
1 parent 4cc2d49 commit 16032b9
Showing 1 changed file with 2 additions and 58 deletions.
60 changes: 2 additions & 58 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,65 +12,9 @@ This crate is currently under some churn -- in case stuff isn't working, please
$ cargo install cargo-fuzz
```

## Usage
## Documentation

First, set up your project for fuzzing:

```sh
$ cd /path/to/project
$ cargo fuzz init
```

This will create a `fuzz` folder, containing a fuzzing script called `fuzz_target_1` in the
`fuzz_targets/` subfolder. It is generally a good idea to check in the files generated by `init`.

`libFuzzer` is going to repeatedly call the body of `fuzz_target!()` with a byte buffer `data`,
until your program hits an error condition (segfault, panic, etc). Write your `fuzz_target!()`
body to hit the entry point you need.

You can add more fuzz target scripts via `cargo fuzz add name_of_script`. There
is a `Cargo.toml` in the `fuzz/` folder where you can add dependencies.

You can add initial corpus for your fuzz target by placing a file with any name into
the `fuzz/corpus/fuzz_target_1/` folder. Starting with a corpus that exercises many control paths
will greatly speed up fuzzing.

To fuzz a fuzz target, run:

```sh
$ cd /path/to/project
$ cargo fuzz run fuzz_target_1 # or whatever the target is named
```

Then, wait till it finds something! More complex invocations are available as well. Consider
looking at `cargo fuzz --help`, `cargo fuzz run --help` and others.

Once you have found something and believe you have fixed it, re-run the fuzz target with the input:

```sh
$ cargo fuzz run fuzz_target_1 fuzz/artifacts/fuzz_target_1/<file mentioned in crash output>
```

### Cargo features

It is possible to fuzz crates with different configurations of Cargo features by using
the command line options `--features`, `--no-default-features` and `--all-features`.
Note that these options control the `fuzz` crate; you will need to forward them to
the crate being fuzzed by e.g. adding the following to `fuzz/Cargo.toml`:

```toml
[features]
unsafe = ["project/unsafe"]
```

### #[cfg(fuzzing)]

Every crate instrumented for fuzzing -- the `fuzz` crate, the project crate, and
their entire dependency tree -- is compiled with the `--cfg fuzzing` rustc option.
This makes it possible to disable code paths that prevent fuzzing from working,
e.g. verification of cryptographic signatures, with a simple `#[cfg(not(fuzzing))]`,
and without the need for an externally visible Cargo feature that must be maintained
throughout every dependency.
Documentation can be found in the [Rust Fuzz Book](https://rust-fuzz.github.io/book/cargo-fuzz.html).

## Trophy case

Expand Down

0 comments on commit 16032b9

Please sign in to comment.