class Controller

Defined at line 9260 of file fidling/gen/src/sys/fuzzing/fidl/fuchsia.fuzzer/hlcpp/fuchsia/fuzzer/cpp/fidl.h

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.

Public Methods

void ~Controller ()

void Configure (::fuchsia::fuzzer::Options options, ConfigureCallback callback)

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.

void GetOptions (GetOptionsCallback callback)

Gets the current values for the various execution and error detection

parameters.

- response `options` the execution and error detection parameters.

void AddToCorpus (::fuchsia::fuzzer::Corpus corpus, ::fuchsia::fuzzer::Input input, AddToCorpusCallback callback)

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.

void ReadCorpus (::fuchsia::fuzzer::Corpus corpus, ::fidl::InterfaceHandle< ::fuchsia::fuzzer::CorpusReader> corpus_reader, ReadCorpusCallback callback)

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.

void WriteDictionary (::fuchsia::fuzzer::Input dictionary, WriteDictionaryCallback callback)

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.

void ReadDictionary (ReadDictionaryCallback callback)

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

- response `dictionary` the current AFL-style dictionary.

void AddMonitor (::fidl::InterfaceHandle< ::fuchsia::fuzzer::Monitor> monitor, AddMonitorCallback callback)

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

`GetStatus`.

+ request `monitor` the client used to send status updates.

void Fuzz (FuzzCallback callback)

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.

void TryOne (::fuchsia::fuzzer::Input test_input, TryOneCallback callback)

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.

void Minimize (::fuchsia::fuzzer::Input test_input, MinimizeCallback callback)

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.

void Cleanse (::fuchsia::fuzzer::Input test_input, CleanseCallback callback)

Attempts to replace bytes of the given `test_input` with "filler" bytes,

e.g.

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

void Merge (MergeCallback callback)

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.

void GetStatus (GetStatusCallback callback)

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

- response `status` the current value of fuzzing metrics.

void WatchArtifact (WatchArtifactCallback callback)

Returns the results of a long-running workflow.

This method uses the

["hanging get" pattern](https://fuchsia.dev/fuchsia-src/development/api/fidl#hanging-get).

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.