pypcapkit 1.3.3.post1__cp313-none-any.whl

pcapkit/dumpkit/pcap.py

@@ -0,0 +1,144 @@
+# -*- coding: utf-8 -*-
+"""PCAP Dumper
+=================
+
+.. module:: pcapkit.dumper.pcap
+
+:mod:`pcapkit.dumpkit.pcap` is the dumper for :mod:`pcapkit` implementation,
+specifically for PCAP format, which is alike those described in
+:mod:`dictdumper`.
+
+"""
+import sys
+from typing import TYPE_CHECKING
+
+from pcapkit.dumpkit.common import DumperBase as Dumper
+from pcapkit.protocols.data.misc.pcap.header import Header as Data_Header
+from pcapkit.protocols.misc.pcap.frame import Frame
+from pcapkit.protocols.misc.pcap.header import Header
+
+if TYPE_CHECKING:
+    from enum import IntEnum as StdlibIntEnum
+    from typing import IO, Any, Optional
+
+    from aenum import IntEnum as AenumIntEnum
+    from typing_extensions import Literal
+
+    from pcapkit.const.reg.linktype import LinkType as Enum_LinkType
+    from pcapkit.protocols.data.misc.pcap.frame import Frame as Data_Frame
+
+__all__ = [
+    'PCAPIO',
+]
+
+
+class PCAPIO(Dumper):
+    """PCAP file dumper.
+
+    Args:
+        fname: output file name
+        protocol: data link type
+        byteorder: header byte order
+        nanosecond: nanosecond-resolution file flag
+        **kwargs: arbitrary keyword arguments
+
+    """
+    if TYPE_CHECKING:
+        #: PCAP file global header.
+        _ghdr: 'Data_Header'
+
+    ##########################################################################
+    # Properties.
+    ##########################################################################
+
+    @property
+    def kind(self) -> 'Literal["pcap"]':
+        """File format of current dumper."""
+        return 'pcap'
+
+    ##########################################################################
+    # Data models.
+    ##########################################################################
+
+    def __init__(self, fname: 'str', *, protocol: 'Enum_LinkType | StdlibIntEnum | AenumIntEnum | str | int',
+                 byteorder: 'Literal["big", "little"]' = sys.byteorder,
+                 nanosecond: 'bool' = False, **kwargs: 'Any') -> 'None':  # pylint: disable=arguments-differ
+        """Initialise dumper.
+
+        Args:
+            fname: output file name
+            protocol: data link type
+            byteorder: header byte order
+            nanosecond: nanosecond-resolution file flag
+            **kwargs: arbitrary keyword arguments
+
+        """
+        #: int: Frame counter.
+        self._fnum = 1
+        #: bool: Nanosecond-resolution file flag.
+        self._nsec = nanosecond
+        #: Enum_LinkType | StdlibIntEnum | AenumIntEnum | str | int: Data link type.
+        self._link = protocol
+
+        super().__init__(fname, protocol=protocol, byteorder=byteorder, nanosecond=nanosecond, **kwargs)
+
+    def __call__(self, value: 'Data_Frame', name: 'Optional[str]' = None) -> 'PCAPIO':
+        """Dump a new frame.
+
+        Args:
+            value: content to be dumped
+            name: name of current content block
+
+        Returns:
+            The dumper class itself (to support chain calling).
+
+        """
+        with open(self._file, 'ab') as file:
+            self._append_value(value, file, name or '')
+        return self
+
+    ##########################################################################
+    # Utilities.
+    ##########################################################################
+
+    def _dump_header(self, *, protocol: 'Enum_LinkType | StdlibIntEnum | AenumIntEnum | str | int',  # pylint: disable=arguments-differ
+                     byteorder: 'Literal["big", "little"]' = sys.byteorder, nanosecond: 'bool' = False,
+                     **kwargs: 'Any') -> 'None':  # pylint: disable=unused-argument
+        """Initially dump file heads and tails.
+
+        Args:
+            protocol: data link type
+            byteorder: header byte order
+            nanosecond: nanosecond-resolution file flag
+            **kwargs: arbitrary keyword arguments
+
+        """
+        header = Header(
+            network=protocol,
+            byteorder=byteorder,
+            nanosecond=nanosecond,
+        )
+        packet = header.data
+        with open(self._file, 'wb') as file:
+            file.write(packet)
+        self._ghdr = header.info
+
+    def _append_value(self, value: 'Data_Frame', file: 'IO[bytes]', name: 'str') -> 'None':  # pylint: disable=unused-argument
+        """Call this function to write contents.
+
+        Args:
+            value: content to be dumped
+            file: output file
+            name: name of current content block
+
+        """
+        packet = Frame(
+            nanosecond=self._nsec,
+            num=self._fnum,
+            proto=self._link,
+            packet=value.packet,
+            header=self._ghdr,
+            **value.frame_info,
+        ).data
+        file.write(packet)
+        self._fnum += 1

pcapkit/foundation/__init__.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=unused-import, unused-wildcard-import
+"""Library Foundation
+========================
+
+.. module:: pcapkit.foundation
+
+:mod:`pcapkit.foundation` is a collection of foundations for
+:mod:`pcapkit`, including PCAP file extraction tool
+:class:`~pcapkit.foundation.extraction.Extrator`, flow tracing
+:mod:`~pcapkit.foundation.tractflow`, registry management
+APIs for :mod:`pcapkit`, and TCP/IP reassembly implementations.
+
+"""
+from pcapkit.foundation.extraction import Extractor
+from pcapkit.foundation.reassembly import *
+from pcapkit.foundation.registry import *
+from pcapkit.foundation.traceflow import *
+
+__all__ = [
+    'Extractor',
+
+    'IPv4_Reassembly', 'IPv6_Reassembly', 'TCP_Reassembly',
+
+    'TCP_TraceFlow',
+
+    'register_protocol',
+    'register_linktype',
+    'register_pcap', 'register_pcapng',
+    'register_ethertype',
+    'register_transtype',
+    'register_ipv4_option', 'register_hip_parameter', 'register_hopopt_option',
+    'register_ipv6_opts_option', 'register_ipv6_route_routing',
+    'register_mh_message', 'register_mh_option', 'register_mh_extension',
+    'register_apptype',
+    'register_tcp', 'register_udp',
+    'register_tcp_option', 'register_tcp_mp_option',
+    'register_http_frame',
+    'register_pcapng_block', 'register_pcapng_option', 'register_pcapng_secrets',
+    'register_pcapng_record',
+
+    'register_extractor_engine',
+    'register_dumper',
+    'register_extractor_dumper', 'register_traceflow_dumper',
+]

pcapkit/foundation/engines/__init__.py

@@ -0,0 +1,36 @@
+# -*- coding: utf-8 -*-
+"""Engine Support
+====================
+
+.. module:: pcapkit.foundation.engines
+
+:mod:`pcapkit.foundation.engines` is a collection of engines
+support for :mod:`pcapkit`, including but not limited to the
+built-in PCAP and `PCAP-NG`_ file support, :mod:`Scapy <scapy>`,
+:mod:`PyShark <pyshark>`, :mod:`DPKT <dpkt>` 3rd party engine
+support.
+
+.. todo::
+
+   Implement support for `PCAP-NG`_ file format.
+
+.. _PCAPNG: https://wiki.wireshark.org/Development/PcapNg
+
+"""
+# Base class
+from pcapkit.foundation.engines.engine import Engine
+
+# Built-in engines
+from pcapkit.foundation.engines.pcap import PCAP
+from pcapkit.foundation.engines.pcapng import PCAPNG
+
+# 3rd party engines
+from pcapkit.foundation.engines.scapy import Scapy
+from pcapkit.foundation.engines.dpkt import DPKT
+from pcapkit.foundation.engines.pyshark import PyShark
+
+__all__ = [
+    'PCAP', 'PCAPNG',
+
+    'Scapy', 'DPKT', 'PyShark',
+]

pcapkit/foundation/engines/dpkt.py

@@ -0,0 +1,230 @@
+# -*- coding: utf-8 -*-
+"""DPKT Support
+==================
+
+.. module:: pcapkit.foundation.engines.dpkt
+
+This module contains the implementation for `DPKT`_ engine
+support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
+
+.. _DPKT: https://dpkt.readthedocs.io
+
+"""
+from typing import TYPE_CHECKING, cast
+
+from pcapkit.const.reg.linktype import LinkType as Enum_LinkType
+from pcapkit.foundation.engines.engine import EngineBase as Engine
+from pcapkit.utilities.exceptions import FormatError, stacklevel
+from pcapkit.utilities.warnings import AttributeWarning, DPKTWarning, warn
+
+__all__ = ['DPKT']
+
+if TYPE_CHECKING:
+    from typing import Optional, Type, Union
+
+    from dpkt.dpkt import Packet as DPKTPacket
+    from dpkt.pcap import Reader as PCAPReader
+    from dpkt.pcapng import Reader as PCAPNGReader
+
+    from pcapkit.foundation.extraction import Extractor
+
+    Reader = Union[PCAPReader, PCAPNGReader]
+
+
+class DPKT(Engine['DPKTPacket']):
+    """DPKT engine support.
+
+    Args:
+        extractor: :class:`~pcapkit.foundation.extraction.Extractor` instance.
+
+    """
+    if TYPE_CHECKING:
+        import dpkt
+
+        #: Engine extraction package.
+        _expkg: 'dpkt'
+        #: Engine extraction temporary storage.
+        _extmp: 'Reader'
+
+    ##########################################################################
+    # Defaults.
+    ##########################################################################
+
+    #: Engine name.
+    __engine_name__ = 'DPKT'
+
+    #: Engine module name.
+    __engine_module__ = 'dpkt'
+
+    ##########################################################################
+    # Data models.
+    ##########################################################################
+
+    def __init__(self, extractor: 'Extractor') -> 'None':
+        import dpkt  # isort:skip
+
+        self._expkg = dpkt
+        self._extmp = cast('Reader', None)
+
+        super().__init__(extractor)
+
+    ##########################################################################
+    # Methods.
+    ##########################################################################
+
+    def run(self) -> 'None':
+        """Call :class:`dpkt.pcap.Reader` to extract PCAP files.
+
+        This method assigns :attr:`self._expkg <DPKT._expkg>`
+        as :mod:`dpkt` and :attr:`self._extmp <DPKT._extmp>`
+        as an iterator from :class:`dpkt.pcap.Reader`.
+
+        Warns:
+            AttributeWarning: If :attr:`self.extractor._exlyr <pcapkit.foundation.extraction.Extractor._exlyr>`
+                and/or :attr:`self.extractor._exptl <pcapkit.foundation.extraction.Extractor._exptl>`
+                is provided as the DPKT engine currently does not support such operations.
+
+        Raises:
+            FormatError: If the file format is not supported, i.e., not a PCAP
+                and/or PCAP-NG file.
+
+        """
+        from pcapkit.foundation.engines.pcap import PCAP
+        from pcapkit.foundation.engines.pcapng import PCAPNG
+
+        ext = self._extractor
+        dpkt = self._expkg
+
+        if ext._exlyr != 'none' or ext._exptl != 'null':
+            warn("'Extractor(engine=dpkt)' does not support protocol and layer threshold; "
+                 f"'layer={ext._exlyr}' and 'protocol={ext._exptl}' ignored",
+                 AttributeWarning, stacklevel=stacklevel())
+
+        # setup verbose handler
+        if ext._flag_v:
+            from pcapkit.toolkit.dpkt import packet2chain  # isort:skip
+            ext._vfunc = lambda e, f: print(
+                f'Frame {e._frnum:>3d}: {packet2chain(f)}'  # pylint: disable=protected-access
+            )  # pylint: disable=logging-fstring-interpolation
+
+        if ext.magic_number in PCAP.MAGIC_NUMBER:
+            reader = dpkt.pcap.Reader(ext._ifile)
+        elif ext.magic_number in PCAPNG.MAGIC_NUMBER:
+            reader = dpkt.pcapng.Reader(ext._ifile)
+        else:
+            raise FormatError(f'unsupported file format: {ext.magic_number!r}')
+
+        # extract & analyse file
+        self._extmp = reader
+
+    def read_frame(self) -> 'DPKTPacket':
+        """Read frames with DPKT engine.
+
+        Returns:
+            Parsed frame instance.
+
+        See Also:
+            Please refer to :meth:`PCAP.read_frame <pcapkit.foundation.engines.pcap.PCAP.read_frame>`
+            for more operational information.
+
+        """
+        from pcapkit.toolkit.dpkt import (ipv4_reassembly, ipv6_reassembly, packet2dict,
+                                          tcp_reassembly, tcp_traceflow)
+        ext = self._extractor
+
+        reader = self._extmp
+        linktype = Enum_LinkType.get(reader.datalink())
+
+        # fetch DPKT packet
+        timestamp, pkt = cast('tuple[float, bytes]', next(reader))
+        protocol = self._get_protocol(linktype)
+        packet = protocol(pkt)  # type: DPKTPacket
+
+        # verbose output
+        ext._frnum += 1
+        ext._vfunc(ext, packet)
+
+        # write plist
+        frnum = f'Frame {ext._frnum}'
+        if not ext._flag_q:
+            info = packet2dict(packet, timestamp, data_link=linktype)
+            if ext._flag_f:
+                ofile = ext._ofile(f'{ext._ofnm}/{frnum}.{ext._fext}')
+                ofile(info, name=frnum)
+            else:
+                ext._ofile(info, name=frnum)
+                ofile = ext._ofile
+            ext._offmt = ofile.kind
+
+        # record fragments
+        if ext._flag_r:
+            if ext._ipv4:
+                data_ipv4 = ipv4_reassembly(packet, count=ext._frnum)
+                if data_ipv4 is not None:
+                    ext._reasm.ipv4(data_ipv4)
+            if ext._ipv6:
+                data_ipv6 = ipv6_reassembly(packet, count=ext._frnum)
+                if data_ipv6 is not None:
+                    ext._reasm.ipv6(data_ipv6)
+            if ext._tcp:
+                data_tcp = tcp_reassembly(packet, count=ext._frnum)
+                if data_tcp is not None:
+                    ext._reasm.tcp(data_tcp)
+
+        # trace flows
+        if ext._flag_t:
+            if ext._tcp:
+                data_tf_tcp = tcp_traceflow(packet, timestamp, data_link=linktype, count=ext._frnum)
+                if data_tf_tcp is not None:
+                    ext._trace.tcp(data_tf_tcp)
+
+        # record frames
+        if ext._flag_d:
+            # setattr(packet, 'packet2dict', packet2dict)
+            # setattr(packet, 'packet2chain', packet2chain)
+            ext._frame.append(packet)
+
+        # return frame record
+        return packet
+
+    ##########################################################################
+    # Utilities.
+    ##########################################################################
+
+    def _get_protocol(self, linktype: 'Optional[Enum_LinkType]' = None) -> 'Type[DPKTPacket]':
+        """Returns the protocol for parsing the current packet.
+
+        Args:
+            linktype: Link type code.
+
+        """
+        dpkt = self._expkg
+        reader = self._extmp
+
+        if linktype is None:
+            linktype = Enum_LinkType.get(reader.datalink())
+
+        if linktype == Enum_LinkType.ETHERNET:
+            pkg = dpkt.ethernet.Ethernet
+        elif linktype.value == Enum_LinkType.IPV4:
+            pkg = dpkt.ip.IP
+        elif linktype.value == Enum_LinkType.IPV6:
+            pkg = dpkt.ip6.IP6
+        else:
+            warn('unrecognised link layer protocol; all analysis functions ignored',
+                 DPKTWarning, stacklevel=stacklevel())
+
+            class RawPacket(dpkt.dpkt.Packet):  # type: ignore[name-defined]
+                """Raw packet."""
+
+                def __len__(ext) -> 'int':
+                    return len(ext.data)
+
+                def __bytes__(ext) -> 'bytes':
+                    return ext.data
+
+                def unpack(ext, buf: 'bytes') -> 'None':
+                    ext.data = buf
+
+            pkg = RawPacket
+        return pkg

pcapkit/foundation/engines/engine.py

@@ -0,0 +1,194 @@
+# -*- coding: utf-8 -*-
+"""Base Class
+================
+
+.. module:: pcapkit.foundation.engines.engine
+
+This is the abstract base class implementation for
+all engine support functionality.
+
+"""
+import abc
+from typing import TYPE_CHECKING, Generic, TypeVar, cast
+
+__all__ = ['Engine']
+
+if TYPE_CHECKING:
+    from typing import Any, Optional
+
+    from pcapkit.foundation.extraction import Extractor
+
+_T = TypeVar('_T')
+
+
+class EngineMeta(abc.ABCMeta, Generic[_T]):
+    """Meta class to add dynamic support to :class:`EngineBase`.
+
+    This meta class is used to generate necessary attributes for the
+    :class:`EngineBase` class. It can be useful to reduce unnecessary
+    registry calls and simplify the customisation process.
+
+    """
+    if TYPE_CHECKING:
+        #: Engine name.
+        __engine_name__: 'str'
+        #: Engine module name.
+        __engine_module__: 'str'
+
+    @property
+    def name(cls) -> 'str':
+        """Engine name."""
+        if hasattr(cls, '__engine_name__'):
+            return cls.__engine_name__
+        return cls.__name__
+
+    @property
+    def module(cls) -> 'str':
+        """Engine module name."""
+        if hasattr(cls, '__engine_module__'):
+            return cls.__engine_module__
+        return cls.__module__
+
+
+class EngineBase(Generic[_T], metaclass=EngineMeta):
+    """Base class for engine support.
+
+    Args:
+        extractor: :class:`~pcapkit.foundation.extraction.Extractor` instance.
+
+    Note:
+        This class is for internal use only. For customisation, please use
+        :class:`Engine` instead.
+
+    """
+    if TYPE_CHECKING:
+        #: Engine name.
+        __engine_name__: 'str'
+        #: Engine module name.
+        __engine_module__: 'str'
+
+    ##########################################################################
+    # Properties.
+    ##########################################################################
+
+    @property
+    def name(self) -> 'str':
+        """Engine name.
+
+        Note:
+            This property is not available as a class
+            attribute.
+
+        """
+        if hasattr(self, '__engine_name__'):
+            return self.__engine_name__
+        return type(self).name  # type: ignore[return-value]
+
+    @property
+    def module(self) -> 'str':
+        """Engine module name.
+
+        Note:
+            This property is not available as a class
+            attribute.
+
+        """
+        if hasattr(self, '__engine_module__'):
+            return self.__engine_module__
+        return type(self).module  # type: ignore[return-value]
+
+    @property
+    def extractor(self) -> 'Extractor':
+        """Extractor instance."""
+        return self._extractor
+
+    ##########################################################################
+    # Data models.
+    ##########################################################################
+
+    def __init__(self, extractor: 'Extractor') -> 'None':
+        self._extractor = extractor
+
+    def __call__(self) -> 'None':
+        """Start extraction.
+
+        This method will directly call :meth:`run` to start the
+        extraction process.
+
+        """
+        self.run()
+
+    ##########################################################################
+    # Methods.
+    ##########################################################################
+
+    @abc.abstractmethod
+    def run(self) -> 'None':
+        """Start extraction.
+
+        This method is the entry point for file extraction. It is to be used
+        for preparing the extraction process, such as parsing the file header
+        and setting up the extraction engines.
+
+        """
+
+    @abc.abstractmethod
+    def read_frame(self) -> '_T':
+        """Read frame.
+
+        This method is to be used for reading a frame from the file. It is to
+        read a frame from the file using the prepared engine instance and
+        return the parsed frame.
+
+        """
+
+    def close(self) -> 'None':
+        """Close engine.
+
+        This method is to be used for closing the engine instance. It is to
+        close the engine instance after the extraction process is finished.
+
+        """
+
+
+class Engine(EngineBase[_T], Generic[_T]):
+    """Base class for engine support.
+
+    Example:
+
+        Use keyword argument ``name`` to specify the engine name at
+        class definition:
+
+        .. code-block:: python
+
+           class MyEngine(Engine, name='my_engine'):
+               ...
+
+    Args:
+        extractor: :class:`~pcapkit.foundation.extraction.Extractor` instance.
+
+    """
+
+    def __init_subclass__(cls, /, name: 'Optional[str]' = None, *args: 'Any', **kwargs: 'Any') -> 'None':
+        """Initialise subclass.
+
+        This method is to be used for registering the engine class to
+        :class:`~pcapkit.foundation.extraction.Extractor` class.
+
+        Args:
+            name: Engine name, default to class name.
+            *args: Arbitrary positional arguments.
+            **kwargs: Arbitrary keyword arguments.
+
+        See Also:
+            For more details, please refer to
+            :meth:`pcapkit.foundation.extraction.Extractor.register_engine`.
+
+        """
+        if name is None:
+            name = cast('str', cls.name)
+
+        from pcapkit.foundation.extraction import Extractor
+        Extractor.register_engine(name.lower(), cls)
+
+        return super().__init_subclass__()