| // 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; |
| }; |
| |
| /// Specifies how a fuzzing engine should configure output streams. |
| /// |
| /// Flags may be combined, e.g. `CLOSE_STDOUT | CLOSE_STDERR`. Support for each |
| /// flag is engine-specific. Specifying an unsupported output mode flag may |
| /// cause `Controller.Configure` to return `ZX_ERR_NOT_SUPPORTED`. |
| type OutputFlags = strict bits { |
| /// Suppress standard output from the engine process. This is analogous to |
| /// libFuzzer's `-close_fd_mask=1`. |
| CLOSE_STDOUT = 0x1; |
| |
| /// Suppress standard error from the engine process. Use with care: this may |
| /// remove diagnostic output from the target code (e.g. messages on assert |
| /// failure). This is analogous to libFuzzer's `-close_fd_mask=2`. |
| CLOSE_STDERR = 0x2; |
| |
| /// Produce more verbose output from the fuzzer engine. The exact meaning of |
| /// "more verbose" is engine-specific. This is analogous to libFuzzer's |
| /// `-verbosity=2`. |
| VERBOSE = 0x4; |
| |
| /// Produce libFuzzer-style output on standard error. This facilitates |
| /// integration with systems like ClusterFuzz. |
| /// See https://llvm.org/docs/LibFuzzer.html#output for example output. |
| LIBFUZZER = 0x8; |
| }; |
| |
| /// 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. Defaults to 1 second. |
| 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 seconds. |
| 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/WatchArtifact`. |
| 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; |
| |
| /// Output flags. See `OutputFlags`. |
| 22: output_flags OutputFlags; |
| }; |