blob: d4e134815491f6468be58803e8d60dbc7b6b0419 [file] [log] [blame]
// Copyright 2021 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
/// The component fuzzer framework.
/// Fuzzing (or fuzz testing) is the process of pseudorandomly generating inputs for some target,
/// executing the target with those inputs, and detecting various error conditions that may arise as
/// a result. Guided fuzzing uses additional feedback from the target besides errors to determine
/// whether inputs should be saved and used as the basis of subsequent inputs. A concrete example
/// of guided fuzzing is coverage-guided fuzzing, which uses whether executing the target with a
/// fuzzing input produced new code coverage to determine whether it should be added to the corpus,
/// that is, the set of saved inputs.
/// Guided fuzzing frameworks can be described using the following taxonomy:
/// * Engine: A target-agnostic feedback loop.
/// * Corpus management: Maintains a collection of fuzzing inputs.
/// * Mutators: Mutation strategies and a PRNG used to create new inputs from exisiting ones.
/// * Feedback analysis: Dispositions an input based on its feedback, e.g. code coverage.
/// * Management interface: Interacts with the user to coordinates workflows.
/// * Target: The specific code under test.
/// * Input processing: Maps the fuzzer input for a single run to the code under test.
/// * Feedback collection: Observes the behavior caused by an input.
/// * Error detection: Determines when an input has caused an error and collects artifacts.
/// In order to fuzz a components and component topologies, the component fuzzer framework leverages
/// the test runner framework for its environment and execution features. It adds the pieces of the
/// taxonomy above into and around the test runner framework:
/// * A fuzz-manager that acts as a sibling to test-manager, and provides the management interface.
/// * A fuzz-registry that allows the fuzz-manager to find running fuzzers.
/// * A fuzz-test-runner within the test runner framework that launches the fuzzed realm and passes
/// it a connection to the fuzz-registry.
/// * A fuzzer engine within the fuzzed realm that registers with the registry. It provides
/// mutators and feedback analysis.
/// * A target adapter that provides input processing from the fuzz-test-driver to specific
/// behaviors in the target components, e.g. via FIDL calls.
/// * A ELF library that is linked against instrumented processes in the target components and that
/// provides feedback collection and error detection to the fuzz-test-driver.
/// This FIDL library provides the protocols and types used by these elements of the framework to
/// interact with one another. These types are found in the following files:
/// * adapter.fidl:
/// * Implementations of the |TargetAdapter| protocol provide input-processing.
/// * controller.fidl:
/// * |Input| structs represent file-like fuzzing inputs that can be transferred over FIDL.
/// * Each |Result| enumerates a possible outcome of executing the target with a fuzzing input.
/// * Implementations of the |ControllerProvider| protocol connect clients to fuzzers.
/// * Implementations of the |Controller| protocol allow clients to control fuzzing execution.
/// * corpus.fidl:
/// * Each |Corpus| enumerates a set of fuzzing inputs.
/// * Implementations of the |CorpusReader| protocol allow iterating over a corpus of inputs.
/// * options.fidl:
/// * The |Options| table details various configurable parameters for the fuzzer.
/// * process.fidl:
/// * The |Feedback| table lists target-provided feedback that can be used to guide fuzzing.
/// * Implementations of the |ProcessProxy| protocol accept feedback from targets.
/// * status.fidl:
/// * |ProcessStats| has ZX_INFO_TASK_STATS and ZX_INFO_TASK_RUNTIME details from targets.
/// * Each |UpdateReason| enumerates why status is being "pushed" by the fuzzer.
/// * Implementations of the |Monitor| protocol subscribe to updates from the fuzzer.
library fuchsia.fuzzer;