diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index bcd4ffea37..9cc0cbf517 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -12,5 +12,8 @@ - [Baby Fuzzer](./baby_fuzzer.md) - [Core Concepts](./core_concepts/core_concepts.md) - - [Executor](./core_concepts/executor.md) - [Observer](./core_concepts/observer.md) + - [Executor](./core_concepts/executor.md) + - [Feedback](./core_concepts/feedback.md) + - [Input](./core_concepts/input.md) + - [Corpus](./core_concepts/corpus.md) diff --git a/docs/src/core_concepts/core_concepts.md b/docs/src/core_concepts/core_concepts.md index 46b3960f44..2da1afbb02 100644 --- a/docs/src/core_concepts/core_concepts.md +++ b/docs/src/core_concepts/core_concepts.md @@ -1,3 +1,7 @@ # Core Concepts +LibAFL is designed around some core concepts that we think can effectively abstract most of the other fuzzers designs. + +In this chapter, we discuss these concepts, provide some examples related to other fuzzers and some details how the defined entities maps to the code in Rust. + diff --git a/docs/src/core_concepts/corpus.md b/docs/src/core_concepts/corpus.md new file mode 100644 index 0000000000..361eb33c64 --- /dev/null +++ b/docs/src/core_concepts/corpus.md @@ -0,0 +1 @@ +# Corpus diff --git a/docs/src/core_concepts/executor.md b/docs/src/core_concepts/executor.md index 3fddc32644..965280e07e 100644 --- a/docs/src/core_concepts/executor.md +++ b/docs/src/core_concepts/executor.md @@ -1 +1,10 @@ # Executor + +In different fuzzers, the concept of executing the program under test each run is now always the same. +For instance, for in-memory fuzzers like libFuzzer an execution is a call to an harness function, for hypervisor-based fuzzers like [kAFL](https://github.com/IntelLabs/kAFL) instead an entire operating system is started from a snapshot each run. + +In our model, an Executor is the entity that defines not only how to execute the target, but all the volatile operations that are related to just a single run of the target. + +So the Executor is for instance reponsible to inform the program about the input that the fuzzer wants to use in the run, writing to a memory location for instance or passing it as a parameter to the harness function. + +It also holds a set of Observers, as thay are related to just a single run of the target. diff --git a/docs/src/core_concepts/feedback.md b/docs/src/core_concepts/feedback.md new file mode 100644 index 0000000000..c4a1060c53 --- /dev/null +++ b/docs/src/core_concepts/feedback.md @@ -0,0 +1,3 @@ +# Feedback + + diff --git a/docs/src/core_concepts/input.md b/docs/src/core_concepts/input.md new file mode 100644 index 0000000000..135b6af33f --- /dev/null +++ b/docs/src/core_concepts/input.md @@ -0,0 +1 @@ +# Input diff --git a/docs/src/core_concepts/observer.md b/docs/src/core_concepts/observer.md index 94e0f8b987..65ba1ec920 100644 --- a/docs/src/core_concepts/observer.md +++ b/docs/src/core_concepts/observer.md @@ -1 +1,5 @@ # Observer + +An Observer, or Observation Channel, is an entity that provide an information related to a single run of the program under test to the fuzzer. + + diff --git a/docs/src/getting_started/crates.md b/docs/src/getting_started/crates.md index 1745da0494..841094e076 100644 --- a/docs/src/getting_started/crates.md +++ b/docs/src/getting_started/crates.md @@ -5,9 +5,36 @@ Each one has its self-contained purpose, and the user may not need to use all of Following the naming convention of the folders in the project's root, they are: -- libafl, the main crate that contains all the components needed to build a fuzzer -- libafl_derive, a proc-macro crate paired with the libafl crate -- libafl_targets, a crate that expose, under feature flags, pieces of code to interact with targets -- libafl_cc, a library that provide some utils to wrap compilers and create source level fuzzers. +### libafl +This is the main crate that contains all the components needed to build a fuzzer. +This crate has the following feature flags: + +- std, that enables the parts of the code that use the Rust standard library. Without this flags, libafl is no_std. +- derive, that enables the usage of the `derive(...)` macros defined in libafl_derive from libafl. + +By default, std and derive are both set. + +### libafl_derive + +This a proc-macro crate paired with the libafl crate. + +At the moment, it just expose the `derive(SerdeAny)` macro that can be used to define metadata structs. + +### libafl_targets + +This crate that exposes, under feature flags, pieces of code to interact with targets + +Currently, the supported flags are: + +- pcguard_edges, that defines the SanitizerCoverage trace-pc-guard hooks to track the executed edges in a map. +- pcguard_hitcounts, that defines the SanitizerCoverage trace-pc-guard hooks to track the executed edges with the hitcounts (like AFL) in a map. +- libfuzzer, that expose a compatibility layer with libFuzzer style harnesses. +- value_profile, that defines the SanitizerCoverage trace-cmp hooks to track the matching bits of each comparison in a map. + +### libafl_cc + +This is a library that provides some utils to wrap compilers and create source level fuzzers. + +At the moment, only the Clang compiler is supported. diff --git a/libafl/Cargo.toml b/libafl/Cargo.toml index 2c1506c38e..72aafb481c 100644 --- a/libafl/Cargo.toml +++ b/libafl/Cargo.toml @@ -32,7 +32,6 @@ harness = false [features] default = ["std", "anymapdbg", "derive"] std = [] # print, sharedmap, ... support -runtime = [] # a runtime for clang inmem-executor anymapdbg = ["serde_json"] # uses serde_json to Debug the anymap trait. Disable for smaller footprint. derive = ["libafl_derive"] # provide derive(SerdeAny) macro. llmp_small_maps = [] # reduces initial map size for llmp