Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions pcapkit/corekit/decorators.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
#: <pcapkit.protocols.protocol.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
#: <pcapkit.protocols.protocol.Protocol._parse_next_layer>` drops its warnings
#: with it (:issue:`2308`).
_beholding = contextvars.ContextVar('_beholding', default=False)


Expand Down
17 changes: 9 additions & 8 deletions pcapkit/protocols/protocol.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
25 changes: 23 additions & 2 deletions pcapkit/toolkit/pypcapfile.py
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand Down
41 changes: 32 additions & 9 deletions tests/protocols/test_trial_parse_full_length_2516_unit.py
Original file line number Diff line number Diff line change
@@ -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`.
Expand Down Expand Up @@ -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

Expand All @@ -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()
104 changes: 104 additions & 0 deletions tests/toolkit/test_pypcapfile_accepts_trial_2526_unit.py
Original file line number Diff line number Diff line change
@@ -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()
97 changes: 97 additions & 0 deletions tests/toolkit/test_pypcapfile_extension_header_trial_2526_unit.py
Original file line number Diff line number Diff line change
@@ -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()
Loading