src/sys/fuzzing/fidl/options.fidl

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

library fuchsia.fuzzer;

using zx;

/// Maximum length of a sanitizer options environment variable name.
///
/// `sanitizer_options.name` must be something like "...SAN_OPTIONS". The longest name currently
/// supported on Fuchsia is "UBSAN_OPTIONS". The longest currently supported on any platform is
/// "HWASAN_OPTIONS".
const MAX_SANITIZER_OPTIONS_NAME_SIZE uint16 = 32;

/// Maximum length of a sanitizer options environment variable value.
///
/// `sanitizer_options.value` is a concatenation of "<key>=<value>" pairs delimited by ':'.
/// AddressSanitizer currently has the most flags, with ~40 sanitizer specific ones and ~70 common
/// ones. Most of these are either boolean values or short integers. The only long types of flags
/// are paths, but none these of these are supported on Fuchsia.
const MAX_SANITIZER_OPTIONS_VALUE_SIZE uint16 = 8192;

/// Corresponds to sanitizer enviroment variables.
///
/// The options are ignored unless `name` must end in "...SAN_OPTIONS", e.g. "ASAN_OPTIONS".
/// `value` should be a ':'-delimited list of options, e.g. "verbosity=1:malloc_context_size=20".
///
/// For more details, see the following:
///   * https://github.com/google/sanitizers/wiki/SanitizerCommonFlags
///   * https://github.com/google/sanitizers/wiki/AddressSanitizerFlags
type SanitizerOptions = struct {
    name string:MAX_SANITIZER_OPTIONS_NAME_SIZE;
    value string:MAX_SANITIZER_OPTIONS_VALUE_SIZE;
};

/// See `fuchsia.fuzzer.Controller/Configure`.
type Options = table {
    /// Perform this many fuzzing runs, then exit normally. If unset (or zero), fuzz indefinitely.
    1: runs uint32;

    /// If non-zero, fuzz for this duration and then exit normally. If zero, fuzz indefinitely.
    /// Defaults to 0.
    2: max_total_time zx.duration;

    // PRNG seed to use when generating inputs. The same seed for the same target should produce the
    // same inputs. If zero, the current ticks will be used. Defaults to 0.
    3: seed uint32;

    /// If non-zero, limit the maximum size of a test input to this size, in bytes. Use 0 to disable
    /// the limit. Defaults to 1 MB.
    4: max_input_size uint64;

    // Maximum number of consecutive mutations to apply to an input. Defaults to 5.
    5: mutation_depth uint16;

    /// If an AFL-style dictionary is supplied using |Controller.WriteDictionary|, include words up
    /// to this level. Defaults to 0, i.e. words without an explicit level.
    6: dictionary_level uint16;

    /// If true, treat instrumented process exits as fuzzing errors. Defaults to false.
    7: detect_exits bool;

    /// If true, and ASan or LSan are available, try to detect memory leaks. Defaults to false.
    /// Leak detection can be expensive, so it is recommended to first develop a corpus that covers
    /// a reasonable amount of the code under test before attempting to detect leaks.
    8: detect_leaks bool;

    /// If non-zero, any run that takes longer than this duration will raise a TIMEOUT error.
    /// Use 0 to disable the limit. Defaults to 20 minutes.
    9: run_limit zx.duration;

    /// If non-zero, any allocation over this size in bytes will raise a BAD_MALLOC error. Use 0 to
    /// disable the limit. Defaults to 2 GB.
   10: malloc_limit uint64;

    /// If non-zero, any process that uses more than this amount of memory in bytes will raise an
    /// OOM error. Use 0 to disable the limit. Defaults to 2 GB.
   11: oom_limit uint64;

    /// If non-zero, purge the sanitizer's allocator quarantine and reclaim memory periodically
    /// between runs after an interval of this many seconds. Use 0 to disable allocator purging.
    /// Default to 1.
   12: purge_interval zx.duration;

    /// Exit code used by the instrumented process if it encounters a bad allocation. Set this
    /// if the target already uses the default for another reason. Defaults to 2000.
   13: malloc_exitcode int32;

    /// Exit code used by the instrumented process if it encounters a sanitizer error. Set this
    /// if the target already uses the default for another reason. Defaults to 2001.
   14: death_exitcode int32;

    /// Exit code used by the instrumented process if it encounters a leak. Set this if the target
    /// already uses the default for another reason. Defaults to 2002.
   15: leak_exitcode int32;

    /// Exit code used by the instrumented process if it exceeds the OOM limit. Set this if the
    /// target already uses the default for another reason. Defaults to 2003.
   16: oom_exitcode int32;

    /// If non-zero, the engine will periodically update any added monitors after this duration.
    /// Defaults to 20.
   17: pulse_interval zx.duration;

    /// If true, allow a debugger like `zxdb` to be attached to an instrumented process. This may
    /// interfere with the engine's ability to detect exceptions and is not recommended when
    /// fuzzing. It can be useful when reproducing an error with a known error-causing input.
    /// Defaults to false.
   18: debug bool;

    /// If true, include ClusterFuzz-compatible final statistics in the output of a call to
    /// `fuchsia.fuzzer.Controller/Fuzz`.
   19: print_final_stats bool;

    /// If true, also use data flow traces as part of the fuzzing coverage data. See
    /// https://clang.llvm.org/docs/SanitizerCoverage.html#tracing-data-flow for more details.
   20: use_value_profile bool;

    /// Sanitizer options. See `SanitizerOptions`.
   21: sanitizer_options SanitizerOptions;
};