Crate libafl_bolts

Expand description

Welcome to LibAFL_bolts

§LibAFL_bolts: OS and Fuzzer Dev’s Libary Collection.

The libafl_bolts crate exposes a lot of low-level features of LibAFL for projects that are unrelated to fuzzing, or just fuzzers completely different to LibAFL. 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
LLMP: A fast, lock-free IPC mechanism via SharedMap
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 of the parts in this list may be hard, don’t be afraid to open a PR if you cannot fix them by yourself, so we can help.

§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::Rng
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 (enabled by default) — Enables llmp compression using GZip
llmp_debug — Enables debug output for LLMP (also needs a logger installed)
llmp_small_maps (enabled by default) — Reduces the initial map size for llmp

Modules§

anymap: Poor-rust-man’s downcasts to have AnyMap
bolts_prelude: The purpose of this module is to alleviate imports of the bolts by adding a glob import.
build_id: Based on https://github.com/alecmocatta/build_id (C) Alec Mocatta alec@mocatta.net under license MIT or Apache 2
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.
core_affinity: This crate manages CPU affinities.
cpu: Fast implementations for specific CPU architectures.
fs: LibAFL functionality for filesystem interaction
llmp: A library for low level message passing
math: Math-related functions that we commonly (or at least sometimes) need
minibsod: Implements a mini-bsod generator. It dumps all important registers and prints a stacktrace.
os: Operating System specific abstractions
ownedref: Wrappers that abstracts references (or pointers) and owned data accesses.
prelude: The purpose of this module is to alleviate imports of many components by adding a glob import.
pybind
rands: The random number generators of LibAFL
serdeany: Poor-rust-man’s downcasts for stuff we send over the wire (or shared maps)
shmem: A generic shared memory region to be used by any functions (queues or feedbacks too.)
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.
tuples: Compiletime lists/tuples used throughout the LibAFL universe

Macros§

create_manual_register: Manually register a SerdeAny type in the RegistryBuilder
create_register: Register a SerdeAny type in the RegistryBuilder
impl_serde_pyobjectwrapper
impl_serdeany: Implement a SerdeAny, registering it in the RegistryBuilder when on std
map_tuple_list_type: Maps the types of a mapping with a MappingFunctor
merge_tuple_list_type: Merges the types of two merged tuple_list!s
nonnull_raw_mut: Get a core::ptr::NonNull to a global static mut (or similar).
nonzero: Zero-cost way to construct core::num::NonZeroUsize at compile-time.
tuple_for_each: Iterate over a tuple, executing the given expr for each element.
tuple_for_each_mut: Iterate over a tuple, executing the given expr for each element, granting mut access.
unwrap_me_body
unwrap_me_mut_body

Structs§

ClientId: The client ID == the sender id.
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

Constants§

IP_LOCALHOST: Localhost addr, this is used, for example, for LLMP Client, which connects to this address

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
AsSizedSlice: Can be converted to a slice
AsSizedSliceMut: Can be converted to a mutable slice
AsSlice: Can be converted to a slice
AsSliceMut: Can be converted to a mutable slice
HasLen: Has a length field
HasRefCnt: Has a ref count
IntoOwned: Trait to convert into an Owned type
Named: We need fixed names for many parts of this lib.
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
dup_and_mute_outputs^⚠: Closes stdout and stderr and returns a new stdout and stderr to be used in the fuzzer for further logging.
format_duration_hms: Format a Duration into a HMS string
generic_hash_std: Hashes the input with a given hash
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
vec_init^⚠: Create a Vec of the given type with nb_elts elements, initialized in place. The closure must initialize Vec (of size nb_elts * sizeo_of::<T>()).

Type Aliases§

ErrorBacktrace: Error Backtrace type when errors_backtrace feature is enabled (== backtrace::Backtrace)

Derive Macros§

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

Crate libafl_boltsCopy item path