From 36b8a346f40e96ae970970c2907a2d9768e50bd7 Mon Sep 17 00:00:00 2001 From: Jarry Shaw Date: Wed, 7 Oct 2026 16:53:40 -0400 Subject: [PATCH] docs(engines): the dpkt engine silently drops PCAP-NG Simple Packet Blocks dpkt.pcapng.Reader yields only Enhanced and (obsolete) Packet Blocks and skips every other block, Simple Packet Blocks included. Document that limit in the DPKT section of 3rdparty.rst and in the DPKT class docstring. Closes #1361 --- .../pcapkit/foundation/engines/3rdparty.rst | 19 +++++++++++++++++++ pcapkit/foundation/engines/dpkt.py | 7 +++++++ 2 files changed, 26 insertions(+) diff --git a/docs/source/pcapkit/foundation/engines/3rdparty.rst b/docs/source/pcapkit/foundation/engines/3rdparty.rst index 0c03be41df..982ba14753 100644 --- a/docs/source/pcapkit/foundation/engines/3rdparty.rst +++ b/docs/source/pcapkit/foundation/engines/3rdparty.rst @@ -64,6 +64,25 @@ support, as is used by :class:`pcapkit.foundation.extraction.Extractor`. .. _DPKT: https://dpkt.readthedocs.io +.. important:: + + On PCAP-NG, `DPKT`_ yields **Enhanced Packet Blocks and (obsolete) Packet + Blocks only**. ``dpkt.pcapng.Reader.__iter__`` skips every other block type + without a warning (``# just ignore other blocks``, as of ``dpkt`` 1.9.8), and + that includes the **Simple Packet Block**, which carries a packet just as an + Enhanced Packet Block does. Such packets are silently missing from this + engine's output, and the frames after them are numbered as if they had never + been captured. + + Reading :file:`examples/captures/test.pcapng` -- four Enhanced Packet Blocks + and one Simple Packet Block, across two sections -- this engine gives four + frames where the default engine and + :class:`~pcapkit.foundation.engines.scapy.Scapy` give five; the missing one is + frame 4, the Simple Packet Block. The second Section Header Block is not the + cause: the Enhanced Packet Block after it is read. This is a limitation of + `DPKT`_, not of :mod:`pcapkit`, so read a capture that may contain Simple + Packet Blocks with the default engine instead. + .. autoclass:: pcapkit.foundation.engines.dpkt.DPKT :no-members: :show-inheritance: diff --git a/pcapkit/foundation/engines/dpkt.py b/pcapkit/foundation/engines/dpkt.py index bbbd12076e..d7474dca28 100644 --- a/pcapkit/foundation/engines/dpkt.py +++ b/pcapkit/foundation/engines/dpkt.py @@ -39,6 +39,13 @@ class DPKT(EngineBase['DPKTPacket']): """DPKT engine support. + On PCAP-NG, `DPKT`_'s reader yields Enhanced Packet Blocks and (obsolete) + Packet Blocks only, and skips every other block without a warning -- the + Simple Packet Block included. A packet carried in a Simple Packet Block is + therefore missing from this engine's output; the default engine reads it. + + .. _DPKT: https://dpkt.readthedocs.io + Args: extractor: :class:`~pcapkit.foundation.extraction.Extractor` instance.