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: boofuzz.connections.itarget_connection.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: boofuzz.connections.base_socket_connection.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: boofuzz.connections.base_socket_connection.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: boofuzz.connections.tcp_socket_connection.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: boofuzz.connections.base_socket_connection.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: boofuzz.connections.base_socket_connection.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 (str) – Layer2 destination address (e.g. MAC address). Default ‘ÿÿÿÿÿÿ’ (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: boofuzz.connections.itarget_connection.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