pypcapkit 1.3.3.post1__cp313-none-any.whl

pcapkit/toolkit/pcapng.py

@@ -0,0 +1,251 @@
+# -*- coding: utf-8 -*-
+"""PCAP-NG-NG Tools
+===================
+
+.. module:: pcapkit.toolkit.pcapng
+
+:mod:`pcapkit.toolkit.pcapng` contains all you need
+for :mod:`pcapkit` handy usage of PCAP-NG-NG file format.
+All functions returns with a flag to indicate if
+usable for its caller.
+
+"""
+from typing import TYPE_CHECKING, cast
+
+from pcapkit.const.ipv6.extension_header import ExtensionHeader as Enum_ExtensionHeader
+from pcapkit.foundation.reassembly.data.ip import Packet as IP_Packet
+from pcapkit.foundation.reassembly.data.tcp import Packet as TCP_Packet
+from pcapkit.foundation.traceflow.data.tcp import Packet as TF_TCP_Packet
+from pcapkit.protocols.data.misc.pcap.frame import Frame as Data_Frame
+from pcapkit.protocols.data.misc.pcap.frame import FrameInfo as Data_FrameInfo
+
+if TYPE_CHECKING:
+    from ipaddress import IPv4Address, IPv6Address
+
+    from pcapkit.protocols.internet.ipv4 import IPv4
+    from pcapkit.protocols.internet.ipv6 import IPv6
+    from pcapkit.protocols.internet.ipv6_frag import IPv6_Frag
+    from pcapkit.protocols.misc.pcapng import PCAPNG, Packet
+    from pcapkit.protocols.transport.tcp import TCP
+
+__all__ = ['ipv4_reassembly', 'ipv6_reassembly', 'tcp_reassembly',
+           'tcp_traceflow', 'block2frame']
+
+
+def ipv4_reassembly(frame: 'PCAPNG') -> 'IP_Packet[IPv4Address] | None':
+    """Make data for IPv4 reassembly.
+
+    Args:
+        frame: PCAP-NG frame.
+
+    Returns:
+       Data for IPv4 reassembly.
+
+        * If the ``frame`` can be used for IPv4 reassembly. A frame can be reassembled
+          if it contains IPv4 layer (:class:`~pcapkit.protocols.internet.ipv4.IPv4`) and
+          the **DF** (:attr:`IPv4.flags.df <pcapkit.protocols.data.internet.ipv4.Flags.df>`)
+          flag is :data:`False`.
+        * If the ``frame`` can be reassembled, then the :obj:`dict` mapping of data for IPv4
+          reassembly (c.f. :term:`reasm.ipv4.packet`) will be returned; otherwise, returns :data:`None`.
+
+    See Also:
+        :class:`pcapkit.foundation.reassembly.ipv4.IPv4`
+
+    """
+    if 'IPv4' in frame:
+        ipv4 = cast('IPv4', frame['IPv4'])
+        ipv4_info = ipv4.info
+        if ipv4_info.flags.df:       # dismiss not fragmented frame
+            return None
+
+        frame_info = cast('Packet', frame.info)
+        data = IP_Packet(
+            bufid=(
+                ipv4_info.src,                       # source IP address
+                ipv4_info.dst,                       # destination IP address
+                ipv4_info.id,                        # identification
+                ipv4_info.protocol,                  # payload protocol type
+            ),
+            num=frame_info.number,                   # original packet range number
+            fo=ipv4_info.offset,                     # fragment offset
+            ihl=ipv4_info.hdr_len,                   # internet header length
+            mf=ipv4_info.flags.mf,                   # more fragment flag
+            tl=ipv4_info.len,                        # total length, header includes
+            header=ipv4.packet.header,               # raw bytes type header
+            payload=bytearray(ipv4.packet.payload),  # raw bytearray type payload
+        )
+        return data
+    return None
+
+
+def ipv6_reassembly(frame: 'PCAPNG') -> 'IP_Packet[IPv6Address] | None':
+    """Make data for IPv6 reassembly.
+
+    Args:
+        frame: PCAP-NG frame.
+
+    Returns:
+        A tuple of data for IPv6 reassembly.
+
+        * If the ``frame`` can be used for IPv6 reassembly. A frame can be reassembled
+          if it contains IPv6 layer (:class:`~pcapkit.protocols.internet.ipv6.IPv6`) and
+          IPv6 Fragment header (:rfc:`2460#section-4.5`, i.e.,
+          :class:`~pcapkit.protocols.internet.ipv6_frag.IPv6_Frag`).
+        * If the ``frame`` can be reassembled, then the :obj:`dict` mapping of data for IPv6
+          reassembly (:term:`reasm.ipv6.packet`) will be returned; otherwise, returns :data:`None`.
+
+    See Also:
+        :class:`pcapkit.foundation.reassembly.ipv6.IPv6`
+
+    """
+    if 'IPv6' in frame:
+        ipv6 = cast('IPv6', frame['IPv6'])
+        ipv6_info = ipv6.info
+        if (ipv6_frag := ipv6.extension_headers.get(  # type: ignore[call-overload]
+            Enum_ExtensionHeader.IPv6_Frag
+        )) is None:  # dismiss not fragmented frame
+            return None
+        ipv6_frag_info = cast('IPv6_Frag', ipv6_frag).info
+
+        frame_info = cast('Packet', frame.info)
+        data = IP_Packet(
+            bufid=(
+                ipv6_info.src,                              # source IP address
+                ipv6_info.dst,                              # destination IP address
+                ipv6_info.label,                            # label
+                ipv6_frag_info.next,                        # next header field in IPv6 Fragment Header
+            ),
+            num=frame_info.number,                          # original packet range number
+            fo=ipv6_frag_info.offset,                       # fragment offset
+            ihl=ipv6_info.hdr_len,                          # header length, only headers before IPv6-Frag
+            mf=ipv6_frag_info.mf,                           # more fragment flag
+            tl=ipv6_info.hdr_len + ipv6_info.raw_len,       # total length, header includes
+            header=ipv6_info.fragment.header,               # raw bytearray type header before IPv6-Frag
+            payload=bytearray(ipv6_info.fragment.payload),  # raw bytearray type payload after IPv6-Frag
+        )
+        return data
+    return None
+
+
+def tcp_reassembly(frame: 'PCAPNG') -> 'TCP_Packet | None':
+    """Make data for TCP reassembly.
+
+    Args:
+        frame: PCAP-NG frame.
+
+    Returns:
+        A tuple of data for TCP reassembly.
+
+        * If the ``frame`` can be used for TCP reassembly. A frame can be reassembled
+          if it contains TCP layer (:class:`~pcapkit.protocols.transport.tcp.TCP`).
+        * If the ``frame`` can be reassembled, then the :obj:`dict` mapping of data for TCP
+          reassembly (:term:`reasm.tcp.packet`) will be returned; otherwise, returns :data:`None`.
+
+    See Also:
+        :class:`pcapkit.foundation.reassembly.tcp.TCP`
+
+    """
+    if 'TCP' in frame:
+        ip = cast('IPv4 | IPv6', frame['IP'])
+        ip_info = ip.info
+        tcp = cast('TCP', frame['TCP'])
+        tcp_info = tcp.info
+
+        raw_len = len(tcp.packet.payload)
+        frame_info = cast('Packet', frame.info)
+
+        data = TCP_Packet(
+            bufid=(
+                ip_info.src,                        # source IP address
+                tcp_info.srcport.port,              # source port
+                ip_info.dst,                        # destination IP address
+                tcp_info.dstport.port,              # destination port
+            ),
+            num=frame_info.number,                  # original packet range number
+            ack=tcp_info.ack,                       # acknowledgement
+            dsn=tcp_info.seq,                       # data sequence number
+            syn=tcp_info.flags.syn,                 # synchronise flag
+            fin=tcp_info.flags.fin,                 # finish flag
+            rst=tcp_info.flags.rst,                 # reset connection flag
+            header=tcp.packet.header,               # raw bytes type header
+            payload=bytearray(tcp.packet.payload),  # raw bytearray type payload
+            first=tcp_info.seq,                     # this sequence number
+            last=tcp_info.seq + raw_len,            # next (wanted) sequence number
+            len=raw_len,                            # payload length, header excludes
+        )
+        return data
+    return None
+
+
+def tcp_traceflow(frame: 'PCAPNG', *, nanosecond: 'bool' = False) -> 'TF_TCP_Packet | None':
+    """Trace packet flow for TCP.
+
+    Args:
+        frame: PCAP-NG frame.
+        nanosecond: Whether to use nanosecond precision.
+
+    Returns:
+        Data for TCP reassembly.
+
+        * If the ``packet`` can be used for TCP flow tracing. A frame can be reassembled
+          if it contains TCP layer (:class:`~pcapkit.protocols.transport.tcp.TCP`).
+        * If the ``frame`` can be reassembled, then the :obj:`dict` mapping of data for TCP
+          flow tracing (:term:`trace.tcp.packet`) will be returned; otherwise, returns :data:`None`.
+
+    See Also:
+        :class:`pcapkit.foundation.traceflow.tcp.TCP`
+
+    """
+    if 'TCP' in frame:
+        ip = cast('IPv4 | IPv6', frame['IP'])
+        ip_info = ip.info
+        tcp = cast('TCP', frame['TCP'])
+        tcp_info = tcp.info
+
+        frame_info = cast('Packet', frame.info)
+        data = TF_TCP_Packet(  # type: ignore[type-var]
+            protocol=frame.linktype,                 # data link type from global header
+            index=frame_info.number,                 # frame number
+            frame=block2frame(frame_info, nanosecond=nanosecond),
+                                                     # extracted frame info
+            syn=tcp_info.flags.syn,                  # TCP synchronise (SYN) flag
+            fin=tcp_info.flags.fin,                  # TCP finish (FIN) flag
+            src=ip_info.src,                         # source IP
+            dst=ip_info.dst,                         # destination IP
+            srcport=tcp_info.srcport.port,           # TCP source port
+            dstport=tcp_info.dstport.port,           # TCP destination port
+            timestamp=float(frame_info.timestamp_epoch),  # frame timestamp
+        )
+        return data
+    return None
+
+
+def block2frame(block: 'Packet', *, nanosecond: 'bool' = False) -> 'Data_Frame':
+    """Convert PCAP-NG block to PCAP frame.
+
+    Args:
+        block: PCAP-NG block.
+        nanosecond: Whether to use nanosecond precision.
+
+    Returns:
+        PCAP frame.
+
+    """
+    ts_sec = int(block.timestamp_epoch)
+    ts_usec = int(block.timestamp_epoch - ts_sec) * (1_000_000_000 if nanosecond else 1_000_000)
+
+    frame = Data_Frame(
+        frame_info=Data_FrameInfo(
+            ts_sec=ts_sec,
+            ts_usec=ts_usec,
+            incl_len=block.captured_len,
+            orig_len=block.original_len,
+        ),
+        time=block.timestamp,
+        number=block.number,
+        time_epoch=block.timestamp_epoch,
+        len=block.original_len,
+        cap_len=block.captured_len,
+    )
+    frame.__update__(packet=block.packet)
+    return frame

pcapkit/toolkit/pyshark.py

@@ -0,0 +1,99 @@
+# -*- coding: utf-8 -*-
+"""PyShark Tools
+===================
+
+:mod:`pcapkit.toolkit.pyshark` contains all you need for
+:mod:`pcapkit` handy usage with `PyShark`_ engine. All
+reforming functions returns with a flag to indicate if
+usable for its caller.
+
+.. _PyShark: https://kiminewt.github.io/pyshark
+
+.. note::
+
+   Due to the lack of functionality of `PyShark`_, some
+   functions of :mod:`pcapkit` may not be available with
+   the `PyShark`_ engine.
+
+"""
+import ipaddress
+from typing import TYPE_CHECKING, cast
+
+from pcapkit.const.reg.linktype import LinkType as Enum_LinkType
+from pcapkit.foundation.traceflow.data.tcp import Packet as TF_TCP_Packet
+
+if TYPE_CHECKING:
+    from typing import Any
+
+    from pyshark.packet.packet import Packet
+
+__all__ = ['packet2dict', 'tcp_traceflow']
+
+
+def packet2dict(packet: 'Packet') -> 'dict[str, Any]':
+    """Convert PyShark packet into :obj:`dict`.
+
+    Args:
+        packet: Scapy packet.
+
+    Returns:
+        A :obj:`dict` mapping of packet data.
+
+    """
+    dict_ = {}  # type: dict[str, Any]
+    frame = packet.frame_info
+    for field in frame.field_names:
+        dict_[field] = getattr(frame, field)
+
+    tempdict = dict_
+    for layer in packet.layers:
+        tempdict[layer.layer_name.upper()] = {}
+        tempdict = tempdict[layer.layer_name.upper()]
+        for field in layer.field_names:
+            tempdict[field] = getattr(layer, field)
+
+    return dict_
+
+
+def tcp_traceflow(packet: 'Packet') -> 'TF_TCP_Packet | None':
+    """Trace packet flow for TCP.
+
+    Args:
+        packet: Scapy packet.
+
+    Returns:
+        Tuple[bool, Dict[str, Any]]: A tuple of data for TCP reassembly.
+
+        * If the ``packet`` can be used for TCP flow tracing. A packet can be reassembled
+          if it contains TCP layer.
+        * If the ``packet`` can be reassembled, then the :obj:`dict` mapping of data for TCP
+          flow tracing (:term:`trace.tcp.packet`) will be returned; otherwise, returns :data:`None`.
+
+    See Also:
+        :class:`pcapkit.foundation.traceflow.tcp.TCP`
+
+    """
+    if 'IP' in packet:
+        ip = cast('Packet', packet.ip)
+    elif 'IPv6' in packet:
+        ip = cast('Packet', packet.ipv6)
+    else:
+        return None
+
+    if 'TCP' in packet:
+        tcp = cast('Packet', packet.tcp)
+
+        data = TF_TCP_Packet(  # type: ignore[type-var]
+            protocol=Enum_LinkType.get(packet.layers[0].layer_name.upper()),  # data link type from global header
+            index=int(packet.number),                                            # frame number
+            frame=packet2dict(packet),                                           # extracted packet
+            syn=bool(int(tcp.flags_syn)),                                        # TCP synchronise (SYN) flag
+            fin=bool(int(tcp.flags_fin)),                                        # TCP finish (FIN) flag
+            src=ipaddress.ip_address(ip.src),                                    # source IP
+            dst=ipaddress.ip_address(ip.dst),                                    # destination IP
+            srcport=int(tcp.srcport),                                            # TCP source port
+            dstport=int(tcp.dstport),                                            # TCP destination port
+            timestamp=packet.frame_info.time_epoch,                              # timestamp
+        )
+        return data
+    return None

pcapkit/toolkit/scapy.py

@@ -0,0 +1,297 @@
+# -*- coding: utf-8 -*-
+"""Scapy Tools
+=================
+
+.. module:: pcapkit.toolkit.scapy
+
+:mod:`pcapkit.toolkit.scapy` contains all you need for
+:mod:`pcapkit` handy usage with `Scapy`_ engine. All reforming
+functions returns with a flag to indicate if usable for
+its caller.
+
+.. _Scapy: https://scapy.net
+
+.. warning::
+
+   This module requires installed `Scapy`_ engine.
+
+"""
+import ipaddress
+import time
+from typing import TYPE_CHECKING, cast
+
+from pcapkit.const.reg.linktype import LinkType as Enum_LinkType
+from pcapkit.const.reg.transtype import TransType as Enum_TransType
+from pcapkit.foundation.reassembly.data.ip import Packet as IP_Packet
+from pcapkit.foundation.reassembly.data.tcp import Packet as TCP_Packet
+from pcapkit.foundation.traceflow.data.tcp import Packet as TF_TCP_Packet
+from pcapkit.utilities.compat import ModuleNotFoundError  # pylint: disable=redefined-builtin
+from pcapkit.utilities.exceptions import ModuleNotFound, stacklevel
+from pcapkit.utilities.warnings import ScapyWarning, warn
+
+try:
+    import scapy
+except ModuleNotFoundError:
+    scapy = None
+    warn("dependency package 'Scapy' not found",
+         ScapyWarning, stacklevel=stacklevel())
+
+if TYPE_CHECKING:
+    from ipaddress import IPv4Address, IPv6Address
+    from typing import Any
+
+    from scapy.layers.inet import IP, TCP
+    from scapy.layers.inet6 import IPv6
+    from scapy.packet import Packet
+
+__all__ = [
+    'packet2chain', 'packet2dict',
+    'ipv4_reassembly', 'ipv6_reassembly', 'tcp_reassembly', 'tcp_traceflow'
+]
+
+
+def packet2chain(packet: 'Packet') -> 'str':
+    """Fetch Scapy packet protocol chain.
+
+    Args:
+        packet: Scapy packet.
+
+    Returns:
+        Colon (``:``) seperated list of protocol chain.
+
+    Raises:
+        ModuleNotFound: If `Scapy`_ is not installed.
+
+    """
+    if scapy is None:
+        raise ModuleNotFound("No module named 'scapy'", name='scapy')
+    from scapy.packet import NoPayload
+
+    chain = [packet.name]
+    payload = packet.payload
+    while not isinstance(payload, NoPayload):
+        chain.append(payload.name)
+        payload = payload.payload
+    return ':'.join(chain)
+
+
+def packet2dict(packet: 'Packet') -> 'dict[str, Any]':
+    """Convert Scapy packet into :obj:`dict`.
+
+    Args:
+        packet: Scapy packet.
+
+    Returns:
+        A :obj:`dict` mapping of packet data.
+
+    Raises:
+        ModuleNotFound: If `Scapy`_ is not installed.
+
+    """
+    if scapy is None:
+        raise ModuleNotFound("No module named 'scapy'", name='scapy')
+    from scapy.packet import NoPayload
+
+    def wrapper(packet: 'Packet') -> 'dict[str, Any]':
+        dict_ = packet.fields
+        payload = packet.payload
+        if not isinstance(payload, NoPayload):
+            dict_[payload.name] = wrapper(payload)
+        return dict_
+
+    return {
+        'packet': bytes(packet),
+        packet.name: wrapper(packet),
+    }
+
+
+def ipv4_reassembly(packet: 'Packet', *, count: 'int' = -1) -> 'IP_Packet[IPv4Address] | None':
+    """Make data for IPv4 reassembly.
+
+    Args:
+        packet: Scapy packet.
+        count: Packet index. If not provided, default to ``-1``.
+
+    Returns:
+        Data for IPv4 reassembly.
+
+        * If the ``packet`` can be used for IPv4 reassembly. A packet can be reassembled
+          if it contains IPv4 layer (:class:`scapy.layers.inet.IP`) and the **DF**
+          (:attr:`scapy.layers.inet.IP.flags.DF`) flag is :data:`False`.
+        * If the ``packet`` can be reassembled, then the :obj:`dict` mapping of data for IPv4
+          reassembly (:term:`reasm.ipv4.packet`) will be returned; otherwise, returns :data:`None`.
+
+    See Also:
+        :class:`pcapkit.foundation.reassembly.ipv4.IPv4`
+
+    """
+    if 'IP' in packet:
+        ipv4 = cast('IP', packet['IP'])
+        if ipv4.flags.DF:       # dismiss not fragmented packet
+            return None
+
+        data = IP_Packet(
+            bufid=(
+                cast('IPv4Address',
+                     ipaddress.ip_address(ipv4.src)),  # source IP address
+                cast('IPv4Address',
+                     ipaddress.ip_address(ipv4.dst)),  # destination IP address
+                ipv4.id,                               # identification
+                Enum_TransType.get(ipv4.proto),     # payload protocol type
+            ),
+            num=count,                                 # original packet range number
+            fo=ipv4.frag,                              # fragment offset
+            ihl=ipv4.ihl,                              # internet header length
+            mf=bool(ipv4.flags.MF),                    # more fragment flag
+            tl=ipv4.len,                               # total length, header includes
+            header=ipv4.raw_packet_cache,              # raw bytes type header
+            payload=bytearray(bytes(ipv4.payload)),    # raw bytearray type payload
+        )
+        return data
+    return None
+
+
+def ipv6_reassembly(packet: 'Packet', *, count: 'int' = -1) -> 'IP_Packet[IPv6Address] | None':
+    """Make data for IPv6 reassembly.
+
+    Args:
+        packet: Scapy packet.
+        count: Packet index. If not provided, default to ``-1``.
+
+    Returns:
+        Data for IPv6 reassembly.
+
+        * If the ``packet`` can be used for IPv6 reassembly. A packet can be reassembled
+          if it contains IPv6 layer (:class:`scapy.layers.inet6.IPv6`) and IPv6 Fragment
+          header (:rfc:`2460#section-4.5`, i.e., :class:`scapy.layers.inet6.IPv6ExtHdrFragment`).
+        * If the ``packet`` can be reassembled, then the :obj:`dict` mapping of data for IPv6
+          reassembly (:term:`reasm.ipv6.packet`) will be returned; otherwise, returns :data:`None`.
+
+    Raises:
+        ModuleNotFound: If `Scapy`_ is not installed.
+
+    See Also:
+        :class:`pcapkit.foundation.reassembly.ipv6.IPv6`
+
+    """
+    if scapy is None:
+        raise ModuleNotFound("No module named 'scapy'", name='scapy')
+    from scapy.layers.inet6 import IPv6ExtHdrFragment
+
+    if 'IPv6' in packet:
+        ipv6 = cast('IPv6', packet['IPv6'])
+        if IPv6ExtHdrFragment not in ipv6:  # pylint: disable=E1101
+            return None                        # dismiss not fragmented packet
+        ipv6_frag = cast('IPv6ExtHdrFragment', ipv6['IPv6ExtHdrFragment'])
+
+        data = IP_Packet(
+            bufid=(
+                cast('IPv6Address',
+                     ipaddress.ip_address(ipv6.src)),     # source IP address
+                cast('IPv6Address',
+                     ipaddress.ip_address(ipv6.dst)),     # destination IP address
+                ipv6.fl,                                  # label
+                Enum_TransType.get(ipv6_frag.nh),      # next header field in IPv6 Fragment Header
+            ),
+            num=count,                                    # original packet range number
+            fo=ipv6_frag.offset,                          # fragment offset
+            ihl=len(ipv6) - len(ipv6_frag),               # header length, only headers before IPv6-Frag
+            mf=bool(ipv6_frag.m),                         # more fragment flag
+            tl=len(ipv6),                                 # total length, header includes
+            header=bytes(ipv6)[:-len(ipv6_frag)],         # raw bytes type header before IPv6-Frag
+            payload=bytearray(bytes(ipv6_frag.payload)),  # raw bytearray type payload after IPv6-Frag
+        )
+        return data
+    return None
+
+
+def tcp_reassembly(packet: 'Packet', *, count: 'int' = -1) -> 'TCP_Packet | None':
+    """Store data for TCP reassembly.
+
+    Args:
+        packet: Scapy packet.
+        count: Packet index. If not provided, default to ``-1``.
+
+    Returns:
+        Data for TCP reassembly.
+
+        * If the ``packet`` can be used for TCP reassembly. A packet can be reassembled
+          if it contains TCP layer (:class:`scapy.layers.inet.TCP`).
+        * If the ``packet`` can be reassembled, then the :obj:`dict` mapping of data for TCP
+          reassembly (:term:`reasm.tcp.packet`) will be returned; otherwise, returns :data:`None`.
+
+    See Also:
+        :class:`pcapkit.foundation.reassembly.tcp.TCP`
+
+    """
+    if 'IP' in packet:
+        ip = cast('IP', packet['IP'])
+    elif 'IPv6' in packet:
+        ip = cast('IPv6', packet['IPv6'])
+    else:
+        return None
+
+    if 'TCP' in packet:
+        tcp = cast('TCP', packet['TCP'])
+
+        raw_len = len(tcp.payload)                  # payload length, header excludes
+        data = TCP_Packet(
+            bufid=(
+                ipaddress.ip_address(ip.src),       # source IP address
+                tcp.sport,                          # source port
+                ipaddress.ip_address(ip.dst),       # destination IP address
+                tcp.dport,                          # destination port
+            ),
+            num=count,                              # original packet range number
+            ack=tcp.ack,                            # acknowledgement
+            dsn=tcp.seq,                            # data sequence number
+            syn=bool(tcp.flags.S),                  # synchronise flag
+            fin=bool(tcp.flags.F),                  # finish flag
+            rst=bool(tcp.flags.R),                  # reset connection flag
+            header=tcp.raw_packet_cache,            # raw bytes type header
+            payload=bytearray(bytes(tcp.payload)),  # raw bytearray type payload
+            first=tcp.seq,                          # this sequence number
+            last=tcp.seq + raw_len,                 # next (wanted) sequence number
+            len=raw_len,                            # payload length, header excludes
+        )
+        return data
+    return None
+
+
+def tcp_traceflow(packet: 'Packet', *, count: 'int' = -1) -> 'TF_TCP_Packet | None':
+    """Trace packet flow for TCP.
+
+    Args:
+        packet: Scapy packet.
+        count: Packet index. If not provided, default to ``-1``.
+
+    Returns:
+        Data for TCP reassembly.
+
+        * If the ``packet`` can be used for TCP flow tracing. A packet can be reassembled
+          if it contains TCP layer (:class:`scapy.layers.inet.TCP`).
+        * If the ``packet`` can be reassembled, then the :obj:`dict` mapping of data for TCP
+          flow tracing (:term:`trace.tcp.packet`) will be returned; otherwise, returns :data:`None`.
+
+    See Also:
+        :class:`pcapkit.foundation.traceflow.tcp.TCP`
+
+    """
+    if 'TCP' in packet:
+        ip = cast('IP', packet['IP']) if 'IP' in packet else cast('IPv6', packet['IPv6'])
+        tcp = cast('TCP', packet['TCP'])
+
+        data = TF_TCP_Packet(  # type: ignore[type-var]
+            protocol=Enum_LinkType.get(packet.name.upper()),  # data link type from global header
+            index=count,                                         # frame number
+            frame=packet2dict(packet),                           # extracted packet
+            syn=bool(tcp.flags.S),                               # TCP synchronise (SYN) flag
+            fin=bool(tcp.flags.F),                               # TCP finish (FIN) flag
+            src=ipaddress.ip_address(ip.src),                    # source IP
+            dst=ipaddress.ip_address(ip.dst),                    # destination IP
+            srcport=tcp.sport,                                   # TCP source port
+            dstport=tcp.dport,                                   # TCP destination port
+            timestamp=time.time(),                               # timestamp
+        )
+        return data
+    return None

pcapkit/utilities/__init__.py

@@ -0,0 +1,20 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=unused-wildcard-import
+"""Module Utilities
+======================
+
+.. module:: pcapkit.utilities
+
+:mod:`pcapkit.utilities` contains several useful functions
+and classes which are fundations of :mod:`pcapkit`, including
+decorater function :func:`~pcapkit.utilities.decorators.seekset`
+and :func:`~pcapkit.utilities.decorators.beholder`, etc., and
+several user-refined exceptions and warnings.
+
+"""
+from pcapkit.utilities.decorators import beholder, prepare, seekset
+from pcapkit.utilities.exceptions import stacklevel
+from pcapkit.utilities.logging import logger
+from pcapkit.utilities.warnings import warn
+
+__all__ = ['logger', 'warn', 'stacklevel']