diff --git a/pcapkit/corekit/decorators.py b/pcapkit/corekit/decorators.py index f0093ae40b..672e5b4ab0 100644 --- a/pcapkit/corekit/decorators.py +++ b/pcapkit/corekit/decorators.py @@ -54,10 +54,12 @@ #: :data:`pcapkit.utilities.logging.logger`. logger = get_logger(__name__) -#: contextvars.ContextVar[bool]: Whether a call :func:`beholder` wraps is under -#: way, so that an :exc:`Exception` raised inside it ends with the layer that -#: raised replaced; see :meth:`Protocol._parse_next_layer -#: ` (:issue:`2308`). +#: contextvars.ContextVar[bool]: Whether a layer that raises is discarded by its +#: caller, as :func:`beholder` replaces it and +#: :func:`~pcapkit.toolkit.pypcapfile._default_extension_header` drops it, so +#: that :meth:`Protocol._parse_next_layer +#: ` drops its warnings +#: with it (:issue:`2308`). _beholding = contextvars.ContextVar('_beholding', default=False) diff --git a/pcapkit/protocols/protocol.py b/pcapkit/protocols/protocol.py index 725a8b73fd..11f46b5d3d 100644 --- a/pcapkit/protocols/protocol.py +++ b/pcapkit/protocols/protocol.py @@ -2418,15 +2418,16 @@ def _parse_next_layer(klass: 'Type[ProtocolBase]', file_: 'bytes', length: 'int' parse ends when it is kept, still inside the guard that catches them under an ``error`` filter. A layer kept with its header cut short still warns. The held warnings of a parse that raises are dropped - too when :func:`~pcapkit.corekit.decorators.beholder` replaces the - layer, as it does around :meth:`_import_next_layer`, since the + too when :func:`~pcapkit.corekit.decorators.beholder`, which wraps + :meth:`_import_next_layer`, replaces the layer, since the replacement's ``error`` reports the failure (:issue:`2308`); outside - it, they are reported as the error leaves. Under it, a layer is - held however much was captured, since one that raises is replaced - at any length (:issue:`2516`), so a kept layer's warnings follow - those of the layers it carries. Outside it, a layer captured at - least as long as its hint cannot be replaced, and is parsed holding - nothing, even inside one that holds. + ``beholder``, they are reported as the error leaves. Under + ``beholder``, a layer is held however much was captured, since one + that raises is replaced at any length (:issue:`2516`), so a kept + layer's warnings follow those of the layers it carries. Outside + ``beholder``, a layer captured at least as long as its hint cannot + be replaced, and is parsed holding nothing, even inside one that + holds. A layer past :data:`~pcapkit.utilities.config.FRAME_LAYER_LIMIT` in its frame is not parsed: it and the rest of the frame are kept as diff --git a/pcapkit/toolkit/pypcapfile.py b/pcapkit/toolkit/pypcapfile.py index 551f4be9a8..132b3d54dd 100644 --- a/pcapkit/toolkit/pypcapfile.py +++ b/pcapkit/toolkit/pypcapfile.py @@ -48,6 +48,7 @@ from pcapkit.const.reg.ethertype import EtherType as Enum_EtherType from pcapkit.const.reg.transtype import TransType as Enum_TransType +from pcapkit.corekit.decorators import _beholding from pcapkit.foundation.engines.pypcapfile import PyPCAPFile from pcapkit.foundation.reassembly.data.ip import Packet as IP_Packet from pcapkit.foundation.reassembly.data.tcp import Packet as TCP_Packet @@ -61,7 +62,7 @@ from pcapkit.protocols.transport.tcp import TCP as Protocol_TCP from pcapkit.utilities import config from pcapkit.utilities.exceptions import ProtocolError, UnsupportedCall, stacklevel -from pcapkit.utilities.warnings import AttributeWarning, warn +from pcapkit.utilities.warnings import AttributeWarning, hold_warnings, warn if TYPE_CHECKING: from collections import OrderedDict @@ -477,10 +478,21 @@ def _default_accepts(name: 'str', header: 'bytes') -> 'bool': dissected. The answer depends on the octets alone, so the most recent answers are remembered, as many as the cache's ``maxsize``. + A header the parser rejects is dropped with its warnings, as a replaced + next layer is, and one it accepts reports them from the caller's line + (:issue:`2308`, :issue:`2526`). + """ protocol = Protocol_IPv4 if name == 'IPv4' else Protocol_TCP try: - protocol(header, len(header), protocol=name) + # NOTE: The parser reads its own header, outside ``_parse_next_layer``, + # so ``_beholding`` would hold nothing here (#2526). + with hold_warnings() as held: + try: + protocol(header, len(header), protocol=name) + except Exception: + held.discard = True + raise except Exception: # as beholder does return False return True @@ -500,14 +512,23 @@ def _default_extension_header(protocol: 'int', data: 'bytes') -> 'Optional[tuple parser raises anything at all, or fewer octets were captured than the header needs. + Note: + The header is parsed on trial as under + :func:`~pcapkit.corekit.decorators.beholder`: one that raises is dropped + with its warnings, as a replaced next layer is (:issue:`2308`, + :issue:`2526`). + """ # pylint: disable-next=protected-access klass = Protocol_IPv4._lookup_next_layer(Protocol_IPv4.__proto__, protocol) + token = _beholding.set(True) try: header = Protocol_IPv4._parse_next_layer( # pylint: disable=protected-access klass, data, len(data), version=4, extension=False, alias=protocol, protocol=klass) except Exception: # as beholder does return None + finally: + _beholding.reset(token) nxt = getattr(header.info, 'next', None) # none on a header cut short, read as raw octets if nxt is None: return None diff --git a/tests/protocols/test_trial_parse_full_length_2516_unit.py b/tests/protocols/test_trial_parse_full_length_2516_unit.py index 30638ee64c..ae3d5052b7 100644 --- a/tests/protocols/test_trial_parse_full_length_2516_unit.py +++ b/tests/protocols/test_trial_parse_full_length_2516_unit.py @@ -1,14 +1,16 @@ # -*- coding: utf-8 -*- """GitHub issue #2516: a trial parse that raises at full length and is kept as ``Raw`` warns nothing. -:meth:`~pcapkit.protocols.protocol.ProtocolBase._parse_next_layer` held only a -next layer captured shorter than its length hint (#1580), but :func:`~pcapkit.corekit.decorators.beholder` replaces a layer that raises at any -length (#2308). Without the fix, a TCP segment to port 443 that starts mid-record -warned ``packet length < 0`` twice, from TLS's record header and from the SSLv2 -fallback it tries, for a TLS layer the result keeps as ``Raw``. Under -``beholder`` every layer is now held, and its warnings are dropped with it. A -kept layer still warns, from the caller's line, after the layers it carries. +length (#2308), so holding only a next layer captured shorter than its length +hint (#1580) lets a full-length layer's warnings through: a TCP segment to port +443 that starts mid-record warns ``packet length < 0`` twice, from TLS's record +header and from the SSLv2 fallback it tries, for a TLS layer the result keeps as +``Raw``. Under ``beholder``, +:meth:`~pcapkit.protocols.protocol.ProtocolBase._parse_next_layer` holds every +layer, and drops a replaced layer's warnings with it. A kept layer warns from the +caller's line, after the layers it carries. Outside ``beholder``, a full-length +layer cannot be replaced and holds nothing. :mod:`pcapkit` is imported inside each test, after :func:`~tests._support.reimport_once_per_class`. @@ -123,13 +125,13 @@ def test_full_length_layer_that_raises_warns_nothing(self) -> None: self.assertEqual([str(item.message) for item in caught], []) def test_well_formed_tls_record_warns_nothing(self) -> None: - """Control: a whole TLS record on 443 parses as TLS, as before, reporting nothing.""" + """Control: a whole TLS record on 443 parses as TLS and reports nothing.""" parsed, caught = self._parse('TCP', TCP_TO_443 + b'\x17\x03\x03\x00\x04abcd') self.assertEqual(str(parsed.protochain), 'TCP:TLS 1.2') # type: ignore[attr-defined] self.assertEqual(caught, []) def test_kept_layer_still_warns_from_the_callers_line(self) -> None: - """Control: a kept IPv4 is held now, and reports its warning as it did.""" + """Control: a kept IPv4 is held, and reports its warning from the caller's line.""" from pcapkit.protocols.link.ethernet import Ethernet from pcapkit.utilities.warnings import ProtocolWarning @@ -148,6 +150,27 @@ def test_kept_layer_reports_after_the_layers_it_carries(self) -> None: _, caught = self._parse('Ethernet', _ipv4(41, shim6_cut, SECURITY)) self.assertEqual([str(item.message) for item in caught], SHIM6_CUT_MESSAGES + [OPTION_WARNING]) + def test_full_length_layer_outside_beholder_holds_nothing(self) -> None: + """Outside ``beholder``, a full-length IPv4 reports its warning before the layers it carries. + + Nothing can replace it, so it holds nothing, even inside a block that + discards: its warning is reported as raised. Only the layers its own + ``beholder`` parses are held, and report as their parse ends. + + """ + from pcapkit.protocols.internet.ipv4 import IPv4 + from pcapkit.protocols.protocol import ProtocolBase + from pcapkit.utilities.warnings import hold_warnings + + packet = _ipv4(41, _ipv6(140, b'\x00'), SECURITY)[len(MACS) + 2:] # past the Ethernet header + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter('always') + with hold_warnings() as outer: + outer.discard = True + parsed = ProtocolBase._parse_next_layer(IPv4, packet, len(packet)) # pylint: disable=protected-access + self.assertEqual(str(parsed.protochain), 'IPv4:IPv6:IPv6-Ext') + self.assertEqual([str(item.message) for item in caught], [OPTION_WARNING] + SHIM6_CUT_MESSAGES) + if __name__ == '__main__': unittest.main() diff --git a/tests/toolkit/test_pypcapfile_accepts_trial_2526_unit.py b/tests/toolkit/test_pypcapfile_accepts_trial_2526_unit.py new file mode 100644 index 0000000000..d81e8a563e --- /dev/null +++ b/tests/toolkit/test_pypcapfile_accepts_trial_2526_unit.py @@ -0,0 +1,104 @@ +# -*- coding: utf-8 -*- +"""GitHub issue #2526: pypcapfile's header check warns nothing for a header it rejects. + +:func:`~pcapkit.toolkit.pypcapfile._default_accepts` asks pcapkit's IPv4 or TCP +parser about a header, and answers :data:`False` when that raises. The #2308 +rule applies: the trial's warnings describe a header nothing keeps, so they go +with it. Held by nothing, a TCP header whose Timestamps option runs past its end +warns ``packet length < 0`` twice before the answer. A header the parser accepts +warns from the caller's line. + +The parser reads its own header rather than a next layer, so setting +``_beholding`` around it holds nothing, and the trial holds its own warnings. + +The answers are cached by octets, so each test clears the cache before it asks. +:mod:`pcapkit` is imported inside each test, after +:func:`~tests._support.reimport_once_per_class`. + +""" + +import inspect +import struct +import unittest +import warnings + +from tests._support import reimport_once_per_class +from tests.utilities._harness import capture + +#: Test tier (#1958): exercises the warning machinery, which free-threaded +#: builds make context-aware. +__tier__ = 'ALL' + + +def _ipv4(options: 'bytes') -> 'bytes': + """A bare IPv4 header carrying ``options``.""" + return struct.pack('!BBHHHBBH4s4s', 0x45 + len(options) // 4, 0, 20 + len(options), + 0, 0, 64, 6, 0, bytes([127, 0, 0, 1]), bytes([127, 0, 0, 2])) + options + + +#: A 24-octet TCP header whose Timestamps option claims 10 octets of the 4 left. +TCP_TIMESTAMPS_CUT = (struct.pack('!HHIIBBHHH', 12345, 80, 1, 0, 6 << 4, 0x02, 4095, 0, 0) + + bytes.fromhex('080a0000')) +#: A 24-octet IPv4 header whose Record Route option claims 40 octets of the 4 left. +IPV4_RECORD_ROUTE_CUT = _ipv4(bytes.fromhex('07280400')) +#: A 28-octet IPv4 header whose Security option runs on past its last octet. +IPV4_SECURITY = _ipv4(bytes.fromhex('8205ab0000') + bytes(3)) +#: The warning :data:`IPV4_SECURITY`'s option reports. +SECURITY_WARNING = 'IPv4: [OptNo 130] invalid format: remaining data' + + +class TestAcceptsTrial(unittest.TestCase): + """Pin that a rejected header reports nothing, and an accepted one does.""" + + def setUp(self) -> None: + reimport_once_per_class(self) + + def _ask(self, name: 'str', header: 'bytes', + action: 'str' = 'always') -> 'tuple[bool, list[warnings.WarningMessage]]': + """Ask the uncached check about ``header``, with the warnings it reports.""" + from pcapkit.toolkit.pypcapfile import _default_accepts + + _default_accepts.cache_clear() + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter(action) + answer = _default_accepts(name, header) + return answer, caught + + def test_rejected_header_warns_nothing(self) -> None: + """A TCP or IPv4 header whose option runs past its end is rejected, reporting nothing on either channel.""" + from pcapkit.utilities.logging import logger + + for name, header in (('TCP', TCP_TIMESTAMPS_CUT), ('IPv4', IPV4_RECORD_ROUTE_CUT)): + with self.subTest(name=name): + with capture(logger) as recorder: + answer, caught = self._ask(name, header) + self.assertFalse(answer) + self.assertEqual([str(item.message) for item in caught], []) + self.assertEqual([record.getMessage() for record in recorder.records + if record.getMessage().startswith('packet length')], []) + + def test_error_filter_rejects_a_warning_header(self) -> None: + """Control: under ``error``, a header that warns is rejected, and nothing escapes.""" + for name, header in (('TCP', TCP_TIMESTAMPS_CUT), ('IPv4', IPV4_SECURITY)): + with self.subTest(name=name): + answer, caught = self._ask(name, header, 'error') + self.assertFalse(answer) + self.assertEqual(caught, []) + + def test_accepted_header_warns_from_the_callers_line(self) -> None: + """Control: an IPv4 header the parser accepts reports its option's warning.""" + from pcapkit.toolkit.pypcapfile import _default_accepts + from pcapkit.utilities.warnings import ProtocolWarning + + _default_accepts.cache_clear() + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter('always') + line = inspect.currentframe().f_lineno + 1 # type: ignore[union-attr] + answer = _default_accepts('IPv4', IPV4_SECURITY) + self.assertTrue(answer) + self.assertEqual([(item.category, str(item.message), item.filename, item.lineno) for item in caught], + [(ProtocolWarning, SECURITY_WARNING, __file__, line)]) + + +if __name__ == '__main__': + unittest.main() diff --git a/tests/toolkit/test_pypcapfile_extension_header_trial_2526_unit.py b/tests/toolkit/test_pypcapfile_extension_header_trial_2526_unit.py new file mode 100644 index 0000000000..3120d0a709 --- /dev/null +++ b/tests/toolkit/test_pypcapfile_extension_header_trial_2526_unit.py @@ -0,0 +1,97 @@ +# -*- coding: utf-8 -*- +"""GitHub issue #2526: pypcapfile's extension-header trial warns nothing when it raises. + +:func:`~pcapkit.toolkit.pypcapfile._default_extension_header` reads a header +inside IPv4 with +:meth:`~pcapkit.protocols.protocol.ProtocolBase._parse_next_layer`, and answers +:data:`None` when that raises, as :func:`~pcapkit.corekit.decorators.beholder` +replaces such a layer. The #2308 rule applies: the trial's warnings describe a +header nothing keeps, so they go with it. Outside ``beholder`` they are reported +as the error leaves, so a HIP header cut to 8 octets warns ``packet length < 0`` +twice before the answer. A header the trial keeps warns from the caller's line. + +The answers are cached by octets, so each test clears the cache before it asks. +:mod:`pcapkit` is imported inside each test, after +:func:`~tests._support.reimport_once_per_class`. + +""" + +import inspect +import unittest +import warnings + +from tests._support import reimport_once_per_class +from tests.utilities._harness import capture + +#: Test tier (#1958): exercises the warning machinery, which free-threaded +#: builds make context-aware. +__tier__ = 'ALL' + +#: IP protocol numbers of HIP and the Mobility Header. +HIP, MOBILITY_HEADER = 139, 135 +#: The first 8 octets of a HIP header, whose fixed part is 40. +HIP_CUT = bytes.fromhex('b0ff89ff0042ff1c') +#: A Mobility Header of 8 octets, 16 short of the Binding Error message it +#: carries, then 1 octet of its UDP payload. +MH_BINDING_ERROR = bytes.fromhex('11000742d5bd297b99') +#: The warning the Mobility Header's message reports. +MH_WARNING = 'packet length < 0: -16' + + +class TestExtensionHeaderTrial(unittest.TestCase): + """Pin that a raising extension-header trial reports nothing, and a kept one does.""" + + def setUp(self) -> None: + reimport_once_per_class(self) + + def _ask(self, protocol: 'int', data: 'bytes', + action: 'str' = 'always') -> 'tuple[object, list[warnings.WarningMessage]]': + """Ask the uncached reader about ``data``, with the warnings it reports. + + The trial must leave ``beholder``'s flag unset, whatever it answers. + + """ + from pcapkit.corekit import decorators + from pcapkit.toolkit.pypcapfile import _default_extension_header + + _default_extension_header.cache_clear() + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter(action) + answer = _default_extension_header(protocol, data) + self.assertFalse(decorators._beholding.get()) # pylint: disable=protected-access + return answer, caught + + def test_raising_trial_warns_nothing(self) -> None: + """The cut HIP header raises, answers ``None``, and reports nothing on either channel.""" + from pcapkit.utilities.logging import logger + + with capture(logger) as recorder: + answer, caught = self._ask(HIP, HIP_CUT) + self.assertIsNone(answer) + self.assertEqual([str(item.message) for item in caught], []) + self.assertEqual([record.getMessage() for record in recorder.records + if record.getMessage().startswith('packet length')], []) + + def test_error_filter_answers_none(self) -> None: + """Control: under ``error``, the cut HIP header answers ``None`` and reports nothing.""" + answer, caught = self._ask(HIP, HIP_CUT, 'error') + self.assertIsNone(answer) + self.assertEqual(caught, []) + + def test_kept_header_warns_from_the_callers_line(self) -> None: + """Control: a Mobility Header the trial keeps reports its message's warning.""" + from pcapkit.toolkit.pypcapfile import _default_extension_header + from pcapkit.utilities.warnings import SchemaWarning + + _default_extension_header.cache_clear() + with warnings.catch_warnings(record=True) as caught: + warnings.simplefilter('always') + line = inspect.currentframe().f_lineno + 1 # type: ignore[union-attr] + answer = _default_extension_header(MOBILITY_HEADER, MH_BINDING_ERROR) + self.assertEqual(answer, (17, 8)) + self.assertEqual([(item.category, str(item.message), item.filename, item.lineno) for item in caught], + [(SchemaWarning, MH_WARNING, __file__, line)]) + + +if __name__ == '__main__': + unittest.main()