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)

Bases: Graph

继承自 pgraph.graph，为协议交互的构造提供了一个容器。

Parameters:

• session_filename (str) – 存放序列化数据的文件名，默认为 None

• index_start (int) – 要运行的第一个测试用例的索引

• index_end (int) – 要运行的最后一个测试用例的索引

• sleep_time (float) – 测试用例之间等待的秒数，默认为 0

• restart_interval (int) – 在 n 个测试用例之后重启目标。默认情况下为0，表示禁用该选项

• console_gui (bool) – 是否使用 curses 在 web 端生成一个静态控制台，默认为 False（还未在 Windows 下进行测试）

• crash_threshold_request (int) – 请求耗尽之前允许的最大崩溃次数，默认为 12。

• crash_threshold_element (int) – 元素耗尽之前允许的最大崩溃次数，默认为 3

• restart_sleep_time (int) – 当目标无法重启时等待的秒数，默认为5

• restart_callbacks (list of method) – 在 post_test_case_callback 失败后调用的回调方法列表，默认为 None

• restart_threshold (int) – 丢失目标连接时的最大重试次数，默认为 None（无限次）

• restart_timeout (float) – 重新连接尝试的超时时间（秒），默认为 None（无限次）

• pre_send_callbacks (list of method) – 在每个模糊（测试）请求之前调用的注册方法列表，默认为 None

• post_test_case_callbacks (list of method) – 在每个模糊测试用例之后调用的注册方法列表，默认为None

• post_start_target_callbacks (list of method) – 目标启动或重新启动后进程监视器调用的方法，默认为 None 。

• web_port (int or None) – 通过 Web 浏览器监视模糊测试活动的端口。设置为 None 表示禁用 Web 应用程序，默认为 26000

• keep_web_open (bool) – 在会话完成后保持 Web 界面打开，默认为 True

• fuzz_loggers (list of ifuzz_logger.IFuzzLogger) – 日志记录器列表，用于保存测试数据和结果。默认将日志记录到 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) – 如果为 True，在传输每个不进行模糊测试的节点后尝试接收回复，默认为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) – 如果该变量为真，那么在传输完一个 fuzzed 消息后，Session 会尝试接收一个响应

• ignore_connection_reset (bool) – 将 ECONNREST 错误（目标连接复位）记录为 “info” 而非 failures

• ignore_connection_aborted (bool) – 将ECONNABORTED错误记录为”info”而不是失败，默认为False。

• ignore_connection_issues_when_sending_fuzz_data (bool) – 忽略发送模糊数据时的连接故障，默认为 True。这通常是一个有用的设置，因为目标一旦消息明显无效就可能会断开连接。

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

• reuse_target_connection (bool) – 如果为 True，则只使用一个目标连接（Target connection），而不是每个测试用例都重新连接。默认为 False。

• target (Target) – 模糊（测试）会话的目标，必须完全初始化。默认为 None。

• db_filename (str) – 存储测试结果和案例信息的 SQLite 数据库文件名。默认为 ./boofuzz-results/{uniq_timestamp}.db。

• web_address – Bofuzz 记录器对外的地址，默认为 localhost。

add_node(node)

将一个 pgraph 节点加入图中并自动生成分配一个 ID 给该节点。

Parameters:

node (pgraph.Node) – 要加入会话图的节点

add_target(target)

将一个 target 加入到 session 中，可同时对多个目标进行模糊测试。

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

Parameters:

target (Target) – 要加入 session 的 Target 对象。

build_webapp_thread(port=26000, address='localhost')

构建 web 应用程序进程，具体来说 Session 对象作为 flask 实例的 session 属性，之后利用 Tornado 根据 flask 实例创建 http 服务。

connect(src, dst=None, callback=None)

在两个 request（nodes）之间创建一个 Connection 对象并注册一个回调函数用于处理源请求和目的请求之间的传输过程。 Session 类维持着一个顶级节点（根节点），所有的 requests 初始时都必须连接到该节点，例如：

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

如果仅给定了一个参数，那么 sess.connect() 默认会将该节点与根节点连接起来。

sess.connect(s_get("HTTP"))

利用回调方法来处理类似于挑战应答机制的情况。回调方法必须遵循 Session.example_test_case_callback() 这样的消息签名，同时为了 后续的兼容性，记得在参数中加上 **kwargs。

Parameters:

• src (str or Request (pgrah.Node)) – 源 request 名称或 reques 节点。（Source request name or request node）

• dst (str or Request (pgrah.Node), optional) – 目的 request 名称或节点。（Destination request name or request node）

• callback (def, optional) – 回调函数。（Callback function to pass received data to between node xmits. Default None.）

Returns:

src 和 dst 之间的边。（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)

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

Dump various object values to disk.

See:

import_file()

feature_check()

Check all messages/features.

Returns:

None

fuzz(name=None, max_depth=None)

对整个协议树进行模糊测试

Fuzz the entire protocol tree.

fuzz() 会遍历所有的 fuzz cases 并对其进行模糊测试，同时也会根据 self.skip 跳过一些元素以及根据 self.restart_interval 进行重启。

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) – 传入一个 Request 对象的名称来表明仅对该 request 消息进行模糊测试。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)

Fuzz a particular test case or node by name.

Parameters:

name (str) – Name of node.

fuzz_single_case(mutant_index)

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

Load various object values from disk.

See:

export_file()

property netmon_results

num_mutations(max_depth=None)

图中的总变异数。

Number of total mutations in the graph.

该方法的逻辑与 fuzz() 是相同的，具体可参看 fuzz()。

The logic of this routine is identical to that of fuzz(). See fuzz() for inline comments.

通过该方法可对 self.total_num_mutations 成员变量进行更新。

The member variable self.total_num_mutations is updated appropriately by this routine.

Parameters:

max_depth (int) – 模糊测试所用的最大组合深度。如果该值为 None 或者大于等于1，那么 num_mutations 返回 None，因为在使用组合模糊测试时，变异数通常是非常大的。（Maximum combinatorial depth used for fuzzing. num_mutations returns None if this value is None or greater than 1, as the number of mutations is typically very large when using combinatorial fuzzing.）

Returns:

当前 session 对象的总变异数。（Total number of mutations in this session.）

Return type:

int

register_post_test_case_callback(method)

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

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

test_case_data(index)

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)

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)

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

boofuzz 模糊测试

下面的几个方法涉及到 boofuzz 框架模糊测试的具体逻辑和实现，是 boofuzz 模糊测试的精髓所在。

Session._generate_mutations_indefinitely(max_depth=None, path=None)

在所有消息中，每条消息产生具有 n 个变异的 MutationContext 对象，n 的值会无限增加。

（Yield MutationContext with n mutations per message over all messages, with n increasing indefinitely.）

Session._main_fuzz_loop(fuzz_case_iterator)

执行主要的模糊测试逻辑，以一个可迭代的 test cases 作为参数。

Execute main fuzz logic; takes an iterator of test cases.

调用条件：self.total_mutant_index and self.total_num_mutations 都已正确设置。

Preconditions: self.total_mutant_index and self.total_num_mutations are set properly.

Parameters:

fuzz_case_iterator (Iterable) – An iterator that walks through fuzz cases and yields MutationContext objects. See _iterate_single_node() for details.

Returns:

None

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