diff --git a/README.md b/README.md index c313fcca30..fc22643573 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,13 @@ Advanced Fuzzing Library - Slot your own fuzzers together and extend their featu LibAFL is written and maintained by Andrea Fioraldi and Dominik Maier . -It is released as Open Source Software under the [Apache v2](LICENSE-APACHE) or [MIT](LICENSE-MIT) licenses. +## What + +LibAFL is a collection of reusable pieces of fuzzers, written in Rust. + +It offers a main crate that provide building blocks for custom fuzzers, [libafl](./libafl), a library containing common code that can be used for targets instrumentation, [libafl_targets](./libafl_targets), and a library providing facilities to wrap compilers, [libafl_cc](./libafl_cc). + +LibAFL is fast, multi-platform, no_std compatible, and scales over cores (and machines in the near future!). ## Getting started @@ -20,29 +26,50 @@ Build the library using cargo build --release ``` -Build the documentation with +Build the API documentation with ``` cargo doc ``` -We collect example fuzzers in `./fuzzers`. They can be build using `cargo build --example [fuzzer_name] --release`. +Browse the LibAFL book with (requires [mdbook](https://github.com/rust-lang/mdBook)) -The best-tested fuzzer is `./fuzzers/libfuzzer_libpng`, a clone of libfuzzer using libafl for a libpng harness. -See its readme [here](./fuzzers/libfuzzer_libpng/README.md). +``` +cd docs && mdbook serve +``` -## The Core Concepts +We collect example fuzzers in [`./fuzzers`](./fuzzers/). -The entire library is based on some core concepts that we think can generalize Fuzz Testing. +The best-tested fuzzer is [`./fuzzers/libfuzzer_libpng`](./fuzzers/libfuzzer_libpng), a multicore libfuzzer-like fuzzer using LibAFL for a libpng harness. -We're still working on extending the documentation. +## Resources -In the meantime, you can watch the Video from last year's RC3, here: ++ [Installation guide](./docs/src/getting_started/setup.md) -[![Video explaining libAFL's core concepts](http://img.youtube.com/vi/3RWkT1Q5IV0/3.jpg)](http://www.youtube.com/watch?v=3RWkT1Q5IV0 "Fuzzers Like LEGO") ++ Our RC3 [talk](http://www.youtube.com/watch?v=3RWkT1Q5IV0 "Fuzzers Like LEGO") explaining the core concepts + ++ [Online API documentation](https://docs.rs/libafl/) + ++ The LibAFL book [online](https://aflplus.plus/libafl-book) or in the [repo](./docs/src/) ## Contributing Check the [TODO.md](./TODO.md) file for features that we plan to support. For bugs, feel free to open issues or contact us directly. Thank you for your support. <3 + +#### License + + +Licensed under either of Apache License, Version +2.0 or MIT license at your option. + + +
+ + +Unless you explicitly state otherwise, any contribution intentionally submitted +for inclusion in this crate by you, as defined in the Apache-2.0 license, shall +be dual licensed as above, without any additional terms or conditions. + + diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md index 5ab55fd332..72152e1872 100644 --- a/docs/src/SUMMARY.md +++ b/docs/src/SUMMARY.md @@ -14,7 +14,6 @@ - [Design](./design/design.md) - [Core Concepts](./design/core_concepts.md) - [Architecture](./design/architecture.md) - - [The State](./design/state.md) - [Understanding Metadata](./medatata/metadata.md) - [Definition](./medatata/definition.md) diff --git a/docs/src/design/architecture.md b/docs/src/design/architecture.md index 0dde078b77..b600ebdc75 100644 --- a/docs/src/design/architecture.md +++ b/docs/src/design/architecture.md @@ -8,6 +8,6 @@ The LibAFL code reuse meachanism is so based on components rather than sub-class Thinking about similar fuzzers, you can observe that most of the times the data structures that are modified are the ones related to testcases and the fuzzer global state. -Beside the entities described previously, we then introduce the Testcase and State entities. The Testcase is a container for an Input stored in the Corpus and its metadata (so, in the implementation, the Corpus stores Testcases) and the State contains all the metadata that are evolved while running the fuzzer, Corpus included. +Beside the entities described previously, we introduce the Testcase and State entities. The Testcase is a container for an Input stored in the Corpus and its metadata (so, in the implementation, the Corpus stores Testcases) and the State contains all the metadata that are evolved while running the fuzzer, Corpus included. diff --git a/docs/src/design/state.md b/docs/src/design/state.md deleted file mode 100644 index a898f3c21a..0000000000 --- a/docs/src/design/state.md +++ /dev/null @@ -1 +0,0 @@ -# The State diff --git a/docs/src/medatata/de_serialization.md b/docs/src/medatata/de_serialization.md index fabf103865..de75e3c413 100644 --- a/docs/src/medatata/de_serialization.md +++ b/docs/src/medatata/de_serialization.md @@ -1 +1,3 @@ # (De)Serialization + +TODO describe the SerdeAny registry diff --git a/docs/src/medatata/definition.md b/docs/src/medatata/definition.md index 9cf6ae572d..f78e552859 100644 --- a/docs/src/medatata/definition.md +++ b/docs/src/medatata/definition.md @@ -1 +1,19 @@ # 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 holds references to borrowed objects. + + diff --git a/docs/src/medatata/metadata.md b/docs/src/medatata/metadata.md index dfcaceb2b9..48511f3a03 100644 --- a/docs/src/medatata/metadata.md +++ b/docs/src/medatata/metadata.md @@ -1 +1,3 @@ # 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 index 8f04b05adb..1dfeb5194c 100644 --- a/docs/src/medatata/usage.md +++ b/docs/src/medatata/usage.md @@ -1 +1,3 @@ # Usage + +TODO describe the HasMetadata interface