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)
- Option
Sections
sut.NAME
: Definitions of a SUT named NAMEOption
call
: Fully qualified name of a python callable that 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, orNone
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 acceptissue
,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 (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 callables.Option
reduce_call
: Fully qualified name of a python callable that acts as the SUT’scall
option during test case reduction. (Optional, default: the value of optioncall
)See package
fuzzinator.call
for potential callables.Option
reduce_cost
: (Optional, default: the value of optioncost
)Option
update_condition
: Fully qualified name of a python callable that must returnTrue
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 NAMEOption
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 andindex
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 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 callableOPT
, 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.
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.
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:
-
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:
-
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.
-
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.
-