fix(link): a GRE frame cut short by the capture reads TRUNCATED (#2653) (#2668)

- pcapkit.utilities.contextvars: frame_length holds the captured and the
  original length of the frame being dissected; Frame and PCAPNG set it,
  Internet clears it and GRE reads it, so it is shared under #2616
- Frame.read, and PCAPNG._read_block_epb, _read_block_spb and
  _read_block_packet, set it around the parse of their payload
- Internet._decode_next_layer clears it around its payload's parse, as
  the length an IP layer hands on bounds that payload
- GRE.read hands verify_message its length plus what the capture cut off
  the frame, since behind LinuxSLL the message runs to the frame's end
- ICMPv4 and IGMP keep the length their IP layer declares, which gives
  TRUNCATED for a cut message; the frame's would misread a cut in padding
- Docs: the contextvars page lists frame_length

Tests: test_gre_snaplen_cut_2653_unit fails without the fix, and its
cases behind IP fail without the Internet reset; the guard, GRE, IP,
frame and PCAP-NG modules pass.

Author: JarryShaw

docs/source/pcapkit/utilities/contextvars.rst

@@ -17,5 +17,8 @@ a module at any layer may import it; see :ref:`utilities-or-corekit`.
 .. autodata:: pcapkit.utilities.contextvars.frame_depth
    :no-value:
 
+.. autodata:: pcapkit.utilities.contextvars.frame_length
+   :no-value:
+
 .. autodata:: pcapkit.utilities.contextvars.rebuilding
    :no-value:

pcapkit/protocols/internet/internet.py

@@ -24,7 +24,7 @@
 from pcapkit.protocols.protocol import _PT, _ST, ProtocolBase
 from pcapkit.protocols.schema.schema import keep_short_read, replay_short_read
 from pcapkit.utilities import config
-from pcapkit.utilities.contextvars import rebuilding
+from pcapkit.utilities.contextvars import frame_length, rebuilding
 from pcapkit.utilities.exceptions import stacklevel
 from pcapkit.utilities.warnings import ProtocolWarning, RegistryWarning, warn
 
@@ -471,10 +471,21 @@ def _decode_next_layer(self, dict_: '_PT', proto: 'Optional[int]' = None,  # pyl
             :meth:`Info.to_dict <pcapkit.corekit.infoclass.Info.to_dict>`
             carries and the dumpers leave out.
 
+            The next layer is parsed with
+            :data:`~pcapkit.utilities.contextvars.frame_length` cleared, since
+            this layer, not the frame, bounds its payload (:issue:`2653`).
+
         """
-        next_ = cast('ProtocolBase',  # type: ignore[redundant-cast]
-                     self._import_next_layer(proto, length, packet=packet, version=version,
-                                             payload=payload))  # type: ignore[misc,call-arg]
+        # NOTE: The length this layer hands on bounds the payload, so octets the
+        # capture cut off the frame past it are none of the next layer's (#2653).
+        # An IPv4 Total Length of 0, read as the rest of the frame, loses the cut.
+        token = frame_length.set(None)
+        try:
+            next_ = cast('ProtocolBase',  # type: ignore[redundant-cast]
+                         self._import_next_layer(proto, length, packet=packet, version=version,
+                                                 payload=payload))  # type: ignore[misc,call-arg]
+        finally:
+            frame_length.reset(token)
         info, chain = next_.info, next_.protochain
 
         # make next layer protocol name

pcapkit/protocols/link/gre.py

@@ -78,6 +78,7 @@
 from pcapkit.protocols.link.link import Link
 from pcapkit.protocols.schema.link.gre import GRE as Schema_GRE
 from pcapkit.utilities import config
+from pcapkit.utilities.contextvars import frame_length
 from pcapkit.utilities.exceptions import ProtocolError
 
 if TYPE_CHECKING:
@@ -108,9 +109,11 @@ class GRE(Link[Data_GRE, Schema_GRE],
     :data:`~pcapkit.utilities.config.CHECKSUM_VERIFY`, and computed by
     :meth:`make` when ``checksum_present`` asks for one without giving it.
     Neither this header nor the Linux cooked-capture header before it states
-    a length, so the octets verified are the ones captured: a frame the
-    capture cut short reads as
-    :attr:`~pcapkit.corekit.checksum.internet.ChecksumStatus.INVALID`.
+    a length, so the message runs to the end of its frame. A frame the
+    capture cut short, holding fewer octets than its original length, reads
+    as :attr:`~pcapkit.corekit.checksum.internet.ChecksumStatus.TRUNCATED`,
+    as :data:`~pcapkit.utilities.contextvars.frame_length` tells it
+    (:issue:`2653`).
 
     """
 
@@ -221,7 +224,13 @@ def read(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'Data_GRE':
             if _checksum is None:
                 status = ChecksumStatus.NOT_COMPUTED
             else:
-                status = verify_message(self.alias, self._data, _checksum.to_bytes(2, 'big'), length=length)
+                # NOTE: Behind LinuxSLL the message runs to the end of its frame, so
+                # what the capture cut off is covered too. Behind IP the value is None:
+                # Internet clears it, as the length IP declares bounds GRE (#2653).
+                lengths = frame_length.get()
+                missing = 0 if lengths is None else max(lengths[1] - lengths[0], 0)
+                status = verify_message(self.alias, self._data, _checksum.to_bytes(2, 'big'),
+                                        length=length + missing)
             gre.__update__([
                 ('checksum_status', status),
             ])

pcapkit/protocols/misc/pcap/frame.py

@@ -48,6 +48,7 @@
 from pcapkit.protocols.schema.misc.pcap.frame import Frame as Schema_Frame
 from pcapkit.protocols.schema.misc.pcap.header import RESOLUTION
 from pcapkit.utilities.compat import localcontext
+from pcapkit.utilities.contextvars import frame_length
 from pcapkit.utilities.datetime import fromtimestamp, totimestamp
 from pcapkit.utilities.exceptions import StreamEOFError, UnsupportedCall, stacklevel
 from pcapkit.utilities.warnings import ProtocolWarning, RegistryWarning, warn
@@ -419,7 +420,14 @@ def read(self, length: 'Optional[int]' = None, *, _read: 'bool' = True,
         # (#2308). As the dissection does not tell the two apart,
         # ``test_truncated_ipv4_header_is_raw_with_its_error`` pins the argument
         # where it is passed (#2236).
-        return self._decode_next_layer(frame, self._ghdr.network, frame.cap_len)
+        #
+        # NOTE: A layer that states no length cannot see the cut, so the layers
+        # below are told both lengths (#2653).
+        token = frame_length.set((_ilen, _olen))
+        try:
+            return self._decode_next_layer(frame, self._ghdr.network, frame.cap_len)
+        finally:
+            frame_length.reset(token)
 
     def make(self,
              timestamp: 'Optional[float | Decimal | int | dt_type]' = None,

pcapkit/protocols/misc/pcapng.py

@@ -211,6 +211,7 @@
 from pcapkit.protocols.schema.misc.pcapng import zigbee_key_held
 from pcapkit.protocols.schema.schema import Schema
 from pcapkit.utilities.compat import StrEnum, localcontext
+from pcapkit.utilities.contextvars import frame_length
 from pcapkit.utilities.datetime import fromtimestamp, totimestamp
 from pcapkit.utilities.exceptions import (BaseError, EnumValueError, FormatError, ProtocolError,
                                           StreamEOFError, UnsupportedCall, stacklevel)
@@ -2666,8 +2667,13 @@ def _read_block_epb(self, schema: 'Schema_EnhancedPacketBlock', *,
             warn(f'PCAP-NG: [Block {header.type}] captured length {schema.captured_len} runs past '
                  f'the block, which holds {len(schema.packet_data)} octet(s); kept as captured',
                  ProtocolWarning, stacklevel=stacklevel())
-        return self._decode_next_layer(data, self._get_linktype(schema.interface_id),
-                                       schema.captured_len)  # type: ignore[return-value]
+        # NOTE: The layers below are told both lengths, as a PCAP frame tells them (#2653).
+        token = frame_length.set((data.captured_len, data.original_len))
+        try:
+            return self._decode_next_layer(data, self._get_linktype(schema.interface_id),
+                                           schema.captured_len)  # type: ignore[return-value]
+        finally:
+            frame_length.reset(token)
 
     def _read_block_spb(self, schema: 'Schema_SimplePacketBlock', *,
                         header: 'Schema_PCAPNG') -> 'Data_SimplePacketBlock':
@@ -2728,7 +2734,12 @@ def _read_block_spb(self, schema: 'Schema_SimplePacketBlock', *,
             warn(f'PCAP-NG: [Block {header.type}] packet data of {data.captured_len} octet(s) '
                  f'exceeds the original length of {data.original_len}; kept as captured',
                  ProtocolWarning, stacklevel=stacklevel())
-        return self._decode_next_layer(data, self._get_linktype(0), data.captured_len)  # type: ignore[return-value]
+        # NOTE: The layers below are told both lengths, as a PCAP frame tells them (#2653).
+        token = frame_length.set((data.captured_len, data.original_len))
+        try:
+            return self._decode_next_layer(data, self._get_linktype(0), data.captured_len)  # type: ignore[return-value]
+        finally:
+            frame_length.reset(token)
 
     def _read_block_nrb(self, schema: 'Schema_NameResolutionBlock', *,
                         header: 'Schema_PCAPNG') -> 'Data_NameResolutionBlock':
@@ -3065,8 +3076,13 @@ def _read_block_packet(self, schema: 'Schema_PacketBlock', *,
             warn(f'PCAP-NG: [Block {header.type}] captured length {schema.captured_length} runs past '
                  f'the block, which holds {len(schema.packet_data)} octet(s); kept as captured',
                  ProtocolWarning, stacklevel=stacklevel())
-        return self._decode_next_layer(data, self._get_linktype(schema.interface_id),
-                                       schema.captured_length)  # type: ignore[return-value]
+        # NOTE: The layers below are told both lengths, as a PCAP frame tells them (#2653).
+        token = frame_length.set((data.captured_len, data.original_len))
+        try:
+            return self._decode_next_layer(data, self._get_linktype(schema.interface_id),
+                                           schema.captured_length)  # type: ignore[return-value]
+        finally:
+            frame_length.reset(token)
 
     def _read_pcapng_options(self, options_schema: 'list[Schema_Option]') -> 'Option':
         """Read PCAP-NG options.

pcapkit/utilities/contextvars.py

@@ -14,8 +14,12 @@
 
 """
 import contextvars
+from typing import TYPE_CHECKING
 
-__all__ = ['beholding', 'frame_depth', 'rebuilding']
+if TYPE_CHECKING:
+    from typing import Optional
+
+__all__ = ['beholding', 'frame_depth', 'frame_length', 'rebuilding']
 
 #: contextvars.ContextVar[bool]: Whether a layer that raises is discarded by its
 #: caller, as :func:`~pcapkit.corekit.decorators.beholder` replaces it and
@@ -31,6 +35,18 @@
 #: :data:`~pcapkit.utilities.config.FRAME_LAYER_LIMIT`.
 frame_depth = contextvars.ContextVar('pcapkit.utilities.contextvars.frame_depth', default=0)
 
+#: contextvars.ContextVar[tuple[int, int] | None]: The captured and the original
+#: length of the frame being dissected, in octets, as its PCAP record or PCAP-NG
+#: packet block states them; :data:`None` outside a frame, and inside the payload
+#: of an :class:`~pcapkit.protocols.internet.internet.Internet` layer, which
+#: bounds it. A frame the capture cut short holds fewer octets than were on the
+#: wire, which a layer stating no length of its own, as
+#: :class:`~pcapkit.protocols.link.gre.GRE`, cannot tell from the octets it is
+#: handed (:issue:`2653`).
+frame_length = contextvars.ContextVar(
+    'pcapkit.utilities.contextvars.frame_length', default=None,
+)  # type: contextvars.ContextVar[Optional[tuple[int, int]]]
+
 #: contextvars.ContextVar[bool]: Whether a payload is being rebuilt by
 #: :meth:`Protocol._make_payload
 #: <pcapkit.protocols.protocol.Protocol._make_payload>`, so that the layer