# libafl_libfuzzer
`libafl_libfuzzer` is a shim for [libFuzzer] which may be used in place of libFuzzer in most contexts.
It can be used both as a direct shim for existing libFuzzer-compatible targets which are simply linked with libFuzzer
(e.g., `clang -fsanitize=fuzzer`) and as a Rust crate for [`libfuzzer-sys`]-based harnesses.
## Background
`libafl_libfuzzer` was first developed as a shim in light of the [de-facto deprecation of libFuzzer].
Given the widespread use of libFuzzer and that LibAFL already supported most of the instrumentation used by libFuzzer,
we sought to develop a replacement which could directly replace it without much additional effort from the end user.
To do so, `libafl_libfuzzer` provides the same interface and uses the same instrumentation as libFuzzer so that
libFuzzer users can change over to a more modern LibAFL-based runtime without needing extensive changes to their
fuzzing environment or updating their harnesses.
## Usage
`libafl_libfuzzer` currently has known support for Rust, C, and C++ targets on Linux and
macOS. Windows is only supported via [usage as a standalone
library](#usage-as-a-standalone-library-for-ccetc).
For both cases, you should install a recent **nightly** version of Rust via `rustup` and add the `llvm-tools` component
with `rustup component add llvm-tools`.
### Usage with Rust harnesses
To use `libafl_libfuzzer` on Rust harnesses which use `libfuzzer-sys`, all you need to do is change the following line
in your Cargo.toml:
```toml
libfuzzer-sys = { version = "...", features = ["your", "features", "here"] }
```
to
```toml
libfuzzer-sys = { version = "0.11.0", features = ["your", "features", "here"], package = "libafl_libfuzzer" }
```
To use the most up-to-date version (with experimental changes), use:
```toml
libfuzzer-sys = { git = "https://github.com/AFLplusplus/LibAFL.git", features = ["your", "features", "here"], package = "libafl_libfuzzer" }
```
As the repository generally offers the highest performance version of `libafl_libfuzzer`, we recommend the latter.
Remember to `cargo update` often if using the experimental changes, and please [submit an issue]
if you encounter problems while using the git branch!
For stability purposes, consider [specifying a commit](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#choice-of-commit).
#### macOS
On macOS, you will need to add weak linking for some functions in a `build.rs` file:
```rust
fn main() {
for func in [
"_libafl_main",
"_LLVMFuzzerCustomMutator",
"_LLVMFuzzerCustomCrossOver",
] {
println!("cargo:rustc-link-arg=-Wl,-U,{func}");
}
}
```
#### Caveats
Like harnesses built with `libfuzzer-sys`, Rust targets which build other libraries (e.g. C/C++ FFI) may not
automatically apply instrumentation.
In addition to installing clang, you may also wish to set the following environmental variables:
```bash
CC=clang
CXX=clang++
CFLAGS='-fsanitize=fuzzer-no-link'
CXXFLAGS='-fsanitize=fuzzer-no-link'
```
### Usage as a standalone library (for C/C++/etc.)
The runtime for `libafl_libfuzzer` may be used standalone as a direct replacement for libFuzzer with other targets as
well.
To do so, [ensure a recent nightly version of Rust is installed](https://rustup.rs/), then enter the
[`libafl_libfuzzer_runtime`](../libafl_libfuzzer_runtime) folder and build the runtime with the following command:
```bash
just build
```
Or you can call `build.sh` (Unix) or `build.ps1` (Windows).
The static library will be available at `libFuzzer.a` (`libFuzzer.lib` for Windows) in
the [`libafl_libfuzzer_runtime`](../libafl_libfuzzer_runtime) directory. If you
encounter build failures without clear error outputs that help you resolve the issue,
please [submit an issue].
#### Unix
This library may now be used in place of libFuzzer. To do so, change your
CFLAGS/CXXFLAGS from `-fsanitize=fuzzer` to:
``` -fsanitize=fuzzer-no-link -L/path/to/libafl_libfuzzer_runtime -lFuzzer ```
Alternatively, you may directly overwrite the system libFuzzer library and use
`-fsanitize=fuzzer` as normal. This changes per system, but on my machine is located at
`/usr/lib64/clang/16/lib/linux/libclang_rt.fuzzer-x86_64.a`.
#### Windows
For Windows, change your CFLAGS/CXXFLAGS from `-fsanitize=fuzzer` to:
```/fsanitize-coverage=inline-8bit-counters /fsanitize-coverage=edge /fsanitize-coverage=trace-cmp /fsanitize-coverage=trace-div```
And then ensure you link with `sancov.lib` when producing your final executable. See
`fuzzers\inprocess\libafl_libfuzzer_windows` for an example.
#### Caveats
This standalone library is _not_ compatible with Rust targets; you must instead use the crate-based dependency.
This is due to potential symbol conflict between your harness and the fuzzer runtime, which is resolved by additional
build steps provided in the `libafl_libfuzzer` crate itself.
#### Troubleshooting
To build the `libafl_libfuzzer` runtime directly, you must have working symbolic links
in your LibAFL git repository. You can enable this with `git config core.symlinks true`.
If you see problems related to the `Cargo.toml` file containing only a path, this is
your problem. Enable symlinks and checkout or re-clone the LibAFL repository.
## Flags
You can pass additional flags to the libFuzzer runtime in `cargo-fuzz` like so:
```bash
cargo fuzz run fuzz_target -- -extra_flag=1
```
When the runtime is used standalone, flags may be passed just like normal libFuzzer.
You will commonly need this for flags such as `-ignore_crashes=1` and `-timeout=5`. In addition
to partial support of libfuzzer flags, `libafl_libfuzzer` offers:
- `-dedup=n`, with `n` = 1 enabling deduplication of crashes by stacktrace.
- `-grimoire=n`, with `n` set to 0 or 1 disabling or enabling [grimoire] mutations, respectively.
- if not specified explicitly, `libafl_libfuzzer` will select based on whether existing inputs are UTF-8
- you should disable grimoire if your target is not string-like
- `-report=n`, with `n` = 1 causing `libafl_libfuzzer` to emit a report on the corpus content.
- `-skip_tracing=n`, with `n` = 1 causing `libafl_libfuzzer` to disable cmplog tracing.
- you should do this if your target performs many comparisons on memory sequences which are
not contained in the input
- `-tui=n`, with `n` = 1 enabling a graphical terminal interface.
- experimental; some users report inconsistent behaviour with tui enabled
### Supported flags from libfuzzer
- `-merge`
- `-minimize_crash`
- `-artifact_prefix`
- `-timeout`
- unlike libfuzzer, `libafl_libfuzzer` supports partial second timeouts (e.g. `-timeout=.5`)
- `-dict`
- `-fork` and `-jobs`
- in `libafl_libfuzzer`, these are synonymous
- `-ignore_crashes`, `-ignore_ooms`, and `-ignore_timeouts`
- note that setting `-tui=1` enables these flags by default, so you'll need to explicitly mention `-ignore_...=0` to
disable them
- `-rss_limit_mb` and `-malloc_limit_mb`
- `-ignore_remaining_args`
- `-shrink`
- `-runs`
- `-close_fd_mask`
[libFuzzer]: https://llvm.org/docs/LibFuzzer.html
[`libfuzzer-sys`]: https://docs.rs/libfuzzer-sys/
[de-facto deprecation of libFuzzer]: https://llvm.org/docs/LibFuzzer.html#status
[submit an issue]: https://github.com/AFLplusplus/LibAFL/issues/new/choose
[grimoire]: https://www.usenix.org/conference/usenixsecurity19/presentation/blazytko