Session

class boofuzz.Session(session_filename=None, index_start=1, index_end=None, sleep_time=0.0, restart_interval=0, web_port=26000, keep_web_open=True, console_gui=False, crash_threshold_request=12, crash_threshold_element=3, restart_sleep_time=5, restart_callbacks=None, pre_send_callbacks=None, post_test_case_callbacks=None, fuzz_data_logger=None, fuzz_loggers=None, fuzz_db_keep_only_n_pass_cases=0, receive_data_after_each_request=True, check_data_received_each_request=False, receive_data_after_fuzz=False, log_level=20, logfile=None, logfile_level=10, ignore_connection_reset=False, ignore_connection_aborted=False, ignore_connection_issues_when_sending_fuzz_data=True, reuse_target_connection=False, target=None)[source]

Bases: boofuzz.pgraph.graph.Graph

Extends pgraph.graph and provides a container for architecting protocol dialogs.

Parameters:
  • session_filename (str) – Filename to serialize persistent data to. Default None.
  • index_start (int) –
  • index_end (int) –
  • sleep_time (float) – Time in seconds to sleep in between tests. Default 0.
  • restart_interval (int) – Restart the target after n test cases, disable by setting to 0 (default).
  • console_gui (bool) – Use curses to generate a static console screen similar to the webinterface. Has not been tested under Windows. Default False.
  • crash_threshold_request (int) – Maximum number of crashes allowed before a request is exhausted. Default 12.
  • crash_threshold_element (int) – Maximum number of crashes allowed before an element is exhausted. Default 3.
  • restart_sleep_time (int) – Time in seconds to sleep when target can’t be restarted. Default 5.
  • restart_callbacks (list of method) – The registered method will be called after a failed post_test_case_callback Default None.
  • pre_send_callbacks (list of method) – The registered method will be called prior to each fuzz request. Default None.
  • post_test_case_callbacks (list of method) – The registered method will be called after each fuzz test case. Default None.
  • web_port (int) – Port for monitoring fuzzing campaign via a web browser. Default 26000.
  • keep_web_open (bool) – Keep the webinterface open after session completion. Default True.
  • fuzz_data_logger (fuzz_logger.FuzzLogger) – DEPRECATED. Use fuzz_loggers instead.
  • fuzz_loggers (list of ifuzz_logger.IFuzzLogger) – For saving test data and results.. Default Log to STDOUT.
  • fuzz_db_keep_only_n_pass_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.
  • receive_data_after_each_request (bool) – If True, Session will attempt to receive a reply after transmitting each non-fuzzed node. Default True.
  • check_data_received_each_request (bool) – If True, Session will verify that some data has been received after transmitting each non-fuzzed node, and if not, register a failure. If False, this check will not be performed. Default False. A receive attempt is still made unless receive_data_after_each_request is False.
  • receive_data_after_fuzz (bool) – If True, Session will attempt to receive a reply after transmitting a fuzzed message. Default False.
  • ignore_connection_reset (bool) – Log ECONNRESET errors (“Target connection reset”) as “info” instead of failures.
  • ignore_connection_aborted (bool) – Log ECONNABORTED errors as “info” instead of failures.
  • ignore_connection_issues_when_sending_fuzz_data (bool) – Ignore fuzz data transmission failures. Default True. This is usually a helpful setting to enable, as targets may drop connections once a message is clearly invalid.
  • reuse_target_connection (bool) – If True, only use one target connection instead of reconnecting each test case. Default False.
  • target (Target) – Target for fuzz session. Target must be fully initialized. Default None.
  • log_level (int) – DEPRECATED Unused. Logger settings are now configured in fuzz_data_logger. Was once used to set the log level.
  • logfile (str) – DEPRECATED Unused. Logger settings are now configured in fuzz_data_logger. Was once the name of the log file.
  • logfile_level (int) – DEPRECATED Unused. Logger settings are now configured in fuzz_data_logger. Was once used to set the log level for the logfile. Default logger.INFO.
add_node(node)[source]

Add a pgraph node to the graph. We overload this routine to automatically generate and assign an ID whenever a node is added.

Parameters:node (pgraph.Node) – Node to add to session graph
add_target(target)[source]

Add a target to the session. Multiple targets can be added for parallel fuzzing.

Parameters:target (Target) – Target to add to session
build_webapp_thread(port=26000)[source]
connect(src, dst=None, callback=None)[source]

Create a connection between the two requests (nodes) and register an optional callback to process in between transmissions of the source and destination request. Leverage this functionality to handle situations such as challenge response systems. The session class maintains a top level node that all initial requests must be connected to. Example:

sess = sessions.session()
sess.connect(sess.root, s_get("HTTP"))

If given only a single parameter, sess.connect() will default to attaching the supplied node to the root node. This is a convenient alias and is identical to the second line from the above example:

sess.connect(s_get("HTTP"))

If you register callback method, it must follow this prototype:

def callback(target, fuzz_data_logger, session, node, edge, *args, **kwargs)

Where node is the node about to be sent, edge is the last edge along the current fuzz path to “node”, session is a pointer to the session instance which is useful for snagging data such as session.last_recv which contains the data returned from the last socket transmission and sock is the live socket. A callback is also useful in situations where, for example, the size of the next packet is specified in the first packet. As another example, if you need to fill in the dynamic IP address of the target register a callback that snags the IP from sock.getpeername()[0].

Parameters:
  • src (str or Request (pgrah.Node)) – Source request name or request node
  • dst (str or Request (pgrah.Node), optional) – Destination request name or request node
  • callback (def, optional) – Callback function to pass received data to between node xmits. Default None.
Returns:

The edge between the src and dst.

Return type:

pgraph.Edge

example_test_case_callback(target, fuzz_data_logger, session, *args, **kwargs)[source]

Example call signature for methods given to register_post_test_case_callback().

Parameters:
  • target (Target) – Target with sock-like interface.
  • fuzz_data_logger (ifuzz_logger.IFuzzLogger) – Allows logging of test checks and passes/failures. Provided with a test case and test step already opened.
  • session (Session) – Session object calling post_send. Useful properties include last_send and last_recv.
  • args – Implementations should include *args and **kwargs for forward-compatibility.
  • kwargs – Implementations should include *args and **kwargs for forward-compatibility.
export_file()[source]

Dump various object values to disk.

@see: import_file()

feature_check()[source]

Check all messages/features.

Returns:None
fuzz()[source]

Fuzz the entire protocol tree.

Iterates through and fuzzes all fuzz cases, skipping according to self.skip and restarting based on self.restart_interval.

If you want the web server to be available, your program must persist after calling this method. helpers.pause_for_signal() is available to this end.

Returns:None
fuzz_by_name(name)[source]

Fuzz a particular test case or node by name.

Parameters:name (str) – Name of node.
fuzz_single_case(mutant_index)[source]

Fuzz a test case by mutant_index.

Parameters:mutant_index (int) – Positive non-zero integer.
Returns:None
Raises:sex.SulleyRuntimeError – If any error is encountered while executing the test case.
fuzz_single_node_by_path(node_names)[source]

Fuzz a particular node via the path in node_names.

Parameters:node_names (list of str) – List of node names leading to target.
import_file()[source]

Load various object values from disk.

@see: export_file()

log(msg, level=1)[source]
num_mutations(this_node=None, path=())[source]

Number of total mutations in the graph. The logic of this routine is identical to that of fuzz(). See fuzz() for inline comments. The member variable self.total_num_mutations is updated appropriately by this routine.

Parameters:
  • this_node (request (node)) – Current node that is being fuzzed. Default None.
  • path (list) – Nodes along the path to the current one being fuzzed. Default [].
Returns:

Total number of mutations in this session.

Return type:

int

register_post_test_case_callback(method)[source]

Register a post- test case method.

The registered method will be called after each fuzz test case.

Potential uses:
  • Closing down a connection.
  • Checking for expected responses.

The order of callback events is as follows:

pre_send() - req - callback ... req - callback - post-test-case-callback
Parameters:method (function) – A method with the same parameters as post_send()
server_init()[source]

Called by fuzz() to initialize variables, web interface, etc.

test_case_data(index)[source]

Return test case data object (for use by web server)

Parameters:index (int) – Test case index
Returns:Test case data object
Return type:DataTestCase
transmit_fuzz(sock, node, edge, callback_data)[source]

Render and transmit a fuzzed node, process callbacks accordingly.

Parameters:
  • sock (Target, optional) – Socket-like object on which to transmit node
  • node (pgraph.node.node (Node), optional) – Request/Node to transmit
  • edge (pgraph.edge.edge (pgraph.edge), optional) – Edge along the current fuzz path from “node” to next node.
  • callback_data (bytes) – Data from previous callback.
transmit_normal(sock, node, edge, callback_data)[source]

Render and transmit a non-fuzzed node, process callbacks accordingly.

Parameters:
  • sock (Target, optional) – Socket-like object on which to transmit node
  • node (pgraph.node.node (Node), optional) – Request/Node to transmit
  • edge (pgraph.edge.edge (pgraph.edge), optional) – Edge along the current fuzz path from “node” to next node.
  • callback_data (bytes) – Data from previous callback.