Skip to content

Update fuzz README to account for additional required RUSTFLAGS #3401

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 1 commit into from
Nov 6, 2024
Merged

Update fuzz README to account for additional required RUSTFLAGS #3401

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 17 additions & 17 deletions fuzz/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,20 @@
# Fuzzing

Fuzz tests generate a ton of random parameter arguments to the program and then validate that none
Fuzz tests generate a ton of random parameter arguments to the program and then validate that none
cause it to crash.

## How does it work?

Typically, CI will run `ci-fuzz.sh` on one of the environments the automated tests are
configured for. Fuzzing is further only effective with a lot of CPU time, indicating that if crash
configured for. Fuzzing is further only effective with a lot of CPU time, indicating that if crash
scenarios are discovered on CI with its low runtime constraints, the crash is caused relatively
easily.

## How do I run fuzz tests locally?

We support multiple fuzzing engines such as `honggfuzz`, `libFuzzer` and `AFL`. You typically won't
need to run the entire suite of different fuzzing tools. For local execution, `honggfuzz`should be
more than sufficient.
We support multiple fuzzing engines such as `honggfuzz`, `libFuzzer` and `AFL`. You typically won't
need to run the entire suite of different fuzzing tools. For local execution, `honggfuzz`should be
more than sufficient.

### Setup
#### Honggfuzz
Expand Down Expand Up @@ -63,12 +63,12 @@ To run fuzzing using `cargo-fuzz / libFuzzer`, run
rustup install nightly # Note: libFuzzer requires a nightly version of rust.
cargo +nightly fuzz run --features "libfuzzer_fuzz" msg_ping_target
```
Note: If you encounter a `SIGKILL` during run/build check for OOM in kernel logs and consider
Note: If you encounter a `SIGKILL` during run/build check for OOM in kernel logs and consider
increasing RAM size for VM.

If you wish to just generate fuzzing binary executables for `libFuzzer` and not run them:
```shell
cargo +nightly fuzz build --features "libfuzzer_fuzz" msg_ping_target
```shell
cargo +nightly fuzz build --features "libfuzzer_fuzz" msg_ping_target
# Generates binary artifact in path ./target/aarch64-unknown-linux-gnu/release/msg_ping_target
# Exact path depends on your system architecture.
```
Expand All @@ -83,7 +83,7 @@ ls ./src/bin/

## A fuzz test failed, what do I do?

You're trying to create a PR, but need to find the underlying cause of that pesky fuzz failure
You're trying to create a PR, but need to find the underlying cause of that pesky fuzz failure
blocking the merge?

Worry not, for this is easily traced.
Expand All @@ -106,7 +106,7 @@ The command "if [ "$(rustup show | grep default | grep stable)" != "" ]; then cd
```

Note that the penultimate stack trace line ends in `release/full_stack_target]`. That indicates that
the failing target was `full_stack`. To reproduce the error locally, simply copy the hex,
the failing target was `full_stack`. To reproduce the error locally, simply copy the hex,
and run the following from the `fuzz` directory:

```shell
Expand All @@ -119,11 +119,11 @@ mkdir -p ./test_cases/$TARGET
echo $HEX | xxd -r -p > ./test_cases/$TARGET/any_filename_works

export RUST_BACKTRACE=1
export RUSTFLAGS="--cfg=fuzzing"
export RUSTFLAGS="--cfg=fuzzing --cfg=secp256k1_fuzz --cfg=hashes_fuzz"
cargo test
```

Note that if the fuzz test failed locally, moving the offending run's trace
Note that if the fuzz test failed locally, moving the offending run's trace
to the `test_cases` folder should also do the trick; simply replace the `echo $HEX |` line above
with (the trace file name is of course a bit longer than in the example):

Expand All @@ -136,9 +136,9 @@ This will reproduce the failing fuzz input and yield a usable stack trace.

## How do I add a new fuzz test?

1. The easiest approach is to take one of the files in `fuzz/src/`, such as
`process_network_graph.rs`, and duplicate it, renaming the new file to something more
suitable. For the sake of example, let's call the new fuzz target we're creating
1. The easiest approach is to take one of the files in `fuzz/src/`, such as
`process_network_graph.rs`, and duplicate it, renaming the new file to something more
suitable. For the sake of example, let's call the new fuzz target we're creating
`my_fuzzy_experiment`.

2. In the newly created file `fuzz/src/my_fuzzy_experiment.rs`, run a string substitution
Expand All @@ -147,12 +147,12 @@ file are `do_test`, `my_fuzzy_experiment_test`, and `my_fuzzy_experiment_run`.

3. Adjust the body (not the signature!) of `do_test` as necessary for the new fuzz test.

4. In `fuzz/src/bin/gen_target.sh`, add a line reading `GEN_TEST my_fuzzy_experiment` to the
4. In `fuzz/src/bin/gen_target.sh`, add a line reading `GEN_TEST my_fuzzy_experiment` to the
first group of `GEN_TEST` lines (starting in line 9).

5. If your test relies on a new local crate, add that crate as a dependency to `fuzz/Cargo.toml`.

6. In `fuzz/src/lib.rs`, add the line `pub mod my_fuzzy_experiment`. Additionally, if
6. In `fuzz/src/lib.rs`, add the line `pub mod my_fuzzy_experiment`. Additionally, if
you added a new crate dependency, add the `extern crate […]` import line.

7. Run `fuzz/src/bin/gen_target.sh`.
Expand Down
Loading