| 1 |
# The `libfuzzer-sys` Crate |
| 2 |
|
| 3 |
Barebones wrapper around LLVM's libFuzzer runtime library. |
| 4 |
|
| 5 |
The CPP parts are extracted from compiler-rt git repository with `git filter-branch`. |
| 6 |
|
| 7 |
libFuzzer relies on LLVM sanitizer support. The Rust compiler has built-in support for LLVM sanitizer support, for now, it's limited to Linux. As a result, `libfuzzer-sys` only works on Linux. |
| 8 |
|
| 9 |
## Usage |
| 10 |
|
| 11 |
### Use `cargo fuzz`! |
| 12 |
|
| 13 |
[The recommended way to use this crate with `cargo fuzz`!][cargo-fuzz]. |
| 14 |
|
| 15 |
[cargo-fuzz]: https://github.com/rust-fuzz/cargo-fuzz |
| 16 |
|
| 17 |
### Manual Usage |
| 18 |
|
| 19 |
This crate can also be used manually as following: |
| 20 |
|
| 21 |
First create a new cargo project: |
| 22 |
|
| 23 |
``` |
| 24 |
$ cargo new --bin fuzzed |
| 25 |
$ cd fuzzed |
| 26 |
``` |
| 27 |
|
| 28 |
Then add a dependency on the `fuzzer-sys` crate and your own crate: |
| 29 |
|
| 30 |
```toml |
| 31 |
[dependencies] |
| 32 |
libfuzzer-sys = "0.4.0" |
| 33 |
your_crate = { path = "../path/to/your/crate" } |
| 34 |
``` |
| 35 |
|
| 36 |
Change the `fuzzed/src/main.rs` to fuzz your code: |
| 37 |
|
| 38 |
```rust |
| 39 |
#![no_main] |
| 40 |
|
| 41 |
use libfuzzer_sys::fuzz_target; |
| 42 |
|
| 43 |
fuzz_target!(|data: &[u8]| { |
| 44 |
// code to fuzz goes here |
| 45 |
}); |
| 46 |
``` |
| 47 |
|
| 48 |
Build by running the following command: |
| 49 |
|
| 50 |
```sh |
| 51 |
$ cargo rustc -- \ |
| 52 |
-C passes='sancov-module' \ |
| 53 |
-C llvm-args='-sanitizer-coverage-level=3' \ |
| 54 |
-C llvm-args='-sanitizer-coverage-inline-8bit-counters' \ |
| 55 |
-Z sanitizer=address |
| 56 |
``` |
| 57 |
|
| 58 |
And finally, run the fuzzer: |
| 59 |
|
| 60 |
```sh |
| 61 |
$ ./target/debug/fuzzed |
| 62 |
``` |
| 63 |
|
| 64 |
### Linking to a local libfuzzer |
| 65 |
|
| 66 |
When using `libfuzzer-sys`, you can provide your own `libfuzzer` runtime in two ways. |
| 67 |
|
| 68 |
If you are developing a fuzzer, you can set the `CUSTOM_LIBFUZZER_PATH` environment variable to the path of your local |
| 69 |
`libfuzzer` runtime, which will then be linked instead of building libfuzzer as part of the build stage of `libfuzzer-sys`. |
| 70 |
For an example, to link to a prebuilt LLVM 16 `libfuzzer`, you could use: |
| 71 |
|
| 72 |
```bash |
| 73 |
$ export CUSTOM_LIBFUZZER_PATH=/usr/lib64/clang/16/lib/libclang_rt.fuzzer-x86_64.a |
| 74 |
$ cargo fuzz run ... |
| 75 |
``` |
| 76 |
|
| 77 |
Alternatively, you may also disable the default `link_libfuzzer` feature: |
| 78 |
|
| 79 |
In `Cargo.toml`: |
| 80 |
```toml |
| 81 |
[dependencies] |
| 82 |
libfuzzer-sys = { path = "../../libfuzzer", default-features = false } |
| 83 |
``` |
| 84 |
|
| 85 |
Then link to your own runtime in your `build.rs`. |
| 86 |
|
| 87 |
## Updating libfuzzer from upstream |
| 88 |
|
| 89 |
* Update the `COMMIT=...` variable in `./update-libfuzzer.sh` with the new |
| 90 |
commit hash from [llvm-mirror/llvm-project](github.com/llvm-mirror/llvm-project) |
| 91 |
that you are vendoring. |
| 92 |
|
| 93 |
* Re-run the script: |
| 94 |
|
| 95 |
``` |
| 96 |
$ ./update-libfuzzer.sh <github.com/llvm-mirror/llvm-project SHA1> |
| 97 |
``` |
| 98 |
|
| 99 |
## License |
| 100 |
|
| 101 |
All files in the `libfuzzer` directory are licensed NCSA. |
| 102 |
|
| 103 |
Everything else is dual-licensed Apache 2.0 and MIT. |