Monitors

Monitors 就是监视目标特定行为的组件，一般称之为监视器。监视器可以是被动的，也可以是主动的。 被动的意思是仅对目标进行观察并提供一些数据，而主动的意思则是表明监视器的行为更加的积极，比如直接和目标进行交互等。 更进一步地，有些监视器甚至具有启动、停止、重启目标的能力。

监测目标的崩溃或异常行为可能是一件复杂的事情，主要取决于在目标系统上有哪些可用的工具。 比如对嵌入式设备来说，在其上通常没有现成的能够监测崩溃/异常的工具。

Boofuzz 主要提供了三种监视器实现类：

• ProcessMonitor：从 Windows 和 Unix 进程中收集调试信息的监视器类。该类也可以重启目标进程以及监测段错误。

• NetworkMonitor：通过 PCAP 被动地捕获网络流量并将其写入测试用例日志中的监视器类。

• CallbackMonitor：用于实现回调函数的监视器类，可以传递给 Session 类。

Monitor Interface (BaseMonitor)

class boofuzz.monitors.BaseMonitor

Bases: object

Interface for Target monitors. All Monitors must adhere to this specification.

New in version 0.2.0.

alive()

Called when a Target containing this Monitor is added to a session. Use this function to connect to e.g. RPC hosts if your target lives on another machine.

You MUST return True if the monitor is alive. You MUST return False otherwise. If a Monitor is not alive, this method will be called until it becomes alive or throws an exception. You SHOULD handle timeouts / connection retry limits in the monitor implementation.

Defaults to return True.

Returns:

Bool

get_crash_synopsis()

Called if any monitor indicates that the current testcase has failed, even if this monitor did not detect a crash. You SHOULD return a human- readable representation of the crash synopsis (e.g. hexdump). You MAY save the full crashdump somewhere.

Returns:

str

post_send(target=None, fuzz_data_logger=None, session=None)

Called after the current fuzz node is transmitted. Use it to collect data about a target and decide whether it crashed.

You MUST return True if the Target is still alive. You MUST return False if the Target crashed. If one Monitor reports a crash, the whole testcase will be marked as crashing.

Defaults to return True.

Returns:

Bool

post_start_target(target=None, fuzz_data_logger=None, session=None)

Called after a target is started or restarted.

pre_send(target=None, fuzz_data_logger=None, session=None)

Called before the current fuzz node is transmitted.

Defaults to no effect.

Returns:

None

restart_target(target=None, fuzz_data_logger=None, session=None)

Restart a target. Must return True if restart was successful, False if it was unsuccessful or this monitor cannot restart a Target, which causes the next monitor in the chain to try to restart.

The first successful monitor causes the restart chain to stop applying.

Defaults to call stop and start, return True if successful.

Returns:

Bool

retrieve_data()

Called to retrieve data independent of whether the current fuzz node crashed the target or not. Called before the fuzzer proceeds to a new testcase.

You SHOULD return any auxiliary data that should be recorded. The data MUST be serializable, e.g. bytestring.

Defaults to return None.

set_options(*args, **kwargs)

Called to set options for your monitor (e.g. local crash dump storage). *args and **kwargs can be explicitly specified by implementing classes, however you SHOULD ignore any kwargs you do not recognize.

Defaults to no effect.

Returns:

None

start_target()

Starts a target. You MUST return True if the start was successful. You MUST return False if not. Monitors will be tried to start the target in the order they were added to the Target; the first Monitor to succeed breaks iterating.

Returns:

Bool

stop_target()

Stops a target. You MUST return True if the stop was successful. You MUST return False if not. Monitors will be tried to stop the target in the order they were added to the Target; the first Monitor to succeed breaks iterating.

Returns:

Bool

ProcessMonitor

The process monitor consists of two parts; the ProcessMonitor class that implements BaseMonitor and a second module that is to be run on the host of your target.

class boofuzz.monitors.ProcessMonitor(host, port)

ProcessMonitor 类继承自 BaseMonitor 以及 pedrpc.Client，是 process monitor 接口的代理类。

在 0.2.0 版本之前，boofuzz 的网络和进程监视器是在 RPC 之上进行通信的， RPC 客户端被直接传递给 Session 类，并在 RPC partner 上动态地解析所有方法调用。

自 0.2.0 版本以后，每个 monitor 类都必须实现抽象类 BaseMonitor。 它定义了所有 monitor 之间的公共接口。 为了有助于以后的类型提示工作并消除网络和进程监视器的歧义， 引入了这个显式代理类，它将所有调用快速转发到 RPC partner。

New in version 0.2.0.

alive()

This method is forwarded to the RPC daemon.

get_crash_synopsis()

This method is forwarded to the RPC daemon.

on_new_server(new_uuid)

Restores all set options to the RPC daemon if it has restarted since the last call.

post_send(target=None, fuzz_data_logger=None, session=None)

This method is forwarded to the RPC daemon.

pre_send(target=None, fuzz_data_logger=None, session=None)

This method is forwarded to the RPC daemon.

restart_target(target=None, fuzz_data_logger=None, session=None)

This method is forwarded to the RPC daemon.

set_crash_filename(new_crash_filename)

Deprecated since version 0.2.0.

This option should be set via set_options.

set_options(*args, **kwargs)

旧的 RPC 接口指明用 set_foobar 方法设置选项，但是不同的 RPC 会实现不同的 set_foobar， 所以 set_options 方法负责转换参数后传给 set_foobar。

如果你调用 set_options(foobar="barbaz")，那么实际上是在 RPC partner 上调用 set_foobar("barbaz")。

set_proc_name(new_proc_name)

Deprecated since version 0.2.0.

This option should be set via set_options.

set_start_commands(new_start_commands)

Deprecated since version 0.2.0.

This option should be set via set_options.

set_stop_commands(new_stop_commands)

Deprecated since version 0.2.0.

This option should be set via set_options.

start_target()

This method is forwarded to the RPC daemon.

stop_target()

This method is forwarded to the RPC daemon.

NetworkMonitor

The network monitor consists of two parts; the NetworkMonitor class that implements BaseMonitor and a second module that is to be run on a host that can monitor the traffic.

class boofuzz.monitors.NetworkMonitor(host, port)

Proxy class for the network monitor interface.

In Versions < 0.2.0, boofuzz had network and process monitors that communicated over RPC. The RPC client was directly passed to the session class, and resolved all method calls dynamically on the RPC partner.

Since 0.2.0, every monitor class must implement the abstract class BaseMonitor, which defines a common interface among all Monitors. To aid future typehinting efforts and to disambiguate Network- and Process Monitors, this explicit proxy class has been introduced that fast-forwards all calls to the RPC partner.

New in version 0.2.0.

alive()

This method is forwarded to the RPC daemon.

on_new_server(new_uuid)

Restores all set options to the RPC daemon if it has restarted since the last call.

post_send(target=None, fuzz_data_logger=None, session=None)

This method is forwarded to the RPC daemon.

pre_send(target=None, fuzz_data_logger=None, session=None)

This method is forwarded to the RPC daemon.

restart_target(target=None, fuzz_data_logger=None, session=None)

Always returns false as this monitor cannot restart a target.

retrieve_data()

This method is forwarded to the RPC daemon.

set_filter(new_filter)

Deprecated since version 0.2.0.

This option should be set via set_options.

set_log_path(new_log_path)

Deprecated since version 0.2.0.

This option should be set via set_options.

set_options(*args, **kwargs)

The old RPC interfaces specified set_foobar methods to set options. As these vary by RPC implementation, this trampoline method translates arguments that have been passed as keyword arguments to set_foobar calls.

If you call set_options(foobar="barbaz"), it will result in a call to set_foobar("barbaz") on the RPC partner.

Additionally, any options set here are cached and re-applied to the RPC server should it restart for whatever reason (e.g. the VM it’s running on was restarted).

CallbackMonitor

class boofuzz.monitors.CallbackMonitor(on_pre_send=None, on_post_send=None, on_restart_target=None, on_post_start_target=None)

New-Style Callback monitor that is used in Session to provide callback-arrays. It’s purpose is to keep the *_callbacks arguments in the session class while simplifying the implementation of session by forwarding these callbacks to the monitor infrastructure.

The mapping of arguments to method implementations of this class is as follows:

• restart_callbacks –> target_restart

• pre_send_callbacks –> pre_send

• post_test_case_callbacks –> post_send

• post_start_target_callbacks –> post_start_target

All other implemented interface members are stubs only, as no corresponding arguments exist in session. In any case, it is probably wiser to implement a custom Monitor than to use the callback functions.

New in version 0.2.0.

post_send(target=None, fuzz_data_logger=None, session=None)

This method iterates over all supplied post send callbacks and executes them. Their return values are discarded, exceptions are caught and logged:

• BoofuzzTargetConnectionReset will log a failure

• BoofuzzTargetConnectionAborted will log an info

• BoofuzzTargetConnectionFailedError will log a failure

• BoofuzzSSLError will log either info or failure, depending on if the session ignores SSL/TLS errors.

• every other exception is logged as an error.

All exceptions are discarded after handling.

post_start_target(target=None, fuzz_data_logger=None, session=None)

Called after a target is started or restarted.

pre_send(target=None, fuzz_data_logger=None, session=None)

This method iterates over all supplied pre send callbacks and executes them. Their return values are discarded, exceptions are catched and logged, but otherwise discarded.

restart_target(target=None, fuzz_data_logger=None, session=None)

This Method tries to restart a target. If no restart callbacks are set, it returns false; otherwise it returns true.

Returns:

bool