diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 72152e1872..dbd505c809 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -14,8 +14,4 @@ - [Design](./design/design.md) - [Core Concepts](./design/core_concepts.md) - [Architecture](./design/architecture.md) - -- [Understanding Metadata](./medatata/metadata.md) - - [Definition](./medatata/definition.md) - - [(De)Serialization](./medatata/de_serialization.md) - - [Usage](./medatata/usage.md) + - [Metadata](./design/metadata.md) diff --git a/docs/src/baby_fuzzer.md b/docs/src/baby_fuzzer.md index 0fbdeef29c..a08ca608e9 100644 --- a/docs/src/baby_fuzzer.md +++ b/docs/src/baby_fuzzer.md @@ -318,4 +318,4 @@ Waiting for broker... Bye! ``` -As you can see, after the panic message, the `objectives` count of the log increased by one and you will find the crashing input in `crashes/id_0`. +As you can see, after the panic message, the `objectives` count of the log increased by one and you will find the crashing input in `crashes/`. diff --git a/docs/src/design/metadata.md b/docs/src/design/metadata.md new file mode 100644 index 0000000000..9eac4eae7b --- /dev/null +++ b/docs/src/design/metadata.md @@ -0,0 +1,41 @@ +# Metadata + +A metadata in LibAFL is a self contained structure that holds associated data to the State or to a Testcase. + +In terms of code, a metadata can be defined as a Rust struct registered in the SerdeAny register. + +```rust +use libafl::SerdeAny; +use serde::{Serialize, Deserialize}; + +#[derive(Serialize, Deserialize, SerdeAny)] +pub struct MyMetadata { + ... +} +``` + +The struct must be static, so it cannot hold references to borrowed objects. + +As an alternative to `derive(SerdeAny)` that is a proc-macro in `libafl_derive` the user can use `libafl::impl_serdeany!(MyMetadata);`. + +## Usage + +Metadata objects are primarly intended to be used inside [`SerdeAnyMap`](https://docs.rs/libafl/0.5.0/libafl/bolts/serdeany/serdeany_registry/struct.SerdeAnyMap.html) and [`NamedSerdeAnyMap`](https://docs.rs/libafl/0.5.0/libafl/bolts/serdeany/serdeany_registry/struct.NamedSerdeAnyMap.html). + +With these maps, the user can retrieve instances by type (and name). Internally, the instances are stored as SerdeAny trait objects. + +Structs that want to have a set of metadata must implement the [`HasMetadata`](https://docs.rs/libafl/0.5.0/libafl/state/trait.HasMetadata.html) trait. + +By default, Testcase and State implement it and hold a SerdeAnyMap testcase. + +## (De)Serialization + +We are interested to store State's Metadata to not lose them in case of crash or stop of a fuzzer. To do that, they must be serialized and unserialized using Serde. + +As Metadata are stored in a SerdeAnyMap as trait objects, they cannot be deserialized using Serde by default. + +To cope with this problem, in LibAFL each SerdeAny struct must be registered in a global registry that keeps track of types and allows the (de)serialization of the registered types. + +Normally, the `impl_serdeany` macro does that for the user creating a constructor function that fills the registry. However, when using LibAFL in no_std mode, this operation must be carried out manually before any other operation in the `main` function. + +To do that, the developer needs to know each metadata type that is used inside the fuzzer and call `RegistryBuilder::register::()` for each of them at the beginning of `main`. diff --git a/docs/src/design/usage.md b/docs/src/design/usage.md new file mode 100644 index 0000000000..33666487f1 --- /dev/null +++ b/docs/src/design/usage.md @@ -0,0 +1 @@ +# Metadata diff --git a/docs/src/getting_started/crates.md b/docs/src/getting_started/crates.md index 8a29e7b7e7..310f8a8ce4 100644 --- a/docs/src/getting_started/crates.md +++ b/docs/src/getting_started/crates.md @@ -38,3 +38,17 @@ Currently, the supported flags are: 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. + +### libafl_frida + +This library bridges libafl with Frida as instrumentation backend. + +With this crate you can instrument targets on Linux/macOS/Windows/Android for coverage collection. + +The CmpLog and AddressSanitizer instrumentation and runtimes are currently supported only for ARM64. + +### libafl_qemu + +This library bridges libafl with QEMU user-mode to fuzz ELF binaries. + +It works on Linux and can collect edge coverage withotu collisions. diff --git a/docs/src/medatata/de_serialization.md b/docs/src/medatata/de_serialization.md deleted file mode 100644 index de75e3c413..0000000000 --- a/docs/src/medatata/de_serialization.md +++ /dev/null @@ -1,3 +0,0 @@ -# (De)Serialization - -TODO describe the SerdeAny registry diff --git a/docs/src/medatata/definition.md b/docs/src/medatata/definition.md deleted file mode 100644 index 1f854ecc5a..0000000000 --- a/docs/src/medatata/definition.md +++ /dev/null @@ -1,19 +0,0 @@ -# Definition - -A metadata in LibAFL is a self contained structure that holds associated data to the State or to a Testcase. - -In terms of code, a metadata can be defined as a Rust struct registered in the SerdeAny register. - -```rust -use libafl::SerdeAny; -use serde::{Serialize, Deserialize}; - -#[derive(Serialize, Deserialize, SerdeAny)] -pub struct MyMetadata { - ... -} -``` - -The struct must be static, so it cannot hold references to borrowed objects. - - diff --git a/docs/src/medatata/metadata.md b/docs/src/medatata/metadata.md deleted file mode 100644 index 48511f3a03..0000000000 --- a/docs/src/medatata/metadata.md +++ /dev/null @@ -1,3 +0,0 @@ -# Understanding Metadata - -In this chapter, we discuss in depth the metadata system of LibAFL and its usage. diff --git a/docs/src/medatata/usage.md b/docs/src/medatata/usage.md deleted file mode 100644 index 1dfeb5194c..0000000000 --- a/docs/src/medatata/usage.md +++ /dev/null @@ -1,3 +0,0 @@ -# Usage - -TODO describe the HasMetadata interface