Implementation

pcapkit.foundation.reassembly.tcp contains Reassembly only, which reconstructs fragmented TCP packets back to origin.

class pcapkit.foundation.reassembly.tcp.TCP_Reassembly(*, strict=True)[source]

Bases: Reassembly[Packet, Datagram, Tuple[IPAddress, int, IPAddress, int], Buffer]

Reassembly for TCP payload.

Example

>>> from pcapkit.reassembly import TCP_Reassembly
# Initialise instance:
>>> tcp_reassembly = TCP_Reassembly()
# Call reassembly:
>>> tcp_reassembly(packet_dict)
# Fetch result:
>>> result = tcp_reassembly.datagram
Parameters
  • *args (Any) – Arbitrary positional arguments.

  • **kwargs (Any) – Arbitrary keyword arguments.

Return type

Reassembly[PT, DT, IT, BT]

property name: Literal['Transmission Control Protocol']

Protocol of current packet.

Return type

Literal[‘Transmission Control Protocol’]

property protocol: Type[TCP]

Protocol of current reassembly object.

Return type

Type[TCP]

reassembly(info)[source]

Reassembly procedure.

Parameters

info (Packet) – info dict of packets to be reassembled

Return type

None

submit(buf, *, bufid)[source]

Submit reassembled payload.

Parameters
  • buf (Buffer) – buffer dict of reassembled packets

  • bufid (BufferID) – buffer identifier

Returns

Reassembled packets.

Return type

list[Datagram]

Terminology

tcp.packet

Data structure for TCP datagram reassembly (TCP_Reassembly.reassembly) is as following:

packet_dict = Info(
  bufid = tuple(
      ip.src,                     # source IP address
      tcp.srcport,                # source port
      ip.dst,                     # destination IP address
      tcp.dstport,                # destination port
  ),
  dsn = tcp.seq,                  # data sequence number
  ack = tcp.ack,                  # acknowledgement number
  num = frame.number,             # original packet range number
  syn = tcp.flags.syn,            # synchronise flag
  fin = tcp.flags.fin,            # finish flag
  rst = tcp.flags.rst,            # reset connection flag
  len = tcp.raw_len,              # payload length, header excludes
  first = tcp.seq,                # this sequence number
  last = tcp.seq + tcp.raw_len,   # next (wanted) sequence number
  header = tcp.packet.header,     # raw bytes type header
  payload = tcp.raw,              # raw bytearray type payload
)
tcp.datagram

Data structure for reassembled TCP datagram (element from TCP_Reassembly.datagram tuple) is as following:

(tuple) datagram
 |--> (Info) data
 |     |--> 'completed' : (bool) True --> implemented
 |     |--> 'id' : (Info) original packet identifier
 |     |            |--> 'src' --> (tuple)
 |     |            |               |--> (IPv4Address) ip.src
 |     |            |               |--> (int) tcp.srcport
 |     |            |--> 'dst' --> (tuple)
 |     |            |               |--> (IPv4Address) ip.dst
 |     |            |               |--> (int) tcp.dstport
 |     |            |--> 'ack' --> (int) original packet ACK number
 |     |--> 'index' : (tuple) packet numbers
 |     |               |--> (int) original packet range number
 |     |               |--> ...
 |     |--> 'header' : (bytes) initial TCP header
 |     |--> 'payload' : (bytes) reassembled payload
 |     |--> 'packet' : (Protocol) parsed reassembled payload
 |--> (Info) data
 |     |--> 'completed' : (bool) False --> not implemented
 |     |--> 'id' : (Info) original packet identifier
 |     |            |--> 'src' --> (tuple)
 |     |            |               |--> (IPv4Address) ip.src
 |     |            |               |--> (int) tcp.srcport
 |     |            |--> 'dst' --> (tuple)
 |     |            |               |--> (IPv4Address) ip.dst
 |     |            |               |--> (int) tcp.dstport
 |     |            |--> 'ack' --> (int) original packet ACK number
 |     |--> 'index' : (tuple) packet numbers
 |     |               |--> (int) original packet range number
 |     |               |--> ...
 |     |--> 'header' : (bytes) initial TCP header
 |     |--> 'payload' : (tuple) partially reassembled payload
 |     |                 |--> (bytes) payload fragment
 |     |                 |--> ...
 |     |--> 'packet' : (None) not implemented
 |--> (Info) data ...
tcp.buffer

Data structure for internal buffering when performing reassembly algorithms (TCP_Reassembly._buffer) is as following:

(dict) buffer --> memory buffer for reassembly
 |--> (tuple) BUFID : (dict)
 |       |--> ip.src      |
 |       |--> ip.dst      |
 |       |--> tcp.srcport |
 |       |--> tcp.dstport |
 |                        |--> 'hdl' : (list) hole descriptor list
 |                        |             |--> (Info) hole --> hole descriptor
 |                        |                   |--> "first" --> (int) start of hole
 |                        |                   |--> "last" --> (int) stop of hole
 |                        |--> 'hdr' : (bytes) initial TCP header
 |                        |--> 'ack' : (dict) ACK list
 |                                      |--> (int) ACK : (dict)
 |                                      |                 |--> 'ind' : (list) list of reassembled packets
 |                                      |                 |             |--> (int) packet range number
 |                                      |                 |--> 'isn' : (int) ISN of payload buffer
 |                                      |                 |--> 'len' : (int) length of payload buffer
 |                                      |                 |--> 'raw' : (bytearray) reassembled payload,
 |                                      |                                          holes set to b'\x00'
 |                                      |--> (int) ACK ...
 |                                      |--> ...
 |--> (tuple) BUFID ...

Data Structures

class pcapkit.foundation.reassembly.tcp.Packet(bufid, dsn, ack, num, syn, fin, rst, len, first, last, header, payload)[source]

Bases: Info

Data model for tcp.packet.

Parameters
  • *args (VT) – Arbitrary positional arguments.

  • **kwargs (VT) – Arbitrary keyword arguments.

Return type

Info

bufid: Tuple[IPAddress, int, IPAddress, int]

Buffer ID.

dsn: int

Data sequence number.

ack: int

Acknowledgment number.

num: int

Original packet range number.

syn: bool

Synchronise flag.

fin: bool

Finish flag.

rst: bool

Reset connection flag.

len: int

Payload length, header excluded.

first: int

This sequence number.

last: int

Next (wanted) sequence number.

header: bytes

Raw bytes type header.

payload: bytearray

Raw bytearray type payload.

class pcapkit.foundation.reassembly.tcp.DatagramID(src, dst, ack)[source]

Bases: Info, Generic[IPAddress]

Data model for tcp.datagram original packet identifier.

Parameters
  • *args (VT) – Arbitrary positional arguments.

  • **kwargs (VT) – Arbitrary keyword arguments.

Return type

Info

src: tuple[IPAddress, int]

Source address.

dst: tuple[IPAddress, int]

Destination address.

ack: int

Original packet ACK number.

class pcapkit.foundation.reassembly.tcp.Datagram(completed, id, index, header, payload, packet)[source]

Bases: Info, Generic[IPAddress]

Data model for tcp.datagram.

Parameters
  • *args (VT) – Arbitrary positional arguments.

  • **kwargs (VT) – Arbitrary keyword arguments.

Return type

Info

completed: bool

Completed flag.

id: DatagramID[IPAddress]

Original packet identifier.

index: tuple[int, ...]

Packet numbers.

header: bytes

Initial TCP header.

payload: bytes | tuple[bytes, ...]

Reassembled payload (application layer data).

packet: Optional[Protocol]

Parsed reassembled payload.

class pcapkit.foundation.reassembly.tcp.HoleDiscriptor(fisrt, last)[source]

Bases: Info

Data model for tcp.buffer hole descriptor.

Parameters
  • *args (VT) – Arbitrary positional arguments.

  • **kwargs (VT) – Arbitrary keyword arguments.

Return type

Info

first: int

Start of hole.

last: int

Stop of hole.

class pcapkit.foundation.reassembly.tcp.Fragment(ind, isn, len, raw)[source]

Bases: Info

Data model for tcp.buffer ACK list fragment item.

Parameters
  • *args (VT) – Arbitrary positional arguments.

  • **kwargs (VT) – Arbitrary keyword arguments.

Return type

Info

ind: list[int]

List of reassembled packets.

isn: int

ISN of payload buffer.

len: int

Length of payload buffer.

raw: bytearray

Reassembled payload holes set to b’x00’.

class pcapkit.foundation.reassembly.tcp.Buffer(hdl, hdr, ack)[source]

Bases: Info

Data model for tcp.buffer.

Parameters
  • *args (VT) – Arbitrary positional arguments.

  • **kwargs (VT) – Arbitrary keyword arguments.

Return type

Info

hdl: list[HoleDiscriptor]

Hole descriptor list.

hdr: bytes

Initial TCP header.

ack: dict[int, Fragment]

ACK list.