Connections

Connection objects implement ITargetConnection. Available options include:

ITargetConnection

class boofuzz.connections.ITargetConnection[source]

Bases: object

Interface for connections to fuzzing targets. Target connections may be opened and closed multiple times. You must open before using send/recv and close afterwards.

Changed in version 0.2.0: ITargetConnection has been moved into the connections subpackage. The full path is now boofuzz.connections.itarget_connection.ITargetConnection

abstract close()[source]

Close connection.

Returns:

None

abstract property info

Return description of connection info.

E.g., “127.0.0.1:2121”

Returns:

Connection info descrption

Return type:

str

abstract open()[source]

Opens connection to the target. Make sure to call close!

Returns:

None

abstract recv(max_bytes)[source]

Receive up to max_bytes data.

Parameters:

max_bytes (int) – Maximum number of bytes to receive.

Returns:

Received data. bytes(‘’) if no data is received.

Return type:

bytes

abstract send(data)[source]

Send data to the target.

Parameters:

data – Data to send.

Returns:

Number of bytes actually sent.

Return type:

int

BaseSocketConnection

class boofuzz.connections.BaseSocketConnection(send_timeout, recv_timeout)[source]

Bases: ITargetConnection

This class serves as a base for a number of Connections over sockets.

New in version 0.2.0.

Parameters:

  • send_timeout (float) – Seconds to wait for send before timing out. Default 5.0.

  • recv_timeout (float) – Seconds to wait for recv before timing out. Default 5.0.

close()[source]

Close connection to the target.

Returns:

None

abstract open()[source]

Opens connection to the target. Make sure to call close!

Returns:

None

TCPSocketConnection

class boofuzz.connections.TCPSocketConnection(host, port, send_timeout=5.0, recv_timeout=5.0, server=False)[source]

Bases: BaseSocketConnection

BaseSocketConnection implementation for use with TCP Sockets.

New in version 0.2.0.

Parameters:

  • host (str) – Hostname or IP adress of target system.

  • port (int) – Port of target service.

  • send_timeout (float) – Seconds to wait for send before timing out. Default 5.0.

  • recv_timeout (float) – Seconds to wait for recv before timing out. Default 5.0.

  • server (bool) – Set to True to enable server side fuzzing.

close()[source]

Close connection to the target.

Returns:

None

property info

Return description of connection info.

E.g., “127.0.0.1:2121”

Returns:

Connection info descrption

Return type:

str

open()[source]

Opens connection to the target. Make sure to call close!

Returns:

None

recv(max_bytes)[source]

Receive up to max_bytes data from the target.

Parameters:

max_bytes (int) – Maximum number of bytes to receive.

Returns:

Received data.

send(data)[source]

Send data to the target. Only valid after calling open!

Parameters:

data – Data to send.

Returns:

Number of bytes actually sent.

Return type:

int

UDPSocketConnection

class boofuzz.connections.UDPSocketConnection(host, port, send_timeout=5.0, recv_timeout=5.0, server=False, bind=None, broadcast=False)[source]

Bases: BaseSocketConnection

BaseSocketConnection implementation for use with UDP Sockets.

New in version 0.2.0.

Parameters:

  • host (str) – Hostname or IP adress of target system.

  • port (int) – Port of target service.

  • send_timeout (float) – Seconds to wait for send before timing out. Default 5.0.

  • recv_timeout (float) – Seconds to wait for recv before timing out. Default 5.0.

  • server (bool) – Set to True to enable server side fuzzing.

  • bind (tuple (host, port)) – Socket bind address and port. Required if using recv().

  • broadcast (bool) – Set to True to enable UDP broadcast. Must supply appropriate broadcast address for send() to work, and ‘’ for bind host for recv() to work.

property info

Return description of connection info.

E.g., “127.0.0.1:2121”

Returns:

Connection info descrption

Return type:

str

classmethod max_payload()[source]

Returns the maximum payload this connection can send at once.

This performs some crazy CTypes magic to do a getsockopt() which determines the max UDP payload size in a platform-agnostic way.

Returns:

The maximum length of a UDP packet the current platform supports

Return type:

int

open()[source]

Opens connection to the target. Make sure to call close!

Returns:

None

recv(max_bytes)[source]

Receive up to max_bytes data from the target.

Parameters:

max_bytes (int) – Maximum number of bytes to receive.

Returns:

Received data.

send(data)[source]

Send data to the target. Only valid after calling open! Some protocols will truncate; see self.MAX_PAYLOADS.

Parameters:

data – Data to send.

Returns:

Number of bytes actually sent.

Return type:

int

SSLSocketConnection

class boofuzz.connections.SSLSocketConnection(host, port, send_timeout=5.0, recv_timeout=5.0, server=False, sslcontext=None, server_hostname=None)[source]

Bases: TCPSocketConnection

BaseSocketConnection implementation for use with SSL Sockets.

New in version 0.2.0.

Parameters:

  • host (str) – Hostname or IP adress of target system.

  • port (int) – Port of target service.

  • send_timeout (float) – Seconds to wait for send before timing out. Default 5.0.

  • recv_timeout (float) – Seconds to wait for recv before timing out. Default 5.0.

  • server (bool) – Set to True to enable server side fuzzing.

  • sslcontext (ssl.SSLContext) – Python SSL context to be used. Required if server=True or server_hostname=None.

  • server_hostname (string) – server_hostname, required for verifying identity of remote SSL/TLS server

open()[source]

Opens connection to the target. Make sure to call close!

Returns:

None

recv(max_bytes)[source]

Receive up to max_bytes data from the target.

Parameters:

max_bytes (int) – Maximum number of bytes to receive.

Returns:

Received data.

send(data)[source]

Send data to the target. Only valid after calling open!

Parameters:

data – Data to send.

Returns:

Number of bytes actually sent.

Return type:

int

RawL2SocketConnection

class boofuzz.connections.RawL2SocketConnection(interface, send_timeout=5.0, recv_timeout=5.0, ethernet_proto=0, mtu=1518, has_framecheck=True)[source]

Bases: BaseSocketConnection

BaseSocketConnection implementation for use with Raw Layer 2 Sockets.

New in version 0.2.0.

Parameters:

  • interface (str) – Hostname or IP adress of target system.

  • send_timeout (float) – Seconds to wait for send before timing out. Default 5.0.

  • recv_timeout (float) – Seconds to wait for recv before timing out. Default 5.0.

  • ethernet_proto (int) – Ethernet protocol to bind to. If supplied, the opened socket gets bound to this protocol, otherwise the python default of 0 is used. Must be supplied if this socket should be used for receiving. For valid options, see <net/if_ether.h> in the Linux Kernel documentation. Usually, ETH_P_ALL (0x0003) is not a good idea.

  • mtu (int) – sets the maximum transmission unit size for this connection. Defaults to 1518 for standard Ethernet.

  • has_framecheck (bool) – Indicates if the target ethernet protocol needs 4 bytes for a framecheck. Default True (for standard Ethernet).

property info

Return description of connection info.

E.g., “127.0.0.1:2121”

Returns:

Connection info descrption

Return type:

str

open()[source]

Opens connection to the target. Make sure to call close!

Returns:

None

recv(max_bytes)[source]

Receives a packet from the raw socket. If max_bytes < mtu, only the first max_bytes are returned and the rest of the packet is discarded. Otherwise, return the whole packet.

Parameters:

max_bytes (int) – Maximum number of bytes to return. 0 to return the whole packet.

Returns:

Received data

send(data)[source]

Send data to the target. Only valid after calling open! Data will be trunctated to self.max_send_size (Default: 1514 bytes).

Parameters:

data – Data to send.

Returns:

Number of bytes actually sent.

Return type:

int

RawL3SocketConnection

class boofuzz.connections.RawL3SocketConnection(interface, send_timeout=5.0, recv_timeout=5.0, ethernet_proto=2048, l2_dst=b'\xff\xff\xff\xff\xff\xff', packet_size=1500)[source]

Bases: BaseSocketConnection

BaseSocketConnection implementation for use with Raw Layer 2 Sockets.

New in version 0.2.0.

Parameters:

  • interface (str) – Interface to send and receive on.

  • send_timeout (float) – Seconds to wait for send before timing out. Default 5.0.

  • recv_timeout (float) – Seconds to wait for recv before timing out. Default 5.0.

  • ethernet_proto (int) – Ethernet protocol to bind to. Defaults to ETH_P_IP (0x0800).

  • l2_dst (bytes) – Layer2 destination address (e.g. MAC address). Default b’ÿÿÿÿÿÿ’ (broadcast)

  • packet_size (int) – Maximum packet size (in bytes). Default 1500 if the underlying interface uses standard ethernet for layer 2. Otherwise, a different packet size may apply (e.g. Jumboframes, 802.5 Token Ring, 802.11 wifi, …) that must be specified.

property info

Return description of connection info.

E.g., “127.0.0.1:2121”

Returns:

Connection info descrption

Return type:

str

open()[source]

Opens connection to the target. Make sure to call close!

Returns:

None

recv(max_bytes)[source]

Receives a packet from the raw socket. If max_bytes < packet_size, only the first max_bytes are returned and the rest of the packet is discarded. Otherwise, return the whole packet.

Parameters:

max_bytes (int) – Maximum number of bytes to return. 0 to return the whole packet.

Returns:

Received data

send(data)[source]

Send data to the target. Only valid after calling open! Data will be trunctated to self.packet_size (Default: 1500 bytes).

Parameters:

data – Data to send.

Returns:

Number of bytes actually sent.

Return type:

int

SocketConnection

boofuzz.connections.SocketConnection(host, port=None, proto='tcp', bind=None, send_timeout=5.0, recv_timeout=5.0, ethernet_proto=None, l2_dst=b'\xff\xff\xff\xff\xff\xff', udp_broadcast=False, server=False, sslcontext=None, server_hostname=None)[source]

ITargetConnection implementation using sockets.

Supports UDP, TCP, SSL, raw layer 2 and raw layer 3 packets.

Note

SocketConnection is deprecated and will be removed in a future version of Boofuzz. Use the classes derived from BaseSocketConnection instead.

Changed in version 0.2.0: SocketConnection has been moved into the connections subpackage. The full path is now boofuzz.connections.socket_connection.SocketConnection

Deprecated since version 0.2.0: Use the classes derived from BaseSocketConnection instead.

Examples:

tcp_connection = SocketConnection(host='127.0.0.1', port=17971)
udp_connection = SocketConnection(host='127.0.0.1', port=17971, proto='udp')
udp_connection_2_way = SocketConnection(host='127.0.0.1', port=17971, proto='udp', bind=('127.0.0.1', 17972)
udp_broadcast = SocketConnection(host='127.0.0.1', port=17971, proto='udp', bind=('127.0.0.1', 17972),
                                 udp_broadcast=True)
raw_layer_2 = (host='lo', proto='raw-l2')
raw_layer_2 = (host='lo', proto='raw-l2',
               l2_dst='\xFF\xFF\xFF\xFF\xFF\xFF', ethernet_proto=socket_connection.ETH_P_IP)
raw_layer_3 = (host='lo', proto='raw-l3')
Parameters:

  • host (str) – Hostname or IP address of target system, or network interface string if using raw-l2 or raw-l3.

  • port (int) – Port of target service. Required for proto values ‘tcp’, ‘udp’, ‘ssl’.

  • proto (str) – Communication protocol (“tcp”, “udp”, “ssl”, “raw-l2”, “raw-l3”). Default “tcp”. raw-l2: Send packets at layer 2. Must include link layer header (e.g. Ethernet frame). raw-l3: Send packets at layer 3. Must include network protocol header (e.g. IPv4).

  • bind (tuple (host, port)) – Socket bind address and port. Required if using recv() with ‘udp’ protocol.

  • send_timeout (float) – Seconds to wait for send before timing out. Default 5.0.

  • recv_timeout (float) – Seconds to wait for recv before timing out. Default 5.0.

  • ethernet_proto (int) – Ethernet protocol when using ‘raw-l3’. 16 bit integer. Default ETH_P_IP (0x0800) when using ‘raw-l3’. See “if_ether.h” in Linux documentation for more options.

  • l2_dst (str) – Layer 2 destination address (e.g. MAC address). Used only by ‘raw-l3’. Default ‘ÿÿÿÿÿÿ’ (broadcast).

  • udp_broadcast (bool) – Set to True to enable UDP broadcast. Must supply appropriate broadcast address for send() to work, and ‘’ for bind host for recv() to work.

  • server (bool) – Set to True to enable server side fuzzing.

  • sslcontext (ssl.SSLContext) – Python SSL context to be used. Required if server=True or server_hostname=None.

  • server_hostname (string) – server_hostname, required for verifying identity of remote SSL/TLS server.

SerialConnection

class boofuzz.connections.SerialConnection(port=0, baudrate=9600, timeout=5, message_separator_time=0.3, content_checker=None)[source]

Bases: ITargetConnection

ITargetConnection implementation for generic serial ports.

Since serial ports provide no default functionality for separating messages/packets, this class provides several means:

  • timeout: Return received bytes after timeout seconds.

  • msg_separator_time: Return received bytes after the wire is silent for a given time. This is useful, e.g., for terminal protocols without a machine-readable delimiter. A response may take a long time to send its information, and you know the message is done when data stops coming.

  • content_check: A user-defined function takes the data received so far and checks for a packet. The function should return 0 if the packet isn’t finished yet, or n if a valid message of n bytes has been received. Remaining bytes are stored for next call to recv(). Example:

    def content_check_newline(data):
if data.find('\n') >= 0:
    return data.find('\n')
else:
    return 0

If none of these methods are used, your connection may hang forever.

Changed in version 0.2.0: SerialConnection has been moved into the connections subpackage. The full path is now boofuzz.connections.serial_connection.SerialConnection

Parameters:

  • port (Union[int, str]) – Serial port name or number.

  • baudrate (int) – Baud rate for port.

  • timeout (float) – For recv(). After timeout seconds from receive start, recv() will return all received data, if any.

  • message_separator_time (float) – After message_separator_time seconds without receiving any more data, recv() will return. Optional. Default None.

  • content_checker (function(str) -> int) – User-defined function. recv() will pass all bytes received so far to this method. If the method returns n > 0, recv() will return n bytes. If it returns 0, recv() will keep on reading.

close()[source]

Close connection to the target.

Returns:

None

property info

Return description of connection info.

E.g., “127.0.0.1:2121”

Returns:

Connection info descrption

Return type:

str

open()[source]

Opens connection to the target. Make sure to call close!

Returns:

None

recv(max_bytes)[source]

Receive up to max_bytes data from the target.

Parameters:

max_bytes (int) – Maximum number of bytes to receive.

Returns:

Received data.

send(data)[source]

Send data to the target. Only valid after calling open!

Parameters:

data – Data to send.

Returns:

Number of bytes actually sent.

Return type:

int