Logging

Boofuzz provides flexible logging. All logging classes implement IFuzzLogger. Built-in logging classes are detailed below.

To use multiple loggers at once, see FuzzLogger.

Logging Interface (IFuzzLogger)

class boofuzz.IFuzzLogger[source]

Bases: object

Abstract class for logging fuzz data.

Usage while testing:

Open test case.
Open test step.
Use other log methods.

IFuzzLogger provides the logging interface for the Sulley framework and test writers.

The methods provided are meant to mirror functional test actions. Instead of generic debug/info/warning methods, IFuzzLogger provides a means for logging test cases, passes, failures, test steps, etc.

This hypothetical sample output gives an idea of how the logger should be used:

Test Case: UDP.Header.Address 3300

Test Step: Fuzzing: Send: 45 00 13 ab 00 01 40 00 40 11 c9 …
Test Step: Process monitor check: Check OK
Test Step: DNP Check: Send: ff ff ff ff ff ff 00 0c 29 d1 10 … Recv: 00 0c 29 d1 10 81 00 30 a7 05 6e … Check: Reply is as expected. Check OK

Test Case: UDP.Header.Address 3301

Test Step: Fuzzing: Send: 45 00 13 ab 00 01 40 00 40 11 c9 …
Test Step: Process monitor check: Check Failed: “Process returned exit code 1”
Test Step: DNP Check: Send: ff ff ff ff ff ff 00 0c 29 d1 10 … Recv: None Check: Reply is as expected. Check Failed

A test case is opened for each fuzzing case. A test step is opened for each high-level test step. Test steps can include, for example:

Fuzzing
Set up (pre-fuzzing)
Post-test cleanup
Instrumentation checks
Reset due to failure

Within a test step, a test may log data sent, data received, checks, check results, and other information.

abstract close_test()[source]

Called after a test has been completed. Can be used to inform the operator or save the test log.

Param:: None
Type:: None
Returns:: None
Return type:: None

abstract close_test_case()[source]

Called after a test case has been completed. Can be used to inform the operator or save the test case log.

Param:: None
Type:: None
Returns:: None
Return type:: None

abstract log_check(description)[source]

Records a check on the system under test. AKA “instrumentation check.”

Parameters:: description (str) – Received data.
Returns:: None
Return type:: None

abstract log_error(description)[source]

Records an internal error. This informs the operaor that the test was not completed successfully.

Parameters:: description (str) – Received data.
Returns:: None
Return type:: None

abstract log_fail(description='')[source]

Records a check that failed. This will flag a fuzzing case as a potential bug or anomaly.

Parameters:: description (str) – Optional supplementary data.
Returns:: None
Return type:: None

abstract log_info(description)[source]

Catch-all method for logging test information

Parameters:: description (str) – Information.
Returns:: None
Return type:: None

abstract log_pass(description='')[source]

Records a check that passed.

Parameters:: description (str) – Optional supplementary data..
Returns:: None
Return type:: None

abstract log_recv(data)[source]

Records data as having been received from the target.

Parameters:: data (bytes) – Received data.
Returns:: None
Return type:: None

abstract log_send(data)[source]

Records data as about to be sent to the target.

Parameters:: data (bytes) – Transmitted data
Returns:: None
Return type:: None

abstract open_test_case(test_case_id, name, index, *args, **kwargs)[source]

Open a test case - i.e., a fuzzing mutation.

Parameters:

test_case_id – Test case name/number. Should be unique.
name (str) – Human readable and unique name for test case.
index (int) – Numeric index for test case

Returns:

None

abstract open_test_step(description)[source]

Open a test step - e.g., “Fuzzing”, “Pre-fuzz”, “Response Check.”

Parameters:: description – Description of fuzzing step.
Returns:: None

boofuzz.IFuzzLoggerBackend: alias of IFuzzLogger

Text Logging

class boofuzz.FuzzLoggerText(file_handle=<colorama.ansitowin32.StreamWrapper object>, bytes_to_str=<function hex_to_hexstr>)[source]

Bases: IFuzzLogger

This class formats FuzzLogger data for text presentation. It can be configured to output to STDOUT, or to a named file.

Using two FuzzLoggerTexts, a FuzzLogger instance can be configured to output to both console and file.

INDENT_SIZE = 2

close_test()[source]

Called after a test has been completed. Can be used to inform the operator or save the test log.

Param:: None
Type:: None
Returns:: None
Return type:: None

close_test_case()[source]

Called after a test case has been completed. Can be used to inform the operator or save the test case log.

Param:: None
Type:: None
Returns:: None
Return type:: None

log_check(description)[source]

Records a check on the system under test. AKA “instrumentation check.”

Parameters:: description (str) – Received data.
Returns:: None
Return type:: None

log_error(description)[source]

Records an internal error. This informs the operaor that the test was not completed successfully.

Parameters:: description (str) – Received data.
Returns:: None
Return type:: None

log_fail(description='')[source]

Records a check that failed. This will flag a fuzzing case as a potential bug or anomaly.

Parameters:: description (str) – Optional supplementary data.
Returns:: None
Return type:: None

log_info(description)[source]

Catch-all method for logging test information

Parameters:: description (str) – Information.
Returns:: None
Return type:: None

log_pass(description='')[source]

Records a check that passed.

Parameters:: description (str) – Optional supplementary data..
Returns:: None
Return type:: None

log_recv(data)[source]

Records data as having been received from the target.

Parameters:: data (bytes) – Received data.
Returns:: None
Return type:: None

log_send(data)[source]

Records data as about to be sent to the target.

Parameters:: data (bytes) – Transmitted data
Returns:: None
Return type:: None

open_test_case(test_case_id, name, index, *args, **kwargs)[source]

Open a test case - i.e., a fuzzing mutation.

Parameters:

test_case_id – Test case name/number. Should be unique.
name (str) – Human readable and unique name for test case.
index (int) – Numeric index for test case

Returns:

None

open_test_step(description)[source]

Open a test step - e.g., “Fuzzing”, “Pre-fuzz”, “Response Check.”

Parameters:: description – Description of fuzzing step.
Returns:: None

CSV Logging

class boofuzz.FuzzLoggerCsv(file_handle=<colorama.ansitowin32.StreamWrapper object>, bytes_to_str=<function hex_to_hexstr>)[source]

Bases: IFuzzLogger

This class formats FuzzLogger data for pcap file. It can be configured to output to a named file.

close_test()[source]

Called after a test has been completed. Can be used to inform the operator or save the test log.

Param:: None
Type:: None
Returns:: None
Return type:: None

close_test_case()[source]

Called after a test case has been completed. Can be used to inform the operator or save the test case log.

Param:: None
Type:: None
Returns:: None
Return type:: None

log_check(description)[source]

Records a check on the system under test. AKA “instrumentation check.”

Parameters:: description (str) – Received data.
Returns:: None
Return type:: None

log_error(description)[source]

Records an internal error. This informs the operaor that the test was not completed successfully.

Parameters:: description (str) – Received data.
Returns:: None
Return type:: None

log_fail(description='')[source]

Records a check that failed. This will flag a fuzzing case as a potential bug or anomaly.

Parameters:: description (str) – Optional supplementary data.
Returns:: None
Return type:: None

log_info(description)[source]

Catch-all method for logging test information

Parameters:: description (str) – Information.
Returns:: None
Return type:: None

log_pass(description='')[source]

Records a check that passed.

Parameters:: description (str) – Optional supplementary data..
Returns:: None
Return type:: None

log_recv(data)[source]

Records data as having been received from the target.

Parameters:: data (bytes) – Received data.
Returns:: None
Return type:: None

log_send(data)[source]

Records data as about to be sent to the target.

Parameters:: data (bytes) – Transmitted data
Returns:: None
Return type:: None

open_test_case(test_case_id, name, index, *args, **kwargs)[source]

Open a test case - i.e., a fuzzing mutation.

Parameters:

test_case_id – Test case name/number. Should be unique.
name (str) – Human readable and unique name for test case.
index (int) – Numeric index for test case

Returns:

None

open_test_step(description)[source]

Open a test step - e.g., “Fuzzing”, “Pre-fuzz”, “Response Check.”

Parameters:: description – Description of fuzzing step.
Returns:: None

Console-GUI Logging

class boofuzz.FuzzLoggerCurses(web_port=26000, web_address='localhost', window_height=40, window_width=130, auto_scroll=True, max_log_lines=500, wait_on_quit=True, min_refresh_rate=1000, bytes_to_str=<function hex_to_hexstr>)[source]

Bases: IFuzzLogger

This class formats FuzzLogger data for a console GUI using curses. This hasn’t been tested on Windows.

INDENT_SIZE = 2

close_test()[source]

Called after a test has been completed. Can be used to inform the operator or save the test log.

Param:: None
Type:: None
Returns:: None
Return type:: None

close_test_case()[source]

Called after a test case has been completed. Can be used to inform the operator or save the test case log.

Param:: None
Type:: None
Returns:: None
Return type:: None

log_check(description)[source]

Records a check on the system under test. AKA “instrumentation check.”

Parameters:: description (str) – Received data.
Returns:: None
Return type:: None

log_error(description='', indent_size=2)[source]

Records an internal error. This informs the operaor that the test was not completed successfully.

Parameters:: description (str) – Received data.
Returns:: None
Return type:: None

log_fail(description='', indent_size=2)[source]

Records a check that failed. This will flag a fuzzing case as a potential bug or anomaly.

Parameters:: description (str) – Optional supplementary data.
Returns:: None
Return type:: None

log_info(description)[source]

Catch-all method for logging test information

Parameters:: description (str) – Information.
Returns:: None
Return type:: None

log_pass(description='')[source]

Records a check that passed.

Parameters:: description (str) – Optional supplementary data..
Returns:: None
Return type:: None

log_recv(data)[source]

Records data as having been received from the target.

Parameters:: data (bytes) – Received data.
Returns:: None
Return type:: None

log_send(data)[source]

Records data as about to be sent to the target.

Parameters:: data (bytes) – Transmitted data
Returns:: None
Return type:: None

open_test_case(test_case_id, name, index, *args, **kwargs)[source]

Open a test case - i.e., a fuzzing mutation.

Parameters:

test_case_id – Test case name/number. Should be unique.
name (str) – Human readable and unique name for test case.
index (int) – Numeric index for test case

Returns:

None

open_test_step(description)[source]

Open a test step - e.g., “Fuzzing”, “Pre-fuzz”, “Response Check.”

Parameters:: description – Description of fuzzing step.
Returns:: None

FuzzLogger Object

class boofuzz.FuzzLogger(fuzz_loggers=None)[source]

Bases: IFuzzLogger

Takes a list of IFuzzLogger objects and multiplexes logged data to each one.

FuzzLogger also maintains summary failure and error data.

Parameters:: fuzz_loggers (list of IFuzzLogger) – IFuzzLogger objects to which to send log data.

close_test()[source]

Called after a test has been completed. Can be used to inform the operator or save the test log.

Param:: None
Type:: None
Returns:: None
Return type:: None

close_test_case()[source]

Called after a test case has been completed. Can be used to inform the operator or save the test case log.

Param:: None
Type:: None
Returns:: None
Return type:: None

failure_summary()[source]

Return test summary string based on fuzz logger results.

Returns:: Test summary string, may be multi-line.

log_check(description)[source]

Records a check on the system under test. AKA “instrumentation check.”

Parameters:: description (str) – Received data.
Returns:: None
Return type:: None

log_error(description)[source]

Records an internal error. This informs the operaor that the test was not completed successfully.

Parameters:: description (str) – Received data.
Returns:: None
Return type:: None

log_fail(description='')[source]

Records a check that failed. This will flag a fuzzing case as a potential bug or anomaly.

Parameters:: description (str) – Optional supplementary data.
Returns:: None
Return type:: None

log_info(description)[source]

Catch-all method for logging test information

Parameters:: description (str) – Information.
Returns:: None
Return type:: None

log_pass(description='')[source]

Records a check that passed.

Parameters:: description (str) – Optional supplementary data..
Returns:: None
Return type:: None

log_recv(data)[source]

Records data as having been received from the target.

Parameters:: data (bytes) – Received data.
Returns:: None
Return type:: None

log_send(data)[source]

Records data as about to be sent to the target.

Parameters:: data (bytes) – Transmitted data
Returns:: None
Return type:: None

property most_recent_test_id: Return a value (e.g. string) representing the most recent test case.

open_test_case(test_case_id, name, index, *args, **kwargs)[source]

Open a test case - i.e., a fuzzing mutation.

Parameters:

test_case_id – Test case name/number. Should be unique.
name (str) – Human readable and unique name for test case.
index (int) – Numeric index for test case

Returns:

None

open_test_step(description)[source]

Open a test step - e.g., “Fuzzing”, “Pre-fuzz”, “Response Check.”

Parameters:: description – Description of fuzzing step.
Returns:: None