pypcapkit 1.3.3.post1__cp313-none-any.whl

pcapkit/foundation/engines/pcap.py

@@ -0,0 +1,188 @@
+# -*- coding: utf-8 -*-
+"""PCAP Support
+==================
+
+.. module:: pcapkit.foundation.engines.pcap
+
+This module contains the implementation for PCAP file extraction
+support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
+
+"""
+from typing import TYPE_CHECKING
+
+from pcapkit.foundation.engines.engine import EngineBase as Engine
+from pcapkit.protocols.misc.pcap.frame import Frame
+from pcapkit.protocols.misc.pcap.header import Header
+
+__all__ = ['PCAP']
+
+if TYPE_CHECKING:
+    from pcapkit.const.reg.linktype import LinkType as Enum_LinkType
+    from pcapkit.corekit.version import VersionInfo
+
+
+class PCAP(Engine[Frame]):
+    """PCAP file extraction support.
+
+    Args:
+        extractor: :class:`~pcapkit.foundation.extraction.Extractor` instance.
+
+    """
+
+    if TYPE_CHECKING:
+        #: Global header.
+        _gbhdr: 'Header'
+        #: Version info.
+        _vinfo: 'VersionInfo'
+        #: Data link layer protocol.
+        _dlink: 'Enum_LinkType'
+        #: Nanosecond flag.
+        _nnsec: 'bool'
+
+    MAGIC_NUMBER = (
+        b'\xa1\xb2\x3c\x4d',
+        b'\xa1\xb2\xc3\xd4',
+        b'\x4d\x3c\xb2\xa1',
+        b'\xd4\xc3\xb2\xa1',
+    )
+
+    ##########################################################################
+    # Defaults.
+    ##########################################################################
+
+    #: Engine name.
+    __engine_name__ = 'PCAP'
+
+    #: Engine module name.
+    __engine_module__ = 'pcapkit.protocols.misc.pcap'
+
+    ##########################################################################
+    # Properties.
+    ##########################################################################
+
+    @property
+    def header(self) -> 'Header':
+        """Global header."""
+        return self._gbhdr
+
+    @property
+    def version(self) -> 'VersionInfo':
+        """Version of input PCAP file."""
+        return self._vinfo
+
+    @property
+    def dlink(self) -> 'Enum_LinkType':
+        """Data link layer protocol."""
+        return self._dlink
+
+    @property
+    def nanosecond(self) -> 'bool':
+        """Nanosecond flag."""
+        return self._nnsec
+
+    ##########################################################################
+    # Methods.
+    ##########################################################################
+
+    def run(self) -> 'None':
+        """Start extraction.
+
+        This method is the entry point for PCAP file extraction. It will start
+        the extraction process by parsing the PCAP global header and then halt
+        the extraction process until the
+        :meth:`self.extractor.record_frames <pcapkit.foundation.extraction.Extractor.record_frames>`
+        method is called.
+
+        The method will parse the PCAP global header and save the parsed result
+        as :attr:`self.header <header>`. Information such as PCAP version, data
+        link layer protocol type, nanosecond flag and byteorder will also be
+        save the current :class:`PCAP` engine instance.
+
+        For output, the method will dump the parsed PCAP global header under
+        the name of ``Global Header``.
+
+        """
+        # pylint: disable=attribute-defined-outside-init,protected-access
+        ext = self._extractor
+
+        self._gbhdr = Header(ext._ifile)
+        self._vinfo = self._gbhdr.version
+        self._dlink = self._gbhdr.protocol
+        self._nnsec = self._gbhdr.nanosecond
+
+        if ext._flag_q:
+            return
+
+        if ext._flag_f:
+            ofile = ext._ofile(f'{ext._ofnm}/Global Header.{ext._fext}')
+            ofile(self._gbhdr.info.to_dict(), name='Global Header')
+        else:
+            ext._ofile(self._gbhdr.info.to_dict(), name='Global Header')
+            ofile = ext._ofile
+        ext._offmt = ofile.kind
+
+    def read_frame(self) -> 'Frame':
+        """Read frames.
+
+        This method performs following operations:
+
+        - extract frames and each layer of packets;
+        - make :class:`~pcapkit.corekit.infoclass.Info` object out of frame properties;
+        - write to output file with corresponding dumper;
+        - reassemble IP and/or TCP datagram;
+        - trace TCP flows if any;
+        - record frame :class:`~pcapkit.corekit.infoclass.Info` object to frame storage.
+
+        Returns:
+            Parsed frame instance.
+
+        """
+        from pcapkit.toolkit.pcap import (ipv4_reassembly, ipv6_reassembly, tcp_reassembly,
+                                          tcp_traceflow)
+        ext = self._extractor
+
+        # read frame header
+        frame = Frame(ext._ifile, num=ext._frnum+1, header=self._gbhdr.info,
+                      layer=ext._exlyr, protocol=ext._exptl, nanosecond=self._nnsec)
+        ext._frnum += 1
+
+        # verbose output
+        ext._vfunc(ext, frame)
+
+        # write plist
+        frnum = f'Frame {ext._frnum}'
+        if not ext._flag_q:
+            if ext._flag_f:
+                ofile = ext._ofile(f'{ext._ofnm}/{frnum}.{ext._fext}')
+                ofile(frame.info.to_dict(), name=frnum)
+            else:
+                ext._ofile(frame.info.to_dict(), name=frnum)
+
+        # record fragments
+        if ext._flag_r:
+            if ext._ipv4:
+                data_ipv4 = ipv4_reassembly(frame)
+                if data_ipv4 is not None:
+                    ext._reasm.ipv4(data_ipv4)
+            if ext._ipv6:
+                data_ipv6 = ipv6_reassembly(frame)
+                if data_ipv6 is not None:
+                    ext._reasm.ipv6(data_ipv6)
+            if ext._tcp:
+                data_tcp = tcp_reassembly(frame)
+                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(frame, data_link=self._dlink)
+                if data_tf_tcp is not None:
+                    ext._trace.tcp(data_tf_tcp)
+
+        # record frames
+        if ext._flag_d:
+            ext._frame.append(frame)
+
+        # return frame record
+        return frame

pcapkit/foundation/engines/pcapng.py

@@ -0,0 +1,310 @@
+# -*- coding: utf-8 -*-
+"""PCAP-NG Support
+=====================
+
+.. module:: pcapkit.foundation.engines.pcapng
+
+This module contains the implementation for PCAP-NG file extraction
+support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
+
+"""
+from logging import warn
+from typing import TYPE_CHECKING, cast
+
+from pcapkit.const.pcapng.block_type import BlockType as Enum_BlockType
+from pcapkit.corekit.infoclass import Info, info_final
+from pcapkit.foundation.engines.engine import EngineBase as Engine
+from pcapkit.protocols.misc.pcapng import PCAPNG as P_PCAPNG
+from pcapkit.utilities.exceptions import FormatError, stacklevel
+from pcapkit.utilities.warnings import DeprecatedFormatWarning
+
+__all__ = ['PCAPNG']
+
+if TYPE_CHECKING:
+    from pcapkit.foundation.extraction import Extractor
+    from pcapkit.protocols.data.misc.pcapng import PCAPNG as Data_PCAPNG
+    from pcapkit.protocols.data.misc.pcapng import CustomBlock as Data_CustomBlock
+    from pcapkit.protocols.data.misc.pcapng import \
+        DecryptionSecretsBlock as Data_DecryptionSecretsBlock
+    from pcapkit.protocols.data.misc.pcapng import EnhancedPacketBlock as Data_EnhancedPacketBlock
+    from pcapkit.protocols.data.misc.pcapng import \
+        InterfaceDescriptionBlock as Data_InterfaceDescriptionBlock
+    from pcapkit.protocols.data.misc.pcapng import \
+        InterfaceStatisticsBlock as Data_InterfaceStatisticsBlock
+    from pcapkit.protocols.data.misc.pcapng import NameResolutionBlock as Data_NameResolutionBlock
+    from pcapkit.protocols.data.misc.pcapng import PacketBlock as Data_PacketBlock
+    from pcapkit.protocols.data.misc.pcapng import SectionHeaderBlock as Data_SectionHeaderBlock
+    from pcapkit.protocols.data.misc.pcapng import \
+        SystemdJournalExportBlock as Data_SystemdJournalExportBlock
+    from pcapkit.protocols.data.misc.pcapng import UnknownBlock as Data_UnknownBlock
+
+
+@info_final
+class Context(Info):
+    """Context manager for PCAP-NG file format."""
+
+    #: Section header.
+    section: 'Data_SectionHeaderBlock'
+
+    def __post_init__(self) -> None:
+        """Post initialisation hook."""
+        self.__update__(
+            interfaces=[],
+            #packets=[],
+            names=[],
+            journals=[],
+            secrets=[],
+            custom=[],
+            statistics=[],
+            unknown=[],
+        )
+
+    if TYPE_CHECKING:
+        #: Interface descriptions.
+        interfaces: 'list[Data_InterfaceDescriptionBlock]'
+        #: Packets.
+        #packets: 'list[Data_PacketBlock | Data_SimplePacketBlock | Data_EnhancedPacketBlock]'
+        #: Name resolution records.
+        names: 'list[Data_NameResolutionBlock]'
+        #: :manpage:`systemd(1)` journal export records.
+        journals: 'list[Data_SystemdJournalExportBlock]'
+        #: Decryption secrets.
+        secrets: 'list[Data_DecryptionSecretsBlock]'
+        #: Custom blocks.
+        custom: 'list[Data_CustomBlock]'
+        #: Interface statistics.
+        statistics: 'list[Data_InterfaceStatisticsBlock]'
+        #: Unknown blocks.
+        unknown: 'list[Data_UnknownBlock]'
+
+        def __init__(self, section: 'Data_SectionHeaderBlock') -> 'None': ...
+
+
+class PCAPNG(Engine[P_PCAPNG]):
+    """PCAP-NG file extraction support.
+
+    Args:
+        extractor: :class:`~pcapkit.foundation.extraction.Extractor` instance.
+
+    """
+    if TYPE_CHECKING:
+        #: Current context.
+        _ctx: 'Context'
+        #: File context storage.
+        _ctx_list: 'list[Context]'
+
+    MAGIC_NUMBER = (
+        b'\x0a\x0d\x0d\x0a',
+    )
+
+    ##########################################################################
+    # Defaults.
+    ##########################################################################
+
+    #: Engine name.
+    __engine_name__ = 'PCAP-NG'
+
+    #: Engine module name.
+    __engine_module__ = 'pcapkit.protocols.misc.pcapng'
+
+    ##########################################################################
+    # Data models.
+    ##########################################################################
+
+    def __init__(self, extractor: 'Extractor') -> 'None':
+        self._ctx = None  # type: ignore[assignment]
+        self._ctx_list = []
+
+        super().__init__(extractor)
+
+    ##########################################################################
+    # Methods.
+    ##########################################################################
+
+    def run(self) -> 'None':
+        """Start extraction.
+
+        This method is the entry point for PCAP-NG file extraction. It will
+        directly extract the first block, which should be a section header
+        block, and then save the related information into the internal
+        context storage.
+
+        """
+        ext = self._extractor
+
+        shb = P_PCAPNG(ext._ifile, num=0, sct=1, ctx=None)
+        if shb.info.type != Enum_BlockType.Section_Header_Block:
+            raise FormatError(f'PCAP-NG: [SHB] invalid block type: {shb.info.type!r}')
+
+        self._ctx = Context(cast('Data_SectionHeaderBlock', shb.info))
+        self._ctx_list.append(self._ctx)
+        shb._ctx = self._ctx
+
+        self._write_file(shb.info, name=f'Section Header {len(self._ctx_list)}')
+
+    def read_frame(self) -> 'P_PCAPNG':
+        """Read frames.
+
+        This method performs following tasks:
+
+        - read the next block from input file;
+        - check if the block is a packet block;
+        - if not, save the block into the internal context storage and repeat;
+        - if yes, save the related information into the internal context storage;
+        - write the parsed block into output file.
+        - reassemble IP and/or TCP fragments;
+        - trace TCP flows if any;
+        - record frame information if any.
+
+        Returns:
+            Parsed PCAP-NG block.
+
+        """
+        from pcapkit.toolkit.pcapng import (ipv4_reassembly, ipv6_reassembly, tcp_reassembly,
+                                            tcp_traceflow)
+        ext = self._extractor
+
+        while True:
+            # read next block
+            block = P_PCAPNG(ext._ifile, num=ext._frnum+1, sct=len(self._ctx_list),
+                             ctx=self._ctx, layer=ext._exlyr, protocol=ext._exptl,
+                             __packet__={
+                                 'snaplen': self._get_snaplen(),
+                             })
+
+            # check block type
+            if block.info.type == Enum_BlockType.Section_Header_Block:
+                self._ctx = Context(cast('Data_SectionHeaderBlock', block.info))
+                self._ctx_list.append(self._ctx)
+                block._ctx = self._ctx
+
+                self._write_file(block.info, name=f'Section Header {len(self._ctx_list)}')
+
+            elif block.info.type == Enum_BlockType.Interface_Description_Block:
+                self._ctx.interfaces.append(cast('Data_InterfaceDescriptionBlock', block.info))
+                self._write_file(block.info, name=f'Interface Description {len(self._ctx.interfaces)}')
+
+            elif block.info.type == Enum_BlockType.Name_Resolution_Block:
+                self._ctx.names.append(cast('Data_NameResolutionBlock', block.info))
+                self._write_file(block.info, name=f'Name Resolution {len(self._ctx.names)}')
+
+            elif block.info.type == Enum_BlockType.systemd_Journal_Export_Block:
+                self._ctx.journals.append(cast('Data_SystemdJournalExportBlock', block.info))
+                self._write_file(block.info, name=f'systemd Journal Export {len(self._ctx.journals)}')
+
+            elif block.info.type == Enum_BlockType.Decryption_Secrets_Block:
+                self._ctx.secrets.append(cast('Data_DecryptionSecretsBlock', block.info))
+                self._write_file(block.info, name=f'Decryption Secrets {len(self._ctx.secrets)}')
+
+            elif block.info.type == Enum_BlockType.Interface_Statistics_Block:
+                isb_info = cast('Data_InterfaceStatisticsBlock', block.info)
+                if isb_info.interface_id >= len(self._ctx.interfaces):
+                    raise FormatError(f'PCAP-NG: [ISB] invalid interface ID: {isb_info.interface_id}')
+                self._ctx.statistics.append(isb_info)
+
+                self._write_file(isb_info, name=f'Interface Statistics {len(self._ctx.statistics)}')
+
+            elif block.info.type in (Enum_BlockType.Custom_Block_that_rewriters_can_copy_into_new_files,
+                                    Enum_BlockType.Custom_Block_that_rewriters_should_not_copy_into_new_files):
+                self._ctx.custom.append(cast('Data_CustomBlock', block.info))
+                self._write_file(block.info, name=f'Custom {len(self._ctx.custom)}')
+
+            elif block.info.type == Enum_BlockType.Enhanced_Packet_Block:
+                epb_info = cast('Data_EnhancedPacketBlock', block.info)
+                if epb_info.interface_id >= len(self._ctx.interfaces):
+                    raise FormatError(f'PCAP-NG: [EPB] invalid interface ID: {epb_info.interface_id}')
+                break
+
+            elif block.info.type == Enum_BlockType.Simple_Packet_Block:
+                if len(self._ctx.interfaces) != 1:
+                    raise FormatError(f'PCAP-NG: [SPB] invalid section with {len(self._ctx.interfaces)} interfaces')
+                break
+
+            elif block.info.type == Enum_BlockType.Packet_Block:
+                pack_info = cast('Data_PacketBlock', block.info)
+                if pack_info.interface_id >= len(self._ctx.interfaces):
+                    raise FormatError(f'PCAP-NG: [Packet] invalid interface ID: {pack_info.interface_id}')
+
+                warn('PCAP-NG: [Packet] deprecated block type', DeprecatedFormatWarning,
+                     stacklevel=stacklevel())
+                break
+
+            else:
+                self._ctx.unknown.append(cast('Data_UnknownBlock', block.info))
+                self._write_file(block.info, name=f'Unknown {len(self._ctx.unknown)}')
+
+        # increment frame number
+        ext._frnum += 1
+
+        # verbose output
+        ext._vfunc(ext, block)
+
+        # write plist
+        self._write_file(block.info, name=f'Frame {ext._frnum}')
+
+        # record fragments
+        if ext._flag_r:
+            if ext._ipv4:
+                data_ipv4 = ipv4_reassembly(block)
+                if data_ipv4 is not None:
+                    ext._reasm.ipv4(data_ipv4)
+            if ext._ipv6:
+                data_ipv6 = ipv6_reassembly(block)
+                if data_ipv6 is not None:
+                    ext._reasm.ipv6(data_ipv6)
+            if ext._tcp:
+                data_tcp = tcp_reassembly(block)
+                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(block, nanosecond=block.nanosecond)
+                if data_tf_tcp is not None:
+                    ext._trace.tcp(data_tf_tcp)
+
+        # record blocks
+        if ext._flag_d:
+            ext._frame.append(block)
+
+        # return block record
+        return block
+
+    ##########################################################################
+    # Utilities.
+    ##########################################################################
+
+    def _write_file(self, block: 'Data_PCAPNG', *, name: 'str') -> 'None':
+        """Write the parsed block into output file.
+
+        Args:
+            block: The parsed block.
+            name: The name of the block.
+
+        """
+        ext = self._extractor
+        if ext._flag_q:
+            return
+
+        if ext._flag_f:
+            ofile = ext._ofile(f'{ext._ofnm}/{name}.{ext._fext}')
+            ofile(block.to_dict(), name=name)
+        else:
+            ext._ofile(block.to_dict(), name=name)
+            ofile = ext._ofile
+        ext._offmt = ofile.kind
+
+    def _get_snaplen(self) -> 'int':
+        """Get snapshot length from the current context.
+
+        This method is used for providing the snapshot length to the ``__packet__``
+        argument when parsing a Simple Packet Block (SPB).
+
+        Notes:
+            If there is no interface, return ``0xFFFF_FFFF_FFFF_FFFF``.
+
+        """
+        if self._ctx.interfaces:
+            return self._ctx.interfaces[0].snaplen
+        return 0xFFFF_FFFF_FFFF_FFFF

pcapkit/foundation/engines/pyshark.py

@@ -0,0 +1,166 @@
+# -*- coding: utf-8 -*-
+"""PyShark Support
+=====================
+
+.. module:: pcapkit.foundation.engines.pyshark
+
+This module contains the implementation for `PyShark`_ engine
+support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
+
+.. _PyShark: https://kiminewt.github.io/pyshark
+
+"""
+from typing import TYPE_CHECKING, cast
+
+from pcapkit.foundation.engines.engine import EngineBase as Engine
+from pcapkit.foundation.reassembly import ReassemblyManager
+from pcapkit.utilities.exceptions import stacklevel
+from pcapkit.utilities.warnings import AttributeWarning, warn
+
+__all__ = ['PyShark']
+
+if TYPE_CHECKING:
+    from pyshark.capture.file_capture import FileCapture
+    from pyshark.packet.packet import Packet as PySharkPacket
+
+    from pcapkit.foundation.extraction import Extractor
+
+
+class PyShark(Engine['PySharkPacket']):
+    """PyShark engine support.
+
+    Args:
+        extractor: :class:`~pcapkit.foundation.extraction.Extractor` instance.
+
+    """
+    if TYPE_CHECKING:
+        import pyshark
+
+        #: Engine extraction package.
+        _expkg: 'pyshark'
+        #: Engine extraction temporary storage.
+        _extmp: 'FileCapture'
+
+    ##########################################################################
+    # Defaults.
+    ##########################################################################
+
+    #: Engine name.
+    __engine_name__ = 'PyShark'
+
+    #: Engine module name.
+    __engine_module__ = 'pyshark'
+
+    ##########################################################################
+    # Data models.
+    ##########################################################################
+
+    def __init__(self, extractor: 'Extractor') -> 'None':
+        import pyshark  # isort:skip
+
+        self._expkg = pyshark
+        self._extmp = cast('FileCapture', None)
+
+        super().__init__(extractor)
+
+    ##########################################################################
+    # Methods.
+    ##########################################################################
+
+    def run(self) -> 'None':
+        """Call :class:`pyshark.FileCapture` to extract PCAP files.
+
+        This method assigns :attr:`self._expkg <PyShark._expkg>`
+        as :mod:`pyshark` and :attr:`self._extmp <PyShark._extmp>`
+        as an iterator from :class:`pyshark.FileCapture`.
+
+        Warns:
+            AttributeWarning: Warns under following circumstances:
+
+                * 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 PyShark engine currently does not
+                  support such operations.
+                * if reassembly is enabled, as the PyShark engine currently
+                  does not support such operation.
+
+        """
+        ext = self._extractor
+
+        if ext._exlyr != 'none' or ext._exptl != 'null':
+            warn("'Extractor(engine='pyshark')' does not support protocol and layer threshold; "
+                 f"'layer={ext._exlyr}' and 'protocol={ext._exptl}' ignored",
+                 AttributeWarning, stacklevel=stacklevel())
+
+        if ext._flag_r and (ext._ipv4 or ext._ipv6 or ext._tcp):
+            ext._flag_r = False
+            ext._reasm = ReassemblyManager(ipv4=None, ipv6=None, tcp=None)
+            warn("'Extractor(engine='pyshark')' object dose not support reassembly; "
+                 f"so 'ipv4={ext._ipv4}', 'ipv6={ext._ipv6}' and 'tcp={ext._tcp}' will be ignored",
+                 AttributeWarning, stacklevel=stacklevel())
+
+        # setup verbose handler
+        if ext._flag_v:
+            ext._vfunc = lambda e, f: print(
+                f'Frame {e._frnum:>3d}: {f.frame_info.protocols}'  # pylint: disable=protected-access
+            )  # pylint: disable=logging-fstring-interpolation
+
+        # extract & analyse file
+        self._extmp = self._expkg.FileCapture(ext._ifnm, keep_packets=False)
+
+    def read_frame(self) -> 'PySharkPacket':
+        """Read frames with PyShark 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.pyshark import packet2dict, tcp_traceflow
+        ext = self._extractor
+
+        # fetch PyShark packet
+        packet = cast('PySharkPacket', self._extmp.next())
+
+        # verbose output
+        ext._frnum = int(packet.number)
+        ext._vfunc(ext, packet)
+
+        # write plist
+        frnum = f'Frame {ext._frnum}'
+        if not ext._flag_q:
+            info = packet2dict(packet)
+            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
+
+        # trace flows
+        if ext._flag_t:
+            if ext._tcp:
+                data_tf_tcp = tcp_traceflow(packet)
+                if data_tf_tcp is not None:
+                    ext._trace.tcp(data_tf_tcp)
+
+        # record frames
+        if ext._flag_d:
+            # setattr(packet, 'packet2dict', packet2dict)
+            ext._frame.append(packet)
+
+        # return frame record
+        return packet
+
+    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.
+
+        """
+        self._extmp.close()