diff --git a/README.md b/README.md index e366be1f3e..c5b8ef11d7 100644 --- a/README.md +++ b/README.md @@ -79,6 +79,12 @@ cd docs && mdbook serve We collect all example fuzzers in [`./fuzzers`](./fuzzers/). Be sure to read their documentation (and source), this is *the natural way to get started!* +You can run each example fuzzer with +``` +cargo make run +``` +as long as the fuzzer directory has `Makefile.toml` file. + The best-tested fuzzer is [`./fuzzers/libfuzzer_libpng`](./fuzzers/libfuzzer_libpng), a multicore libfuzzer-like fuzzer using LibAFL for a libpng harness. ## Resources diff --git a/docs/src/core_concepts/executor.md b/docs/src/core_concepts/executor.md index 6502a0addd..817edf1fd3 100644 --- a/docs/src/core_concepts/executor.md +++ b/docs/src/core_concepts/executor.md @@ -11,13 +11,13 @@ In our model, it can also hold a set of Observers connected with each execution. In Rust, we bind this concept to the [`Executor`](https://docs.rs/libafl/0/libafl/executors/trait.Executor.html) trait. A structure implementing this trait must implement [`HasObservers`](https://docs.rs/libafl/0/libafl/executors/trait.HasObservers.html) too if wants to hold a set of Observers. -By default, we implement some commonly used Executors such as [`InProcessExecutor`](https://docs.rs/libafl/0/libafl/executors/inprocess/struct.InProcessExecutor.html) is which the target is a harness function providing in-process crash detection. Another Executor is the [`ForkserverExecutor`](https://docs.rs/libafl/0/libafl/executors/forkserver/struct.ForkserverExecutor.html) that implements an AFL-like mechanism to spawn child processes to fuzz. +By default, we implement some commonly used Executors such as [`InProcessExecutor`](https://docs.rs/libafl/0/libafl/executors/inprocess/struct.InProcessExecutor.html) in which the target is a harness function providing in-process crash detection. Another Executor is the [`ForkserverExecutor`](https://docs.rs/libafl/0/libafl/executors/forkserver/struct.ForkserverExecutor.html) that implements an AFL-like mechanism to spawn child processes to fuzz. A common pattern when creating an Executor is wrapping an existing one, for instance [`TimeoutExecutor`](https://docs.rs/libafl/0.6.1/libafl/executors/timeout/struct.TimeoutExecutor.html) wraps an executor and install a timeout callback before calling the original run function of the wrapped executor. ## InProcessExecutor Let's begin with the base case; `InProcessExecutor`. -This executor uses [_SanitizerCoverage_](https://clang.llvm.org/docs/SanitizerCoverage.html) as its backend, as you can find the related code in `libafl_targets/src/sancov_pcguards`. Here we allocate a map called `EDGES_MAP` and then our compiler wrapper compiles the harness to write the coverage into this map. +This executor executes the harness program (function) inside the fuzzer process. When you want to execute the harness as fast as possible, you will most probably want to use this `InprocessExecutor`. diff --git a/fuzzers/frida_libpng/README.md b/fuzzers/frida_libpng/README.md index b59c2ad189..b4dd9d93d8 100644 --- a/fuzzers/frida_libpng/README.md +++ b/fuzzers/frida_libpng/README.md @@ -12,6 +12,8 @@ Then, it will link (the fuzzer)[./src/fuzzer.rs] against (the C++ harness)[./har Afterwards, the fuzzer will be ready to run, from `target/frida_libpng`. On unix platforms, you'll need [libc++](https://libcxx.llvm.org/) to build it. +Alternatively you can run `cargo make run` and this command will automatically build and run the fuzzer + ### Build For Android When building for android using a cross-compiler, make sure you have a _standalone toolchain_, and then add the following: 1. In the ~/.cargo/config file add a target with the correct cross-compiler toolchain name (in this case aarch64-linux-android, but names may vary) @@ -27,8 +29,8 @@ This example uses in-process-fuzzing, using the `launcher` feature, in combinati This means running --cores each client will start itself again to listen for crashes and timeouts. By restarting the actual fuzzer, it can recover from these exit conditions. -After building the libpng-harness, too, you can run `find . -name libpng-harness.so` to find the location of your harness, then run -`./target/release/frida_libpng ./libpng-harness.so LLVMFuzzerTestOneInput ./libpng-harness.so --cores=0 --input=./corpus` +After building the libpng-harness, you can run `find . -name libpng-harness.so` to find the location of your harness, then run +`./frida_fuzzer -F LLVMFuzzerTestOneInput -H ./libpng-harness.so -l ./libpng-harness.so` ## Windows You can also fuzz libpng-1.6.37 on windows with frida mode @@ -58,6 +60,6 @@ clang++ -L.\zlib.dll .\harness.o .\libpng16.lib -lzlib -shared -o .\libpng-harne ``` 5. Run the fuzzer ``` -./frida_libpng.exe ./libpng-harness.dll LLVMFuzzerTestOneInput ./libpng-harness.dll --cores=0 --input=./corpus +./frida_fuzzer.exe ./libpng-harness.dll LLVMFuzzerTestOneInput ./libpng-harness.dll ``` diff --git a/libafl/src/fuzzer/mod.rs b/libafl/src/fuzzer/mod.rs index a0e0e3b538..377af632a7 100644 --- a/libafl/src/fuzzer/mod.rs +++ b/libafl/src/fuzzer/mod.rs @@ -154,6 +154,9 @@ where { /// Fuzz for a single iteration. /// Returns the index of the last fuzzed corpus item. + /// (Note: An iteration represents a complete run of every stage. + /// Therefore it does not mean that the harness is executed for once, + /// because each stage could run the harness for multiple times) /// /// If you use this fn in a restarting scenario to only run for `n` iterations, /// before exiting, make sure you call `event_mgr.on_restart(&mut state)?;`. @@ -184,6 +187,9 @@ where /// Fuzz for n iterations. /// Returns the index of the last fuzzed corpus item. + /// (Note: An iteration represents a complete run of every stage. + /// therefore the number n is not always equal to the number of the actual harness executions, + /// because each stage could run the harness for multiple times) /// /// If you use this fn in a restarting scenario to only run for `n` iterations, /// before exiting, make sure you call `event_mgr.on_restart(&mut state)?;`.