feat(link): add a FRAD dissector for Frame Relay over LinuxSLL (#2460)

CHANGELOG.md

@@ -2,6 +2,8 @@
 
 Wave 2 of the roadmap, per the contributing docs' enhancement-proposal page: the protocol pairs that wanted a shared abstract base, and the two that simply had no dissector at all.
 
+- **Added** -- `FRAD`, a dissector for Frame Relay's multiprotocol encapsulation ([RFC 2427](https://datatracker.ietf.org/doc/html/rfc2427), obsoleting [RFC 1490](https://datatracker.ietf.org/doc/html/rfc1490)). `LinuxSLL`/ `LinuxSLL1`/ `LinuxSLL2` dispatch to it for the `ARPHRD_FRAD` case instead of falling back to `Raw`; the direct NLPID and SNAP-encapsulated forms both dispatch onward, to IPv4/IPv6 and (via the EtherType registry every Ethernet/VLAN/LinuxSLL frame shares) ARP among others. The first of [#2460](https://github.com/JarryShaw/PyPCAPKit/issues/2460)'s five `arphrd_type` follow-ups to get a dissector; the other four (`NETLINK`, `IPGRE`/`IP6GRE`, `IEEE80211_RADIOTAP`) remain `Raw`.
+
 ---
 
 Full changelog: <https://jarryshaw.github.io/PyPCAPKit/changelog.html>

docs/source/changelog/1.6.0.rst

@@ -4,3 +4,16 @@
 Wave 2 of the roadmap, per the contributing docs' enhancement-proposal page: the
 protocol pairs that wanted a shared abstract base, and the two that simply had
 no dissector at all.
+
+* **Added** -- :class:`~pcapkit.protocols.link.frad.FRAD`, a dissector for Frame
+  Relay's multiprotocol encapsulation (:rfc:`2427`, obsoleting :rfc:`1490`).
+  :class:`~pcapkit.protocols.link.linux_sll.LinuxSLL`/
+  :class:`~pcapkit.protocols.link.linux_sll1.LinuxSLL1`/
+  :class:`~pcapkit.protocols.link.linux_sll2.LinuxSLL2` dispatch to it for the
+  ``ARPHRD_FRAD`` case instead of falling back to
+  :class:`~pcapkit.protocols.misc.raw.Raw`; the direct NLPID and SNAP-encapsulated
+  forms both dispatch onward, to IPv4/IPv6 and (via the EtherType registry every
+  Ethernet/VLAN/LinuxSLL frame shares) ARP among others. The first of :issue:`2460`'s
+  five ``arphrd_type`` follow-ups to get a dissector; the other four
+  (``NETLINK``, ``IPGRE``/``IP6GRE``, ``IEEE80211_RADIOTAP``) remain
+  :class:`~pcapkit.protocols.misc.raw.Raw`.

docs/source/pcapkit/protocols/link/frad.rst

@@ -0,0 +1,71 @@
+FRAD - Frame Relay Access Device
+=================================
+
+.. module:: pcapkit.protocols.link.frad
+
+:mod:`pcapkit.protocols.link.frad` contains
+:class:`~pcapkit.protocols.link.frad.FRAD`
+only, which implements the extractor for Frame Relay's multiprotocol
+encapsulation [*]_, as seen on a ``LINKTYPE_LINUX_SLL``/``LINKTYPE_LINUX_SLL2``
+capture whose ``arphrd_type`` is ``ARPHRD_FRAD``. Its structure, the Q.922
+LAPF address onward with no trailing FCS, is described as below:
+
+.. table::
+
+   ====== ==== ================= ==========================================
+   Octets Bits Name              Description
+   ====== ==== ================= ==========================================
+   0      0    ``frad.addr``     Q.922 Address (2-octet form)
+   2      16   ``frad.control``  Control (``0x03``, UI, for data traffic)
+   3      24   ``frad.nlpid``    NLPID, or the ``0x00`` pad ahead of a SNAP
+                                  header
+   ====== ==== ================= ==========================================
+
+When ``nlpid`` is the ``0x00`` pad marker, a further NLPID octet (``0x80``
+for SNAP), a 3-octet OUI and a 2-octet PID follow, kept as ``frad.ext_nlpid``,
+``frad.oui`` and ``frad.pid``.
+
+.. autoclass:: pcapkit.protocols.link.frad.FRAD
+   :no-members:
+   :show-inheritance:
+
+   .. autoproperty:: name
+   .. autoproperty:: alias
+   .. autoproperty:: length
+   .. autoproperty:: protocol
+
+   .. automethod:: id
+
+   .. automethod:: read
+   .. automethod:: make
+
+   .. automethod:: __length_hint__
+   .. automethod:: __index__
+
+   .. automethod:: _make_data
+   .. automethod:: _import_next_layer
+
+   .. autoattribute:: __proto__
+      :no-value:
+
+Header Schemas
+--------------
+
+.. module:: pcapkit.protocols.schema.link.frad
+
+.. autoclass:: pcapkit.protocols.schema.link.frad.FRAD
+   :members:
+   :show-inheritance:
+
+Data Models
+-----------
+
+.. module:: pcapkit.protocols.data.link.frad
+
+.. autoclass:: pcapkit.protocols.data.link.frad.FRAD
+   :members:
+   :show-inheritance:
+
+.. rubric:: Footnotes
+
+.. [*] :rfc:`2427` (obsoleting :rfc:`1490`)

docs/source/pcapkit/protocols/link/index.rst

@@ -24,6 +24,7 @@ link layer, with detailed implementation and methods.
    link
    ethernet
    arp
+   frad
    l2tp
    l2tpv2
    linux_sll

pcapkit/__init__.py

@@ -111,7 +111,7 @@
     'NoPayload',                                            # No Payload
     'Raw',                                                  # Raw Packet
 
-    'ARP', 'C_Tag', 'Ethernet', 'InARP', 'L2TP',            # Link Layer
+    'ARP', 'C_Tag', 'Ethernet', 'FRAD', 'InARP', 'L2TP',    # Link Layer
     'L2TPv2', 'LinuxSLL', 'LinuxSLL1', 'LinuxSLL2', 'Loopback', 'S_Tag', 'VLAN',
 
     'AH', 'ESP', 'ICMP', 'ICMPv4', 'ICMPv6',                # Internet Layer

pcapkit/all.py

@@ -121,7 +121,7 @@
     'PCAPNG',                                               # PCAPNG Format
     'NoPayload',                                            # No Payload
     'Raw',                                                  # Raw Packet
-    'ARP', 'C_Tag', 'Ethernet', 'InARP', 'L2TP', 'L2TPv2', 'LinuxSLL', 'LinuxSLL1',
+    'ARP', 'C_Tag', 'Ethernet', 'FRAD', 'InARP', 'L2TP', 'L2TPv2', 'LinuxSLL', 'LinuxSLL1',
     'LinuxSLL2', 'Loopback', 'S_Tag', 'VLAN',               # Link Layer
     'AH', 'ESP', 'ICMP', 'ICMPv4', 'ICMPv6', 'IGMP', 'IGMPv1', 'IGMPv2', 'IGMPv3',
     'IP', 'IPsec', 'IPv4', 'IPv6', 'IPX',                   # Internet Layer

pcapkit/protocols/__init__.py

@@ -50,7 +50,7 @@
     'Raw',
 
     # Link Layer
-    'ARP', 'C_Tag', 'Ethernet', 'InARP', 'L2TP', 'L2TPv2', 'LinuxSLL', 'LinuxSLL1',
+    'ARP', 'C_Tag', 'Ethernet', 'FRAD', 'InARP', 'L2TP', 'L2TPv2', 'LinuxSLL', 'LinuxSLL1',
     'LinuxSLL2', 'Loopback', 'S_Tag', 'VLAN',
 
     # Internet Layer

pcapkit/protocols/data/__init__.py

@@ -62,6 +62,9 @@
     # Ethernet Protocol
     'Ethernet',
 
+    # Frame Relay Access Device
+    'FRAD',
+
     # Layer Two Tunnelling Protocol
     'L2TP', 'L2TP_Flags',
 

pcapkit/protocols/data/link/__init__.py

@@ -9,6 +9,9 @@
 # Ethernet Protocol
 from pcapkit.protocols.data.link.ethernet import Ethernet
 
+# Frame Relay Access Device
+from pcapkit.protocols.data.link.frad import FRAD
+
 # Layer Two Tunnelling Protocol
 from pcapkit.protocols.data.link.l2tp import L2TP
 from pcapkit.protocols.data.link.l2tp import Flags as L2TP_Flags
@@ -31,6 +34,9 @@
     # Ethernet Protocol
     'Ethernet',
 
+    # Frame Relay Access Device
+    'FRAD',
+
     # Layer Two Tunnelling Protocol
     'L2TP', 'L2TP_Flags',
 

pcapkit/protocols/data/link/frad.py

@@ -0,0 +1,45 @@
+# -*- coding: utf-8 -*-
+"""data models for Frame Relay Access Device (FRAD) frames"""
+
+from typing import TYPE_CHECKING
+
+from pcapkit.corekit.infoclass import info_final
+from pcapkit.protocols.data.protocol import Protocol
+
+if TYPE_CHECKING:
+    from typing import Optional
+
+__all__ = ['FRAD']
+
+
+@info_final
+class FRAD(Protocol):
+    """Data model for a Frame Relay Access Device (FRAD) frame."""
+
+    #: Data Link Connection Identifier, from the Q.922 address field.
+    dlci: 'int'
+    #: Command/response indication bit.
+    cr: 'int'
+    #: Forward explicit congestion notification.
+    fecn: 'int'
+    #: Backward explicit congestion notification.
+    becn: 'int'
+    #: Discard eligibility.
+    de: 'int'
+    #: Control field; ``0x03`` (UI) for ordinary data traffic.
+    control: 'int'
+    #: NLPID selecting the encapsulated protocol, with any ``0x00`` pad
+    #: already resolved to the real value that followed it.
+    nlpid: 'int'
+    #: SNAP OUI, present only when :attr:`nlpid` is ``0x80``.
+    snap_oui: 'Optional[bytes]'
+    #: SNAP PID, present only when :attr:`nlpid` is ``0x80``.
+    snap_pid: 'Optional[int]'
+    #: Header length, in octets -- 4 for a direct NLPID, 5 with the pad byte,
+    #: or 10 with the SNAP header besides.
+    len: 'int'
+
+    if TYPE_CHECKING:
+        def __init__(self, dlci: 'int', cr: 'int', fecn: 'int', becn: 'int', de: 'int',  # pylint: disable=unused-argument,super-init-not-called
+                     control: 'int', nlpid: 'int', snap_oui: 'Optional[bytes]',  # pylint: disable=unused-argument
+                     snap_pid: 'Optional[int]', len: 'int') -> 'None': ...  # pylint: disable=unused-argument,redefined-builtin

pcapkit/protocols/link/__init__.py

@@ -17,6 +17,7 @@
 # Link Layer Protocols
 from pcapkit.protocols.link.arp import ARP, InARP
 from pcapkit.protocols.link.ethernet import Ethernet
+from pcapkit.protocols.link.frad import FRAD
 from pcapkit.protocols.link.loopback import Loopback
 
 # Linux "Cooked" Capture Encapsulation Family
@@ -41,6 +42,6 @@
     'LINKTYPE',
 
     # Link Layer Protocols
-    'ARP', 'C_Tag', 'Ethernet', 'InARP', 'L2TP', 'L2TPv2', 'LinuxSLL', 'LinuxSLL1',
+    'ARP', 'C_Tag', 'Ethernet', 'FRAD', 'InARP', 'L2TP', 'L2TPv2', 'LinuxSLL', 'LinuxSLL1',
     'LinuxSLL2', 'Loopback', 'S_Tag', 'VLAN',
 ]