refactor(toolkit): revert scapy's agreement-only code (#1708)

[JarryShaw]

Please follow the guide below

• You will be asked some questions, please read them carefully and answer honestly

• Put an x into all the boxes [ ] relevant to your pull request (like that [x])

• Use Preview tab to see how your pull request will actually look like

• Searched for similar pull requests

• Followed the coding style (make pylint, make mypy, make isort)

• make test passes, and a test case covers the change. Narrow runs only, listed below.

• Added a changelog entry under docs/source/changelog/ and regenerated CHANGELOG.md, if the change is user-visible: N/A — centralised in docs(changelog): shared 1.5.0 changelog — long-lived, merges last (#610, #616, #617, #618, #620) #657

What is the purpose of your pull request?

Tick the commit type your subject line carries.

• fix — corrects a defect
• feat — adds a feature
• perf — changes performance, not behaviour
• refactor — changes neither behaviour nor performance
• test — tests only
• docs — documentation only
• ci — workflows or build tooling
• release — bumps the version or rolls up a distribution
• chore — anything else

---

Description of your pull request and other information

Phase 2 of #1708, for scapy, per the plan on #1687.

• Reverted: fix(toolkit): scapy reads nothing in a zero-length frame, and a hand-built packet off its octets (#1676) #1683, fix(toolkit): scapy walks link types, layer bounds and IPv6 extension headers as the default engine does (#1609, #1626, #1650) #1663, fix(toolkit): scapy reads IP and TCP only in layers the default engine dissects (#1635, #1636) #1652 and fix(toolkit): scapy cuts 4in6 at each Payload Length and skips ICMP quotes (#1623, #1627) #1631, and the scapy hunks of fix(toolkit): dpkt and scapy check IPv4 headers as the default engine does (#1607) #1614. That removes _ipv4_accepted, _quoted, _linktype, _network, _ipv6_chain, _dissected, _first_ipv4, _first_ipv6 and LOOPBACK_FAMILIES, plus four test modules.
• Kept:
  • fix(toolkit): key tunnelled TCP by the innermost IP header (#1581) #1605's TCP keying by the innermost IP header, and fix(toolkit): the scapy adapters stop at the IP datagram's declared length (#1584) #1589's trailer cut;
  • fix(toolkit): dpkt and scapy find TCP in IPv4 where the default engine does (#1606, #1617) #1624's scapy half (TCP behind AH or an IPv6 extension header in IPv4, and the stop at a later fragment), which the plan does not list. Say if its fix(toolkit): the dpkt and scapy engines drop TCP behind an IPv6 extension header carried in IPv4 #1606 part should go too.
• Re-landed as guards whose tests assert constants:
  • the zero-length frame (fix(toolkit): scapy ends the extraction on a zero-length RAW frame when IPv4 reassembly is on #1676);
  • the 4in6 trailer cut (fix(toolkit): scapy hands IPv4 reassembly the octets past the carrying IPv6 Payload Length #1623 via fix(toolkit): scapy cuts 4in6 at each Payload Length and skips ICMP quotes (#1623, #1627) #1631), whose defect the old code does show;
  • three own-job defects found by probing: hand-built packets raising TypeError, an inner Fragment header handed to IPv6 reassembly in 6in6, and IPv6 read inside a later IPv4 fragment.
• Shared helper: the walk calls _walk_extension_headers, which refactor(toolkit): revert pypcapfile's agreement-only code (#1708) #1721 keeps, instead of _past_extension_headers, which refactor(toolkit): revert pypcapfile's agreement-only code (#1708) #1721 deletes. The combined tree passes.
• Captures: the 23 generated captures give byte-identical scapy output. Edge frames now read as scapy dissects them, and the docs list each silent gap.
• Tests: tests/toolkit (251 passed) and tests/foundation/engines (147 passed) on 3.14 with scapy 2.7.0, and both on 3.11 with scapy 2.8.0 (430 passed). Sphinx gives 63 warnings, unchanged.

[JarryShaw]

Verdict: GOOD TO GO at 6f1feb52f. A Sonnet cross-review checked it; the author was Opus.

• Reverted rows: against scapy.py as it stood after fix(toolkit): dpkt and scapy find TCP in IPv4 where the default engine does (#1606, #1617) #1624, the diff is only the guards, the helper rename and docstrings. Nothing from fix(toolkit): scapy cuts 4in6 at each Payload Length and skips ICMP quotes (#1623, #1627) #1631, fix(toolkit): scapy reads IP and TCP only in layers the default engine dissects (#1635, #1636) #1652, fix(toolkit): scapy walks link types, layer bounds and IPv6 extension headers as the default engine does (#1609, #1626, #1650) #1663 or fix(toolkit): scapy reads nothing in a zero-length frame, and a hand-built packet off its octets (#1676) #1683 survives, and the keep list is intact.
• Guards: I removed each of the 10 guards in turn, and every removal fails its test. The restored old fix(toolkit): scapy hands IPv4 reassembly the octets past the carrying IPv6 Payload Length #1623 test passes for scapy on all 8 cases.
• Prose: a case-insensitive grep finds 302 hits in 31 files. No false statement about scapy survives, and probes confirm the new prose about VLAN depth, extension headers and loopback families.
• Fuzz: 4,896 frames across 8 link types. Every frame main reads and this branch does not falls in a gap the docs list. No crash and no malformed hand-over.
• With refactor(toolkit): revert pypcapfile's agreement-only code (#1708) #1721: a combined tree passes test_scapy_unit and test_scapy_engine.
• Untouched: no pypcapfile, dpkt or pyshark source, and fix(engines): the scapy engine cuts a captured record at 65,535 octets #1717.

[JarryShaw]

Heads-up: this conflicts with #1721 (pypcapfile) in toolkit/scapy.py, ext.rst, index.rst, internet.rst and protocol.rst, where both rewrite the same sentences about the engines. Either can merge first, and I will rebase the other onto it.

[JarryShaw]

Rebased onto main after #1721 as 53bf23eda.

Verdict: GOOD TO GO at 53bf23eda. A Sonnet cross-review (author: Opus) checked 41a149d8a. 53bf23eda differs from it only in one commit-body line, corrected because the toolkit applies the extension-header bound behind IPv4.

• Unchanged code: toolkit/scapy.py is byte-identical to 6f1feb52f. The rebase changes only the five conflicted doc hunks, and no refactor(toolkit): revert pypcapfile's agreement-only code (#1708) #1721 file is in the diff.
• Merged sentences: in ext.rst, index.rst, internet.rst and protocol.rst they are true of main's pypcapfile adapter and this scapy adapter.
• Measured: behind IPv4, TCP is read after 32 extension headers and not after 33. In an IP-in-IP tunnel it is read 65 layers deep. pypcapfile drops TCP behind VLAN, IP-in-IP and AH without a warning.
• Sphinx and tests: Sphinx warnings are the same as main's (63). tests/toolkit and tests/foundation/engines pass on 3.14 (363 passed) and on 3.11 with scapy 2.8.0 (378 passed).

[github-actions]

Coverage: 89.65% (unit tier, Python 3.15, 53bf23eda, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	3	20	3	95.16%
pcapkit/const	18860	954	2368	868	91.06%
pcapkit/corekit	2372	67	762	35	96.49%
pcapkit/dumpkit	275	3	100	3	98.40%
pcapkit/foundation	2885	144	1010	34	94.20%
pcapkit/interface	138	7	52	5	93.68%
pcapkit/protocols	17181	226	4590	190	98.07%
pcapkit/toolkit	1015	173	372	10	80.89%
pcapkit/utilities	508	4	154	4	98.79%
pcapkit/vendor	4417	2342	1010	157	43.38%

Per-file detail: the coverage-html artifact of this run.