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, web_address='localhost', db_filename=None)[source]
Bases:
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.
db_filename (str) – Filename to store sqlite db for test results and case information. Defaults to ./boofuzz-results/{uniq_timestamp}.db
web_address – Address where’s Boofuzz logger exposed. Default ‘localhost’
Changed in version 0.4.2: This class has been moved into the sessions subpackage. The full path is now boofuzz.sessions.session.Session.
- 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
- 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()
orregister_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 typeProtocolSessionReference
.args – Implementations should include *args and **kwargs for forward-compatibility.
kwargs – Implementations should include *args and **kwargs for forward-compatibility.
- property exec_speed
- 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.
Deprecated since version 0.4.0: Use
Session.fuzz()
instead.
- 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.
- 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
- 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