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.

To edit logging styling, see the helpers.py and boofuzz.css files.

Fuzzing Levels

Fuzzungus now supports multiple levels of logging for the CLI :

Log level	Description	CLI option
0	Print on the same line the “open test case” log and also print fail, error and target-error.	Default
1	Same as log level 0 but do not print on the same line.	-v
2	Log level 1 + check, pass, info and target-warn.	-vv
3	Most verbose level : log level 2 + open test step, receive and send.	-vvv

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 log_target_error(description='')[source]

Records a major problem detected on the target.

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

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

Records a problem detected on the target.

Parameters:: description (str) – Optional supplementary 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

Postgres Logging

Note

To use this method of logging, the Postgres database have to be running. Fuzzungus use docker to achieve that. Use docker compose up db -d to achieve that.

Each campaign create a different database. The name of the databases are the id of each campaign, so it’s easy to find which database is for each campaign.

In each database, there are at least two tables : steps and cases.

Furthermore, a replay creates two other tables in the same database of the original campaign : steps and cases ones but prefix with date and time.

Do ./boo db list to see all databases which their size.

And, inside a database (in a Postgres shell), type \d+ to list all tables.

class boofuzz.FuzzLoggerPostgres(db_name: str, db_table_name: str | None = None, num_log_cases=0)[source]

Bases: IFuzzLogger

Log fuzz data in a PostgreSQL database. Using an existing database requires more graceful exits to prevent case number duplication.

Parameters:

db_name (str) – Name of the database.
db_table_name (str | None) – Name of tables in database. Default “”.
num_log_cases (int) – Minimize disk usage by only saving passing test cases if they are in the n test cases preceding a failure or error. Set to 0 to save after every test case (high disk I/O!). Default 0.

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

get_test_case_data(index: int) → DataTestCase[source]

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

log_target_error(description='')[source]

Records a major problem detected on the target.

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

log_target_warn(description='')[source]

Records a problem detected on the target.

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

open_test_case(test_case_id, name, index, round_type=None, seed=None, seed_index=None, *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

Text Logging

Note

The Text Logger now uses one more logger, log-recap, to print the recap of the fuzzing session when a SIGINT is received.

class boofuzz.FuzzLoggerText(file_handle=<colorama.ansitowin32.StreamWrapper object>, bytes_to_str=<function hex_to_hexstr>, log_level: int = None)[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.

Log level | Description |

——— | —————————————————————————— |

0 | Print on the same line the “open test case” log and also print fail, error |

| and target-error. |

1 | Same as log level 0 but do not print on the same line. |

2 | Log level 1 + check, pass, info and target-warn. |

3 | Most verbose level : log level 2 + open test step, receive and send. |

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_recap(description='')[source]: Specific to FuzzLoggerText. Print a recap message.

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

log_target_error(description='')[source]

Records a major problem detected on the target.

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

log_target_warn(description='')[source]

Records a problem detected on the target.

Parameters:: description (str) – Optional supplementary 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

Db Logging

Deprecated since version 1.0: Deprecated if favor of FuzzLoggerPostgres This is the old way to log in a db : sqlite database file.

class boofuzz.FuzzLoggerDb(*args, **kwargs)[source]

Bases: IFuzzLogger

Deprecated if favor of FuzzLoggerPostgres. This is the old way to log in a db : sqlite database file.

Old docstring : Log fuzz data in a sqlite database file. Using an existing database requires more graceful exits to prevent case number duplication.

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

get_test_case_data(index)[source]

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

log_target_error(description='')[source]

Records a major problem detected on the target.

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

log_target_warn(description='')[source]

Records a problem detected on the target.

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

open_test_case(test_case_id, name, index, round_type=None, seed=None, seed_index=None, *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=<_io.TextIOWrapper name='<stdout>' mode='w' encoding='utf-8'>, 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

log_target_error(description='')[source]

Records a major problem detected on the target.

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

log_target_warn(description='')[source]

Records a problem detected on the target.

Parameters:: description (str) – Optional supplementary 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() → str[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

log_target_error(description='')[source]

Records a major problem detected on the target.

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

log_target_warn(description='')[source]

Records a problem detected on the target.

Parameters:: description (str) – Optional supplementary 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