docs: add AGENTS.md to help AI agents guide new users building a LibAFL fuzzer - #3907
docs: add AGENTS.md to help AI agents guide new users building a LibAFL fuzzer#3907Aditya30ag wants to merge 1 commit into
Conversation
|
@domenukk is that looks good?? |
| - MSRV (minimum supported Rust version): see `rust-version` in the root | ||
| `Cargo.toml` and `crates/libafl/Cargo.toml` -- always read it fresh rather | ||
| than assuming, it changes over time. | ||
| - LLVM tools (clang/clang++, newer than 15.0.0, up to 18.1.3) are required |
There was a problem hiding this comment.
let's not have a hard coded max here? maybe not even a min, this develops over time...
There was a problem hiding this comment.
removed the version range entirely
|
|
||
| ## Repository layout | ||
|
|
||
| - `crates/` -- the actual library. `libafl` is the core; `libafl_bolts` has |
There was a problem hiding this comment.
replaced the list with a pointer to crates/README.md
| `libafl_tinyinst` are instrumentation backends; `libafl_cc` wraps | ||
| compilers for source-based instrumentation; `libafl_sugar` is a | ||
| simplified high-level API for common cases. | ||
| - `fuzzers/` -- ~69 real, working example fuzzers, organized by category |
There was a problem hiding this comment.
the count is irrelevant. better have less data than more in here
There was a problem hiding this comment.
removed the count
|
|
||
| | Target situation | Look in | Concrete starting example | | ||
| |---|---|---| | ||
| | Source-available, single target function, want to see it work fast | `fuzzers/baby/` | `baby_fuzzer` -- the minimal in-process example | |
There was a problem hiding this comment.
the baby fuzzers are almost never what fuzzers should be built upon
There was a problem hiding this comment.
removed that row from the table
| | Binary-only, no source access, want AFL++-style forkserver | `fuzzers/forkserver/` | `forkserver_simple` (minimal) or `libafl-fuzz` (fuller afl-fuzz-alike) | | ||
| | Binary-only via dynamic instrumentation (no recompilation, incl. closed-source) | `fuzzers/binary_only/` | `frida_libpng` (Frida) or `qemu_launcher` (QEMU user-mode, full-featured multi-core) | | ||
| | Full-system / kernel / firmware / bootloader targets | `fuzzers/full_system/` | `qemu_linux_kernel`, `qemu_baremetal`, `nyx_launcher` depending on the system | | ||
| | Structured/grammar-based input (not raw bytes) | `fuzzers/structure_aware/` | `baby_fuzzer_gramatron`, `baby_fuzzer_nautilus`, or `baby_fuzzer_tokens` depending on the grammar formalism | |
There was a problem hiding this comment.
it'd be important to note when to use strucutred fuzzzing instead of bytes-only fuzzing (higher level / strucutred targets etc)
There was a problem hiding this comment.
added guidance on when byte-level mutation isn't enough
| checking the dependency features line up). | ||
| 2. Rename the package in `Cargo.toml`, and point the `libafl`/`libafl_bolts` | ||
| (and any backend-specific crate) dependencies at either a local path | ||
| (`{ path = "../../crates/libafl" }`, adjusted for the new project's |
There was a problem hiding this comment.
usually the path shouldn't be local - usually you want the upstream crates.io version I think?
There was a problem hiding this comment.
changed to crates.io by default
| SanitizerCoverage (source-available) or the appropriate binary-only | ||
| backend -- don't leave a fake/manual coverage map in place for a real | ||
| target, it will misguide the fuzzer's mutation strategy. | ||
| 5. Build and run (`cargo build`, `cargo run`), and confirm the corpus and |
There was a problem hiding this comment.
Usually optimal fuzzers should have
- cmplog / i2s / tracing stage of sorts
- calibration stage
- a good corpus of seed input
There was a problem hiding this comment.
added cmplog/i2s, calibration stage, and seed corpus as step 5
Bumps [vergen-git2](https://github.com/rustyhorde/vergen) from 10.0.2 to 10.0.3. - [Release notes](https://github.com/rustyhorde/vergen/releases) - [Commits](https://github.com/rustyhorde/vergen/commits) --- updated-dependencies: - dependency-name: vergen-git2 dependency-version: 10.0.3 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <support@github.com> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com>
4296779 to
71aa672
Compare
|
@domenukk, I had addressed the requested changes. |
2 participants
Closes #3896
What
Adds
AGENTS.mdat the repo root a structured guide for AI coding agents (Claude Code, Cursor, Codex, etc.) to help new users build a LibAFL-based fuzzer without having to browse all 69 examples infuzzers/and guess which one fits their target.Why
Following @domenukk suggestion in #3896 that a good
AGENTS.mdwould be more practical than a dedicated scaffolding tool.What's in it
fuzzers/example to start from (source-available, binary-only, QEMU, Frida, full-system, grammar-based, etc.)just fmt,scripts/clippy.sh,scripts/precommit.sh,no_stdcheck)CONTRIBUTING.md's AI-assistance policy — scoped to helping agents assist downstream users, not to inviting AI-assisted PRs against this repoWhat it does NOT do
CONTRIBUTING.md(zero diff, verified)Checklist
./scripts/precommit.shand addressed all comments