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:
  1. Open test case.

  2. Open test step.

  3. 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 boofuzz.ifuzz_logger.IFuzzLogger

Text Logging

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

Bases: boofuzz.ifuzz_logger.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: boofuzz.ifuzz_logger.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, 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: boofuzz.ifuzz_logger.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: boofuzz.ifuzz_logger.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