byteblower_test_framework.endpoint module

ByteBlower traffic endpoint interfaces.

class byteblower_test_framework.endpoint.Endpoint

Bases: Taggable, ABC

ByteBlower Endpoint interface.

Added in version 1.2.0: Added for ByteBlower Endpoint support.

__init__(meeting_point: MeetingPoint, uuid: str, name: str | None = None, tags: Sequence[str] | None = None, **kwargs) → None

Initialize a ByteBlower Endpoint.

Parameters:

  • meeting_point (MeetingPoint) – Meeting point this Endpoint is registered on

  • uuid (str) – Unique identifier of the device to use

  • name (Optional[str], optional) – Friendly name for this endpoint, used for reporting, defaults to None (auto-generated)

  • tags (Optional[Sequence[str]], optional) – List of tags to assign, defaults to None

Raises:

InvalidInput – when unsupported configuration is provided

property active: bool

Return whether this Endpoint is active.

Returns:

Whether this endpoint is active or not.

Return type:

bool

property bb_endpoint: WirelessEndpoint

Endpoint object from the ByteBlower API.

discover_nat(remote_port: Port, remote_udp_port: int = 49152, local_udp_port: int = 49152) → Tuple[IPv4Address | IPv6Address, int]

Resolve the IP address (and/or UDP port) as seen by remote_port.

This will resolve either the IP address of the endpoint or the public IP address of the (IPv4 NAT/NAPT) gateway when the endpoint is using IPv4 and is located behind a NAT/NAPT gateway.

Note

UDP ports (remote_udp_port and local_udp_port) can be left to the default if you are only interested in the public IP.

Return type:

Tuple[IPv4Address | IPv6Address, int]

property failed: bool

Return whether (IP) address configuration failed.

abstract property gateway: IPv4Address | IPv6Address

Return the default gateway.

Note

Useful for reporting. Furthermore not used in traffic generation or analysis.

Note

Subject to change in dual stack implementations.

abstract property ip: IPv4Address | IPv6Address

Return the preferred IP address.

Note

Subject to change in dual stack implementations.

property meeting_point: MeetingPoint

Meeting Point object from the ByteBlower Test Framework.

property name: str

Return this endpoint’s given friendly name.

abstract property network: IPv4Network | IPv6Network

Return the network of the preferred IP address.

Note

Useful for reporting. Furthermore not used in traffic generation or analysis.

Note

Subject to change in dual stack implementations.

release() → None

Release this endpoint resources used on the ByteBlower system.

Warning

Releasing resources related to traffic generation and analysis should be done first via the Scenario.release() and/or Flow.release().

Note

The ByteBlower Meeting Point is not released. This should be done afterwards via MeetingPoint.release()

property require_nat_discovery: bool

Return whether this endpoint requires NAT/NAPT discovery.

This is typically required when this endpoint is located behind a NAT/NAPT gateway or you are testing on a carrier-grade NAT (CGN/CGNAT, RFC 6888) network.

Note

Hook function for extending Endpoint implementations.

property status: DeviceStatus

Return this endpoint’s current status.

Returns:

The Endpoint’s current status.

Return type:

DeviceStatus

property uuid: WirelessEndpoint

Return unique identifier of the ByteBlower Endpoint app.

property vlan_config: Iterator[Sequence[Tuple[int, int, bool, int]]]

VLAN configurations of the ByteBlower Lower Layer API.

Note

Currently not supported by the ByteBlower Endpoint.

Returns:

Ordered collection (Outer -> Inner) of VLAN configuration tuples

Yield:

VLAN configuration for current layer 2.5

Return type:

Iterator[Sequence[VlanFlatConfig]]

class byteblower_test_framework.endpoint.IPv4Endpoint

Bases: NatDiscoveryEndpoint

ByteBlower Endpoint interface.

This type of endpoint supports discovery of the actual source IP address (and UDP port) used by an Endpoint when transmitting to a specific destination. This is particularly important for IPv4 multihoming.

The discovery also supports Traditional NAT (RFC 3022, Traditional IP Network Address Translator). Traditional NAT has two variants: Basic NAT and Network Address Port Translation (NAPT).

Added in version 1.2.0: Added for ByteBlower Endpoint support.

__init__(meeting_point: MeetingPoint, uuid: str, name: str | None = None, **kwargs) → None

Initialize a ByteBlower IPv4 Endpoint.

Parameters:

  • meeting_point (MeetingPoint) – Meeting point this Endpoint is registered on

  • uuid (str) – Unique identifier of the device to use

  • name (Optional[str], optional) – Friendly name for this endpoint, used for reporting, defaults to None (auto-generated)

  • tags (Optional[Sequence[str]], optional) – List of tags to assign, defaults to None

Raises:

InvalidInput – when unsupported configuration is provided

property gateway: IPv4Address

Return the default gateway.

Note

Useful for reporting. Furthermore not used in traffic generation or analysis.

property ip: IPv4Address

Return the Endpoint host IP address.

property network: IPv4Network

Return the network of the preferred IP address.

Note

Useful for reporting. Furthermore not used in traffic generation or analysis.

class byteblower_test_framework.endpoint.IPv4Port

Bases: Port

ByteBlower Port interface for IPv4.

__init__(server: Server, interface: str | None = None, name: str | None = None, mac: str | None = None, vlans: Sequence[Mapping[str, int | bool]] | None = None, ipv4: str | None = None, netmask: str | None = None, gateway: str | None = None, tags: Sequence[str] | None = None, **kwargs) → None

Initialize a ByteBlowerPort.

Note

L2 is only configured if:

  1. Explicitly given MAC address

  2. Layer 3 is configured

A port without L2/L3 configuration can for example be used for pure ‘promiscuous’ capturing of data.

Note

Configuring VLAN Protocol ID (TPID) requires at least ByteBlower server version >= 2.20

property failed: bool

Return whether (IP) address configuration failed.

property gateway: IPv4Address

Return the default gateway.

Note

Subject to change in dual stack implementations.

property ip: IPv4Address

Return the preferred IP address.

Note

Subject to change in dual stack implementations.

property layer3: IPv4Configuration

IPv4 configuration of the ByteBlower Lower Layer API.

Note

Subject to change in dual stack implementations.

property network: IPv4Network

Return the network of the preferred IP address.

Note

Subject to change in dual stack implementations.

class byteblower_test_framework.endpoint.IPv6Endpoint

Bases: NatDiscoveryEndpoint

ByteBlower Endpoint interface for IPv6.

This type of endpoint supports discovery of the actual source IP address (and UDP port) used by an Endpoint when transmitting to a specific destination.

This is particularly important for IPv6 multihoming (RFC 7157, IPv6 Multihoming without Network Address Translation).

The discovery can also support NPTv6 (RFC 6296, IPv6-to-IPv6 Network Prefix Translation).

Added in version 1.2.0: Added for ByteBlower Endpoint support.

__init__(meeting_point: MeetingPoint, uuid: str, name: str | None = None, network_interface: str | None = None, **kwargs) → None

Initialize ByteBlower IPv6 Endpoint.

Parameters:

  • meeting_point (MeetingPoint) – Meeting point this Endpoint is registered on

  • uuid (str) – Unique identifier of the device to use

  • name (Optional[str], optional) – Friendly name for this endpoint, used for reporting, defaults to None (auto-generated)

  • network_interface (Optional[str]) –

    Name of the network interface used by the endpoint for traffic generation and analysis, defaults to None (first interface found with IPv6 address).

    Note

    Mostly relevant for reporting and frame blasting flows. When multiple network interfaces are available on the Endpoint and automatic selection is not (always) correct.

  • tags (Optional[Sequence[str]], optional) – List of tags to assign, defaults to None

Raises:

InvalidInput – when unsupported configuration is provided

property gateway: IPv6Address

Return the default gateway.

Note

Useful for reporting. Furthermore not used in traffic generation or analysis.

property ip: IPv6Address

Return the Endpoint host IP address.

property network: IPv6Network

Return the network of the preferred IP address.

Note

Useful for reporting. Furthermore not used in traffic generation or analysis.

class byteblower_test_framework.endpoint.IPv6Port

Bases: Port

ByteBlower Port interface for IPv6.

__init__(server: Server, interface: str | None = None, name: str | None = None, mac: str | None = None, vlans: Sequence[Mapping[str, int | bool]] | None = None, ipv6: str | None = None, tags: Sequence[str] | None = None, **kwargs) → None

Initialize a ByteBlowerPort.

Note

L2 is only configured if:

  1. Explicitly given MAC address

  2. Layer 3 is configured

A port without L2/L3 configuration can for example be used for pure ‘promiscuous’ capturing of data.

Note

Configuring VLAN Protocol ID (TPID) requires at least ByteBlower server version >= 2.20

property failed: bool

Return whether (IP) address configuration failed.

property gateway: IPv6Address

Return the default gateway.

Note

Subject to change in dual stack implementations.

property ip: IPv6Address

Return the preferred IP address.

Note

Subject to change in dual stack implementations.

property layer3: IPv6Configuration

IPv6 configuration of the ByteBlower Lower Layer API.

Note

Subject to change in dual stack implementations.

property network: IPv6Network

Return the network of the preferred IP address.

Note

Subject to change in dual stack implementations.

class byteblower_test_framework.endpoint.NatDiscoveryEndpoint

Bases: Endpoint

ByteBlower Endpoint interface requiring NAT/NAPT discovery.

This type of endpoint supports discovery of the actual source IP address (and UDP port) used by an Endpoint when transmitting to a specific destination.

This is particularly important for IPv4 multihoming or IPv6 multihoming (RFC 7157, IPv6 Multihoming without Network Address Translation).

For IPv4, the discovery also supports Traditional NAT (RFC 3022, Traditional IP Network Address Translator). Traditional NAT has two variants: Basic NAT and Network Address Port Translation (NAPT).

For IPv6, the discovery can also support NPTv6 (RFC 6296, IPv6-to-IPv6 Network Prefix Translation).

Added in version 1.2.0: Added for ByteBlower Endpoint support.

__init__(meeting_point: MeetingPoint, uuid: str, name: str | None = None, **kwargs) → None

Initialize a ByteBlower Endpoint.

Parameters:

  • meeting_point (MeetingPoint) – Meeting point this Endpoint is registered on

  • uuid (str) – Unique identifier of the device to use

  • name (Optional[str], optional) – Friendly name for this endpoint, used for reporting, defaults to None (auto-generated)

  • tags (Optional[Sequence[str]], optional) – List of tags to assign, defaults to None

Raises:

InvalidInput – when unsupported configuration is provided

discover_nat(remote_port: Port, remote_udp_port: int = 49152, local_udp_port: int = 49152) → Tuple[IPv4Address | IPv6Address, int]

Resolve the IP address (and/or UDP port) as seen by remote_port.

This will resolve either the IP address of the endpoint or the public IP address of the (IPv4 NAT/NAPT) gateway when the endpoint is using IPv4 and is located behind a NAT/NAPT gateway.

Note

UDP ports (remote_udp_port and local_udp_port) can be left to the default if you are only interested in the public IP.

Return type:

Tuple[IPv4Address | IPv6Address, int]

property public_ip: IPv4Address | IPv6Address

Return the public IP address resolved from last NAT discovery.

property require_nat_discovery: bool

Return whether this endpoint requires NAT/NAPT discovery.

This is typically required when this endpoint is located behind a NAT/NAPT gateway or you are testing on a carrier-grade NAT (CGN/CGNAT, RFC 6888) network.

class byteblower_test_framework.endpoint.NatDiscoveryIPv4Port

Bases: IPv4Port

ByteBlower Port interface for IPv4 which requires NAT/NAPT discovery.

This type of endpoint supports discovery of Traditional NAT (RFC 3022, Traditional IP Network Address Translator). Traditional NAT has two variants: Basic NAT and Network Address Port Translation (NAPT).

Changed in version 1.2.0: Improved naming for NAT/NAPT discovery related interfaces.

__init__(server: Server, interface: str | None = None, mac: str | None = None, ipv4: str | None = None, netmask: str | None = None, gateway: str | None = None, name: str | None = None, tags: Sequence[str] | None = None, **kwargs) → None

Initialize a ByteBlowerPort.

Note

L2 is only configured if:

  1. Explicitly given MAC address

  2. Layer 3 is configured

A port without L2/L3 configuration can for example be used for pure ‘promiscuous’ capturing of data.

Note

Configuring VLAN Protocol ID (TPID) requires at least ByteBlower server version >= 2.20

discover_nat(remote_port: IPv4Port, remote_udp_port: int = 49152, local_udp_port: int = 49152) → Tuple[IPv4Address, int]

Resolve the IP address (and/or UDP port) as seen by remote_port.

This will resolve either the IP address of the endpoint or the public IP address of the (IPv4 NAT/NAPT) gateway when the endpoint is using IPv4 and is located behind a NAT/NAPT gateway.

Note

UDP ports (remote_udp_port and local_udp_port) can be left to the default if you are only interested in the public IP.

Return type:

Tuple[IPv4Address, int]

property public_ip: IPv4Address

Return the public IP address resolved from last NAT discovery.

property require_nat_discovery: bool

Return whether this endpoint requires NAT/NAPT discovery.

This is typically required when this endpoint is located behind a NAT/NAPT gateway or you are testing on a carrier-grade NAT (CGN/CGNAT, RFC 6888) network.

Note

Hook function for extending Port implementations.

Changed in version 1.2.0: Improved naming for NAT/NAPT discovery related interfaces.

class byteblower_test_framework.endpoint.Port

Bases: Taggable, ABC

ByteBlower Port interface.

__init__(server: Server, interface: str | None = None, name: str | None = None, mac: str | None = None, vlans: Sequence[Mapping[str, int | bool]] | None = None, tags: Sequence[str] | None = None, **kwargs) → None

Initialize a ByteBlowerPort.

Note

L2 is only configured if:

  1. Explicitly given MAC address

  2. Layer 3 is configured

A port without L2/L3 configuration can for example be used for pure ‘promiscuous’ capturing of data.

Note

Configuring VLAN Protocol ID (TPID) requires at least ByteBlower server version >= 2.20

property bb_port: ByteBlowerPort
discover_nat(remote_port: Port, remote_udp_port: int = 49152, local_udp_port: int = 49152) → Tuple[IPv4Address | IPv6Address, int]

Resolve the IP address (and/or UDP port) as seen by remote_port.

This will resolve either the IP address of the endpoint or the public IP address of the (IPv4 NAT/NAPT) gateway when the endpoint is using IPv4 and is located behind a NAT/NAPT gateway.

Note

UDP ports (remote_udp_port and local_udp_port) can be left to the default if you are only interested in the public IP.

Changed in version 1.2.0: Make endpoint interfaces consistent. Generic interface which will return the own IP address and local UDP port when no address/port discovery is required.

Return type:

Tuple[IPv4Address | IPv6Address, int]

abstract property failed: bool

Return whether (IP) address configuration failed.

abstract property gateway: IPv4Address | IPv6Address

Return the default gateway.

Note

Subject to change in dual stack implementations.

abstract property ip: IPv4Address | IPv6Address

Return the preferred IP address.

Note

Subject to change in dual stack implementations.

property layer2_5: Sequence[Layer25Configuration]

Layer 2.5 configurations of the ByteBlower Lower Layer API.

Returns:

Ordered collection of Layer 2.5 Configuration objects

Return type:

Sequence[Layer25Configuration]

property layer3: Layer3Configuration

Layer 3 configuration of the ByteBlower Lower Layer API.

Note

Subject to change in dual stack implementations.

property mac: str

Return the MAC address currently configured on this endpoint.

property name: str

Return this endpoint’s given friendly name.

abstract property network: IPv4Network | IPv6Network

Return the network of the preferred IP address.

Note

Subject to change in dual stack implementations.

property port_type: str
release() → None

Release this endpoint resources used on the ByteBlower system.

Warning

Releasing resources related to traffic generation and analysis should be done first via the Scenario.release() and/or Flow.release().

Note

The ByteBlower Server is not released. This should be done afterwards via Server.release()

property require_nat_discovery: bool

Return whether this endpoint requires NAT/NAPT discovery.

This is typically required when this endpoint is located behind a NAT/NAPT gateway or you are testing on a carrier-grade NAT (CGN/CGNAT, RFC 6888) network.

Note

Hook function for extending Port implementations.

Changed in version 1.2.0: Improved naming for NAT/NAPT discovery related interfaces.

property server: Server
property vlan_config: Iterator[Sequence[Tuple[int, int, bool, int]]]

VLAN configurations of the ByteBlower Lower Layer API.

Returns:

Ordered collection (Outer -> Inner) of VLAN configuration tuples

Yield:

VLAN configuration for current layer 2.5

Return type:

Iterator[Sequence[VlanFlatConfig]]