Skip to content

Commit e0989d6

Browse files
authored
fix(toolkit): drop a rejected trial's warnings in pypcapfile's header checks (#2526) (#2577)
1 parent dcc0cb5 commit e0989d6

6 files changed

Lines changed: 271 additions & 23 deletions

File tree

‎pcapkit/corekit/decorators.py‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -54,10 +54,12 @@
5454
#: :data:`pcapkit.utilities.logging.logger`.
5555
logger = get_logger(__name__)
5656

57-
#: contextvars.ContextVar[bool]: Whether a call :func:`beholder` wraps is under
58-
#: way, so that an :exc:`Exception` raised inside it ends with the layer that
59-
#: raised replaced; see :meth:`Protocol._parse_next_layer
60-
#: <pcapkit.protocols.protocol.Protocol._parse_next_layer>` (:issue:`2308`).
57+
#: contextvars.ContextVar[bool]: Whether a layer that raises is discarded by its
58+
#: caller, as :func:`beholder` replaces it and
59+
#: :func:`~pcapkit.toolkit.pypcapfile._default_extension_header` drops it, so
60+
#: that :meth:`Protocol._parse_next_layer
61+
#: <pcapkit.protocols.protocol.Protocol._parse_next_layer>` drops its warnings
62+
#: with it (:issue:`2308`).
6163
_beholding = contextvars.ContextVar('_beholding', default=False)
6264

6365

‎pcapkit/protocols/protocol.py‎

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -2418,15 +2418,16 @@ def _parse_next_layer(klass: 'Type[ProtocolBase]', file_: 'bytes', length: 'int'
24182418
parse ends when it is kept, still inside the guard that catches them
24192419
under an ``error`` filter. A layer kept with its header cut short
24202420
still warns. The held warnings of a parse that raises are dropped
2421-
too when :func:`~pcapkit.corekit.decorators.beholder` replaces the
2422-
layer, as it does around :meth:`_import_next_layer`, since the
2421+
too when :func:`~pcapkit.corekit.decorators.beholder`, which wraps
2422+
:meth:`_import_next_layer`, replaces the layer, since the
24232423
replacement's ``error`` reports the failure (:issue:`2308`); outside
2424-
it, they are reported as the error leaves. Under it, a layer is
2425-
held however much was captured, since one that raises is replaced
2426-
at any length (:issue:`2516`), so a kept layer's warnings follow
2427-
those of the layers it carries. Outside it, a layer captured at
2428-
least as long as its hint cannot be replaced, and is parsed holding
2429-
nothing, even inside one that holds.
2424+
``beholder``, they are reported as the error leaves. Under
2425+
``beholder``, a layer is held however much was captured, since one
2426+
that raises is replaced at any length (:issue:`2516`), so a kept
2427+
layer's warnings follow those of the layers it carries. Outside
2428+
``beholder``, a layer captured at least as long as its hint cannot
2429+
be replaced, and is parsed holding nothing, even inside one that
2430+
holds.
24302431
24312432
A layer past :data:`~pcapkit.utilities.config.FRAME_LAYER_LIMIT` in its frame is not parsed:
24322433
it and the rest of the frame are kept as

‎pcapkit/toolkit/pypcapfile.py‎

Lines changed: 23 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,7 @@
4848

4949
from pcapkit.const.reg.ethertype import EtherType as Enum_EtherType
5050
from pcapkit.const.reg.transtype import TransType as Enum_TransType
51+
from pcapkit.corekit.decorators import _beholding
5152
from pcapkit.foundation.engines.pypcapfile import PyPCAPFile
5253
from pcapkit.foundation.reassembly.data.ip import Packet as IP_Packet
5354
from pcapkit.foundation.reassembly.data.tcp import Packet as TCP_Packet
@@ -61,7 +62,7 @@
6162
from pcapkit.protocols.transport.tcp import TCP as Protocol_TCP
6263
from pcapkit.utilities import config
6364
from pcapkit.utilities.exceptions import ProtocolError, UnsupportedCall, stacklevel
64-
from pcapkit.utilities.warnings import AttributeWarning, warn
65+
from pcapkit.utilities.warnings import AttributeWarning, hold_warnings, warn
6566

6667
if TYPE_CHECKING:
6768
from collections import OrderedDict
@@ -477,10 +478,21 @@ def _default_accepts(name: 'str', header: 'bytes') -> 'bool':
477478
dissected. The answer depends on the octets alone, so the most recent
478479
answers are remembered, as many as the cache's ``maxsize``.
479480
481+
A header the parser rejects is dropped with its warnings, as a replaced
482+
next layer is, and one it accepts reports them from the caller's line
483+
(:issue:`2308`, :issue:`2526`).
484+
480485
"""
481486
protocol = Protocol_IPv4 if name == 'IPv4' else Protocol_TCP
482487
try:
483-
protocol(header, len(header), protocol=name)
488+
# NOTE: The parser reads its own header, outside ``_parse_next_layer``,
489+
# so ``_beholding`` would hold nothing here (#2526).
490+
with hold_warnings() as held:
491+
try:
492+
protocol(header, len(header), protocol=name)
493+
except Exception:
494+
held.discard = True
495+
raise
484496
except Exception: # as beholder does
485497
return False
486498
return True
@@ -500,14 +512,23 @@ def _default_extension_header(protocol: 'int', data: 'bytes') -> 'Optional[tuple
500512
parser raises anything at all, or fewer octets were captured than the
501513
header needs.
502514
515+
Note:
516+
The header is parsed on trial as under
517+
:func:`~pcapkit.corekit.decorators.beholder`: one that raises is dropped
518+
with its warnings, as a replaced next layer is (:issue:`2308`,
519+
:issue:`2526`).
520+
503521
"""
504522
# pylint: disable-next=protected-access
505523
klass = Protocol_IPv4._lookup_next_layer(Protocol_IPv4.__proto__, protocol)
524+
token = _beholding.set(True)
506525
try:
507526
header = Protocol_IPv4._parse_next_layer( # pylint: disable=protected-access
508527
klass, data, len(data), version=4, extension=False, alias=protocol, protocol=klass)
509528
except Exception: # as beholder does
510529
return None
530+
finally:
531+
_beholding.reset(token)
511532
nxt = getattr(header.info, 'next', None) # none on a header cut short, read as raw octets
512533
if nxt is None:
513534
return None

‎tests/protocols/test_trial_parse_full_length_2516_unit.py‎

Lines changed: 32 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,16 @@
11
# -*- coding: utf-8 -*-
22
"""GitHub issue #2516: a trial parse that raises at full length and is kept as ``Raw`` warns nothing.
33
4-
:meth:`~pcapkit.protocols.protocol.ProtocolBase._parse_next_layer` held only a
5-
next layer captured shorter than its length hint (#1580), but
64
:func:`~pcapkit.corekit.decorators.beholder` replaces a layer that raises at any
7-
length (#2308). Without the fix, a TCP segment to port 443 that starts mid-record
8-
warned ``packet length < 0`` twice, from TLS's record header and from the SSLv2
9-
fallback it tries, for a TLS layer the result keeps as ``Raw``. Under
10-
``beholder`` every layer is now held, and its warnings are dropped with it. A
11-
kept layer still warns, from the caller's line, after the layers it carries.
5+
length (#2308), so holding only a next layer captured shorter than its length
6+
hint (#1580) lets a full-length layer's warnings through: a TCP segment to port
7+
443 that starts mid-record warns ``packet length < 0`` twice, from TLS's record
8+
header and from the SSLv2 fallback it tries, for a TLS layer the result keeps as
9+
``Raw``. Under ``beholder``,
10+
:meth:`~pcapkit.protocols.protocol.ProtocolBase._parse_next_layer` holds every
11+
layer, and drops a replaced layer's warnings with it. A kept layer warns from the
12+
caller's line, after the layers it carries. Outside ``beholder``, a full-length
13+
layer cannot be replaced and holds nothing.
1214
1315
:mod:`pcapkit` is imported inside each test, after
1416
:func:`~tests._support.reimport_once_per_class`.
@@ -123,13 +125,13 @@ def test_full_length_layer_that_raises_warns_nothing(self) -> None:
123125
self.assertEqual([str(item.message) for item in caught], [])
124126

125127
def test_well_formed_tls_record_warns_nothing(self) -> None:
126-
"""Control: a whole TLS record on 443 parses as TLS, as before, reporting nothing."""
128+
"""Control: a whole TLS record on 443 parses as TLS and reports nothing."""
127129
parsed, caught = self._parse('TCP', TCP_TO_443 + b'\x17\x03\x03\x00\x04abcd')
128130
self.assertEqual(str(parsed.protochain), 'TCP:TLS 1.2') # type: ignore[attr-defined]
129131
self.assertEqual(caught, [])
130132

131133
def test_kept_layer_still_warns_from_the_callers_line(self) -> None:
132-
"""Control: a kept IPv4 is held now, and reports its warning as it did."""
134+
"""Control: a kept IPv4 is held, and reports its warning from the caller's line."""
133135
from pcapkit.protocols.link.ethernet import Ethernet
134136
from pcapkit.utilities.warnings import ProtocolWarning
135137

@@ -148,6 +150,27 @@ def test_kept_layer_reports_after_the_layers_it_carries(self) -> None:
148150
_, caught = self._parse('Ethernet', _ipv4(41, shim6_cut, SECURITY))
149151
self.assertEqual([str(item.message) for item in caught], SHIM6_CUT_MESSAGES + [OPTION_WARNING])
150152

153+
def test_full_length_layer_outside_beholder_holds_nothing(self) -> None:
154+
"""Outside ``beholder``, a full-length IPv4 reports its warning before the layers it carries.
155+
156+
Nothing can replace it, so it holds nothing, even inside a block that
157+
discards: its warning is reported as raised. Only the layers its own
158+
``beholder`` parses are held, and report as their parse ends.
159+
160+
"""
161+
from pcapkit.protocols.internet.ipv4 import IPv4
162+
from pcapkit.protocols.protocol import ProtocolBase
163+
from pcapkit.utilities.warnings import hold_warnings
164+
165+
packet = _ipv4(41, _ipv6(140, b'\x00'), SECURITY)[len(MACS) + 2:] # past the Ethernet header
166+
with warnings.catch_warnings(record=True) as caught:
167+
warnings.simplefilter('always')
168+
with hold_warnings() as outer:
169+
outer.discard = True
170+
parsed = ProtocolBase._parse_next_layer(IPv4, packet, len(packet)) # pylint: disable=protected-access
171+
self.assertEqual(str(parsed.protochain), 'IPv4:IPv6:IPv6-Ext')
172+
self.assertEqual([str(item.message) for item in caught], [OPTION_WARNING] + SHIM6_CUT_MESSAGES)
173+
151174

152175
if __name__ == '__main__':
153176
unittest.main()
Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
# -*- coding: utf-8 -*-
2+
"""GitHub issue #2526: pypcapfile's header check warns nothing for a header it rejects.
3+
4+
:func:`~pcapkit.toolkit.pypcapfile._default_accepts` asks pcapkit's IPv4 or TCP
5+
parser about a header, and answers :data:`False` when that raises. The #2308
6+
rule applies: the trial's warnings describe a header nothing keeps, so they go
7+
with it. Held by nothing, a TCP header whose Timestamps option runs past its end
8+
warns ``packet length < 0`` twice before the answer. A header the parser accepts
9+
warns from the caller's line.
10+
11+
The parser reads its own header rather than a next layer, so setting
12+
``_beholding`` around it holds nothing, and the trial holds its own warnings.
13+
14+
The answers are cached by octets, so each test clears the cache before it asks.
15+
:mod:`pcapkit` is imported inside each test, after
16+
:func:`~tests._support.reimport_once_per_class`.
17+
18+
"""
19+
20+
import inspect
21+
import struct
22+
import unittest
23+
import warnings
24+
25+
from tests._support import reimport_once_per_class
26+
from tests.utilities._harness import capture
27+
28+
#: Test tier (#1958): exercises the warning machinery, which free-threaded
29+
#: builds make context-aware.
30+
__tier__ = 'ALL'
31+
32+
33+
def _ipv4(options: 'bytes') -> 'bytes':
34+
"""A bare IPv4 header carrying ``options``."""
35+
return struct.pack('!BBHHHBBH4s4s', 0x45 + len(options) // 4, 0, 20 + len(options),
36+
0, 0, 64, 6, 0, bytes([127, 0, 0, 1]), bytes([127, 0, 0, 2])) + options
37+
38+
39+
#: A 24-octet TCP header whose Timestamps option claims 10 octets of the 4 left.
40+
TCP_TIMESTAMPS_CUT = (struct.pack('!HHIIBBHHH', 12345, 80, 1, 0, 6 << 4, 0x02, 4095, 0, 0)
41+
+ bytes.fromhex('080a0000'))
42+
#: A 24-octet IPv4 header whose Record Route option claims 40 octets of the 4 left.
43+
IPV4_RECORD_ROUTE_CUT = _ipv4(bytes.fromhex('07280400'))
44+
#: A 28-octet IPv4 header whose Security option runs on past its last octet.
45+
IPV4_SECURITY = _ipv4(bytes.fromhex('8205ab0000') + bytes(3))
46+
#: The warning :data:`IPV4_SECURITY`'s option reports.
47+
SECURITY_WARNING = 'IPv4: [OptNo 130] invalid format: remaining data'
48+
49+
50+
class TestAcceptsTrial(unittest.TestCase):
51+
"""Pin that a rejected header reports nothing, and an accepted one does."""
52+
53+
def setUp(self) -> None:
54+
reimport_once_per_class(self)
55+
56+
def _ask(self, name: 'str', header: 'bytes',
57+
action: 'str' = 'always') -> 'tuple[bool, list[warnings.WarningMessage]]':
58+
"""Ask the uncached check about ``header``, with the warnings it reports."""
59+
from pcapkit.toolkit.pypcapfile import _default_accepts
60+
61+
_default_accepts.cache_clear()
62+
with warnings.catch_warnings(record=True) as caught:
63+
warnings.simplefilter(action)
64+
answer = _default_accepts(name, header)
65+
return answer, caught
66+
67+
def test_rejected_header_warns_nothing(self) -> None:
68+
"""A TCP or IPv4 header whose option runs past its end is rejected, reporting nothing on either channel."""
69+
from pcapkit.utilities.logging import logger
70+
71+
for name, header in (('TCP', TCP_TIMESTAMPS_CUT), ('IPv4', IPV4_RECORD_ROUTE_CUT)):
72+
with self.subTest(name=name):
73+
with capture(logger) as recorder:
74+
answer, caught = self._ask(name, header)
75+
self.assertFalse(answer)
76+
self.assertEqual([str(item.message) for item in caught], [])
77+
self.assertEqual([record.getMessage() for record in recorder.records
78+
if record.getMessage().startswith('packet length')], [])
79+
80+
def test_error_filter_rejects_a_warning_header(self) -> None:
81+
"""Control: under ``error``, a header that warns is rejected, and nothing escapes."""
82+
for name, header in (('TCP', TCP_TIMESTAMPS_CUT), ('IPv4', IPV4_SECURITY)):
83+
with self.subTest(name=name):
84+
answer, caught = self._ask(name, header, 'error')
85+
self.assertFalse(answer)
86+
self.assertEqual(caught, [])
87+
88+
def test_accepted_header_warns_from_the_callers_line(self) -> None:
89+
"""Control: an IPv4 header the parser accepts reports its option's warning."""
90+
from pcapkit.toolkit.pypcapfile import _default_accepts
91+
from pcapkit.utilities.warnings import ProtocolWarning
92+
93+
_default_accepts.cache_clear()
94+
with warnings.catch_warnings(record=True) as caught:
95+
warnings.simplefilter('always')
96+
line = inspect.currentframe().f_lineno + 1 # type: ignore[union-attr]
97+
answer = _default_accepts('IPv4', IPV4_SECURITY)
98+
self.assertTrue(answer)
99+
self.assertEqual([(item.category, str(item.message), item.filename, item.lineno) for item in caught],
100+
[(ProtocolWarning, SECURITY_WARNING, __file__, line)])
101+
102+
103+
if __name__ == '__main__':
104+
unittest.main()
Lines changed: 97 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,97 @@
1+
# -*- coding: utf-8 -*-
2+
"""GitHub issue #2526: pypcapfile's extension-header trial warns nothing when it raises.
3+
4+
:func:`~pcapkit.toolkit.pypcapfile._default_extension_header` reads a header
5+
inside IPv4 with
6+
:meth:`~pcapkit.protocols.protocol.ProtocolBase._parse_next_layer`, and answers
7+
:data:`None` when that raises, as :func:`~pcapkit.corekit.decorators.beholder`
8+
replaces such a layer. The #2308 rule applies: the trial's warnings describe a
9+
header nothing keeps, so they go with it. Outside ``beholder`` they are reported
10+
as the error leaves, so a HIP header cut to 8 octets warns ``packet length < 0``
11+
twice before the answer. A header the trial keeps warns from the caller's line.
12+
13+
The answers are cached by octets, so each test clears the cache before it asks.
14+
:mod:`pcapkit` is imported inside each test, after
15+
:func:`~tests._support.reimport_once_per_class`.
16+
17+
"""
18+
19+
import inspect
20+
import unittest
21+
import warnings
22+
23+
from tests._support import reimport_once_per_class
24+
from tests.utilities._harness import capture
25+
26+
#: Test tier (#1958): exercises the warning machinery, which free-threaded
27+
#: builds make context-aware.
28+
__tier__ = 'ALL'
29+
30+
#: IP protocol numbers of HIP and the Mobility Header.
31+
HIP, MOBILITY_HEADER = 139, 135
32+
#: The first 8 octets of a HIP header, whose fixed part is 40.
33+
HIP_CUT = bytes.fromhex('b0ff89ff0042ff1c')
34+
#: A Mobility Header of 8 octets, 16 short of the Binding Error message it
35+
#: carries, then 1 octet of its UDP payload.
36+
MH_BINDING_ERROR = bytes.fromhex('11000742d5bd297b99')
37+
#: The warning the Mobility Header's message reports.
38+
MH_WARNING = 'packet length < 0: -16'
39+
40+
41+
class TestExtensionHeaderTrial(unittest.TestCase):
42+
"""Pin that a raising extension-header trial reports nothing, and a kept one does."""
43+
44+
def setUp(self) -> None:
45+
reimport_once_per_class(self)
46+
47+
def _ask(self, protocol: 'int', data: 'bytes',
48+
action: 'str' = 'always') -> 'tuple[object, list[warnings.WarningMessage]]':
49+
"""Ask the uncached reader about ``data``, with the warnings it reports.
50+
51+
The trial must leave ``beholder``'s flag unset, whatever it answers.
52+
53+
"""
54+
from pcapkit.corekit import decorators
55+
from pcapkit.toolkit.pypcapfile import _default_extension_header
56+
57+
_default_extension_header.cache_clear()
58+
with warnings.catch_warnings(record=True) as caught:
59+
warnings.simplefilter(action)
60+
answer = _default_extension_header(protocol, data)
61+
self.assertFalse(decorators._beholding.get()) # pylint: disable=protected-access
62+
return answer, caught
63+
64+
def test_raising_trial_warns_nothing(self) -> None:
65+
"""The cut HIP header raises, answers ``None``, and reports nothing on either channel."""
66+
from pcapkit.utilities.logging import logger
67+
68+
with capture(logger) as recorder:
69+
answer, caught = self._ask(HIP, HIP_CUT)
70+
self.assertIsNone(answer)
71+
self.assertEqual([str(item.message) for item in caught], [])
72+
self.assertEqual([record.getMessage() for record in recorder.records
73+
if record.getMessage().startswith('packet length')], [])
74+
75+
def test_error_filter_answers_none(self) -> None:
76+
"""Control: under ``error``, the cut HIP header answers ``None`` and reports nothing."""
77+
answer, caught = self._ask(HIP, HIP_CUT, 'error')
78+
self.assertIsNone(answer)
79+
self.assertEqual(caught, [])
80+
81+
def test_kept_header_warns_from_the_callers_line(self) -> None:
82+
"""Control: a Mobility Header the trial keeps reports its message's warning."""
83+
from pcapkit.toolkit.pypcapfile import _default_extension_header
84+
from pcapkit.utilities.warnings import SchemaWarning
85+
86+
_default_extension_header.cache_clear()
87+
with warnings.catch_warnings(record=True) as caught:
88+
warnings.simplefilter('always')
89+
line = inspect.currentframe().f_lineno + 1 # type: ignore[union-attr]
90+
answer = _default_extension_header(MOBILITY_HEADER, MH_BINDING_ERROR)
91+
self.assertEqual(answer, (17, 8))
92+
self.assertEqual([(item.category, str(item.message), item.filename, item.lineno) for item in caught],
93+
[(SchemaWarning, MH_WARNING, __file__, line)])
94+
95+
96+
if __name__ == '__main__':
97+
unittest.main()

0 commit comments

Comments
 (0)