Fuzzinator Core: package fuzzinator

class fuzzinator.Controller(config)

Fuzzinator’s main controller that orchestrates a fuzz session by scheduling all related activities (e.g., keeps SUTs up-to-date, runs fuzzers and feeds test cases to SUTs, or minimizes failure inducing test cases). All configuration options of the framework must be encapsulated in a configparser.ConfigParser object.

The following config sections and options are recognized:

• Section fuzzinator: Global settings of the framework.

  • Option work_dir: Pattern of work directory for temporary files, which may contain the substring {uid} as a placeholder for a unique string (replaced by the framework). (Optional, default: ~/.fuzzinator/{uid})

  • Option db_uri: URI to a MongoDB database to store found issues and execution statistics. (Optional, default: mongodb://localhost/fuzzinator)

  • Option db_server_selection_timeout: Controls how long the database driver will wait to find an available server (in milliseconds). (Optional, default: 30000)

  • Option cost_budget: (Optional, default: number of cpus)

  • Option validate_after_update: Boolean to enable the validation of valid issues of all SUTs after their update. (Optional, default: False)

• Sections sut.NAME: Definitions of a SUT named NAME

  • Option call: Fully qualified name of a callable context manager class. When an instance of the class is called, it must accept a test keyword argument representing the input to the SUT and must return a dictionary object if the input triggered an issue in the SUT, or a value considered false otherwise (which can be a simple None, but can also be a NonIssue in complex cases). The returned issue dictionary (if any) should contain an 'id' field that equals for issues that are not considered unique. (Mandatory)

    See package fuzzinator.call for potential SUT calls.

  • Option cost: (Optional, default: 1)

  • Option validate_call: Fully qualified name of a callable context manager class that acts as the SUT’s call option during test case validation. (Optional, default: the value of option call)

    See package fuzzinator.call for potential SUT calls.

  • Option validate_cost: (Optional, default: the value of option cost)

  • Option reduce: Fully qualified name of a callable class. When an instance of the class is called, it must accept issue, sut_call, on_job_progressed keyword arguments representing an issue to be reduced, and must return a tuple consisting of a reduced test case for the issue (or None if the issue’s current test case could not be reduced) and a (potentially empty) list of new issues that were discovered during test case reduction (if any). (Optional, no reduction for this SUT if option is missing.)

    See package fuzzinator.reduce for potential reducers.

  • Option reduce_call: Fully qualified name of a callable context manager class that acts as the SUT’s call option during test case reduction. (Optional, default: the value of option validate_call if defined, otherwise the value of option call)

    See package fuzzinator.call for potential SUT calls.

  • Option reduce_cost: (Optional, default: the value of option cost)

  • Option update_condition: Fully qualified name of a callable class. When an instance of the class is called, it must return True if and only if the SUT should be updated. (Optional, SUT is never updated automatically if option is missing.)

    See package fuzzinator.update for potential update conditions.

  • Option update: Fully qualified name of a callable class. When an instance of the class is called, it should perform the update of the SUT. (Optional, SUT is never updated if option is missing.)

    See package fuzzinator.update for potential updaters.

  • Option update_cost: (Optional, default: the value of option fuzzinator:cost_budget)

  • Option validate_after_update: Boolean to enable the validation of the valid issues of the SUT after its update. (Optional, default: the value of option fuzzinator:validate_after_update)

  • Option formatter: Fully qualified name of a callable class. When an instance of the class is called, it must format the issue dictionary of the SUT by returning a custom string representation. It must accept an issue keyword argument representing an issue to be formatted. The class must also contain a method named summary, also accepting an issue keyword argument, which should return a summary description (preferably a single line of text). (Optional, default: fuzzinator.formatter.JsonFormatter.)

    See package fuzzinator.formatter for further potential formatters.

  • Options tui_formatter, wui_formatter, and email_formatter: Fully qualified name of a callable class that formats the issue dictionary of the SUT to display it in the TUI issue viewer, on the WUI issue page, or to insert it into an e-mail notification. (Optional, default: the value of option formatter)

    See package fuzzinator.formatter for potential formatters.

  • Option exporter: Fully qualified name of a callable class. When an instance of the class is called, it must export the issue dictionary in a custom SUT-specific format. It must accept an issue keyword argument representing the issue to be exported and its result must be writable to a file, i.e., it must be either a string or a byte array. The export format does not necessarily have to contain all elements of the issue dictionary (e.g., it is often useful to only extract the test input that triggered the issue). (Optional, no custom export for this SUT if option is missing.)

    See package fuzzinator.exporter for potential exporters.

  • Option tracker: Fully qualified name of a class that can report issues to an external issue tracker. (Optional, no reporting to tracker if option is missing.)

    See package fuzzinator.tracker for potential trackers.

• Sections fuzz.NAME: Definitions of a fuzz job named NAME

  • Option sut: Name of the SUT that describes the subject of this fuzz job. (Mandatory)

  • Option fuzzer: Fully qualified name of a callable context manager class. When an instance of the class is called, it must accept an index keyword argument representing a running counter in the fuzz job and must return a test input (or None, which signals that the fuzzer is “exhausted” and cannot generate more test cases in this fuzz job). The semantics of the generated test input is not restricted by the framework, it is up to the configuration to ensure that the SUT of the fuzz job can deal with the tests generated by the fuzzer of the fuzz job. (Mandatory)

    See package fuzzinator.fuzzer for potential fuzzers.

  • Option batch: Number of times the fuzzer is requested to generate a new test for the SUT. (Optional, default: 1)

  • Option instances: Number of instances of this fuzz job allowed to run in parallel. (Optional, default: inf)

  • Option refresh: Statistics update frequency in terms of executed test cases. (Optional, default: batch size)

• Section listeners: Definitions of custom event listeners. This section is optional.

  • Options OPT: Fully qualified name of a class that executes custom actions for selected events.

  See package fuzzinator.listener for potential listeners.

• For classes referenced in options with their fully qualified name, constructor keyword arguments can be given. These arguments have to be specified in sections (sut|fuzz).NAME.OPT with appropriate names.

• All classes can be decorated according to python semantics. The decorators must be callable classes and have to be specified in options OPT.decorate(N) with fully qualified name. Multiple decorators can be applied to a class OPT, their order is specified by an integer index in parentheses. Keyword arguments to be passed to the decorators have to be listed in sections (sut|fuzz).NAME.OPT.decorate(N).

  See packages fuzzinator.call and fuzzinator.fuzzer for potential decorators.

• The constructors of all classes (including decorators) can have a work_dir keyword argument. If present, its value is not filled in from the corresponding section but provided by the framework with a unique path under fuzzinator:work_dir.

Parameters:

config (ConfigParser) – the configuration options of the fuzz session.

Variables:

listener (ListenerManager) – a listener manager object that is called on various events during the fuzz session.

run(*, max_cycles=None, validate=None, reduce=None)

Start the fuzz session.

Parameters:

• max_cycles (int) – maximum number to iterate through the fuzz jobs defined in the configuration (defaults to inf).

• validate (str) – name of SUT to validate issues of at the start of the fuzz session (the empty string denotes all SUTs; defaults to no SUT).

• reduce (str) – name of SUT to reduce issues of at the start of the fuzz session (the empty string denotes all SUTs; defaults to no SUT).