Fix seven PCAP-NG parser defects (#341-#347)

[JarryShaw]

Draft. Seven defects found while building deterministic PCAP-NG fixtures for the test suite; each has a regression test that builds the block bytes in-test, and each was proven to fail before the fix and pass after.

Schema (pcapkit/protocols/schema/misc/pcapng.py)

• PCAP-NG Custom Block padding computed on bytes, not len(bytes) #341 Custom Block — padding was (4 - pkt['data'] % 4) % 4 on bytes, so every custom block raised TypeError. The field is dropped rather than repaired with a len(): data already spans the whole region between the PEN and the trailing block length, which is what Data_CustomBlock and _make_block_cb assumed all along. _make_block_cb now pads to 32 bits so the length it writes is a multiple of four.
• PCAP-NG ISB option area sized 4 octets too long (length - 20) #342 Interface Statistics Block — option area sized length - 20 where the fixed fields occupy 24 octets. Unconditional, and reproduces on Wireshark's own many_interfaces.pcapng.
• PCAP-NG NRB nrb_record_ipv6 sized as if the address were 4 octets #343 Name Resolution Block IPv6 records — name sized length - 4, copied from the IPv4 record. On a real capture the names came back ['v6.example', '', '', '', '', '', '', '', 'res'] and the following record decoded as garbage with length=29285.
• PCAP-NG NRB options field reads past the end of the block #344 NRB options read past the end of the block — not a constant, as first suspected. records spans both the record and option areas, and Schema.unpack advances the file by each field's declared length, so options began beyond the block. Fixed in OptionField (schema.py), which now rewinds its unconsumed remainder exactly as ForwardMatchField already does. That also removes a latent double-read behind every other OptionField in the tree, TCP's and IPv4's included.
• PCAP-NG obsolete Packet Block: 32-bit fields vs 32-octet arithmetic #345 obsolete Packet Block — two independent causes: interface_id/drop_count declared 32-bit where the spec makes both 16-bit, and _read_block_packet reaching for the linktype property before _info exists. Field widths alone do not clear the AttributeError.

Field and engine

• if_IPv6addr prefix length parsed as an ASCII string, not an octet #346 if_IPv6addr — IPv6InterfaceField.post_process parsed the trailing prefix-length octet as an ASCII decimal string, so /64 raised ValueError and /56 silently decoded as /8. Only lengths 48–57 parsed at all, every one wrongly, and the field could not read what its own pre_process wrote. IPv4InterfaceField was checked and is genuinely unaffected — its encoding is symmetric — which a test now pins.
• Simple Packet Block rejected in any multi-interface section #347 Simple Packet Block — rejected in any section with more than one interface, which §4.4 permits. The check belonged on the zero-interface case, and had to move before the block is parsed: a section with no IDB died in _get_linktype first, which also left the EPB and Packet Block bounds guards unreachable. The engine now peeks the next block type.

Blast radius of the shared OptionField change

The full format='tree' dissection of all 15 fixtures was compared before and after. Only test.pcapng differs, and only by becoming correct: its three ns_* options now appear where there were none, and one spurious packet length < 0 warning is gone. No .pcap dissection changed.

Tests

Nine tests across tests/protocols/misc/test_pcapng_unit.py, a new tests/corekit/test_fields_ipaddress.py (exhaustive round trip over all 129 IPv6 prefix lengths, with an explicit case per length 48–57, since a test that only checked /64 would have passed on the old code for /56), and tests/foundation/engines/test_pcapng_engine.py (SPB in multi-IDB sections in both byte orders; FormatError rather than IndexError when a section has no IDB).

Closes #341, #342, #343, #344, #345, #346, #347.

[Copilot]

🔵 Needs a closer look

It changes core schema unpacking semantics (OptionField rewind) and PCAP-NG engine control flow, which can have wide parsing impact beyond the specific fixtures even with added tests.

Pull request overview

This PR fixes seven PCAP-NG parsing/engine defects discovered while building deterministic PCAP-NG fixtures, and adds targeted regression tests to ensure the corrected block/option/field behaviors remain stable across byte orders and section/interface shapes.

Changes:

• Fixes multiple PCAP-NG schema layout/length bugs (ISB option sizing, NRB IPv6 record sizing, NRB option parsing/rewind, Custom Block data semantics, obsolete Packet Block 16-bit IDs, ns_dnsname padding).
• Fixes PCAP-NG engine section-rule handling for packet blocks (SPB allowed in multi-IDB sections; packet blocks rejected early when no IDB exists via peeking next block type).
• Fixes IPv6 interface option prefix-length decoding and adds exhaustive round-trip tests; adds multiple new unit and end-to-end regression tests.

File summaries

File	Description
tests/protocols/misc/test_pcapng_unit.py	Adds schema-level regression tests for CB/ISB/NRB/PacketBlock parsing and OptionField remainder behavior.
tests/foundation/engines/test_runtime_engines.py	Updates engine test harness to use a peekable buffered reader, matching Extractor behavior.
tests/foundation/engines/test_pcapng_engine.py	Adds end-to-end section-rule tests via a synthetic PCAP-NG writer; expands engine unit coverage for peek/context checks.
tests/corekit/test_fields_ipaddress.py	Adds new exhaustive IPv6 interface prefix-length round-trip/spec tests and IPv4/IPv6 encoding non-interchangeability checks.
pcapkit/protocols/schema/schema.py	Rewinds underlying stream by OptionField unconsumed remainder so subsequent fields read the correct bytes.
pcapkit/protocols/schema/misc/pcapng.py	Fixes multiple PCAP-NG schema defects (NRB IPv6 sizing, NS_DNSName padding, NRB option sizing, ISB option sizing, CB data field, PacketBlock ID widths).
pcapkit/protocols/misc/pcapng.py	Fixes obsolete Packet Block linktype resolution; ensures Custom Block maker pads data/options to 32-bit boundaries.
pcapkit/foundation/engines/pcapng.py	Corrects SPB section rule; adds “peek next block type” guard to reject packet blocks before any IDB.
pcapkit/corekit/fields/ipaddress.py	Fixes IPv6 prefix-length octet parsing and adds explicit out-of-range validation; clarifies IPv4 vs IPv6 interface encoding notes.
examples/generators/pcapng.py	Updates generator documentation to reflect which constructs are now fixed vs still problematic.

Review details

• Files reviewed: 10/10 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

The updated generator documentation still claims if_IPv6addr and multi-interface SPB are broken even though this PR fixes both, leaving the docs inconsistent with the new behavior.

Review details

Suppressed comments (2)

Previously missed (2) — in code that hasn't changed since the last review.

examples/generators/pcapng.py:86

• This section describes a Simple Packet Block multi-interface rejection as an active defect and says test.pcapng carries an SPB in a second section as a workaround. In this PR the engine guard is changed to only reject the zero-interface case and new tests cover multi-interface SPB parsing, so the documentation should be updated accordingly.

A further defect is worked around rather than avoided. A **Simple Packet Block**
in a section declaring more than one interface raises ``FormatError: PCAP-NG:
[SPB] invalid section with 2 interfaces`` at
``pcapkit/foundation/engines/pcapng.py:218``, which tests
``len(interfaces) != 1``. The format specification (section 4.4 of

examples/generators/pcapng.py:80

• The generator doc still states that if_IPv6addr raises due to parsing the prefix-length octet as an ASCII string, but this PR changes IPv6InterfaceField.post_process to read the octet as a binary integer and adds tests verifying round-trips for all prefix lengths. This section should be updated so the documentation matches the new behavior.

• Files reviewed: 10/10 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

There are a couple of correctness/documentation issues in the changed code paths (notably float-based padding math in _make_block_cb and misleading __option_padding__ doc wording) that should be addressed before approval.

Review details

Suppressed comments (2)

Previously missed (1) — in code that hasn't changed since the last review.

pcapkit/protocols/misc/pcapng.py:3713

• _make_block_cb pads using math.ceil(len(cb_data) / 4), which goes through floating-point arithmetic. For extremely large cb_data lengths (>= 2**53), float precision can produce an incorrect pad length. Using pure integer modulo avoids this edge case and is simpler.

pcapkit/protocols/schema/schema.py:587

• The docstring describes __option_padding__ as “the length of the padding field after an OptionField”, but it can also represent the unconsumed remainder of the option area (e.g., when a following field reads options out of that remainder). This wording is misleading given the behavior described immediately below and the use cases in PCAP-NG NRB parsing.

            And an ``__option_padding__`` key in the ``packet`` to record the
            length of the padding field after an
            :class:`~pcapkit.corekit.fields.collections.OptionField`, which
            is used to potentially determine the length of the remaining
            padding field data.

• Files reviewed: 10/10 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

It changes core schema unpacking and PCAP-NG engine control flow in ways that can have broad parsing impact beyond the covered fixtures, so a final human review is warranted.

Review details

• Files reviewed: 10/10 changed files
• Comments generated: 0 new
• Review effort level: Lite