| // 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. | |
| #ifndef SRC_SYS_FUZZING_REALMFUZZER_ENGINE_RUNNER_H_ | |
| #define SRC_SYS_FUZZING_REALMFUZZER_ENGINE_RUNNER_H_ | |
| #include <fuchsia/fuzzer/cpp/fidl.h> | |
| #include <lib/fidl/cpp/interface_request.h> | |
| #include <lib/zx/channel.h> | |
| #include <lib/zx/time.h> | |
| #include <stddef.h> | |
| #include <memory> | |
| #include <vector> | |
| #include "src/lib/fxl/macros.h" | |
| #include "src/sys/fuzzing/common/async-deque.h" | |
| #include "src/sys/fuzzing/common/async-types.h" | |
| #include "src/sys/fuzzing/common/input.h" | |
| #include "src/sys/fuzzing/common/runner.h" | |
| #include "src/sys/fuzzing/realmfuzzer/engine/adapter-client.h" | |
| #include "src/sys/fuzzing/realmfuzzer/engine/corpus.h" | |
| #include "src/sys/fuzzing/realmfuzzer/engine/coverage-data-provider-client.h" | |
| #include "src/sys/fuzzing/realmfuzzer/engine/module-pool.h" | |
| #include "src/sys/fuzzing/realmfuzzer/engine/mutagen.h" | |
| #include "src/sys/fuzzing/realmfuzzer/engine/process-proxy.h" | |
| namespace fuzzing { | |
| using ::fuchsia::fuzzer::CoverageData; | |
| // The concrete implementation of |Runner| for the realmfuzzer engine. | |
| class RealmFuzzerRunner final : public Runner { | |
| public: | |
| ~RealmFuzzerRunner() override = default; | |
| // Factory method. | |
| static RunnerPtr MakePtr(ExecutorPtr executor); | |
| // Sets the |handler| to use to (re)connect to the target adapter. | |
| void SetAdapterHandler(TargetAdapterClient::RequestHandler handler); | |
| // Sets the |handler| to use to connect to the coverage data provider. | |
| void SetProviderHandler(CoverageDataProviderClient::RequestHandler handler); | |
| // |Runner| method implementations. | |
| ZxPromise<> Initialize(std::string pkg_dir, std::vector<std::string> args) override; | |
| ZxPromise<> Configure() override; | |
| __WARN_UNUSED_RESULT zx_status_t AddToCorpus(CorpusType corpus_type, Input input) override; | |
| std::vector<Input> GetCorpus(CorpusType corpus_type) override; | |
| __WARN_UNUSED_RESULT zx_status_t ParseDictionary(const Input& input) override; | |
| Input GetDictionaryAsInput() const override; | |
| ZxPromise<Artifact> Fuzz() override; | |
| ZxPromise<Artifact> TryEach(std::vector<Input> inputs) override; | |
| ZxPromise<Artifact> ValidateMinimize(Input input) override; | |
| ZxPromise<Artifact> Minimize(Artifact artifact) override; | |
| ZxPromise<Artifact> Cleanse(Input input) override; | |
| ZxPromise<> ValidateMerge() override; | |
| ZxPromise<Artifact> Merge() override; | |
| Status CollectStatus() override; | |
| ZxPromise<> Stop() override; | |
| protected: | |
| // |Reset|s input queues, records start times, and notifies monitors that the workflow is | |
| // starting. This method is called automatically by |Workflow::Start|. | |
| void StartWorkflow(Scope& scope) override; | |
| // Drops remaining inputs from queues, |Disconnect|s, and notifies monitors that the workflow is | |
| // done. This method is called automatically by |Workflow::Finish|. | |
| void FinishWorkflow() override; | |
| // In addition to the base class's behavior, this method may produce additional output depending | |
| // on the configured output mode in the options. | |
| void UpdateMonitorsWithStatus(UpdateReason reason, Status status) override; | |
| private: | |
| // Indicates how the engine should handle inputs that don't trigger an error. | |
| enum PostProcessing { | |
| // No-op. | |
| kNoPostProcessing, | |
| // Add the input's coverage to the overall coverage. | |
| kAccumulateCoverage, | |
| // Determine if any of the input's coverage is new. If so, record the coverage in the input and | |
| // add it to the live corpus. | |
| kMeasureCoverageAndKeepInputs, | |
| // Determine if any of the input's coverage is new. If so, add it to the overall coverage and | |
| // add the input to the live corpus. | |
| kAccumulateCoverageAndKeepInputs, | |
| }; | |
| explicit RealmFuzzerRunner(ExecutorPtr executor); | |
| // Returns a promise to generate |num_inputs| inputs for testing by taking them from the | |
| // |processed| queue, mutating corpus elements, and sending them to the |generated| queue. If | |
| // |num_inputs| is 0, this will continuously generate new inputs until the |processed| queue is | |
| // closed and empty. | |
| // If a workflow does not depend on the coverage produced by each input, a |backlog| of inputs can | |
| // be generated, e.g. while waiting for target processes to respond. A |backlog| of 0 makes the | |
| // generation of each input depend on the processing of the previous one. | |
| ZxPromise<> GenerateInputs(size_t num_inputs, size_t backlog = 0); | |
| // Returns a promise to generate inputs from "cleaning" inputs received from the given `receiver` | |
| // and return them via the object's `generated_sender_`. To clean the input, it replaces each byte | |
| // with either a space or 0xFF. It keeps the change if the modified input triggers an error, as | |
| // determined by examining the artifacts that are sent back again via the `receiver`. | |
| Promise<> GenerateCleanInputs(AsyncReceiverPtr<Artifact> receiver, size_t attempts_left); | |
| // Returns a promise to |GenerateInputs| and |TestInputs|. This will first iterate through the | |
| // seed and live corpora before mutating new inputs. See |GenerateInputs| for details on | |
| // |backlog|. | |
| ZxPromise<Artifact> FuzzInputs(size_t backlog = 0); | |
| // Returns a promise to test a single |input|. The promise returns an artifact if found or an | |
| // error; in particular it returns |ZX_ERR_STOP| if it completed without finding an artifact. | |
| // | |
| // Inputs that do not trigger errors are analyzed according to the given |mode|. | |
| ZxPromise<Artifact> TestOneAsync(Input input, PostProcessing mode); | |
| // Returns a promise to test each non-empty input of a |corpus| in turn. The promise returns an | |
| // artifact if found or an error; in particular it returns |ZX_ERR_STOP| if it completed without | |
| // finding an artifact. | |
| // | |
| // Inputs that do not trigger errors are analyzed according to the given |mode|. | |
| // | |
| // Callers may specify they wish to |collect_errors| rather than stopping on the first artifact | |
| // found. See |TestInputs| for additional details. | |
| using InputsPtr = std::shared_ptr<std::vector<Input>>; | |
| ZxPromise<Artifact> TestCorpusAsync(CorpusPtr corpus, PostProcessing mode, | |
| InputsPtr collect_errors = nullptr); | |
| // Returns a promise that will read successive |Input|s from the |generated| queue, test them, and | |
| // release them to the |processed| queue. The promise returns an artifact if found or an error; | |
| // in particular it returns |ZX_ERR_STOP| if it completed without finding an artifact to return. | |
| // | |
| // Inputs that do not trigger errors are analyzed according to the given |mode|. | |
| // | |
| // Callers may specify they wish to |collect_errors| rather than return artifacts. In this case, | |
| // errors will be cleared after the associated input has been saved, and testing will continue | |
| // until it exhausts inputs and returns |ZX_ERR_STOP|. | |
| ZxPromise<Artifact> TestInputs(PostProcessing mode, InputsPtr collect_errors = nullptr); | |
| // Returns a promise that checks a |previous| error returned from a |Test...| method. The promise | |
| // will complete successfully if the error was |ZX_ERR_STOP|, indicating the previous test did not | |
| // find an artifact. Otherwise, the error will be forwarded. | |
| ZxPromise<> CheckPrevious(zx_status_t previous); | |
| // Returns a promise that updates the |Monitor|s with status periodically. To end updates, exit | |
| // the given |workflow| scope. | |
| Promise<> MakePulsePromise(int64_t pulse_interval, Scope& workflow); | |
| // Returns a promise to coordinate the target processes to start a new run and get the next | |
| // |Input| to be tested from the |generated_| queue. The promise will return any unexpected errors | |
| // from target processes, or |ZX_ERR_STOP| if there are no more |Input|s. to be tested. | |
| ZxPromise<Input> Prepare(bool detect_leaks); | |
| // Sends the |input| to the |target_adapter_|, and returns a promise to wait for and return the | |
| // results of the run. On completion, the promise will either return the error encountered when | |
| // testing the |input| or whether a memory leak is suspected, i.e. the |input| caused more | |
| // |malloc|s than |free|s. | |
| Promise<bool, FuzzResult> RunOne(const Input& input); | |
| // Adds a new process proxy for the process represented by the given `coverage` data. The coverage | |
| // data must be of the `instrumented` variant. | |
| void ConnectProcess(CoverageData instrumented); | |
| // Adds the given sanitizer `coverage` data. The coverage data must be of the | |
| // `inline_8bit_counters` variant. | |
| void AddInline8bitCounters(CoverageData inline_8bit_counters); | |
| // Returns a promise to determine the cause of an error in the target process identified by the | |
| // given |target_id|. In the case of multiple errors, only the first error is reported. However, | |
| // determining the error cause typically involves waiting for the process to terminate. | |
| // To accurately record which error is first, only the |target_id| is recorded initially, and the | |
| // other details are collected asynchronously using this method. | |
| Promise<bool, FuzzResult> GetFuzzResult(uint64_t target_id); | |
| // Examines the effects of a previous call to |RunOne| with the given |input|. This may collect | |
| // coverage and/or record new features for the input, according to the given |mode|. | |
| void Analyze(Input& input, PostProcessing mode); | |
| // Takes an |Input| and determines whether it should be retried to check for leaks or released for | |
| // reuse by a workflow to generate new |Input|s. Returns whether the next run will retry the input | |
| // to detect leaks, i.e. if the previous run was not |detecting| leaks, a leak was |suspected|, | |
| // and there are leak detection |attempts_left|. | |
| bool Recycle(Input&& input, size_t& attempts_left, bool suspected, bool detecting); | |
| // Disconnects from the target adapter and all target processes. | |
| void Disconnect(); | |
| // Clears errors and any inputs in queues and returns the runner to a "clean slate". This is | |
| // useful when resuming after arrors, e.g. in a workflow that finds multiple errors. | |
| void Reset(); | |
| // General configuration. | |
| uint32_t run_ = 0; | |
| // Time at which a workflow starts. | |
| zx::time start_ = zx::time::infinite_past(); | |
| // Time at after which "pulse" status updates may be sent to monitors. | |
| zx::time pulse_start_; | |
| // Flag to indicate no more inputs should be produced. | |
| bool stopped_ = true; | |
| // Input generation and management variables. | |
| CorpusPtr seed_corpus_; | |
| CorpusPtr live_corpus_; | |
| Mutagen mutagen_; | |
| // Queue of generated inputs for a workflow that are consumed by |TestInputs|. | |
| AsyncSender<Input> generated_sender_; | |
| AsyncReceiver<Input> generated_receiver_; | |
| // A separate, high-priority queue of previously tested inputs that are suspected to cause leaks. | |
| AsyncSender<Input> leak_sender_; | |
| AsyncReceiver<Input> leak_receiver_; | |
| // Interfaces to other components. | |
| TargetAdapterClient adapter_; | |
| CoverageDataProviderClient provider_; | |
| // Feedback collection and analysis variables. | |
| ModulePoolPtr pool_; | |
| std::unordered_map<uint64_t, std::unique_ptr<ProcessProxy>> process_proxies_; | |
| // A list of futures that include running the target adapter and awaiting errors or completion | |
| // status from process proxies. This is primarily used within |RunOne|, but needs to be visible | |
| // outside that method so completion futures for newly added processes can be added to it. | |
| std::vector<Future<bool, uint64_t>> futures_; | |
| fpromise::suspended_task suspended_; | |
| // Queue of tested input for a workflow that are ready to be processed and/or recycled. | |
| AsyncSender<Input> processed_sender_; | |
| AsyncReceiver<Input> processed_receiver_; | |
| Workflow workflow_; | |
| FXL_DISALLOW_COPY_ASSIGN_AND_MOVE(RealmFuzzerRunner); | |
| }; | |
| } // namespace fuzzing | |
| #endif // SRC_SYS_FUZZING_REALMFUZZER_ENGINE_RUNNER_H_ |