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 or None) – Port for monitoring fuzzing campaign via a web browser. Set to None to disable the web app. 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. 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. The following line is identical to the second line from the above example:

sess.connect(s_get("HTTP"))

Leverage callback methods to handle situations such as challenge response systems. A callback method must follow the message signature of Session.example_test_case_callback(). Remember to include **kwargs for forward-compatibility.

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, test_case_context, *args, **kwargs)[source]

Example call signature for methods given to connect() or 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.

  • test_case_context (ProtocolSession) – Context for test case-scoped data. ProtocolSession session_variables values are generally set within a callback and referenced in elements via default values of type ProtocolSessionReference.

  • args – Implementations should include *args and **kwargs for forward-compatibility.

  • kwargs – Implementations should include *args and **kwargs for forward-compatibility.

property exec_speed
export_file()[source]

Dump various object values to disk.

See

import_file()

feature_check()[source]

Check all messages/features.

Returns

None

fuzz(name=None, max_depth=None)[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.

Parameters
  • name (str) – Pass in a Request name to fuzz only a single request message. Pass in a test case name to fuzz only a single test case.

  • max_depth (int) – Maximum combinatorial depth; set to 1 for “simple” fuzzing.

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]

Deprecated: Fuzz a test case by mutant_index.

Deprecation note: The new approach is to set Session’s start and end indices to the same value.

Parameters

mutant_index (int) – Positive non-zero integer.

Returns

None

Raises

sex.SulleyRuntimeError – If any error is encountered while executing the test case.

import_file()[source]

Load various object values from disk.

See

export_file()

property netmon_results
num_mutations(max_depth=None)[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
  • max_depth (int) – Maximum combinatorial depth used for fuzzing. num_mutations returns None if this value is

  • 1 (None or greater than) –

  • fuzzing. (as the number of mutations is typically very large when using combinatorial) –

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

property runtime
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, mutation_context)[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.

  • mutation_context (MutationContext) – Current mutation context.

transmit_normal(sock, node, edge, callback_data, mutation_context)[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.

  • mutation_context (MutationContext) – active mutation context

Request-Graph visualisation options

The following methods are available to render data, which can then be used to visualise the request structure.

Session.render_graph_gml()

Render the GML graph description.

Returns

GML graph description.

Return type

str

Session.render_graph_graphviz()

Render the graphviz graph structure.

Example to create a png:

with open('somefile.png', 'wb') as file:
    file.write(session.render_graph_graphviz().create_png())
Returns

Pydot object representing entire graph

Return type

pydot.Dot

Session.render_graph_udraw()

Render the uDraw graph description.

Returns

uDraw graph description.

Return type

str

Session.render_graph_udraw_update()

Render the uDraw graph update description.

Returns

uDraw graph description.

Return type

str