Concrete PDUs¶

IEEE 802.1q
Ethernet
PPPoE
ARP
STP
Loopback
ICMP
IPv4
- IP class
- IP helpers
  - IP.OptionIdentifier
  - IP.SecurityType
IPSEC
TCP
UDP
RAW
PPI

IEEE 802.1q ¶

class Dot1Q(tag_id=0, append_pad=True)¶

Bases: cycapture.libtins._tins.PDU

IEEE 802.1q PDU class

Parameters:	tag_id (uint16_t) -- Tag VLAN ID append_pad (bool) -- flag indicating whether padding will be appended at the end of this packet

append_padding¶

Flag indicating whether the appropriate padding will be at the end of the packet (read-write, bool).

The flag could be set to False when two or more contiguous Dot1Q PDUs are added to a packet. In that case, only the Dot1Q that is closer to the link layer should add a padding at the end.

cfi¶: Canonical Format Identifie field (read-write, uint8_t)

id¶: VLAN Id (read-write, uint16_t)

payload_type¶: Payload type field (read-write, uint16_t)

priority¶: Priority field (read-write, uint8_t)

Ethernet ¶

class EthernetII(dst_addr=None, src_addr=None)¶

Bases: cycapture.libtins._tins.PDU

Ethernet packet

Parameters:	dst_addr (bytes or `HWAddress`) -- destination address of the ethernet packet src_addr (bytes or `HWAddress`) -- source address of the ethernet packet

dst_addr¶: Destination address (read-write property)

payload_type¶: Payload type (uint16_t, read-write property)

src_addr¶: Source address (read-write property)

PPPoE ¶

class PPPoE¶

Bases: cycapture.libtins._tins.PDU

Point-to-point protocol over Ethernet packet

The default constructor sets the version and type fields to 0x1.

class TagTypes¶

Bases: enum.IntEnum

Tag types enum

Attributes: END_OF_LIST, RELAY_SESSION_ID, SERVICE_NAME, AC_NAME, SERVICE_NAME_ERROR, AC_SYSTEM_ERROR, HOST_UNIQ, GENERIC_ERROR, AC_COOKIE, VENDOR_SPECIFIC

PPPoE.add_tag(tag_type, data=None)¶

Add a tag

Parameters:	tag_type (`PPPoE:TagTypes`) data (bytes)

PPPoE.get_vendor_specific()¶

Returns:	(vendor_id, data) ((uint32_t, bytes))
Raises:	`exception` (`OptionNotFound`) -- if the PDU does not have a Vendor-Specific tag

PPPoE.search_tag(tag_type)¶

Search for a tag by type.

Parameters:	tag_type (`PPPoE:TagTypes`)
Returns:	tag (bytes or `None`)

PPPoE.set_vendor_specific(vendor_id, data)¶

Add a Vendor-Specific tag

Parameters:	vendor_id (uint32_t) data (bytes)

PPPoE.ac_cookie¶: AC-Cookie tag (read-write, bytes)

PPPoE.ac_name¶: AC-name tag (read-write, bytes)

PPPoE.ac_system_error¶: AC-System-Error tag (read-write, bytes)

PPPoE.code¶: code field (read-write, uint8_t)

PPPoE.generic_error¶: Generic-Error tag (read-write, bytes)

PPPoE.host_uniq¶: host-uniq tag (read-write, bytes)

PPPoE.payload_length¶: the payload_length field (read-write, uint16_t)

PPPoE.relay_session_id¶: Relay-Session-Id tag (read-write, bytes)

PPPoE.service_name¶: service-name tag (read-write, bytes)

PPPoE.service_name_error¶: Service-Name-Error tag (read-write, bytes)

PPPoE.session_id¶: session_id field (read-write, uint16_t)

PPPoE.tags¶: The list of current tags (read-only)

PPPoE.type¶: type field (read-write, 4 bits int)

PPPoE.version¶: version field (read-write, 4 bits int)

ARP ¶

class ARP(target_ip=None, sender_ip=None, target_hw=None, sender_hw=None)¶

Bases: cycapture.libtins._tins.PDU

ARP packet

ARP requests and replies can be constructed easily using static methods make_arp_request() and make_arp_reply().

Parameters:	target_ip (`IPv4Address`) -- target IP address sender_ip (`IPv4Address`) -- sender IP address target_hw (`HWAddress`) -- target hardware address sender_hw (`HWAddress`) -- sender hardware address

class Flags¶

Bases: enum.IntEnum

Indicates the type of ARP packet

Attributes: REQUEST, REPLY

static ARP.make_arp_reply(target, sender, hw_tgt=None, hw_snd=None)¶

Creates an ARP Reply within an EthernetII PDU.

Parameters:	target (`IPv4Address`) -- Target IP address sender (`IPv4Address`) -- Sender IP address hw_tgt (`HWAddress`) -- Target hardware address hw_snd (`HWAddress`) -- Sender hardware address
Returns:	packet (`EthernetII`)

static ARP.make_arp_request(target, sender, hw_snd=None)¶

Creates an ARP Request within an EthernetII PDU.

Parameters:	target (`IPv4Address`) -- Target IP address sender (`IPv4Address`) -- Sender IP address hw_snd (`HWAddress`) -- Sender hardware address
Returns:	packet (`EthernetII`)

ARP.hw_addr_format¶: Hardware address format field (read-write, uint16_t)

ARP.hw_addr_length¶: Hardware address length field (read-write, uint8_t)

ARP.opcode¶: ARP opcode field (Flags)

ARP.prot_addr_format¶: Protocol address format field (read-write, uint16_t)

ARP.prot_addr_length¶: Protocol address length field (read-write, uint8_t)

ARP.sender_hw_addr¶: Sender's hardware address (read-write, HWAddress)

ARP.sender_ip_addr¶: Sender's IP address (read-write, IPv4Address)

ARP.target_hw_addr¶: Target's hardware address (read-write, HWAddress)

ARP.target_ip_addr¶: Target's IP address (read-write, IPv4Address)

STP ¶

class STP¶

Bases: cycapture.libtins._tins.PDU

Spanning Tree Protocol frame.

bpdu_id_t¶: alias of bpdu_id

bpdu_flags¶: BPDU Flags field (read-write, uint8_t)

bpdu_type¶: BPDU Type field (read-write, uint8_t)

bridge_id¶: Bridge ID field (read-write, bpdu_id)

fwd_delay¶: Forward Delay field (read-write, uint16_t)

hello_time¶: Hello Time field (read-write, uint16_t)

max_age¶: Maximum Age field (read-write, uint16_t)

msg_age¶: Message Age field (read-write, uint16_t)

port_id¶: Port ID field (read-write, uint16_t)

proto_id¶: Protocol ID field (read-write, uint16_t)

proto_version¶: Protocol Version field (read-write, uint8_t)

root_id¶: Root ID field (read-write, bpdu_id)

root_path_cost¶: Root Path Cost field (read-write, uint32_t)

Loopback ¶

class Loopback¶

Bases: cycapture.libtins._tins.PDU

Loopback PDU

family¶: family identifier (read-write, uint32_t)

ICMP ¶

class ICMP(flag=None)¶

Bases: cycapture.libtins._tins.PDU

ICMP packet.

Instances of this class must be sent over a level 3 PDU.

Parameters:	flag (int or `Flags`) -- The type flag which will be set (ECHO_REQUEST if none provided)

class Flags¶

Bases: enum.IntEnum

ICMP flags

Attributes: ECHO_REPLY, DEST_UNREACHABLE, SOURCE_QUENCH, REDIRECT, ECHO_REQUEST, TIME_EXCEEDED, PARAM_PROBLEM, TIMESTAMP_REQUEST, TIMESTAMP_REPLY, INFO_REQUEST, INFO_REPLY, ADDRESS_MASK_REQUEST, ADDRESS_MASK_REPLY

ICMP.set_dest_unreachable()¶: Sets destination unreachable for this PDU.

ICMP.address_mask¶: Address mask field (read-write, IPv4Address)

ICMP.checksum¶: The checksum field (read-only)

ICMP.code¶: Code field (read-write, uint8_t)

ICMP.gateway¶: Gateway field (read-write, IPv4Address)

ICMP.id¶: Id field (read-write, uint16_t)

ICMP.mtu¶: MTU field (read-write, uint16_t)

ICMP.original_timestamp¶: Original timestamp field (read-write, uint32_t)

ICMP.pointer¶: Pointer field (read-write, uint8_t)

ICMP.receive_timestamp¶: Receive timestamp field (read-write, uint32_t)

ICMP.sequence¶: Sequence field (read-write, uint16_t)

ICMP.transmit_timestamp¶: Transmit timestamp field (read-write, uint32_t)

ICMP.type¶: Type field (read-write, Flags

IPv4 ¶

IP class ¶

class IP(dst_addr=None, src_addr=None)¶

Bases: cycapture.libtins._tins.PDU

IP packet

Parameters:	dst_addr (bytes or `IPv4Address`) -- IPv4 destination address src_addr (bytes or `IPv4Address`) -- IPv4 source address

class OptionClass¶

Bases: enum.IntEnum

Options class for the IP PDU

Attributes: CONTROL, MEASUREMENT

IP.OptionIdentifier¶: alias of IPOptionIdentifier

class IP.OptionNumber¶

Bases: enum.IntEnum

Options numbers for the IP PDU

Attributes: END, NOOP, SEC, LSSR, TIMESTAMP, EXTSEC, RR, SID, SSRR, MTUPROBE, MTUREPLY, EIP, TR, ADDEXT, RTRALT, SDB, DPS, UMP, QS

IP.SecurityType¶: alias of IPSecurityType

IP.add_option(identifier, data=None)¶

Adds an IP option.

Parameters:	identifier (`IPOptionIdentifier`) -- option identifier data (bytes) -- option data

IP.eol()¶: Adds an End Of List option.

IP.get_lsrr()¶

Searchs and returns a Loose Source and Record Route option, or None is the option is not present.

Returns:	pointer (int) routes (list of IPv4Address)

IP.get_record_route()¶

Returns the record route option, or None is the option is not present.

Returns:	pointer (int) routes (list of IPv4Address)

IP.get_security()¶

Searchs and returns a security option, or None if such option can't be found

Returns:	opt (`IPSecurityType`)

IP.get_ssrr()¶

Searchs and returns a Strict Source and Record Route option, or None if the option is not present.

Returns:	pointer (int) routes (list of IPv4Address)

IP.noop()¶: Adds a NOP option.

IP.options()¶

Returns all the PDU's options.

Returns:	opts (list of dicts)

IP.search_option(identifier)¶

Searchs for an option that matchs the given flag. Returns the option data, or None if such option can't be found.

Parameters:	identifier (`IPOptionIdentifier`)
Returns:	opt (bytes)

IP.set_lsrr(pointer, routes)¶

Adds a Loose Source and Record Route option.

Parameters:	pointer (uint8_t) routes (list of IPv4 addresses)

IP.set_record_route(pointer, routes)¶

Adds a Record Route option.

Parameters:	pointer (uint8_t) routes (list of IPv4 addresses)

IP.set_security(security_obj)¶

Adds a security option.

Parameters:	security_obj (`IPSecurityType`) -- the security option

IP.set_ssrr(pointer, routes)¶

Adds a Strict Source and Record Route option.

Parameters:	pointer (uint8_t) routes (list of IPv4 addresses)

IP.checksum¶: the checksum field (uint16_t, read-write)

IP.dst_addr¶: the destination address field (IPv4Address, read-write)

IP.frag_off¶: the fragment offset field (uint16_t, read-write)

IP.fragmented¶: True if the IP PDU is fragmented (read-only)

IP.head_len¶: the header length field (read-only)

IP.id¶: the id field (uint16_t, read-write)

IP.protocol¶: the protocol field (uint8_t, read-write)

IP.src_addr¶: the source address field (IPv4Address, read-write)

IP.stream_identifier¶

Stream Identifier option (uint16_t, read-write)

The getter returns None if the option is not set

IP.tos¶: the type of service field (uint8_t, read-write)

IP.tot_len¶: the total length field (uint16_t, read-write)

IP.ttl¶: the time to live field (uint8_t, read-write)

IP.version¶: the version field (4 bits, read-write)

IP helpers ¶

IP.OptionIdentifier ¶

class IPOptionIdentifier(number, op_class, copied)¶

Bases: object

The type used to represent an IP option's identifier.

Parameters:	number (IP.OptionNumber or uint8_t) op_class (IP.OptionClass or uint8_t) copied (1 or 0)

copied¶: copied getter

number¶: number getter

op_class¶: op_class getter

IP.SecurityType ¶

class IPSecurityType(security=0, compartments=0, handling_restrictions=0, transmission_control=0)¶

Bases: object

The type for the IP security option.

Parameters:	security (uint16_t) compartments (uint16_t) handling_restrictions (uint16_t) transmission_control (24 bits integer)

compartments¶: compartments getter

handling_restrictions¶: handling_restrictions getter

security¶: security getter

transmission_control¶: transmission_control getter

IPSEC ¶

class IPSecAH¶

Bases: cycapture.libtins._tins.PDU

IPSec Authentication Header

The ICV field is initialized with four 0 bytes. The length field is initialized appropriately.

icv¶: ICV field (read-write, bytes)

length¶: Length field (read-write, uint8_t)

next_header¶: Next header field (read-write, uint8_t)

seq_number¶: Sequence number field (read-write, uint32_t)

spi¶: Security Parameters Index field (read-write, uint32_t)

class IPSecESP¶

Bases: cycapture.libtins._tins.PDU

IPSEC Encapsulating Security Payload

seq_number¶: Sequence number field (read-write, uint32_t)

spi¶: Security Parameters Index field (read-write, uint32_t)

TCP ¶

class TCP(dest=0, src=0)¶

Bases: cycapture.libtins._tins.PDU

TCP packet

When sending TCP PDUs, the checksum is calculated automatically every time you send the packet.

While sniffing, the payload sent in each packet will be wrapped in a RAW PDU:

>>> from cycapture.libtins import TCP, RAW
>>> buf = ...
>>> pdu = TCP.from_buffer(buf)
>>> raw = pdu.rfind_pdu(RAW)
>>> payload = raw.payload

Parameters:	dest (uint16_t) -- destination port src (uint16_t) -- source port

class AltChecksums¶

Bases: enum.IntEnum

Alternate checksum enum

Attributes: CHK_TCP, CHK_8FLETCHER, CHK_16FLETCHER

class TCP.Flags¶

Bases: enum.IntEnum

Flags supported by the TCP PDU.

Attributes: FIN, SYN, RST, PSH, ACK, URG, ECE, CWR

class TCP.OptionTypes¶

Bases: enum.IntEnum

Option types supported by TCP PDU

Attributes: EOL, NOP, MSS, WSCALE, SACK_OK, SACK, TSOPT, ALTCHK

TCP.get_flag(flag)¶

Gets the value of a flag.

Parameters:	flag (`Flags`)
Returns:	flag (bool)

TCP.set_flag(flag, value)¶

Sets a TCP flag value.

Parameters:	flag (`Flags`) value (bool)

TCP.ack_seq¶: Acknowledge number field (read-write, uint32_t)

TCP.checksum¶: The checksum field (read-only)

TCP.data_offset¶: Data offset field (read-write, uint8_t)

TCP.dport¶: Destination port (read-write, uint16_t)

TCP.seq¶: Sequence number field (read-write, uint32_t)

TCP.sport¶: Source port (read-write, uint16_t)

TCP.urg_ptr¶: Urgent pointer field (read-write, uint16_t)

TCP.window¶: Window size field (read-write, uint16_t)

UDP ¶

class UDP(dport=0, sport=0)¶

Bases: cycapture.libtins._tins.PDU

Encapsulate an UDP PDU.

While sniffing, the payload sent in each packet will be wrapped in a RAW PDU:

>>> from cycapture.libtins import UDP, RAW
>>> buf = ...
>>> pdu = UDP.from_buffer(buf)
>>> raw = pdu.rfind_pdu(RAW)
>>> payload = raw.payload

Parameters:	dport (uint16_t) -- destination port sport (uint16_t) -- source port

checksum¶: checksum of the datagram (read-only)

dport¶: Destination port (read-write, uint16_t)

length¶: Length of the datagram (read-write, uint16_t)

sport¶: Source port (read-write, uint16_t)

RAW ¶

class RAW(data=b'')¶

Bases: cycapture.libtins._tins.PDU

RAW PDU packet.

This class is a wrapper over a byte array. It can be used to hold the payload sent over transport layer protocols (such as TCP or UDP).

RAW packets can be converted to another PDU using the to method:

>>> from cycapture.libtins import RAW, DNS, DHCP
>>> raw = RAW(...)
>>> dhcp = raw.to(DHCP)     # if we know the payload is in fact a DHCP packet, we can convert
>>> dns = raw.to(DNS)       # if the conversion fails, a MalformedException is raised

RAW.matches_response always returns True.

Parameters:	data (bytes) -- the payload that will be copied into the RAW PDU

to(pdu_class)¶

Convert the payload to another concrete PDU (the payload is copied).

Parameters:	pdu_class (a concrete PDU)
Returns:	pdu (an instance of pdu_class)
Raises:	`exception` (`MalformedPacket`) -- if the payload can't be parsed to pdu_class

payload¶: The payload (read-write, bytes)

payload_size¶: The payload size (read-only)

PPI ¶

class PPI¶

Bases: cycapture.libtins._tins.PDU

Per-Packet Information PDU

This type of packet can't be costructed directly, and can't be serialized. It is useful only for sniffing.

dlt¶: Data Link Type field (read-only)

flags¶: Flags field (read-only)

length¶: Length field (read-only)

version¶: Version field (read-only)

Quick search

Concrete PDUs¶