From 29088b1ea418a993bba3c50c224748c79024f75d Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Mon, 2 Nov 2026 20:53:14 -0500 Subject: [PATCH] fix(link): rebuild a cut FRAD header as captured and quietly, or refuse its address (#2710) - A header cut before its NLPID reads that octet as the 0x00 pad, so its data model holds an NLPID of 0. FRAD.make left out the ext_nlpid the schema reads after the pad, and the rebuild logged NoDefaultValue at CRITICAL. It writes the pad and an NLPID of 0, which the schema's own short read cuts back. - The data model keeps no EA bits and make writes the 2-octet form's 0 then 1, so a header with other EA bits rebuilt other octets, cut or whole, alone or behind LinuxSLL: the octets #2710 saw differ. FRAD.read refuses an address that is not the 2-octet form, the only one the schema reads; an EA bit the capture cut off is not checked. LinuxSLL keeps such a frame as Raw, quietly. test_frad_cut_rebuild_2710_unit cuts FRAD frames at every octet and fails without the pcapkit/ change. Shipped captures parse identically. The link, internet and root protocols modules, both schema round trips, the short-read and #2703 modules, the project guards and the plain-unittest link leg pass. Closes #2710 --- pcapkit/protocols/link/frad.py | 32 ++- .../link/test_frad_cut_rebuild_2710_unit.py | 190 ++++++++++++++++++ 2 files changed, 219 insertions(+), 3 deletions(-) create mode 100644 tests/protocols/link/test_frad_cut_rebuild_2710_unit.py diff --git a/pcapkit/protocols/link/frad.py b/pcapkit/protocols/link/frad.py index 5b13d8e30d..a1b84fb6c0 100644 --- a/pcapkit/protocols/link/frad.py +++ b/pcapkit/protocols/link/frad.py @@ -69,6 +69,12 @@ class FRAD(Link[Data_FRAD, Schema_FRAD], whose OUI names a bridged medium rather than an EtherType) is kept as :class:`~pcapkit.protocols.misc.raw.Raw`, exactly as every ``arphrd_type`` this module's docstring lists already was before this class existed. + A frame whose Q.922 address is not the 2-octet form is refused: + :meth:`read` raises :exc:`~pcapkit.utilities.exceptions.ProtocolError`. + It becomes :class:`~pcapkit.protocols.misc.raw.Raw` only behind a caller + that catches the error, such as + :class:`~pcapkit.protocols.link.linux_sll.LinuxSLL` or a + ``LINKTYPE_FRELAY`` capture. """ @@ -148,12 +154,24 @@ def read(self, length: 'Optional[int]' = None, **kwargs: 'Any') -> 'Data_FRAD': Returns: Parsed packet data. + Raises: + ProtocolError: If the address is not the 2-octet Q.922 form, the + only one the schema reads (:rfc:`2427#section-3`): an EA bit + other than ``0`` then ``1``. An EA bit the capture cut off is + not checked. + """ if length is None: length = len(self) schema = self.__header__ addr = schema.addr + # NOTE: The data model keeps no EA bits, so another address form would + # rebuild as the 2-octet one (#2710). + cut = schema.__dict__.get('__short_read__') + if addr['ea1'] or not (addr['ea2'] or (cut is not None and cut[0] == 'addr')): + raise ProtocolError(f'{self.alias}: not a 2-octet Q.922 address: ' + f'EA bits {addr["ea1"]} and {addr["ea2"]}') _dlci = (addr['dlci_hi'] << 4) | addr['dlci_lo'] _raw_nlpid = schema.nlpid @@ -232,15 +250,19 @@ def make(self, ``0x80``. Note: - ``nlpid`` is not refused for being ``0`` -- the SNAP pad marker, - never a value of its own on the wire -- even though no caller + ``nlpid`` is not refused for being ``0`` -- the value of the one + pad octet :rfc:`2427#section-3` allows, if present, ahead of any + NLPID, never an NLPID of its own -- even though no caller building a frame from scratch should pass it: :meth:`from_data ` replays a capture that ended inside the header through this same method, and a capture cut short of the ``nlpid`` octet reads as ``0`` (zero rather than missing). Rejecting it here would make a short capture fail to rebuild, the one invariant every protocol in - this package keeps (:issue:`1458`). + this package keeps (:issue:`1458`). It is written as the pad and + an NLPID of ``0``, the octets that read back as it, and the + schema's own short read cuts them back to those captured + (:issue:`2710`). """ dlci = self._make_uint(dlci, bits=10, name='DLCI') @@ -263,6 +285,10 @@ def make(self, f'when nlpid is 0x80, not {nlpid!r}') _schema_nlpid, _ext_nlpid = nlpid, None _oui, _pid = None, None + if not nlpid: + # NOTE: A zero NLPID is the pad, which the schema follows with + # ``ext_nlpid``, so that is written too (#2710). + _ext_nlpid = 0 return Schema_FRAD( addr={ diff --git a/tests/protocols/link/test_frad_cut_rebuild_2710_unit.py b/tests/protocols/link/test_frad_cut_rebuild_2710_unit.py new file mode 100644 index 0000000000..2191143920 --- /dev/null +++ b/tests/protocols/link/test_frad_cut_rebuild_2710_unit.py @@ -0,0 +1,190 @@ +# -*- coding: utf-8 -*- +"""A FRAD header rebuilds as captured and quietly at every cut, or is refused. + +GitHub issue #2710: a :class:`~pcapkit.protocols.link.frad.FRAD` header the data ends +before its NLPID reads that octet as the ``0x00`` pad, so its data model holds an NLPID +of zero. :meth:`FRAD.make ` then left out the +``ext_nlpid`` the schema reads after the pad, and the rebuild logged ``NoDefaultValue`` +at ``CRITICAL``. It writes the pad and an NLPID of zero instead, which the schema's own +short read cuts back. + +The data model keeps no EA bits of the Q.922 address, so a header whose EA bits are not +the 2-octet form, ``0`` then ``1``, rebuilt other octets, cut or whole. +:meth:`FRAD.read ` refuses it, which a +:class:`~pcapkit.protocols.link.linux_sll.LinuxSLL` frame keeps as +:class:`~pcapkit.protocols.misc.raw.Raw`, quietly. An EA bit the data never held is not +checked. + +The frames are built here; this module is unit-tier and reads no capture file. + +""" +from __future__ import annotations + +import contextlib +import logging +import struct +import unittest +import warnings +from typing import TYPE_CHECKING + +from tests._support import reimport_once_per_class + +if TYPE_CHECKING: + from typing import Any, Callable, Iterator + +#: Test tier (#1958): hand-picked parse -> rebuild round trips. +__tier__ = 'ALL' + +#: An IPv4 header (protocol UDP) and an 8-octet UDP header. +IPV4 = (bytes.fromhex('4500001c00010000401100000a0000010a000002') + + bytes.fromhex('3039003500080000')) +#: A minimal ARP request (RFC 826), 28 octets. +ARP = bytes.fromhex('00010800060400010011223344550a0000010000000000000a000002') + +#: Each frame cut at every octet: the RFC 2427 address of DLCI 50, UI control, then a +#: direct NLPID, a SNAP header, or the pad and an NLPID of zero. +FRAMES = { + 'direct': bytes.fromhex('0c21' '03' 'cc') + IPV4, + 'SNAP': bytes.fromhex('0c21' '03' '00' '80' '000000' '0806') + ARP, + 'pad, zero NLPID': bytes.fromhex('0c21' '03' '00' '00') + b'\xaa\xbb', +} + +#: Addresses of DLCI 50 whose EA bits are not ``0`` then ``1``. +OTHER_FORMS = { + 'EA 1 then 1': bytes.fromhex('0d21'), + 'EA 0 then 0': bytes.fromhex('0c20'), + 'EA 1 then 0': bytes.fromhex('0d20'), +} + +#: A Linux cooked-capture source address, padded to its 8 octets. +LINK_ADDR = bytes.fromhex('001122334455') + bytes(2) + + +class _Logged(logging.Handler): + """Collect what the ``pcapkit`` logger reports.""" + + def __init__(self) -> None: + super().__init__(logging.DEBUG) + self.messages = [] # type: list[str] + + def emit(self, record: 'logging.LogRecord') -> None: + self.messages.append(f'logged: {record.getMessage()}') + + +@contextlib.contextmanager +def _reported() -> 'Iterator[list[str]]': + """Collect what the block reports, on the :mod:`warnings` channel and the logger.""" + handler = _Logged() + logger = logging.getLogger('pcapkit') + logger.addHandler(handler) + try: + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter('always') + yield handler.messages + finally: + logger.removeHandler(handler) + handler.messages.extend(f'warned: {item.message}' for item in caught) + + +class FRADCutRebuildTests(unittest.TestCase): + """A FRAD header rebuilds as captured, or the address form is refused.""" + + def setUp(self) -> None: + reimport_once_per_class(self) + from pcapkit.const.linux.arphrd import ARPHRD + from pcapkit.protocols.link.frad import FRAD + from pcapkit.protocols.link.linux_sll1 import LinuxSLL1 + from pcapkit.protocols.link.linux_sll2 import LinuxSLL2 + from pcapkit.utilities.exceptions import ProtocolError + + self.FRAD = FRAD + self.ProtocolError = ProtocolError + self.cooked = { + 'LinuxSLL1': (LinuxSLL1, struct.pack('>HHH', 0, ARPHRD.FRAD, 6) + LINK_ADDR + + struct.pack('>H', 0)), + 'LinuxSLL2': (LinuxSLL2, struct.pack('>HHIHBB', 0, 0, 1, ARPHRD.FRAD, 0, 6) + LINK_ADDR), + } # type: dict[str, tuple[Any, bytes]] + + def parse(self, build: 'Callable[[], Any]') -> 'tuple[Any, list[str]]': + """What ``build`` returns, and what it reported.""" + with _reported() as messages: + layer = build() + return layer, messages + + def assertRebuildsQuietly(self, layer: 'Any') -> 'None': # pylint: disable=invalid-name + """``layer`` rebuilt from its data model and its dict: its octets, and nothing reported.""" + for path, data in (('model', layer.info), ('dict', layer.info.to_dict())): + with self.subTest(path=path): + rebuilt, messages = self.parse(lambda: type(layer).from_data(data)) # pylint: disable=cell-var-from-loop + self.assertEqual((rebuilt.data.hex(), messages), (layer.data.hex(), [])) + + def test_every_cut_rebuilds_as_captured(self) -> None: + for label, frame in FRAMES.items(): + for count in range(1, len(frame) + 1): + with self.subTest(frame=label, captured=count): + with warnings.catch_warnings(): + warnings.simplefilter('ignore') + layer = self.FRAD(frame[:count], count) + self.assertEqual(layer.data, frame[:count]) + self.assertRebuildsQuietly(layer) + + def test_a_cut_before_the_nlpid_reads_the_pad(self) -> None: + for count in (1, 2, 3): + with self.subTest(captured=count): + with warnings.catch_warnings(): + warnings.simplefilter('ignore') + layer = self.FRAD(FRAMES['direct'][:count], count) + self.assertIsNotNone(layer.info.get('__short_read__')) + self.assertEqual((layer.info.nlpid, layer.info.len), (0, 5)) + + def test_make_writes_the_pad_and_a_zero_nlpid(self) -> None: + made, messages = self.parse(lambda: self.FRAD(dlci=50, nlpid=0)) + self.assertEqual((made.data.hex(), messages), ('0c21030000', [])) + + def test_another_address_form_is_refused(self) -> None: + from pcapkit.utilities.exceptions import CaughtByCaller + + for label, addr in OTHER_FORMS.items(): + frame = addr + FRAMES['direct'][2:] + for count in range(2, len(frame) + 1): + with self.subTest(address=label, captured=count), CaughtByCaller(self.ProtocolError), \ + self.assertRaisesRegex(self.ProtocolError, r'^FRAD: not a 2-octet Q\.922 address: EA bits'): + self.FRAD(frame[:count], count) + + def test_an_ea_bit_cut_off_is_not_checked(self) -> None: + # One octet holds the first EA bit alone: 0 reads, 1 is refused. + from pcapkit.utilities.exceptions import CaughtByCaller + + with warnings.catch_warnings(): + warnings.simplefilter('ignore') + layer = self.FRAD(b'\x0c', 1) + self.assertEqual(layer.info.get('__short_read__'), ('addr', 1)) + self.assertRebuildsQuietly(layer) + with CaughtByCaller(self.ProtocolError), self.assertRaises(self.ProtocolError): + self.FRAD(b'\x0d', 1) + + def test_linux_sll_keeps_another_address_form_raw(self) -> None: + for name, (cls, head) in self.cooked.items(): + for label, addr in OTHER_FORMS.items(): + raw = head + addr + FRAMES['direct'][2:] + with self.subTest(cooked=name, address=label): + frame, messages = self.parse(lambda: cls(raw, len(raw))) # pylint: disable=cell-var-from-loop + self.assertEqual(messages, []) + self.assertEqual(type(frame.payload).__name__, 'Raw') + self.assertRegex(frame.payload.info.error, r'^FRAD: not a 2-octet Q\.922 address: ') + self.assertEqual(frame.data, raw) + self.assertRebuildsQuietly(frame) + + def test_linux_sll_dispatches_the_2_octet_form(self) -> None: + # The control: the RFC 2427 address is still FRAD behind LinuxSLL. + for name, (cls, head) in self.cooked.items(): + raw = head + FRAMES['direct'] + with self.subTest(cooked=name): + frame, messages = self.parse(lambda: cls(raw, len(raw))) # pylint: disable=cell-var-from-loop + self.assertEqual(messages, []) + self.assertIsInstance(frame.payload, self.FRAD) + self.assertRebuildsQuietly(frame) + + +if __name__ == '__main__': + unittest.main()