Skip to content

Commit 627fa25

Browse files
authored
Merge branch 'main' into ci/1660-python-version-tiers-file
2 parents c605ea3 + 7aeeaf8 commit 627fa25

13 files changed

Lines changed: 1409 additions & 121 deletions

‎docs/source/pcapkit/foundation/engines/3rdparty.rst‎

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -399,7 +399,9 @@ support, as is used by :class:`pcapkit.foundation.extraction.Extractor`.
399399
TCP and UDP and nothing else. IPv6 reassembly is therefore unavailable and is
400400
disabled -- with an :class:`~pcapkit.utilities.warnings.AttributeWarning` --
401401
when requested; IPv4 and TCP reassembly and TCP flow tracing remain
402-
available. PCAP-NG is rejected with a
402+
available. The IP packet of a BSD loopback or raw-IP frame, which it does
403+
not decode, is read by :mod:`pcapkit.toolkit.pypcapfile` instead
404+
(:issue:`1667`). PCAP-NG is rejected with a
403405
:exc:`~pcapkit.utilities.exceptions.FormatError`. `PyPCAPFile`_ 0.12.0 drops
404406
every record of a big-endian savefile, every record from a zero-length one
405407
on, and a truncated final record, so the engine reads the records itself,

‎docs/source/pcapkit/protocols/protocol.rst‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -116,9 +116,9 @@ there back out, as they do one the TCP parser rejected (:issue:`1518`). A
116116
protocol constructed from its own octets is not counted itself, so the count
117117
starts at the first layer it dissects. One chain of extension headers is also bounded on
118118
its own, by :data:`~pcapkit.protocols.internet.internet.EXTENSION_HEADER_LIMIT`.
119-
The ``pyshark`` and ``pypcapfile`` engines dissect with their own parsers,
120-
which do not apply this bound (:issue:`1609`). The ``dpkt`` and ``scapy``
121-
toolkits count the layers they walk as the default engine does, and stop at it.
119+
The ``pyshark`` engine dissects with its own parser, which does not apply this
120+
bound (:issue:`1609`). The ``dpkt``, ``scapy`` and ``pypcapfile`` toolkits
121+
count the layers they walk as the default engine does, and stop at it.
122122

123123
.. autodata:: pcapkit.protocols.protocol.FRAME_LAYER_LIMIT
124124

‎docs/source/pcapkit/toolkit/3rdparty.rst‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -193,6 +193,17 @@ cannot be used for it.
193193
:func:`~pcapkit.toolkit.pypcapfile.tcp_traceflow`, with an
194194
:class:`~pcapkit.utilities.warnings.AttributeWarning` once per capture.
195195

196+
Nor does it decode a link layer but Ethernet. The adapters read the IP packet
197+
of a BSD loopback (``NULL``, ``LOOP``) or raw-IP (``RAW``, ``IPV4``,
198+
``IPV6``) frame themselves, as the default engine dissects it (see
199+
:data:`~pcapkit.toolkit.pypcapfile.READ_LINKTYPES`, :issue:`1667`). Every
200+
other link type is left unread, as the default engine leaves it, and the
201+
engine warns of it with an :class:`~pcapkit.utilities.warnings.AttributeWarning`.
202+
Nor do the adapters read deeper than the default engine dissects: each VLAN
203+
tag, IP header, AH and IPv6 extension header is one of the
204+
:data:`~pcapkit.protocols.protocol.FRAME_LAYER_LIMIT` layers of a frame, and
205+
nothing past the last of them is read (:issue:`1609`).
206+
196207
.. autofunction:: pcapkit.toolkit.pypcapfile.ipv4_reassembly
197208

198209
.. autofunction:: pcapkit.toolkit.pypcapfile.ipv6_reassembly
@@ -215,6 +226,9 @@ Auxiliary Functions
215226
Internal Definitions
216227
--------------------
217228

229+
.. autodata:: pcapkit.toolkit.pypcapfile.READ_LINKTYPES
230+
:no-value:
231+
218232
.. autodata:: pcapkit.toolkit.pypcapfile.TCP_MIN_HEADER_LEN
219233

220234
.. autodata:: pcapkit.toolkit.pypcapfile.IPV4_FLAG_DF

‎pcapkit/foundation/engines/pypcapfile.py‎

Lines changed: 24 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -47,10 +47,15 @@ class PyPCAPFile(EngineBase['PCAPFilePacket']):
4747
objects, as `PyPCAPFile`_ 0.12.0 drops records the ``default`` engine
4848
reads -- see :meth:`_read_records`,
4949
* disables IPv6 reassembly, warning as it does so, while leaving IPv4 and
50-
TCP reassembly and TCP flow tracing in place, and
50+
TCP reassembly and TCP flow tracing in place,
5151
* leaves TCP over IPv6 out of TCP reassembly and flow tracing, with one
5252
:exc:`~pcapkit.utilities.warnings.AttributeWarning` per capture -- see
53-
:mod:`pcapkit.toolkit.pypcapfile`.
53+
:mod:`pcapkit.toolkit.pypcapfile` -- and
54+
* leaves the frames of a link type `PyPCAPFile`_ has no decoder for
55+
undecoded, from which :mod:`pcapkit.toolkit.pypcapfile` reads the IP
56+
packet of the BSD loopback and raw-IP ones itself, as the ``default``
57+
engine dissects it (see
58+
:data:`~pcapkit.toolkit.pypcapfile.READ_LINKTYPES`).
5459
5560
The engine stops decoding at the network layer rather than descending into
5661
the transport layer. `PyPCAPFile`_ decoders *replace* the payload bytes of
@@ -184,8 +189,10 @@ def run(self) -> 'None':
184189
support such operations.
185190
* if IPv6 reassembly is enabled, as :mod:`pcapfile` has no IPv6
186191
decoder.
187-
* if :mod:`pcapfile` has no decoder for the savefile's link layer
188-
type, in which case frames are left undecoded.
192+
* if the savefile's link layer type is left unread: neither
193+
:mod:`pcapfile` has a decoder for it nor
194+
:mod:`pcapkit.toolkit.pypcapfile` reads it (see
195+
:meth:`_get_decoder`).
189196
190197
Raises:
191198
FormatError: If the file format is not supported, i.e., not a PCAP
@@ -302,20 +309,27 @@ def _get_decoder(self, linktype: 'int') -> 'Optional[Callable[..., Any]]':
302309
The decoder class, or :data:`None` when :mod:`pcapfile` has none.
303310
304311
Warns:
305-
AttributeWarning: If no decoder is available, as frames will then be
306-
left hexlified -- see :meth:`run` -- and no reassembly or flow
307-
tracing is possible.
312+
AttributeWarning: If no decoder is available and the link layer type
313+
is none of the :data:`~pcapkit.toolkit.pypcapfile.READ_LINKTYPES`,
314+
as frames will then be left hexlified -- see :meth:`run` -- and
315+
no reassembly or flow tracing is possible. The frames of those
316+
link types are left undecoded too, but reassembly and flow
317+
tracing read the IP packet in them, as the ``default`` engine
318+
does, so nothing is lost there to warn of.
308319
309320
"""
321+
from pcapkit.toolkit.pypcapfile import READ_LINKTYPES # isort:skip
322+
310323
try:
311324
decoder = self._expkg.linklayer.clookup(linktype)
312325
except IndexError: # malformed entry in ``pcapfile.linklayer.__LL_TYPES__``
313326
decoder = None
314327

315328
if not callable(decoder):
316-
warn(f'unrecognised link layer protocol: {self._dlink!r}; frames will be left '
317-
'undecoded and all analysis functions ignored', AttributeWarning,
318-
stacklevel=stacklevel())
329+
if linktype not in READ_LINKTYPES:
330+
warn(f'unrecognised link layer protocol: {self._dlink!r}; frames will be left '
331+
'undecoded and all analysis functions ignored', AttributeWarning,
332+
stacklevel=stacklevel())
319333
return None
320334
return decoder
321335

0 commit comments

Comments
 (0)