From 6b95361123cd385ccafe94ce4686ecacd1b43055 Mon Sep 17 00:00:00 2001 From: syheliel <45957390+syheliel@users.noreply.github.com> Date: Tue, 15 Mar 2022 02:14:46 +0800 Subject: [PATCH] Add doc for example `baby_fuzzer_*` (#564) * Add doc for example `baby_fuzzer_*` * Fix `mdbook build` Co-authored-by: syheliel --- docs/src/SUMMARY.md | 4 +-- docs/src/{ => baby_fuzzer}/baby_fuzzer.md | 2 +- docs/src/baby_fuzzer/more_examples.md | 11 ++++++++ fuzzers/baby_fuzzer_gramatron/README.md | 19 +++++++++----- fuzzers/baby_fuzzer_grimoire/README.md | 13 +++++----- fuzzers/baby_fuzzer_nautilus/README.md | 17 +++++++------ fuzzers/baby_fuzzer_tokens/README.md | 25 +++++++++++++------ .../baby_fuzzer_with_forkexecutor/README.md | 10 ++------ 8 files changed, 61 insertions(+), 40 deletions(-) rename docs/src/{ => baby_fuzzer}/baby_fuzzer.md (99%) create mode 100644 docs/src/baby_fuzzer/more_examples.md diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index d78cebcb95..d530223d3b 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -9,8 +9,8 @@ - [Build](./getting_started/build.md) - [Crates](./getting_started/crates.md) -- [Baby Fuzzer](./baby_fuzzer.md) - +- [Baby Fuzzer](./baby_fuzzer/baby_fuzzer.md) + - [More Examples](./baby_fuzzer/more_examples.md) - [Core Concepts](./core_concepts/core_concepts.md) - [Observer](./core_concepts/observer.md) - [Executor](./core_concepts/executor.md) diff --git a/docs/src/baby_fuzzer.md b/docs/src/baby_fuzzer/baby_fuzzer.md similarity index 99% rename from docs/src/baby_fuzzer.md rename to docs/src/baby_fuzzer/baby_fuzzer.md index 5614fafacf..dbd9a92596 100644 --- a/docs/src/baby_fuzzer.md +++ b/docs/src/baby_fuzzer/baby_fuzzer.md @@ -11,7 +11,7 @@ You can find a complete version of this tutorial as an example fuzzer in [`fuzze > ### Warning > > This example fuzzer is too naive for any real-world usage. -> Its purpose is solely to show the main components of the library, for a more in-depth walkthrough on building a custom fuzzer go to the [Tutorial chapter](./tutorial/intro.md) directly. +> Its purpose is solely to show the main components of the library, for a more in-depth walkthrough on building a custom fuzzer go to the [Tutorial chapter](../tutorial/intro.md) directly. ## Creating a project diff --git a/docs/src/baby_fuzzer/more_examples.md b/docs/src/baby_fuzzer/more_examples.md new file mode 100644 index 0000000000..792ecc1edc --- /dev/null +++ b/docs/src/baby_fuzzer/more_examples.md @@ -0,0 +1,11 @@ +# More Examples +Examples can be found under `./fuzzer`. + +|fuzzer name|usage| +| ---- | ---- | +| baby_fuzzer_gramatron | [Gramatron](https://github.com/HexHive/Gramatron) is a fuzzer that uses **grammar automatons** in conjunction with aggressive mutation operators to synthesize complex bug triggers | +| baby_fuzzer_grimoire | [Grimoire](https://www.usenix.org/system/files/sec19-blazytko.pdf) is a fully automated coverage-guided fuzzer which works **without any form of human interaction or pre-configuration** | +| baby_fuzzer_nautilus | [nautilus](https://www.ndss-symposium.org/wp-content/uploads/2019/02/ndss2019_04A-3_Aschermann_paper.pdf) is a **coverage guided, grammar based** fuzzer| +|baby_fuzzer_tokens| basic **token level** fuzzer with token level mutations| +|baby_fuzzer_with_forkexecutor| example for **InProcessForkExecutor**| +|baby_no_std|a minimalistic example how to create a libafl based fuzzer that works on **`no_std`** environments like TEEs, Kernels or on barew metal| \ No newline at end of file diff --git a/fuzzers/baby_fuzzer_gramatron/README.md b/fuzzers/baby_fuzzer_gramatron/README.md index 42fd9a5011..e3ca832c01 100644 --- a/fuzzers/baby_fuzzer_gramatron/README.md +++ b/fuzzers/baby_fuzzer_gramatron/README.md @@ -1,8 +1,15 @@ -# Baby fuzzer +# Baby Gramatron -This is a minimalistic example about how to create a libafl based fuzzer. +This fuzzer shows how to implement grammar-aware fuzzing. [Gramatron](https://github.com/HexHive/Gramatron) uses grammar automatons in conjunction with aggressive mutation operators to synthesize complex bug triggers. `auto.json` records grammar automaton of php,which is corresponding to `libafl::generators::Automaton`and serialized into `auto.postcard`. `libafl::generators::gramatron` will generate valid grammar sequences using `Automaton` and then pass them into `harness`. The function of `harness` is to print the original input. -It runs on a single core until a crash occurs and then exits. - -The tested program is a simple Rust function without any instrumentation. -For real fuzzing, you will want to add some sort to add coverage or other feedback. \ No newline at end of file +When you use `cargo run`, You may see output as follows: +``` +b=mlhs_node.isz(c,c, ) +d=false.keyword__FILE__(c,b,a,b) +a=select.Jan(d) +a=first.literal( ) +b=[0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,nil].DomainError(c) +next a +b=Oo.gsub(a,d,b) +d=0.hex( ) +``` \ No newline at end of file diff --git a/fuzzers/baby_fuzzer_grimoire/README.md b/fuzzers/baby_fuzzer_grimoire/README.md index 42fd9a5011..3d801096d7 100644 --- a/fuzzers/baby_fuzzer_grimoire/README.md +++ b/fuzzers/baby_fuzzer_grimoire/README.md @@ -1,8 +1,7 @@ -# Baby fuzzer +# baby grimoire fuzzer +This fuzzer shows how to implement [Grimoire fuzzer](https://www.usenix.org/system/files/sec19-blazytko.pdf), a fully automated coverage-guided fuzzer which works without any form of human interaction or pre-configuration. `libafl::mutators::grimoire` provides four mutators : +`GrimoireExtensionMutator`,`GrimoireRecursiveReplacementMutator`, +`GrimoireStringReplacementMutator`,`GrimoireRandomDeleteMutator`. -This is a minimalistic example about how to create a libafl based fuzzer. - -It runs on a single core until a crash occurs and then exits. - -The tested program is a simple Rust function without any instrumentation. -For real fuzzing, you will want to add some sort to add coverage or other feedback. \ No newline at end of file +The fuzzer will regard all files in `./corpus` as inputs. Inputs will be mutated by `mutator`(havoc_mutations) and `grimoire_mutator`. `harness` will firstly check if `input` contains substring `fn` or `pippopippo` then print the input mutated by `grimoire_mutator`. +> **_NOTE:_** This harness is not designed for a crash, so `cargo run` will not terminate. \ No newline at end of file diff --git a/fuzzers/baby_fuzzer_nautilus/README.md b/fuzzers/baby_fuzzer_nautilus/README.md index 42fd9a5011..e5917fce39 100644 --- a/fuzzers/baby_fuzzer_nautilus/README.md +++ b/fuzzers/baby_fuzzer_nautilus/README.md @@ -1,8 +1,9 @@ -# Baby fuzzer - -This is a minimalistic example about how to create a libafl based fuzzer. - -It runs on a single core until a crash occurs and then exits. - -The tested program is a simple Rust function without any instrumentation. -For real fuzzing, you will want to add some sort to add coverage or other feedback. \ No newline at end of file +## baby nautilus fuzzer +(Nautilus)[https://www.ndss-symposium.org/ndss-paper/nautilus-fishing-for-deep-bugs-with-grammars/] is a coverage-guided and grammar-based fuzzer. It needs to read the mruby's context-free grammar stored in `grammar.json`. And then use the corresponding feedback, generator, and mutator to fuzz. +`libafl::mutators::nautilus` contains: +``` +NautilusInput,NautilusContext +NautilusChunksMetadata,NautilusFeedback +NautilusGenerator +NautilusRandomMutator,NautilusRecursionMutator,NautilusSpliceMutator +``` \ No newline at end of file diff --git a/fuzzers/baby_fuzzer_tokens/README.md b/fuzzers/baby_fuzzer_tokens/README.md index 42fd9a5011..efc8e6254d 100644 --- a/fuzzers/baby_fuzzer_tokens/README.md +++ b/fuzzers/baby_fuzzer_tokens/README.md @@ -1,8 +1,17 @@ -# Baby fuzzer - -This is a minimalistic example about how to create a libafl based fuzzer. - -It runs on a single core until a crash occurs and then exits. - -The tested program is a simple Rust function without any instrumentation. -For real fuzzing, you will want to add some sort to add coverage or other feedback. \ No newline at end of file +# Baby tokens fuzzer +1. `tokenizer` are used to split inputs into tokens +2. `encoder_decoder` will give every new token a new id and record the mapping relation. Then it can convert tokens to `EncodedInput`, vice versa. +3. `encoded_mutations` are used to deal with token level mutation, following is the definition: +''' +pub fn encoded_mutations() -> tuple_list_type!( + EncodedRandMutator, + EncodedIncMutator, + EncodedDecMutator, + EncodedAddMutator, + EncodedDeleteMutator, + EncodedInsertCopyMutator, + EncodedCopyMutator, + EncodedCrossoverInsertMutator, + EncodedCrossoverReplaceMutator, +) +''' \ No newline at end of file diff --git a/fuzzers/baby_fuzzer_with_forkexecutor/README.md b/fuzzers/baby_fuzzer_with_forkexecutor/README.md index 42fd9a5011..a358516d2e 100644 --- a/fuzzers/baby_fuzzer_with_forkexecutor/README.md +++ b/fuzzers/baby_fuzzer_with_forkexecutor/README.md @@ -1,8 +1,2 @@ -# Baby fuzzer - -This is a minimalistic example about how to create a libafl based fuzzer. - -It runs on a single core until a crash occurs and then exits. - -The tested program is a simple Rust function without any instrumentation. -For real fuzzing, you will want to add some sort to add coverage or other feedback. \ No newline at end of file +# Baby fuzzer with forkexecutor +Example for `InProcessForkExecutor`. Compared with `InProcessExecutor`, it needs additional param `shmem_provider` to make it work. \ No newline at end of file