Document cargo-afl fuzzing support - #2815
Open
leighmcculloch wants to merge 16 commits into
Open
Conversation
leighmcculloch
force-pushed
the
docs-cargo-afl-fuzzing
branch
from
September 3, 2026 11:28
3031dac to
b05257e
Compare
Contributor
Contributor
github-actions
Bot
added
preview
Contributor
leighmcculloch
marked this pull request as ready for review
September 3, 2026 13:18
leighmcculloch
requested review from
ElliotFriend
and
a balanced review from Copilot
September 3, 2026 13:18
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a step-by-step guide for fuzzing Soroban contracts with cargo-afl.
Changes:
- Documents installation, configuration, execution, and crash replay.
- Adds an AFL++ fuzz-target example and references.
Suppressed comments (5)
docs/build/guides/testing/fuzzing.mdx:148
- This dependency name does not match the package used by the linked increment example (
soroban-increment-contract). Cargo therefore looks for a package namedmy-contractat..and fails before compiling the target.
my-contract = { path = ".." }
docs/build/guides/testing/fuzzing.mdx:169
- An arbitrary
u64makes most executions effectively unbounded: the provided eight-byte seed decodes to a value in the quadrillions, so the very first execution spends its time in the loop and is classified as a timeout instead of exercising useful inputs. Bound the generated operation count to keep every fuzz iteration fast.
pub by: u64,
docs/build/guides/testing/fuzzing.mdx:184
lastis never updated, soSome(current) > Noneis true on every successful call and the stated monotonicity property is not actually tested. Save each successful value after asserting it.
Ok(Ok(current)) => assert!(Some(current) > last),
docs/build/guides/testing/fuzzing.mdx:218
- After AFL++ records more than one crash, this wildcard expands to multiple paths and the shell rejects the input redirection as ambiguous. Select and quote one concrete crash path before replaying it.
RUST_BACKTRACE=1 ./target/debug/fuzz_target_1 < out/default/crashes/id:000000*
docs/build/guides/testing/fuzzing.mdx:211
- This rationale is incorrect for
cargo-afl: its build wrapper explicitly passes both-C overflow_checksand-C debug-assertionsfor instrumented Cargo builds, including release builds. Avoid telling readers that release mode necessarily loses these checks.
Fuzz debug builds, at least at first: they keep integer overflow checks and `debug_assert!`s enabled, and those catch bugs a release build won't.
💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
| cargo afl system-config | ||
| ``` | ||
|
|
||
| 3. Create a fuzz target crate, for example with `cargo new --bin fuzz` inside your contract's directory. Unlike a `cargo-fuzz` target, an AFL++ target depends on the `arbitrary` crate directly, because the `fuzz!` macro expands to code that refers to it by an absolute path, which only resolves if `arbitrary` is a direct dependency. Add the following to the new crate's `Cargo.toml`: |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Add a step-by-step guide for fuzzing Soroban contracts with
cargo-afl(AFL++) to the fuzzing guide, replacing the placeholder note that just pointed readers to the generic Rust Fuzz book.Why
We should demonstrate it as the fuzzing tools can be a bit overwhelming.