pypcapkit 1.3.3.post1__cp313-none-any.whl

pcapkit/interface/misc.py

@@ -0,0 +1,120 @@
+# -*- coding: utf-8 -*-
+"""Auxiliary Interface
+=========================
+
+.. module:: pcapkit.interface.misc
+
+:mod:`pcapkit.interface.misc` contains miscellaneous
+user interface functions, classes, etc., which are
+generally provided per user's requests.
+
+"""
+import sys
+from typing import TYPE_CHECKING
+
+from pcapkit.corekit.infoclass import Info, info_final
+from pcapkit.foundation.extraction import Extractor
+from pcapkit.foundation.reassembly.tcp import TCP as TCP_Reassembly
+from pcapkit.utilities.exceptions import stacklevel
+from pcapkit.utilities.warnings import EngineWarning, warn
+
+if TYPE_CHECKING:
+    from typing import Optional
+
+    from typing_extensions import Literal
+
+    from pcapkit.foundation.extraction import Packet
+
+    ByteOrder = Literal['little', 'big']
+    Formats = Literal['pcap', 'json', 'tree', 'plist']
+    Engines = Literal['default', 'pcapkit', 'dpkt', 'scapy', 'pyshark']
+
+__all__ = ['follow_tcp_stream']
+
+###############################################################################
+# Follow TCP Stream
+###############################################################################
+
+
+@info_final
+class Stream(Info):
+    """Data model for TCP streams."""
+
+    #: Output filename.
+    filename: 'Optional[str]'
+    #: Packet list.
+    packets: 'tuple[Packet, ...]'
+    #: TCP conversation.
+    conversations: 'tuple[bytes | tuple[bytes, ...], ...]'
+
+    if TYPE_CHECKING:
+        def __init__(self, filename: 'Optional[str]', packets: 'tuple[Packet, ...]', conversations: 'tuple[bytes | tuple[bytes, ...], ...]') -> 'None': ...  # pylint: disable=unused-argument,super-init-not-called,multiple-statements,line-too-long
+
+
+def follow_tcp_stream(fin: 'Optional[str]' = None, verbose: 'bool' = False,              # Extrator options
+                      extension: 'bool' = True, engine: 'Optional[Engines]' = None,
+                      fout: 'Optional[str]' = None, format: 'Optional[Formats]' = None,  # TraceFlow options # pylint: disable=redefined-builtin
+                      byteorder: 'ByteOrder' = sys.byteorder, nanosecond: 'bool' = False) -> 'tuple[Stream, ...]':
+    """Follow TCP streams.
+
+    Arguments:
+        fin: file name to be read; if file not exist, raise :exc:`FileNotFound`
+        extension: if check and append extensions to output file
+        verbose: if print verbose output information
+        engine: extraction engine to be used
+
+        fout: path name for flow tracer if necessary
+        format: output file format of flow tracer
+        byteorder: output file byte order
+        nanosecond: output nanosecond-resolution file flag
+
+    Returns:
+        List of extracted TCP streams.
+
+    """
+    if engine is not None and engine.lower() == 'pyshark':
+        warn(f'unsupported extraction engine: {engine}; fallback to default engine',
+             EngineWarning, stacklevel=stacklevel())
+        engine = None
+
+    extraction = Extractor(fin=fin, fout=None, format=None, auto=True, extension=extension,
+                           store=True, files=False, nofile=True, verbose=verbose, engine=engine,
+                           layer=None, protocol=None, ip=False, ipv4=False, ipv6=False, tcp=True,
+                           reassembly=False, trace=True, trace_fout=fout, trace_format=format,
+                           trace_byteorder=byteorder, trace_nanosecond=nanosecond)  # type: ignore[var-annotated]
+
+    fallback = False
+    if extraction.engine == 'dpkt':  # type: ignore[comparison-overlap]
+        from pcapkit.toolkit.dpkt import tcp_reassembly  # pylint: disable=import-outside-toplevel
+    elif extraction.engine == 'scapy':  # type: ignore[comparison-overlap]
+        from pcapkit.toolkit.scapy import tcp_reassembly  # isort: skip # pylint: disable=import-outside-toplevel
+    else:
+        from pcapkit.toolkit.pcap import tcp_reassembly  # type: ignore[assignment] # isort: skip # pylint: disable=import-outside-toplevel
+        fallback = True
+
+    streams = []  # type: list[Stream]
+    frames = extraction.frame
+    for stream in extraction.trace.tcp:
+        reassembly = TCP_Reassembly(strict=False)
+
+        packets = []  # type: list[Packet]
+        for index in stream.index:
+            frame = frames[index-1]
+            packets.append(frame)
+
+            if fallback:
+                data = tcp_reassembly(frame)
+            else:
+                data = tcp_reassembly(frame, count=index)
+
+            if data is not None:
+                reassembly(data)
+
+        streams.append(Stream(
+            filename=stream.fpout,
+            packets=tuple(packets),
+            conversations=tuple(datagram.payload for datagram in sorted(
+                reassembly.datagram, key=lambda datagram: datagram.index  # make sure the converstations are in order
+            )),
+        ))
+    return tuple(streams)

pcapkit/protocols/__init__.py

@@ -0,0 +1,85 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=unused-import,unused-wildcard-import,fixme
+"""Protocol Family
+=====================
+
+.. module:: pcapkit.protocols
+
+:mod:`pcapkit.protocols` is collection of all protocol families,
+with detailed implementation and methods.
+
+"""
+from typing import TYPE_CHECKING
+
+# Base Class for Protocols
+from pcapkit.protocols.protocol import Protocol
+
+# Utility Classes for Protocols
+from pcapkit.protocols.misc import *
+
+# Protocols & Macros
+from pcapkit.protocols.link import *
+from pcapkit.protocols.internet import *
+from pcapkit.protocols.transport import *
+from pcapkit.protocols.application import *
+
+# Protocol Data
+from pcapkit.protocols import data
+from pcapkit.protocols.data.data import Data
+
+# Protocol Schema
+from pcapkit.protocols import schema
+from pcapkit.protocols.schema.schema import Schema
+
+if TYPE_CHECKING:
+    from typing import Type
+
+    from pcapkit.protocols.protocol import ProtocolBase
+
+__all__ = [
+    # PCAP Headers
+    'Header', 'Frame',
+
+    # PCAPNG Format
+    'PCAPNG',
+
+    # No Payload
+    'NoPayload',
+
+    # Raw Packet
+    'Raw',
+
+    # Link Layer
+    'ARP', 'DRARP', 'Ethernet', 'InARP', 'L2TP',
+    'OSPF', 'RARP', 'VLAN',
+
+    # Internet Layer
+    'AH', 'IP', 'IPsec', 'IPv4', 'IPv6', 'IPX',
+
+    # IPv6 Extension Header
+    'HIP', 'HOPOPT', 'IPv6_Frag', 'IPv6_Opts',
+    'IPv6_Route', 'MH',
+
+    # Transport Layer
+    'TCP', 'UDP',
+
+    # Application Layer
+    'FTP', 'FTP_DATA',
+    'HTTP', 'HTTPv1', 'HTTPv2',
+]
+
+#: dict[str, Type[Protocol]]: Protocol registry.
+__proto__ = {}  # type: dict[str, Type[ProtocolBase]]
+for name in __all__:
+    __proto__[name.upper()] = globals()[name]
+
+__all__.extend((
+    # Protocol Numbers
+    'LINKTYPE', 'ETHERTYPE', 'TRANSTYPE', 'APPTYPE',
+
+    # Protocol Data
+    'Data', 'data',
+
+    # Protocol Schema
+    'Schema', 'schema',
+))

pcapkit/protocols/application/__init__.py

@@ -0,0 +1,34 @@
+# -*- coding: utf-8 -*-
+# pylint: disable=unused-import,fixme
+"""Application Layer Protocols
+=================================
+
+.. module:: pcapkit.protocols.application
+
+:mod:`pcapkit.protocols.application` is collection of all protocols in
+application layer, with detailed implementation and methods.
+
+"""
+# TODO: Implements BGP, DHCP, DHCPv6, DNS, IMAP, LDAP, MQTT,
+#       NNTP, NTP, ONC:RPC, POP, RIP, RTP, SIP, SMTP, SNMP,
+#       SSH, TELNET, TLS/SSL, XMPP.
+
+# Base Class for Internet Layer
+from pcapkit.protocols.application.application import Application
+
+# Utility Classes for Protocols
+from pcapkit.protocols.application.ftp import FTP, FTP_DATA
+from pcapkit.protocols.application.httpv1 import HTTP as HTTPv1
+from pcapkit.protocols.application.httpv2 import HTTP as HTTPv2
+
+# Deprecated / Base Classes
+from pcapkit.protocols.application.http import HTTP
+
+# Transport Layer Protocol Numbers
+from pcapkit.const.reg.apptype import AppType as APPTYPE
+
+__all__ = [
+    'APPTYPE',
+    'FTP', 'FTP_DATA',
+    'HTTP', 'HTTPv1', 'HTTPv2',
+]

pcapkit/protocols/application/application.py

@@ -0,0 +1,114 @@
+# -*- coding: utf-8 -*-
+"""Base Protocol
+===================
+
+.. module:: pcapkit.protocols.application.application
+
+:mod:`pcapkit.protocols.application.application` contains only
+:class:`~pcapkit.protocols.application.application.Application`,
+which is a base class for application layer protocols, eg.
+:class:`HTTP/1.* <pcapkit.protocols.application.application.httpv1>`,
+:class:`HTTP/2 <pcapkit.protocols.application.application.httpv2>`
+and etc.
+
+"""
+from typing import TYPE_CHECKING, Generic, overload
+
+from pcapkit.corekit.protochain import ProtoChain
+from pcapkit.protocols.misc.null import NoPayload
+from pcapkit.protocols.protocol import _PT, _ST
+from pcapkit.protocols.protocol import ProtocolBase as Protocol
+from pcapkit.utilities.exceptions import IntError, UnsupportedCall
+
+if TYPE_CHECKING:
+    from typing import IO, Any, NoReturn, Optional
+
+    from typing_extensions import Literal
+
+__all__ = ['Application']
+
+
+class Application(Protocol[_PT, _ST], Generic[_PT, _ST]):  # pylint: disable=abstract-method
+    """Abstract base class for transport layer protocol family."""
+
+    ##########################################################################
+    # Defaults.
+    ##########################################################################
+
+    #: Layer of protocol.
+    __layer__ = 'Application'  # type: Literal['Application']
+
+    ##########################################################################
+    # Properties.
+    ##########################################################################
+
+    # protocol layer
+    @property
+    def layer(self) -> 'Literal["Application"]':
+        """Protocol layer."""
+        return self.__layer__
+
+    ##########################################################################
+    # Data models.
+    ##########################################################################
+
+    @overload
+    def __post_init__(self, file: 'IO[bytes] | bytes', length: 'Optional[int]' = ..., **kwargs: 'Any') -> 'None': ...
+    @overload
+    def __post_init__(self, **kwargs: 'Any') -> 'None': ...
+
+    def __post_init__(self, file: 'Optional[IO[bytes] | bytes]' = None,
+                      length: 'Optional[int]' = None, **kwargs: 'Any') -> 'None':
+        """Post initialisation hook.
+
+        Args:
+            file: Source packet stream.
+            length: Length of packet data.
+            **kwargs: Arbitrary keyword arguments.
+
+        See Also:
+            For construction arguments, please refer to
+            :meth:`self.make <pcapkit.protocols.protocol.Protocol.make>`.
+
+        """
+        # call super post-init
+        super().__post_init__(file, length, **kwargs)  # type: ignore[arg-type]
+
+        #: pcapkit.protocols.null.NoPayload: Payload of current instance.
+        self._next = NoPayload()
+        #: pcapkit.corekit.protochain.ProtoChain: Protocol chain of current instance.
+        self._protos = ProtoChain(self.__class__, self.alias)
+
+    @classmethod
+    def __index__(cls) -> 'NoReturn':  # pylint: disable=invalid-index-returned
+        """Numeral registry index of the protocol.
+
+        Raises:
+            IntError: This protocol doesn't support :meth:`__index__`.
+
+        """
+        raise IntError(f'{cls.__name__!r} object cannot be interpreted as an integer')
+
+    ##########################################################################
+    # Utilities.
+    ##########################################################################
+
+    def _decode_next_layer(self, dict_: '_PT', proto: 'Optional[int]' = None, length: 'Optional[int]' = None, *,
+                           packet: 'Optional[dict[str, Any]]' = None) -> 'NoReturn':
+        """Decode next layer protocol.
+
+        Raises:
+            UnsupportedCall: This protocol doesn't support :meth:`_decode_next_layer`.
+
+        """
+        raise UnsupportedCall(f"'{self.__class__.__name__}' object has no attribute '_decode_next_layer'")
+
+    def _import_next_layer(self, proto: 'int', length: 'Optional[int]' = None, *,  # type: ignore[override]
+                           packet: 'Optional[dict[str, Any]]' = None) -> 'NoReturn':
+        """Import next layer extractor.
+
+        Raises:
+            UnsupportedCall: This protocol doesn't support :meth:`_import_next_layer`.
+
+        """
+        raise UnsupportedCall(f"'{self.__class__.__name__}' object has no attribute '_import_next_layer'")

pcapkit/protocols/application/ftp.py

@@ -0,0 +1,206 @@
+# -*- coding: utf-8 -*-
+"""file transfer protocol
+
+.. module:: pcapkit.protocols.application.ftp
+
+:mod:`pcapkit.protocols.application.ftp` contains
+:class:`~pcapkit.protocols.application.ftp.FTP` only,
+which implements extractor for File Transfer Protocol
+(FTP) [*]_.
+
+.. [*] https://en.wikipedia.org/wiki/File_Transfer_Protocol
+
+"""
+import re
+from typing import TYPE_CHECKING
+
+from pcapkit.const.ftp.command import Command as Enum_Command
+from pcapkit.const.ftp.return_code import ReturnCode as Enum_ReturnCode
+from pcapkit.protocols.application.application import Application
+from pcapkit.protocols.data.application.ftp import FTP as Data_FTP
+from pcapkit.protocols.data.application.ftp import Request as Data_Request
+from pcapkit.protocols.data.application.ftp import Response as Data_Response
+from pcapkit.protocols.misc.raw import Raw
+from pcapkit.protocols.schema.application.ftp import FTP as Schema_FTP
+from pcapkit.utilities.compat import StrEnum
+from pcapkit.utilities.exceptions import ProtocolError, UnsupportedCall
+
+if TYPE_CHECKING:
+    from typing import Any, NoReturn, Optional
+
+    from typing_extensions import Literal
+
+__all__ = ['FTP', 'FTP_DATA']
+
+# regex for FTP
+FTP_REQUEST = re.compile(rb'^(?P<cmmd>[A-Z]{3,4})( +(?P<args>.*))?\r\n$', re.I)
+FTP_RESPONSE = re.compile(rb'^(?P<code>[0-9]{3})(?P<more>\-)?( +(?P<args>.*))?\r\n$', re.I)
+
+
+class Type(StrEnum):
+    """FTP packet type."""
+
+    #: Request packet.
+    REQUEST = 'request'
+    #: Response packet.
+    RESPONSE = 'response'
+
+
+class FTP(Application[Data_FTP, Schema_FTP],
+          data=Data_FTP, schema=Schema_FTP):
+    """This class implements File Transfer Protocol."""
+
+    ##########################################################################
+    # Properties.
+    ##########################################################################
+
+    @property
+    def name(self) -> 'Literal["File Transfer Protocol"]':
+        """Name of current protocol."""
+        return 'File Transfer Protocol'
+
+    @property
+    def length(self) -> 'NoReturn':
+        """Header length of current protocol.
+
+        Raises:
+            UnsupportedCall: This protocol doesn't support :attr:`length`.
+
+        """
+        raise UnsupportedCall(f"'{self.__class__.__name__}' object has no attribute 'length'")
+
+    ##########################################################################
+    # Methods.
+    ##########################################################################
+
+    def read(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'Data_FTP':  # pylint: disable=unused-argument
+        """Read File Transfer Protocol (FTP).
+
+        Args:
+            length: Length of packet data.
+            **kwargs: Arbitrary keyword arguments.
+
+        Returns:
+            Parsed packet data.
+
+        Raises:
+            ProtocolError: If the packet is malformed.
+
+        """
+        if length is None:
+            length = len(self)
+        schema = self.__header__
+
+        data = schema.data
+        if (match := FTP_REQUEST.match(data)) is not None:
+            cmmd = match.group('cmmd').decode()
+            args = match.group('args')
+
+            cmmd_val = Enum_Command.get(cmmd)
+            args_val = self.decode(args)
+
+            ftp = Data_Request(
+                type=Type.REQUEST,
+                cmmd=cmmd_val,
+                args=args_val,
+            )  # type: Data_FTP
+        elif (match := FTP_RESPONSE.match(data)) is not None:
+            code = int(match.group('code'))
+            more = bool(match.group('more'))
+            args = match.group('args')
+
+            code_val = Enum_ReturnCode.get(code)
+            args_val = self.decode(args)
+
+            ftp = Data_Response(
+                type=Type.RESPONSE,
+                code=code_val,
+                more=more,
+                args=args_val,
+            )
+        else:
+            raise ProtocolError('FTP: invalid packet format')
+        return ftp
+
+    def make(self,
+             cmmd: 'Optional[Enum_Command | str | bytes]' = None,
+             code: 'Optional[Enum_ReturnCode | int | str | bytes]' = None,
+             args: 'Optional[str | bytes]' = None,
+             more: 'bool' = False,
+             **kwargs: 'Any') -> 'Schema_FTP':
+        """Make (construct) packet data.
+
+        Args:
+            cmmd: FTP command.
+            code: FTP status code.
+            args: Optional FTP command arguments and/or status messages.
+            more: More status messages to follow for response packets.
+            **kwargs: Arbitrary keyword arguments.
+
+        Returns:
+            Constructed packet data.
+
+        """
+        if cmmd is not None and code is None:
+            if isinstance(cmmd, bytes):
+                prefix = cmmd
+            elif isinstance(cmmd, str):
+                prefix = cmmd.encode()
+            else:
+                prefix = cmmd.value
+
+            mf = b''
+        elif cmmd is None and code is not None:
+            code_val = int(code)
+            prefix = str(code_val).encode()
+
+            mf = b'-' if more else b''
+        else:
+            raise ProtocolError('FTP: invalid packet type')
+
+        if args is None:
+            suffix = b''
+        elif isinstance(args, bytes):
+            suffix = args
+        else:
+            suffix = args.encode()
+
+        return Schema_FTP(
+            data=b'%s%s %s' % (prefix, mf, suffix),
+        )
+
+    ##########################################################################
+    # Utilities.
+    ##########################################################################
+
+    @classmethod
+    def _make_data(cls, data: 'Data_FTP') -> 'dict[str, Any]':  # type: ignore[override]
+        """Create key-value pairs from ``data`` for protocol construction.
+
+        Args:
+            data: protocol data
+
+        Returns:
+            Key-value pairs for protocol construction.
+
+        """
+        return {
+            'cmmd': getattr(data, 'cmmd', None),
+            'code': getattr(data, 'code', None),
+            'args': getattr(data, 'args', None),
+            'more': getattr(data, 'more', False),
+        }
+
+
+class FTP_DATA(Raw):
+    """This class implements FTP data channel transmission."""
+
+    ##########################################################################
+    # Properties.
+    ##########################################################################
+
+    # name of current protocol
+    @property
+    def name(self) -> 'Literal["FTP_DATA"]':  # type: ignore[override]
+        """Name of current protocol."""
+        return 'FTP_DATA'