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, restart_threshold=None, restart_timeout=None, pre_send_callbacks=None, post_test_case_callbacks=None, post_start_target_callbacks=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, ignore_connection_reset=False, ignore_connection_aborted=False, ignore_connection_issues_when_sending_fuzz_data=True, ignore_connection_ssl_errors=False, 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.

  • restart_threshold (int) – Maximum number of retries on lost target connection. Default None (indefinitely).

  • restart_timeout (float) – Time in seconds for that a connection attempt should be retried. Default None (indefinitely).

  • 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.

  • post_start_target_callbacks (list of method) – Method(s) will be called after the target is started or restarted, say, by a process monitor.

  • 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_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.

  • ignore_connection_ssl_errors (bool) – Log SSL related errors as “info” instead of failures. Default False.

  • 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.

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()

property netmon_results
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.