fix(toolkit): pyshark traces no TCP inside encapsulations the default engine leaves raw (#1639)

[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

• 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

Cause. pyshark traced whatever TCP tshark dissects. tshark dissects TCP inside DLT 12 and 14 (it reads both as raw IP), Linux SLL, MPLS, PPPoE, LLC/SNAP, Cisco ISL, GRE, VXLAN and L2TP, and the default engine leaves all of these raw.

Fix. Every frame tshark finds TCP in now takes #1642's octet path (pcapkit/toolkit/pyshark.py:958): the outermost IP layer by the capture file's link type, then IP-in-IP only. Nothing is traced where the default engine reads no IP, or where tshark's IP layer is elsewhere. _network matches that layer's destination address where tshark reports it (:835), because behind an LSRR or SSRR route not yet used up tshark's ip.dst is the route's last address, in the option. OCTETS_FILTER gains tcp (:356). The second tshark pass costs about 0.1 s per capture with TCP: 0.12 s against 0.23 s median on 3 frames. On 5,000 TCP frames it is lost in run-to-run noise (28.8–29.2 s on both). If the octets can't be read, the frame is traced as tshark dissects it, as before.

Measured on 3.11 with tshark 4.6.9, against main. The sweep covers 18,050 frames on DLTs 0, 1, 12, 14, 101, 108, 113, 228, 229 and 276 plus PCAP-NG, and 10,080 more behind LSRR, SSRR and Record Route options (live, used up and malformed). Result: 0 new disagreements, 10,685 fixed, 126 left (#1626 and FRAME_LAYER_LIMIT, below). 2,357 of the fixed frames are in 12 source-route captures that main's pyshark aborted with a bare AttributeError, because tshark gives no ip.dst behind a length-9 route. This branch reads them through.

Tests. New tests/toolkit/test_pyshark_encapsulated_tcp_1639_unit.py. With pcapkit/ at main, all 11 tests fail (32 failures). On this branch's previous revision, its source-route cases fail (3 tests, 5 failures). Three existing files pinned #1642's interim fallback and are updated, as before.

Not fixed here, unchanged from main:

• TCP behind Mobility or HIP in IPv6, which is fix(toolkit): dpkt, scapy and pyshark drop TCP and IPv4 behind some IPv6 extension-header chains #1626, and IP-in-IP past FRAME_LAYER_LIMIT.
• Where the octets can't be read, the fallback keys a source-routed segment by tshark's ip.dst, and raises AttributeError where there is none.
• pyshark 0.6's TSharkCrashException (retcode 255) is a race that also happens on main. It hits test_engine_agreement_runtime.py about 0.3 times per run on both: 11 in 37 runs on main, 12 in 42 here.

Closes #1639

[JarryShaw]

Verdict: GOOD TO GO at 6890f38f6. Round 2 passed a Sonnet cross-review: three fresh sweeps of 28,352 independently built frames showed 0 new disagreements and 0 new errors against main. Round 1 had come back NEEDS CHANGES for an LSRR/SSRR disagreement in _network. I re-ran the 1639, 1625, test_pyshark_unit and 1604 agreement tests on 3.11 with tshark 4.6.9: 11, 28, 38 and 3 passed.

Round 2's fix: tshark moves ip.dst to the route's last address while an LSRR or SSRR route is still live. _network now matches the destination at the position tshark reports for it (ip.dst.pos), rather than at the header's place.

Unverified:

• behaviour on tshark versions other than 4.6.9, which CI's engine tests will exercise;
• the cost, about +0.1 s per capture with TCP, which was not re-measured.

A TSharkCrashException in test_engine_agreement_runtime.py predates this PR and occurs at the same rate on main.

Left for a follow-up, being filed: the _from_layers fallback still raises a bare AttributeError when tshark reports no ip.dst.

[JarryShaw]

resolve conflicts

[JarryShaw]

Recorded: resolving the conflicts. With #1663 merged, the only conflict is in tests/foundation/engines/test_ext_chain_limit_agreement_1604_unit.py, whose docstring #1663 rewrote. A worker is rebasing onto main, keeping #1663's state and adding this PR's pyshark edits on top. The rebased head then gets a short Sonnet check, and runs the pyshark tests on 3.11 with tshark, before the label is renewed.

[github-actions]

Coverage: 89.46% (unit tier, Python 3.14, f0c02f0e5, Unit Tests run success)

Package	Statements	Missed	Branches	Partial	Cover
pcapkit (top level)	104	3	20	3	95.16%
pcapkit/const	18858	954	2366	868	91.06%
pcapkit/corekit	2366	67	760	35	96.48%
pcapkit/dumpkit	275	3	100	3	98.40%
pcapkit/foundation	3031	152	1074	35	94.23%
pcapkit/interface	138	7	52	5	93.68%
pcapkit/protocols	17166	226	4580	190	98.07%
pcapkit/toolkit	1354	275	558	6	77.25%
pcapkit/utilities	494	4	146	4	98.75%
pcapkit/vendor	4409	2342	1006	157	43.25%

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

[JarryShaw]

Verdict: GOOD TO GO at f0c02f0e5. It is rebased onto main at 257580444, after #1663 and #1669, and a Sonnet check confirmed the result. I re-ran the 1604 agreement and 1639 tests on 3.11 with tshark 4.6.9: 3 and 11 passed.

git range-diff shows five of the six files byte-identical. The sixth, test_ext_chain_limit_agreement_1604_unit.py, keeps #1663's state and drops the last Gap, ipv6-33/pyshark/trace. KNOWN_FAILURES is now empty. On main's code that case still fails ("INPUTS: frame 1: extra"), so this PR is what closes it.