| // 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 existing 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 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 analyzes feedback and generates new inputs using mutators. |
| /// * A target adapter that provides transforms inputs from the engine to |
| /// 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 transform inputs. |
| /// * controller.fidl: |
| /// * Each `Result` enumerates a possible outcome of executing the target |
| /// with a test input. |
| /// * `Input` structs represent sequences of bytes used to test the target |
| /// and that can be transferred to and from a development host. |
| /// * Implementations of the `Controller` protocol allow clients to control |
| /// fuzzing execution. |
| /// * Implementations of the `ControllerProvider` protocol connect clients |
| /// to fuzzers. |
| /// * corpus.fidl: |
| /// * Each `Corpus` enumerates a set of fuzzing inputs. |
| /// * Implementations of the `CorpusReader` protocol allow iterating over a |
| /// corpus of inputs. |
| /// * coverage.fidl: |
| /// * The `InstrumentedProcess` struct represents a process that can collect |
| /// code coverage data. |
| /// * Implementations of `CoverageDataCollector` aggregate LLVM module code |
| /// coverage data from instrumented processes. |
| /// * `CoverageData` is a union that can represent instrumented processes or |
| /// modules. |
| /// * Implementations of `CoverageDataProvider` allow the engine to retrieve |
| /// code coverage data for instrumented processes. |
| /// * manager.fidl: |
| /// * Implementations of `Manager` allow clients to start, connect to, and |
| /// stop fuzz test realms. |
| /// * Each `TestOutput` enumerates a diagnostic stream from the test realm. |
| /// * options.fidl: |
| /// * The `Options` table details various configurable parameters for the |
| /// fuzzer. |
| /// * registry.fidl: |
| /// * Implementations of `Registrar` allow each fuzzer to register its |
| /// `ControllerProvider` on launch. |
| /// * Implementations of `Registry` allow the `fuzz_manager` to connect to |
| /// or disconnect fuzz test realms. |
| /// * 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; |