Enum ControllerRequest

pub enum ControllerRequest {
    Configure {
        options: Options,
        responder: ControllerConfigureResponder,
    },
    GetOptions {
        responder: ControllerGetOptionsResponder,
    },
    AddToCorpus {
        corpus: Corpus,
        input: Input,
        responder: ControllerAddToCorpusResponder,
    },
    ReadCorpus {
        corpus: Corpus,
        corpus_reader: ClientEnd<CorpusReaderMarker>,
        responder: ControllerReadCorpusResponder,
    },
    WriteDictionary {
        dictionary: Input,
        responder: ControllerWriteDictionaryResponder,
    },
    ReadDictionary {
        responder: ControllerReadDictionaryResponder,
    },
    AddMonitor {
        monitor: ClientEnd<MonitorMarker>,
        responder: ControllerAddMonitorResponder,
    },
    Fuzz {
        responder: ControllerFuzzResponder,
    },
    TryOne {
        test_input: Input,
        responder: ControllerTryOneResponder,
    },
    Minimize {
        test_input: Input,
        responder: ControllerMinimizeResponder,
    },
    Cleanse {
        test_input: Input,
        responder: ControllerCleanseResponder,
    },
    Merge {
        responder: ControllerMergeResponder,
    },
    GetStatus {
        responder: ControllerGetStatusResponder,
    },
    WatchArtifact {
        responder: ControllerWatchArtifactResponder,
    },
}

Provides the management interface for fuzzing.

This protocol is implemented by the fuzzing engine. Clients for this protocol are provided by fuchsia.fuzzer/ControllerProvider.Connect.

The channel is closed when the fuzzer is no longer needed, and on error. Clients should exit and not attempt to reconnect.

Variants

Configure

Sets various execution and error detection parameters. This may be called multiple times; only the most recently received options are used. If the Options parameter omits one or more fields, those parameters are unchanged in the fuzzer. Until the initial call to this method, the fuzzer should assume the default values for Options.

• request options the execution and error detection parameters.

• error one of the following:
• error
  • ZX_ERR_BAD_STATE if a long-running call such as Execute, Cleanse, Minimize, Fuzz, or Merge is in progress.
  • ZX_ERR_NOT_SUPPORTED if a value provided for an option is not supported by the engine. Check the logs for additional details.

Fields

options: Options

responder: ControllerConfigureResponder

GetOptions

Gets the current values for the various execution and error detection parameters.

• response options the execution and error detection parameters.

Fields

responder: ControllerGetOptionsResponder

AddToCorpus

Writes the provided input to either the “seed” or “live” corpus. Returns an error if transferring the input fails; see Input for details.

• request corpus the type of corpus to add to.
• request input the sequence of bytes to add as a test input.

• error one of the following:
  • ZX_ERR_INVALID_ARGS if corpus type is invalid.
  • A socket error if transferring the input fails.

Fields

corpus: Corpus

input: Input

responder: ControllerAddToCorpusResponder

ReadCorpus

Connects a corpus_reader for either the “seed” or “live” corpus.

• request corpus the type of corpus to read from.
• request corpus_reader the client used to send test inputs.

Fields

corpus: Corpus

corpus_reader: ClientEnd<CorpusReaderMarker>

responder: ControllerReadCorpusResponder

WriteDictionary

Parses and loads an AFL-style dictionary. Invalid entries are logged and skipped.

See also:

• https://github.com/mirrorer/afl/blob/master/dictionaries/README.dictionaries

• request dictionary the AFL-style dictionary

• error one of the following:
  • A socket error if transferring the input fails. *ZX_ERR_INVALID_ARGS if parsing the dictionary fails.

Fields

dictionary: Input

responder: ControllerWriteDictionaryResponder

ReadDictionary

Returns the current dictionary as an Input, which may be empty.

• response dictionary the current AFL-style dictionary.

Fields

responder: ControllerReadDictionaryResponder

AddMonitor

Installs a Monitor to push status. To pull status instead, use GetStatus.

• request monitor the client used to send status updates.

Fields

monitor: ClientEnd<MonitorMarker>

responder: ControllerAddMonitorResponder

Fuzz

Runs the normal fuzzing feedback loop:

1. Selects an input from the corpus.
2. Mutates the input.
3. Uses the TargetAdapter to execute the input.
4. Checks feedback from the InstrumentedProcesses.
5. If the input produced useful feedback, adds it to the corpus.

This call returns quickly, but the loop continues until one of three conditions is met:

1. The configured, non-zero number of runs has been reached.
2. The configured, non-zero duration elapses.
3. An error is detected, and returned.

See Result for more details on long running workflows such as this one.

• error ZX_ERR_BAD_STATE if another long-running workflow is in progress.

Fields

responder: ControllerFuzzResponder

TryOne

Executes the target code with a single test_input.

See Result for more details on long running workflows such as this one.

• request input the sequence of bytes to use with the fuzz target.

• error one of the following:
  • ZX_ERR_BAD_STATE if another long-running workflow is in progress.
  • A socket error if transferring the input fails.

Fields

test_input: Input

responder: ControllerTryOneResponder

Minimize

Attempts to find the smallest input that produces the same error as the given test_input, constrained by the configured total_time and/or runs options.

See Result for more details on long running workflows such as this one.

• request input the sequence of bytes to minimize.

• error one of the following:
  • ZX_ERR_BAD_STATE if another long-running workflow is in progress.
  • A socket error if transferring the input fails.
  • ZX_ERR_INVALID_ARGS if the provided test_input does not cause an error.

Fields

test_input: Input

responder: ControllerMinimizeResponder

Cleanse

Attempts to replace bytes of the given test_input with “filler” bytes, e.g. \x00, \xFF, without changing the error produced.

See Result for more details on long running workflows such as this one.

To preserve backwards compatibility with libFuzzer and ClusterFuzz, an input that produces no result is not considered an error, and is returned as-is.

• request input the sequence of bytes to cleanse.

• error one of the following:
  • ZX_ERR_BAD_STATE if another long-running workflow is in progress.
  • A socket error if transferring the input fails.

Fields

test_input: Input

responder: ControllerCleanseResponder

Merge

Attempts to shrink the corpora. Inputs from the seed corpus will be preserved. All other inputs will be sorted by amount of feedback produced and input size, and only those inputs that add new feedback not seen earlier in the sequence will be kept.

See Result for more details on long running workflows such as this one.

• error one of the following:
  • ZX_ERR_BAD_STATE if another long-running workflow is in progress.
  • ZX_ERR_INVALID_ARGS if an input in the seed corpus causes an error. Inputs in the live corpus that cause errors are skipped.

Fields

responder: ControllerMergeResponder

GetStatus

Returns various fuzzing metrics, e.g. total coverage, speed, etc.

• response status the current value of fuzzing metrics.

Fields

responder: ControllerGetStatusResponder

WatchArtifact

Returns the results of a long-running workflow.

This method uses the “hanging get” pattern. Upon the first call for a given connection, it will immediately return the controller’s current artifact. Upon subsequent calls, it will block until the controller’s artifact changes before returning. Clients should use GetStatus to ensure the fuzzer is not idle before making a blocking call to WatchArtifact.

Combined with the Status.running value obtained from GetStatus, this allows a (re-)connecting client to infer the state of the fuzzer:

• If the fuzzer is idle and has an empty artifact, then it is unchanged since the last connection, if any.
• If the fuzzer is running and has an empty artifact, then it is performing a long-running workflow started by a previous connection. The client may call WatchArtifact again to wait for the workflow to complete.
• If the fuzzer is idle and has a non-empty artifact, then it has completed a long-running workflow since the last connection.

It is not an error for clients to disconnect while waiting for a response from this method. This method is intended to allow clients to resume waiting for a long-running workflow to complete after intentionally or inadvertently being disconnected for an indefinite amount of time.

• response artifact the most recent result and/or error-causing input.

Fields

responder: ControllerWatchArtifactResponder

Implementations

impl ControllerRequest

pub fn into_configure(self) -> Option<(Options, ControllerConfigureResponder)>

pub fn into_get_options(self) -> Option<ControllerGetOptionsResponder>

pub fn into_add_to_corpus( self, ) -> Option<(Corpus, Input, ControllerAddToCorpusResponder)>

pub fn into_read_corpus( self, ) -> Option<(Corpus, ClientEnd<CorpusReaderMarker>, ControllerReadCorpusResponder)>

pub fn into_write_dictionary( self, ) -> Option<(Input, ControllerWriteDictionaryResponder)>

pub fn into_read_dictionary(self) -> Option<ControllerReadDictionaryResponder>

pub fn into_add_monitor( self, ) -> Option<(ClientEnd<MonitorMarker>, ControllerAddMonitorResponder)>

pub fn into_fuzz(self) -> Option<ControllerFuzzResponder>

pub fn into_try_one(self) -> Option<(Input, ControllerTryOneResponder)>

pub fn into_minimize(self) -> Option<(Input, ControllerMinimizeResponder)>

pub fn into_cleanse(self) -> Option<(Input, ControllerCleanseResponder)>

pub fn into_merge(self) -> Option<ControllerMergeResponder>

pub fn into_get_status(self) -> Option<ControllerGetStatusResponder>

pub fn into_watch_artifact(self) -> Option<ControllerWatchArtifactResponder>

pub fn method_name(&self) -> &'static str

Name of the method defined in FIDL

Trait Implementations

impl Debug for ControllerRequest

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

Formats the value using the given formatter.