pub enum ControllerRequest {
Show 14 variants 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, },
}
Expand description

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

Fields

§options: Options

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.
§

GetOptions

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

  • response options the execution and error detection parameters.
§

AddToCorpus

Fields

§corpus: Corpus
§input: Input

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.
§

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.
§

WriteDictionary

Fields

§dictionary: Input

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.
§

ReadDictionary

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

  • response dictionary the current AFL-style dictionary.
§

AddMonitor

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

  • request monitor the client used to send status updates.
§

Fuzz

Fields

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.
§

TryOne

Fields

§test_input: Input

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.
§

Minimize

Fields

§test_input: Input

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.
§

Cleanse

Fields

§test_input: Input

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.
§

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.
§

GetStatus

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

  • response status the current value of fuzzing metrics.
§

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.

Implementations§

Trait Implementations§

source§

impl Debug for ControllerRequest

source§

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

Formats the value using the given formatter. Read more

Auto Trait Implementations§

Blanket Implementations§

source§

impl<T> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> Encode<Ambiguous1> for T

source§

unsafe fn encode( self, _encoder: &mut Encoder<'_>, _offset: usize, _depth: Depth ) -> Result<(), Error>

Encodes the object into the encoder’s buffers. Any handles stored in the object are swapped for Handle::INVALID. Read more
source§

impl<T> Encode<Ambiguous2> for T

source§

unsafe fn encode( self, _encoder: &mut Encoder<'_>, _offset: usize, _depth: Depth ) -> Result<(), Error>

Encodes the object into the encoder’s buffers. Any handles stored in the object are swapped for Handle::INVALID. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

§

impl<T> Instrument for T

§

fn instrument(self, span: Span) -> Instrumented<Self>

Instruments this type with the provided [Span], returning an Instrumented wrapper. Read more
§

fn in_current_span(self) -> Instrumented<Self>

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
source§

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

§

impl<T> Pointable for T

§

const ALIGN: usize = _

The alignment of pointer.
§

type Init = T

The type for initializers.
§

unsafe fn init(init: <T as Pointable>::Init) -> usize

Initializes a with the given initializer. Read more
§

unsafe fn deref<'a>(ptr: usize) -> &'a T

Dereferences the given pointer. Read more
§

unsafe fn deref_mut<'a>(ptr: usize) -> &'a mut T

Mutably dereferences the given pointer. Read more
§

unsafe fn drop(ptr: usize)

Drops the object pointed to by the given pointer. Read more
source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
§

impl<T> WithSubscriber for T

§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a [WithDispatch] wrapper. Read more
§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a [WithDispatch] wrapper. Read more