Struct Controller

pub struct Controller<O: OutputSink> { /* private fields */ }

Represents a fuchsia.fuzzer.Controller connection to a fuzzer.

Implementations

impl<O: OutputSink> Controller<O>

pub fn new(proxy: ControllerProxy, writer: &Writer<O>) -> Self

Returns a new Controller instance.

pub fn set_output<P: AsRef<Path>>( &mut self, socket: Socket, output: TestOutput, logs_dir: &Option<P>, ) -> Result<()>

Registers the provided output socket with the forwarder.

pub fn set_min_timeout(&mut self, min_timeout: i64)

Sets the minimum amount of time, in nanoseconds, before a workflow can time out.

If a the max_total_time option is set for a workflow that hangs, it will eventually timeout. This method can be used to specify the minimum duration that must elapse before a workflow is considered hung. The default of 1 minute is usually appropriate, but this method can be useful when testing.

pub async fn configure(&self, options: Options) -> Result<()>

Sets various execution and error detection parameters for the fuzzer.

Returns an error if:

• Communicating with the fuzzer fails
• A long-running call such as try_one, fuzz, cleanse, minimize, or merge is in progress.

pub async fn get_options(&self) -> Result<Options>

Returns a fuzzer’s current values for the various execution and error detection parameters.

Returns an error if communicating with the fuzzer fails

pub async fn reset_timer(&self) -> Result<()>

Recalculates the timeout for a long-running workflow based on the configured maximum total time and reported elapsed time.

Returns an error if communicating with the fuzzer fails

pub async fn read_corpus<P: AsRef<Path>>( &self, corpus_type: Corpus, corpus_dir: P, ) -> Result<Stats>

Retrieves test inputs from one of the fuzzer’s corpora.

The compacted corpus is saved to the corpus_dir. Returns details on how much data was received.

Returns an error if:

• Communicating with the fuzzer fails.
• One or more inputs fails to be received and saved.

pub async fn add_to_corpus( &self, input_pairs: Vec<InputPair>, corpus_type: Corpus, ) -> Result<Stats>

Adds a test input to one of the fuzzer’s corpora.

The test_input may be either a single file or a directory. Returns details on how much data was sent.

Returns an error if:

• Converting the input to an Input/fuchsia.fuzzer.Input pair fails.
• Communicating with the fuzzer fails
• The fuzzer returns an error, e.g. if it failed to transfer the input.

pub async fn get_status(&self) -> Result<Status>

Returns information about fuzzer execution.

The status typically includes information such as how long the fuzzer has been running, how many edges in the call graph have been covered, how large the corpus is, etc.

Refer to fuchsia.fuzzer.Status for precise details on the returned information.

pub async fn fuzz(&self) -> Result<()>

Runs the fuzzer in a loop to generate and test new inputs.

The fuzzer will continuously generate new inputs and tries them until one of four conditions are met:

• The number of inputs tested exceeds the configured number of runs.
• The configured amount of max_total_time has elapsed.
• An input triggers a fatal error, e.g. death by AddressSanitizer.
• fuchsia.fuzzer.Controller/Stop is called.

Returns an error if:

• Either runs or time is provided but cannot be parsed to a valid value.
• Communicating with the fuzzer fails.
• The fuzzer returns an error, e.g. it is already performing another workflow.

pub async fn try_one(&self, input_pair: InputPair) -> Result<()>

Tries running the fuzzer once using the given input.

Returns an error if:

• Converting the input to an Input/fuchsia.fuzzer.Input pair fails.
• Communicating with the fuzzer fails.
• The fuzzer returns an error, e.g. it is already performing another workflow.

pub async fn minimize(&self, input_pair: InputPair) -> Result<()>

Reduces the length of an error-causing input while preserving the error.

The fuzzer will bound its attempt to find shorter inputs using the given runs or time, if provided.

Returns an error if:

• Either runs or time is provided but cannot be parsed to a valid value.
• Converting the input to an Input/fuchsia.fuzzer.Input pair fails.
• Communicating with the fuzzer fails.
• The fuzzer returns an error, e.g. it is already performing another workflow.
• The minimized input fails to be received and saved.

pub async fn cleanse(&self, input_pair: InputPair) -> Result<()>

Replaces bytes in a error-causing input with PII-safe bytes, e.g. spaces.

The fuzzer will try to reproduce the error caused by the input with each byte replaced by a fixed number of “clean” candidates.

Returns an error if:

• Converting the input to an Input/fuchsia.fuzzer.Input pair fails.
• Communicating with the fuzzer fails.
• The fuzzer returns an error, e.g. it is already performing another workflow.
• The cleansed input fails to be received and saved.

pub async fn merge(&self) -> Result<()>

Removes inputs from the corpus that produce duplicate coverage.

The fuzzer makes a finite number of passes over its seed and live corpora. The seed corpus is unchanged, but the fuzzer will try to find the set of shortest inputs that preserves coverage.

Returns an error if:

• Communicating with the fuzzer fails.
• The fuzzer returns an error, e.g. it is already performing another workflow.
• One or more inputs fails to be received and saved.

pub async fn watch_artifact(&self) -> Result<FidlArtifact>

Waits for the results of a long-running workflow.

The fuchsia.fuzzer.Controller/WatchArtifact method uses a “hanging get” pattern. The first call will return whatever the current artifact is for the fuzzer; subsequent calls will block until the artifact changes. The implementation below may retry the FIDL method to ensure it only returns Ok(None) on channel close.

Trait Implementations

impl<O: Debug + OutputSink> Debug for Controller<O>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.