Crate libafl_bolts

Expand description

Welcome to LibAFL_bolts

§`LibAFL_bolts`: Handy Libary Collection for Everybody

The libafl_bolts crate is a toolshed combinding a lot of low-level features and crates LibAFL uses. It can be a good starting point for low-level projects, even those that are not specifically fuzzers. Some cross-platform things in bolts include (but are not limited to):

SerdeAnyMap: a map that stores and retrieves elements by type and is serializable and deserializable
ShMem: A cross-platform (Windows, Linux, Android, macOS) shared memory implementation
LL_MP: A fast, lock-free IPC mechanism via shared maps
Core_affinity: A maintained version of core_affinity that can be used to get core information and bind processes to cores
Rands: Fast random number generators for fuzzing (like RomuRand)
MiniBSOD: get and print information about the current process state including important registers.
Tuples: Haskel-like compile-time tuple lists
Os: OS specific stuff like signal handling, windows exception handling, pipes, and helpers for fork

LibAFL_bolts is written and maintained by

§Contributing

For bugs, feel free to open issues or contact us directly. Thank you for your support. <3

Even though we will gladly assist you in finishing up your PR, try to

keep all the crates compiling with stable rust (hide the eventual non-stable code under cfgs.)
run cargo nightly fmt on your code before pushing
check the output of cargo clippy --all or ./clippy.sh
run cargo build --no-default-features to check for no_std compatibility (and possibly add #[cfg(feature = "std")]) to hide parts of your code.

Some parts in this list may sound hard, but don’t be afraid to open a PR if you cannot fix them by yourself. We will gladly assist.

§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.}
_{Dependencies under more restrictive licenses, such as GPL or AGPL, can be enabled
using the respective feature in each crate when it is present, such as the
'agpl' feature of the libafl crate.}

§Feature Flags

§General Features

std (enabled by default) — Enables features that need rust’s std lib to work, like print, env, … support
alloc (enabled by default) — Enables all features that allocate in no_std
derive (enabled by default) — Provide the #[derive(SerdeAny)] macro.
rand_trait (enabled by default) — If set, libafl_bolt’s rand implementations will implement rand_core::CoreRng and, inversely, all seedable rand_core::RngCore types can be used as Rng for LibAFL.
python — Will build the pyo3 bindings
prelude — Expose libafl::prelude for direct access to all types without additional use directives
cli — Expose libafl_bolts::cli for easy commandline parsing of common fuzzer settings
qemu_cli — Enables extra commandline flags for qemu-based fuzzers in cli
frida_cli — Enables extra commandline flags for frida-based fuzzers in cli
errors_backtrace — Stores the backtraces of all generated Errors. Good for debugging, but may come with a slight performance hit.
gzip (enabled by default) — Enables gzip compression in certain parts of the lib
xxh3 (enabled by default) — Replaces ahash with the potentially faster xxh3 in some parts of the lib. This yields a stable and fast hash, but may increase the resulting binary size slightly This also enables certain hashing and rand features in no_std no-alloc.

§SerdeAny features

stable_anymap — With this feature, the AnyMap uses type_name instead of TypeId::of for deserialization. With this feature, stored state remains deserializable across multiple compilations of LibAFL. The rust doc specifically states that “multiple types may map to the same type name”, so it could potentially lead to bugs. However, we make sure that no two types with the same name ever exist.
serdeany_autoreg (enabled by default) — Automatically register all #[derive(SerdeAny)] types at startup.

§LLMP features

llmp_bind_public — If set, llmp will bind to 0.0.0.0, allowing cross-device communication. Binds to localhost by default.
llmp_compression — Enables llmp compression using GZip
llmp_debug — Enables debug output for LLMP (also needs a logger installed)
llmp_small_maps — Reduces the initial map size for llmp

§Stable SIMD features

simd (enabled by default) — Use the best SIMD implementation by our benchmark.

Re-exports§

pub use build_id2 as build_id;
pub use core_affinity2 as core_affinity;
pub use ll_mp as llmp;
pub use minibsod;
pub use tuple_list_ex as tuples;
pub use fast_rands as rands;
pub use ownedref;
pub use shmem_providers as shmem;
pub use nonzero_macros;
pub use argparse::*;
pub use target_args::*;

Modules§

anymap: Poor-rust-man’s downcasts to have AnyMap
argparse: Parse command line argument like AFL, then put it in a C-compatible way
bolts_prelude: The purpose of this module is to alleviate imports of the bolts by adding a glob import.
cli: A one-size-fits-most approach to defining runtime behavior of LibAFL fuzzers
compress: Compression of events passed between a broker and clients. Currently we use the gzip compression algorithm for its fast decompression performance.
fs: LibAFL functionality for filesystem interaction
math: Math-related functions that we commonly (or at least sometimes) need
os: Operating System specific abstractions
prelude: The purpose of this module is to alleviate imports of many components by adding a glob import.
pybind
serdeany: Poor-rust-man’s downcasts for stuff we send over the wire (or shared maps)
simd: Module for SIMD assisted methods.
staterestore: Stores and restores state when a client needs to relaunch. Uses a ShMem up to a threshold, then write to disk.
subrange: Subrange of things. Convenient wrappers to handle sub-slices efficiently.
target_args: Shared implementation of afl style arguments

Macros§

impl_serde_pyobjectwrapper
impl_serdeany: Implement a SerdeAny, registering it in the RegistryBuilder when on std
nonnull_raw_mut: Get a core::ptr::NonNull to a global static mut (or similar).
nonzero: Zero-cost way to construct NonZero* types from core::num at compile-time.
try_nonzero: Construct Option<NonZero*> types from core::num.
unwrap_me_body

Structs§

ClientId: The client ID for various use cases across LibAFL
SimpleFdLogger: A simple logger struct that logs to a RawFd when used with log::set_logger.
SimpleStderrLogger: A simple logger struct that logs to stderr when used with log::set_logger.
SimpleStdoutLogger: A simple logger struct that logs to stdout when used with log::set_logger.

Enums§

Error: Main error struct for LibAFL

Statics§

LIBAFL_STDERR_LOGGER: Stderr logger
LIBAFL_STDOUT_LOGGER: Stdout logger

Traits§

AsIter: Create an Iterator from a reference
AsIterMut: Create an Iterator from a mutable reference
AsSizedSliceDeprecated: Can be converted to a slice
AsSizedSliceMutDeprecated: Can be converted to a mutable slice
AsSliceDeprecated: Can be converted to a slice
AsSliceMutDeprecated: Can be converted to a mutable slice
HasLen: Has a length field
HasRefCnt: Has a ref count
Named: We need fixed names for many parts of this lib.
ToSizedSlice: Can be converted to a slice
ToSizedSliceMut: Can be converted to a mutable slice
ToSlice: Can be converted to a slice
ToSliceMut: Can be converted to a mutable slice
Truncate: Trait to truncate slices and maps to a new size

Functions§

current_milliseconds: Gets current milliseconds since UNIX_EPOCH
current_nanos: Gets current nanoseconds since UNIX_EPOCH
current_time: Current time
format_big_number: Format a number with thousands separators
format_duration: Format a Duration into a HMS string
generic_hash_std: Hashes the input with a given hash
get_thread_id: Return thread ID without using TLS
has_tls: Some of our hooks can be invoked from threads that do not have TLS yet. Many Rust and Frida functions require TLS to be set up, so we need to check if we have TLS. This was observed on Windows, so for now for other platforms we assume that we have TLS.
hash_64_fast: Fast hash function for 64 bits integers minimizing collisions. Adapted from https://xorshift.di.unimi.it/splitmix64.c
hash_std: Hashes the input with a given hash
hasher_std: Returns the standard input Hasher
set_error_print_panic_hook^⚠: Set up an error print hook that will

Derive Macros§

SerdeAny: Derive macro to implement SerdeAny, to use a type in a SerdeAnyMap