Crate libafl_targets

Expand description

libafl_targets contains runtime code, injected in the target itself during compilation.

§`LibAFL_Targets`: Runtime Components for Instrumented Fuzzing Targets

The libafl_targets crate provides the essential runtime components that are injected into a target program during its compilation for fuzzing with LibAFL. This crate contains the code that runs inside the fuzzed program, communicating with the LibAFL fuzzer to provide coverage information, comparison data, and other feedback.

§Features

libafl_targets is highly modular and uses a feature-based system to allow users to select the specific instrumentation and runtime components needed for their fuzzing campaign. This ensures that only the necessary code is included in the target, minimizing overhead.

A non-exhaustive list of features includes:

Coverage Tracking: Different strategies for tracking code coverage are available:
- sancov_pcguard: Implements coverage tracking using __sanitizer_cov_pc_guard, which can be used for edge coverage (sancov_pcguard_edges) or hit count tracking (sancov_pcguard_hitcounts).
- sancov_ngram: Supports N-gram coverage to track sequences of executed basic blocks.
- sancov_ctx: Provides context-sensitive coverage.
- …
Comparison and Value Profiling:
- sancov_cmplog: Instruments compare instructions and memcmp/strcmp calls to log interesting values, which can be used by the CmpLog feedback mechanism in LibAFL and solve comparisons during fuzzing.
- sancov_value_profile: Gathers information about values observed at compare sites.
LibFuzzer Compatibility Layer:
- libfuzzer: A set of features to provide compatibility with the LibFuzzer fuzzing engine, allowing LibAFL to be used for LibFuzzer harnesses.
Forkserver:
- forkserver: Includes the client-side implementation of a forkserver, which can significantly speed up the fuzzing of programs that have a slow initialization phase.
Dynamic Analysis:
- drcov: Support for drcov output format (DynamoRIO code coverage) for coverage visualizations.
…

§The `LibAFL` Project

The LibAFL project is part of AFLplusplus 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
introspection — Collects performance statistics of the fuzzing pipeline and displays it on Monitor components
sancov_8bit — Support for the sancov 8-bit counters. This feature enables the 8-bit-counters runtime for LibAFL, which uses a global COUNTERS_MAPS to store coverage maps. It is compatible with LLVM’s SanitizerCoverage 8-bit counters instrumentation.
sancov_pcguard_edges — Support for sancov pcguard edge coverage. This feature enables the pcguard runtime for LibAFL, specifically for edge coverage. It instruments edges by writing a 1 to the coverage map at the corresponding index. This is non-colliding coverage. Mutually exclusive with sancov_pcguard_hitcounts.
sancov_pcguard_hitcounts — Support for sancov pcguard hitcounts coverage. This feature enables the pcguard runtime for LibAFL, specifically for hitcounts coverage. It instruments edges by incrementing the counter in the coverage map at the corresponding index. This is non-colliding coverage. Mutually exclusive with sancov_pcguard_edges.
sancov_value_profile — Support for sancov value profile. This feature enables value profiling in the sancov runtime. It compiles sancov_cmp.c with SANCOV_VALUE_PROFILE defined, enabling tracing of comparisons.
sancov_ngram4 — Support for sancov ngram4 coverage. This feature enables NGRAM-4 instrumentation in the sancov runtime. It maintains a history of the last 4 locations to provide context-sensitive coverage.
sancov_ngram8 — Support for sancov ngram8 coverage. This feature enables NGRAM-8 instrumentation in the sancov runtime. It maintains a history of the last 8 locations to provide context-sensitive coverage.
sancov_ctx — Support for sancov context coverage. This feature enables context-sensitive coverage in the sancov runtime. It XORs the current position with the previous context ID to distinguish paths based on calling context.
sancov_cmplog — Support for sancov-based cmplog. This feature enables comparison logging using the LLVM sancov runtime. It compiles sancov_cmp.c with SANCOV_CMPLOG defined and links against weak symbols for comparison hooks. This allows tracing of comparison operands for advanced fuzzing techniques like RedQueen. Defines cmp and __sanitizer_weak_hook functions. Use libfuzzer_interceptors to define interceptors (only compatible with Linux)
sancov_pcguard — Support for sancov pcguard. This is an alias for sancov_pcguard_hitcounts, enabling hitcounts coverage by default.
sancov_pcguard_dump_cov — Support for sancov pcguard dump cov. This uses pcguard to be able to dump lcov-compatible .info files.
common (enabled by default) — Compile common C code defining sanitizer options and cross-platform intrinsics. This feature compiles common.c and common.h, which are used by many other features.
coverage (enabled by default) — Compile C code definining coverage maps. This feature compiles coverage.c, which defines the edge coverage map (EDGES_MAP) and related variables.
cmplog (enabled by default) — Compile C code defining cmp log maps. This feature compiles cmplog.c and cmplog.h, which define the comparison logging map and related structures.
forkserver (enabled by default) — Compile C code for forkserver support. This feature compiles forkserver.rs and enables the forkserver protocol for communicating with the fuzzer. It allows the target to be spawned and controlled by a parent fuzzer process.
windows_asan (enabled by default) — Compile C code for ASan on Windows. This feature compiles windows_asan.c and windows_asan.rs to provide AddressSanitizer support on Windows.
whole_archive — use +whole-archive to ensure the presence of weak symbols. This feature adds the +whole-archive modifier to linked libraries in build.rs. This is important for ensuring that weak symbols (like sanitizer hooks) are included in the final binary.
cmplog_extended_instrumentation — This feature enables extended CmpLog instrumentation, compatible with AFL++. It compiles cmplog.c with CMPLOG_EXTENDED defined.
function-logging — Support for function logging. This feature enables the call module, which provides hooks for function calls. It allows tracing function entries and exits.
track_hit_feedbacks — Tracks the Feedbacks and the Objectives that were interesting for a Testcase. This feature enables tracking of hit feedbacks in the libfuzzer OOM observer.

§Libfuzzer-compatibility Features

libfuzzer — Libfuzzer compatibility mode. This feature compiles libfuzzer.c and enables Libfuzzer compatibility. It allows LibAFL to be used as a drop-in replacement for Libfuzzer.
libfuzzer_no_link_main — Libfuzzer mode without linking main. This feature defines FUZZER_NO_LINK_MAIN when compiling libfuzzer.c. It prevents the definition of a main function, which is useful when the target already has a main.
libfuzzer_define_run_driver — Libfuzzer mode defining run driver. This feature defines FUZZER_DEFINE_RUN_DRIVER when compiling libfuzzer.c. It defines the run_driver symbol, which is used by some Libfuzzer targets.
libfuzzer_interceptors — Libfuzzer interceptors. This feature compiles FuzzerInterceptors.cpp, which defines interceptors for common library functions (e.g., malloc, free). It is used to track memory allocations and other events in Libfuzzer compatibility mode.
libfuzzer_oom — Libfuzzer OOM handling. This feature enables Out-Of-Memory (OOM) handling in Libfuzzer compatibility mode. It registers a handler to catch OOM errors and report them to the fuzzer.

§Sanitizer Features

sanitizers_flags (enabled by default) — Sanitizer flags. This feature defines DEFAULT_SANITIZERS_OPTIONS in common.c. It sets default options for sanitizers (e.g., ASAN, MSAN) to be compatible with fuzzing.
pointer_maps — Pointer maps. This feature changes the way coverage maps are accessed. Instead of using fixed-size arrays, it uses pointers to access the maps. This is useful when the map location is not known at compile time or when using shared memory.
sanitizer_interfaces — Sanitizer interfaces. This feature generates Rust bindings for sanitizer interface headers (sanitizer_interfaces.h). It allows accessing sanitizer functions and structures from Rust code.
clippy — Ignore compiler warnings during clippy. This feature suppresses clippy warnings in generated code or specific modules.
observers — Observers. This feature enables observer implementations in sancov_8bit and cmps. It allows using these observers to track coverage and comparison values.
document-features — Document all features of this crate (for cargo doc)

Re-exports§

pub use sancov_pcguard::*;
pub use sancov_cmp::*;
pub use libfuzzer::*;
pub use sancov_8bit::*;
pub use coverage::*;
pub use value_profile::*;
pub use call::*;
pub use cmps::*;
pub use forkserver::*;

Modules§

call: The module to hook call instructions
cmps: runtime related to comparisons
coverage: Coverage maps as static mut array
drcov: DrCov support for LibAFL FRIDA mode.
forkserver: Forkserver logic into targets
libfuzzer: Libfuzzer-style runtime wrapper for LibAFL.
sancov_8bit: LLVM 8-bit-counters runtime for LibAFL.
sancov_cmp: Sanitizer Coverage comparison functions
sancov_pcguard: LLVM PcGuard runtime for LibAFL.
sancov_pcguard_dump_cov: Dump coverage to gcov/lcov .info files. Use them with genhtml to generate HTML coverage reports.
sanitizer_ifaces: Module containing bindings to the various sanitizer interface headers
value_profile: Value profile support for LibAFL

Constants§

ACCOUNTING_MAP_SIZE: The size of the accounting maps
CMPLOG_MAP_H: The height of the CmpLog map
CMPLOG_MAP_W: The width of the CmpLog map
CMP_MAP_SIZE: The size of the cmps map
EDGES_MAP_ALLOCATED_SIZE: The real allocated size of the edges map
EDGES_MAP_DEFAULT_SIZE: The default size of the edges map the fuzzer uses