SimpleEthernet Documentation

This module containts a number of simple classes than can be used to create Ethernet, IP and UDP packets. The basic functionality of these packet formats are supported which should cover 95% of the use cases.

You should understand the struct.pack() and struct.unpack() functions in python before using this module

When reading a packet, typically a new instance of the class is created and the source of data is passed to the Ethernet.pack() method.

For writing a packet, the various attributes of the packets are created and the packed. This returns a string buffer which is the byte representation of the packet.

Packet types which encapsulate other packets are unpacked by passing the payload of the outter packet to the inner packet. For example

>>> import AcraNetwork.SimpleEthernet as se
>>> ip_pkt = se.IP()
>>> ip_pkt.payload = b"\xFF"
>>> ip_pkt.dstip = "192.168.28.2"
>>> ip_pkt.srcip = "192.168.28.1"
>>> eth_pkt = se.Ethernet()
>>> eth_pkt.dstmac = 0x1
>>> eth_pkt.srcmac = 0x2
>>> #At this point we have the bones of two packets. Now to encapsulate the IP packet in the Ethernet packet
>>> eth_pkt.payload = ip_pkt.pack()

Ethernet Objects

Used to build Ethernet packets. Payload encapsulated is typically the output of IP.pack()

class AcraNetwork.SimpleEthernet.Ethernet(buf: bytes | None = None)

This is simple class to pack or unpack an Ethernet packet. Handles very basic packets that are used in FTI

Read an Ethernet Packet from a pcap file

>>> from base64 import b64decode
>>> raw_packet = b64decode('AQBeAAABAAxNAApsCABFAAA61p1AAP8R3VrAqBwQ6wAAAQP/H0oAJgAAAB8ADwAPA1ffwH8A1pwAAQvUQGAAAP3NEAEoHP//')
>>> e = Ethernet()
>>> e.unpack(raw_packet)
True
>>> print(e)
SRCMAC=00:0C:4D:00:0A:6C DSTMAC=01:00:5E:00:00:01 TYPE=0X800

pack(fcs: bool = False) → bytes

Pack the Ethernet object into a buffer

Parameters:

fcs – Include FCS in the buffer returned

Return type:

bytes

unpack(buf: bytes, fcs=False) → bool

Unpack a raw byte stream to an Ethernet object

Parameters:

• buf (bytes) – The string buffer to unpack

• fcs (bool) – Assume FCS is included in the buffer

Return type:

bool

payload: bytes

The Ethernet payload. Typically an IP packet.

type: int

The Ethertype field. Assign using the TYPE_* constants. https://en.wikipedia.org/wiki/EtherType

IP Objects

Used to build IP packets. Payload encapsulated is typically the output of UDP.pack().

Currently only supports IPv4

class AcraNetwork.SimpleEthernet.IP(buf: bytes | None = None)

Create or unpack an IP packet https://en.wikipedia.org/wiki/IPv4#Header

If you wanted to unpack an Ethernet object payload which contains an IP packet

>>> from base64 import b64decode
>>> raw_packet = b64decode('AQBeAAABAAxNAApsCABFAAA61p1AAP8R3VrAqBwQ6wAAAQP/H0oAJgAAAB8ADwAPA1ffwH8A1pwAAQvUQGAAAP3NEAEoHP//')
>>> i = IP()
>>> i.unpack(raw_packet[0x10:])
True

pack() → bytes

Pack the IP object into a buffer

Return type:

bytes

unpack(buf: bytes) → bool

Unpack a raw byte stream to an IP object

Parameters:

buf (bytes) – The string buffer to unpack

Return type:

bool

dscp: int

Differentiated Services Code Point

dstip: str

Destination IP Address

flags: int

Three bit field identifying a flag

fragment_offset: int

Fragment offset

id: int

Identification Field

ihl: int

Header length in 32 bit words

len: int

Total Length. This is calculated when packing the packet

payload: bytes

The IPv4 payload

protocol: int

The type of the payload

srcip: str

Source IP Address

ttl: int

Time to Live. In practice the hop count.

version: int

IP version field

UDP Objects

Used to build UDP packets. Payload encapsulated is typically an iNetX or IENA packet.

class AcraNetwork.SimpleEthernet.UDP(buf: bytes | None = None)

Class to build and unpack a UDP packet

https://en.wikipedia.org/wiki/User_Datagram_Protocol#Packet_structure

Packet structure:

-----2B----- -----2B----- -----2B----- -----2B----- --0-65527B----
| SRC PORT  |  DEST PORT |   LENGTH   | CHECKSUM   | PAYLOAD
------------ ------------ ------------ ------------ --------------

Create a UDP packet

>>> u = UDP()
>>> u.dstport = 5500
>>> u.srcport = 4400
>>> u.payload = struct.pack('B',0x5)
>>> mypacket = u.pack()

pack() → bytes

Pack the UDP object into a buffer

Return type:

bytes

unpack(buf: bytes)

Unpack a raw byte stream to a UDP object

Parameters:

buf (bytes) – The string buffer to unpack

Return type:

bool

dstport: int

The UDP desitnation port number

len: int

The length of the UDP header and payload in bytes

payload: bytes

The UDP payload

srcport: int

The UDP source port number

ARP Objects

Minimal ARP implementation

class AcraNetwork.SimpleEthernet.ARP

Minimal ARP class,. Very limited

Args:

object (_type_): _description_

Returns:

_type_: _description_

>>> a = ARP()
>>> a.dstip = "192.168.28.2"
>>> b = ARP()
>>> b.unpack(a.pack())
>>> a == b
True

pack() → bytes

Convert ARP object into bytes

Returns:

bytes: bytes representation of the ARP packet

unpack(buffer: bytes) → None

Conmvert the buffer into an ARP object

Args:

buffer (bytes): Buffer of bytes

ICMP Objects

Minimal ICMP implementation

class AcraNetwork.SimpleEthernet.ICMP

Class to handle ICMP packets

>>> i = ICMP()
>>> i.type = ICMP.TYPE_REPLY
>>> i.code = 0
>>> i.payload = bytes(1)
>>> mypacket = i.pack()

pack() → bytes

Pack an ICMP object into a buffer of bytes

IGMPv3 Objects

Minimal IGMPv3 implementation

class AcraNetwork.SimpleEthernet.IGMPv3

Simplified IGMPv3 support to generate queries and join requests

static join_groups(groups: List[str]) → bytes

Join the specified groups :param groups: List of IP addresses :return: bytes

static membership_query() → bytes

Return a membership query :return:

SimpleEthernet functions

These are useful functions than are associated with Ethernet packets

AcraNetwork.SimpleEthernet.unpack48(x: bytes) → int

Unpack a 48bit string returning an integer

Parameters:

x (bytes) – 6 byte buffer

Return type:

int

AcraNetwork.SimpleEthernet.mactoreadable(macaddress: int) → str

Convert a macaddress into the readable form

Parameters:

macaddress (int) – The mac address in integer format

Return type:

str

AcraNetwork.SimpleEthernet.combine_ip_fragments(packets: List[IP]) → IP

Combine the lists of fragmented IP packets into one IP packet