Fuzzinator Core: package fuzzinator

class Controller

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: Work directory for temporary files. (Optional, default: ~/.fuzzinator)
    • Option db_uri: URI to a MongoDB database to store found issues and execution statistics. (Optional, default: mongodb://localhost/fuzzinator)
    • Option cost_budget: (Optional, default: number of cpus)

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

    • Option call: Fully qualified name of a python callable that 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 None otherwise. 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 callables.

    • Option cost: (Optional, default: 1)

    • Option reduce: Fully qualified name of a python callable that must accept issue, sut_call, sut_call_kwargs, listener, ident, work_dir keyword arguments representing an issue to be reduced (and various other potentially needed objects), 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 callables.

    • Option reduce_call: Fully qualified name of a python callable that acts as the SUT’s call option during test case reduction. (Optional, default: the value of option call)

      See package fuzzinator.call for potential callables.

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

    • Option update_condition: Fully qualified name of a python callable that must return True if and only if the SUT should be updated. (Optional, SUT is never updated if option is missing.)

      See package fuzzinator.update for potential callables.

    • Option update: Fully qualified name of a python callable that should perform the update of the SUT. (Optional, SUT is never updated if option is missing.)

      See package fuzzinator.update for potential callables.

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

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

    • Option fuzzer: Fully qualified name of a python callable that must accept and 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 callables.

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

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

  • Callable options can be implemented as functions or classes with __call__ method (the latter are instantiated first to get a callable object). Both constructor calls (if any) and the “real” calls can be given keyword arguments. These arguments have to be specified in sections (sut|fuzz).NAME.OPT[.init] with appropriate names (where the .init sections stand for the constructor arguments).

  • All callables can be decorated according to python semantics. The decorators must be callable classes themselves and have to be specified in options OPT.decorate(N) with fully qualified name. Multiple decorators can be applied to a callable 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.

Parameters:config (configparser.ConfigParser) – the configuration options of the fuzz session.
Variables:listener (fuzzinator.ListenerManager) – a listener manager object that is called on various events during the fuzz session.
run(*, max_cycles=None)

Start the fuzz session.

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

class EmailListener

class fuzzinator.EmailListener(event, param_name, from_address, to_address, subject, content, smtp_host, smtp_port)

EventListener subclass that can be used to send e-mail notification about various events.

Parameters:
  • event – The name of the event to send notification about.
  • param_name – The name of the event’s parameter containing the information to send.
  • from_address – E-mail address to send notifications from.
  • to_address – Target e-mail address to send the notification to.
  • subject – Subject of the e-mail (it may contain placeholders, that will be filled by parameter information).
  • content – Content of the e-mail (it may contain placeholders, that will be filled by parameter information).
  • smtp_host – Host of the smtp server to send e-mails from.
  • smtp_port – Port of the smtp server to send e-mails from.
send_mail(data)

Send e-mail with the provided data.

Parameters:data – Information to fill subject and content fields with.

class EventListener

class fuzzinator.EventListener

A no-op base class for listeners that can get notified by fuzzinator.Controller on various events of a fuzz sessions.

Note

Subclasses should be aware that some notification methods may be called from subprocesses.

activate_job(ident)

Invoked when a previously instantiated job is activated (started).

Parameters:ident (int) – unique identifier of the activated job.
invalid_issue(issue)

Invoked when an issue seems invalid.

Parameters:issue (dict) – the issue object that did not pass re-validation (listener is free to decide how to react, an option is to remove the issue from the database).
job_progress(ident, progress)

Invoked when an activated job makes progress.

Parameters:
  • ident (int) – unique identifier of the progressing job.
  • progress (int) – for fuzz jobs, this is the number of already generated tests (number between 0 and the job’s batch size); for reduce jobs, this is the current size of the test case being reduced (number between the original test size and 0).
new_fuzz_job(ident, fuzzer, sut, cost, batch)

Invoked when a new (still inactive) fuzz job is instantiated.

Parameters:
  • ident (int) – a unique identifier of the new fuzz job.
  • fuzzer (str) – short name of the new fuzz job (name of the corresponding config section without the “fuzz.” prefix).
  • sut (str) – short name of the SUT of the new fuzz job (name of the corresponding config section without the “sut.” prefix).
  • cost (int) – cost associated with the new fuzz job.
  • batch (int, float) – batch size of the new fuzz job, i.e., number of test cases requested from the fuzzer (may be inf).
new_issue(issue)

Invoked when a new issue is found.

Parameters:issue (dict) – the issue that was found (all relevant information - e.g., the SUT that reported the issue, the test case that triggered the issue, the fuzzer that generated the test case, the ID of the issue - is stored in appropriate properties of the issue).
new_reduce_job(ident, sut, cost, issue_id, size)

Invoked when a new (still inactive) reduce job is instantiated.

Parameters:
  • ident (int) – a unique identifier of the new reduce job.
  • sut (str) – short name of the SUT used in the new reduce job (name of the corresponding config section without the “sut.” prefix).
  • cost (int) – cost associated with the new reduce job.
  • issue_id (Any) – 'id' property of the issue to be reduced.
  • size (int) – size of the test case associated with the issue to be reduced.
new_update_job(ident, sut)

Invoked when a new (still inactive) update job is instantiated.

Parameters:
  • ident (int) – a unique identifier of the new update job.
  • sut (str) – short name of the SUT to be updated (name of the corresponding config section without the “sut.” prefix).
remove_job(ident)

Invoked when an active job has finished.

Parameters:ident (int) – unique identifier of the finished job.
update_fuzz_stat()

Invoked when statistics about fuzzers, SUTs, and issues (e.g., execution counts, crash counts, unique issue counts) are updated in the framework’s database.

update_issue(issue)

Invoked when the status of an issue changed.

Parameters:issue (dict) – the issue object that has changed.
update_load(load)

Invoked when the framework’s load changes.

Parameters:load (int) – number between 0 and controller’s capacity.
warning(msg)

Invoked on unexpected events.

Parameters:msg (str) – a string representation of the problem.

class ListenerManager

class fuzzinator.ListenerManager(listeners=None)

Class that registers listeners to various events and executes all of them when the event has triggered.

Parameters:listeners – List of listener objects.
add(listener)

Register a new listener in the manager.

Parameters:listener – The new listener to register.