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 NAMEOption
call
: Fully qualified name of a callable context manager class. When an instance of the class is called, it must accept atest
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 simpleNone
, but can also be aNonIssue
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’scall
option during test case validation. (Optional, default: the value of optioncall
)See package
fuzzinator.call
for potential SUT calls.Option
validate_cost
: (Optional, default: the value of optioncost
)Option
reduce
: Fully qualified name of a callable class. When an instance of the class is called, it must acceptissue
,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 (orNone
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’scall
option during test case reduction. (Optional, default: the value of optionvalidate_call
if defined, otherwise the value of optioncall
)See package
fuzzinator.call
for potential SUT calls.Option
reduce_cost
: (Optional, default: the value of optioncost
)Option
update_condition
: Fully qualified name of a callable class. When an instance of the class is called, it must returnTrue
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 optionfuzzinator: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 optionfuzzinator: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 anissue
keyword argument representing an issue to be formatted. The class must also contain a method namedsummary
, also accepting anissue
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
, andemail_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 optionformatter
)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 anissue
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 NAMEOption
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 anindex
keyword argument representing a running counter in the fuzz job and must return a test input (orNone
, 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 classOPT
, 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
andfuzzinator.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 underfuzzinator: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).