[PR #2318] [MERGED] feat(captures): inspect recorded packets with bounded TShark delivery #5163

Closed
opened 2026-10-31 01:04:27 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/2318
Author: @N0zoM1z0
Created: 10/12/2026
Status: ✅ Merged
Merged: 10/12/2026
Merged by: @N0zoM1z0

Base: main ← Head: feat/tshark-analysis-2130-20261012


📝 Commits (3)

  • 7138358 feat(captures): inspect recorded packet fields with TShark
  • f9208a9 test(captures): verify retained descriptor cleanup
  • 8a049df chore: sync current main for packet capture integration

📊 Changes

50 files changed (+2850 additions, -0 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/SKILL.md (+7 -0)
➕ .github/workflows/real-packet-capture.yml (+50 -0)
📝 README.md (+1 -0)
📝 README_ar.md (+1 -0)
📝 README_de.md (+1 -0)
📝 README_es.md (+1 -0)
📝 README_fa.md (+1 -0)
📝 README_fr.md (+1 -0)
📝 README_id.md (+1 -0)
📝 README_it.md (+1 -0)
📝 README_ja.md (+1 -0)
📝 README_ko.md (+1 -0)
📝 README_pl.md (+1 -0)
📝 README_pt-BR.md (+1 -0)
📝 README_ru.md (+1 -0)
📝 README_th.md (+1 -0)
📝 README_tr.md (+1 -0)
📝 README_uk.md (+1 -0)
📝 README_vi.md (+1 -0)
📝 README_zh-TW.md (+1 -0)

...and 30 more files

📄 Description

Summary

Inspect caller-selected fields in an existing packet capture through shared CLI/MCP workflows. This replaces #2130, credited to Olorinm, with current-main integration, bounded delivery and cleanup regressions. There is no linked issue.

Problem and expected behavior

Analysts need offline network/USB/Bluetooth field inspection without opening an active binary or acquiring traffic. Selecting two fields from a real 12,023-frame capture previously returned about 1.10 MB of text. The default now returns 50 matching frames with original frame numbers and explicit coverage; callers can page or request all remaining matches.

Change and scope

Linux-only TShark 4.x provider; caller supplies absolute REA_TSHARK_COMMAND and trusted util-linux prlimit. Fields, display filter, decode-as, input-packet limit and pass mode remain caller-selected. Paging happens after dissection and filtering, preserving two-pass/reassembly semantics. MCP match_limit: null and CLI --all_matches explicitly request full output; conflicting CLI options are rejected before effects.

Use existing process supervision, artifact descriptor ownership, session admission and Evidence delivery. Admit one inspection at a time and return retryable capacity errors instead of accumulating work. Failed descriptor/process/private-file cleanup remains owned for retry, including shutdown. Source bytes are copied privately and never passed directly to TShark.

Contract and boundary impact

  • Semantic owner: shared domain schemas and PacketCaptureService; TShark owns producer parsing, resource supervision and artifact identity.
  • Contribution scope: offline inspection of caller-selected existing data. Maintainer explicitly requested this recorded-only feature; target execution/injection/mutation/protection recovery decision is not applicable.
  • CLI/MCP: inspect-packet-capture / inspect_packet_capture, selected fields required. Default match_limit: 50, match_offset: 0; output_window reports matching/returned counts and has_more within the input read scope.
  • Compatibility: Linux with TShark 4.x and util-linux; other hosts fail before analysis. Missing provider configuration has actionable discovery diagnostics.
  • Evidence: source/tool/limiter paths and digests, source size, exact selections/argv, version banner, warnings, typed repeated fields, coverage, limits and explicit hardware-acquisition status. Completed observations survive late cancellation/cleanup errors in the session.
  • Authority/cleanup: read existing captures; launch an owned local analyzer; write private temporary copies/configuration. No live capture or device communication.
  • Generated/install impact: authored guides, skill and contract catalog sources updated. Ignored catalogs/build outputs are regenerated, not committed. No new npm dependency or installer behavior.

Expected effects:

  • Read existing files or captured data.
  • Launch or attach to a process (launch owned analyzer).
  • Change files or configuration (private temporary workspace only).

Evidence and regression coverage

  • Reproduced admission-after-close, excess admission and retained descriptor-close failures against the imported implementation before fixing them. Descriptor tests cover capture, executable, limiter and kernel report; successful retry returns descriptor counts to baseline.

  • Real compiled CLI/MCP verifier: 15 cases on Debian 12 / TShark 4.0.17, including generated Ethernet/DNS/Bluetooth HCI recordings, field repetition/omission, filters, decode-as, both pass modes, input prefix before filter, output paging/full selection, schemas, errors, persistence, identity and cleanup.

  • Additional real data: pinned Wireshark 4.0.17 HTTP PCAP and DNS/ICMP PCAPNG; owned HTTP server/curl recording; a real recording of 1,000 owned HTTP requests (1,526,684 bytes / 12,023 frames). Known request URIs and source SHA-256 checked independently. Full packet arrays exactly match the imported implementation; bounded results exactly match their prefixes.

  • Representative result: output_window: { matching_packets: 12023, returned_packets: 50, has_more: true }, with original frame.number values and selected fields.

  • Proof gaps: TShark versions beyond verified 4.0.17/4.2.2, other platforms, USB, BLE ATT and physical hardware are not established by these tests. Fixture Bluetooth HCI is not a hardware claim. Installed global plugins/libraries/configuration are trusted and not fully fingerprinted.

  • Observed, derived and inferred claims remain distinguishable.

  • Artifact identity, provenance and failed attempts remain preserved.

  • Unsupported/incomplete outcomes remain visible.

Validation performed

  • npm run test:focused -- ten capture/CLI/MCP/kernel/capability/effect/schema files — 79 passed on synchronized main.
  • REA_TSHARK_COMMAND=/usr/bin/tshark node scripts/verify-packet-capture.mjs — 15 real CLI/MCP cases passed locally after synchronization; Ubuntu 24.04 CI / TShark 4.2.2 also passed all 15 cases and all 47 provider-boundary tests.
  • npm run check, npm run docs:check, npm run verify:test-discovery — all passed again on synchronized main.
  • SDK-converted advertised schemas validated by the final integrated tool-schema suite.

Performance: three repetitions per case, warm MCP process, new TShark process each call, two CPU cores, 8 GiB family RSS guard. No filesystem-cache flushing. On the 12,023-frame recording, selected two-field response text went from 1,099,961 to 9,541 bytes; latency from 1.66–2.00 s to 1.22–1.41 s. Explicit full output remains available (1,100,118 bytes; 1.63–1.99 s). Filtered 1,000 HTTP requests return 50 by default (144,124 to 12,137 text bytes; 1.05–1.21 s). The nine-call optimized run peaked at 868.68 MiB family RSS; all guarded work stayed below 8 GiB.

For the task of inspecting the first 50 frames, o200k_base estimates including one common current capture-tool definition, one request and measured response text are 449,644 before paging versus 7,633 after. The common definition contributes 4,266 tokens to both comparisons. These are tokenizer estimates, not billed usage; other tool catalogs, prompt conversion, agent reasoning and subsequent calls are unmeasured. No cache claim is made; later pages repeat dissection and remain subject to producer limits.

Compatibility, safety, and release

New feature; no previously released capture-tool call changes. Input <=32 MiB, combined producer stdout/stderr <=4 MiB, 30-second deadlines, enforced 1 GiB address space / 64 MiB file / 30 CPU-second ceilings per producer; stricter inherited limits are preserved. Paging bounds delivery but does not bypass producer-output limits. This is not an OS sandbox or an aggregate filesystem/memory quota. Unsupported authority remains refused.

Before merge

  • Concrete agreed enhancement and resolved material scope.
  • Focused outcome and Conventional Commit title.
  • Original PR linked; no linked issue exists.
  • Observable behavior and meaningful failure paths covered.
  • Owning docs/contracts/generated sources updated.
  • Representative CLI/MCP output included.
  • Final diff checked for secrets, unrelated changes and unsupported claims.
  • Final synchronized validation and applicable CI/review findings checked.

Final CI: all 38 checks passed for 8a049dfc82171c798601eb9b88606eed003a380c, including required CI, real TShark, six full test shards, coverage, static/docs/workflow checks and all native package lanes. Automatic Codex review did not execute because repository review credits were exhausted; it supplied no code findings. Own source inspection, regression reproduction and real-provider verification were completed.

Merged as f611d8ce722cd36345e9ff83b9669ef2e7fe57a9.


🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.

## 📋 Pull Request Information **Original PR:** https://github.com/morluto/rea/pull/2318 **Author:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Created:** 10/12/2026 **Status:** ✅ Merged **Merged:** 10/12/2026 **Merged by:** [@N0zoM1z0](https://github.com/N0zoM1z0) **Base:** `main` ← **Head:** `feat/tshark-analysis-2130-20261012` --- ### 📝 Commits (3) - [`7138358`](https://github.com/morluto/rea/commit/71383580ec2826cbc710a0be33545eaa91dde33a) feat(captures): inspect recorded packet fields with TShark - [`f9208a9`](https://github.com/morluto/rea/commit/f9208a90988b1049d79737c3e2c877ec97ed99f8) test(captures): verify retained descriptor cleanup - [`8a049df`](https://github.com/morluto/rea/commit/8a049dfc82171c798601eb9b88606eed003a380c) chore: sync current main for packet capture integration ### 📊 Changes **50 files changed** (+2850 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+7 -0) ➕ `.github/workflows/real-packet-capture.yml` (+50 -0) 📝 `README.md` (+1 -0) 📝 `README_ar.md` (+1 -0) 📝 `README_de.md` (+1 -0) 📝 `README_es.md` (+1 -0) 📝 `README_fa.md` (+1 -0) 📝 `README_fr.md` (+1 -0) 📝 `README_id.md` (+1 -0) 📝 `README_it.md` (+1 -0) 📝 `README_ja.md` (+1 -0) 📝 `README_ko.md` (+1 -0) 📝 `README_pl.md` (+1 -0) 📝 `README_pt-BR.md` (+1 -0) 📝 `README_ru.md` (+1 -0) 📝 `README_th.md` (+1 -0) 📝 `README_tr.md` (+1 -0) 📝 `README_uk.md` (+1 -0) 📝 `README_vi.md` (+1 -0) 📝 `README_zh-TW.md` (+1 -0) _...and 30 more files_ </details> ### 📄 Description ## Summary Inspect caller-selected fields in an existing packet capture through shared CLI/MCP workflows. This replaces #2130, credited to Olorinm, with current-main integration, bounded delivery and cleanup regressions. There is no linked issue. ## Problem and expected behavior Analysts need offline network/USB/Bluetooth field inspection without opening an active binary or acquiring traffic. Selecting two fields from a real 12,023-frame capture previously returned about 1.10 MB of text. The default now returns 50 matching frames with original frame numbers and explicit coverage; callers can page or request all remaining matches. ## Change and scope Linux-only TShark 4.x provider; caller supplies absolute `REA_TSHARK_COMMAND` and trusted util-linux `prlimit`. Fields, display filter, decode-as, input-packet limit and pass mode remain caller-selected. Paging happens after dissection and filtering, preserving two-pass/reassembly semantics. MCP `match_limit: null` and CLI `--all_matches` explicitly request full output; conflicting CLI options are rejected before effects. Use existing process supervision, artifact descriptor ownership, session admission and Evidence delivery. Admit one inspection at a time and return retryable capacity errors instead of accumulating work. Failed descriptor/process/private-file cleanup remains owned for retry, including shutdown. Source bytes are copied privately and never passed directly to TShark. ## Contract and boundary impact - Semantic owner: shared domain schemas and `PacketCaptureService`; TShark owns producer parsing, resource supervision and artifact identity. - Contribution scope: offline inspection of caller-selected existing data. Maintainer explicitly requested this recorded-only feature; target execution/injection/mutation/protection recovery decision is not applicable. - CLI/MCP: `inspect-packet-capture` / `inspect_packet_capture`, selected fields required. Default `match_limit: 50`, `match_offset: 0`; `output_window` reports matching/returned counts and `has_more` within the input read scope. - Compatibility: Linux with TShark 4.x and util-linux; other hosts fail before analysis. Missing provider configuration has actionable discovery diagnostics. - Evidence: source/tool/limiter paths and digests, source size, exact selections/argv, version banner, warnings, typed repeated fields, coverage, limits and explicit hardware-acquisition status. Completed observations survive late cancellation/cleanup errors in the session. - Authority/cleanup: read existing captures; launch an owned local analyzer; write private temporary copies/configuration. No live capture or device communication. - Generated/install impact: authored guides, skill and contract catalog sources updated. Ignored catalogs/build outputs are regenerated, not committed. No new npm dependency or installer behavior. Expected effects: - [x] Read existing files or captured data. - [x] Launch or attach to a process (launch owned analyzer). - [x] Change files or configuration (private temporary workspace only). ## Evidence and regression coverage - Reproduced admission-after-close, excess admission and retained descriptor-close failures against the imported implementation before fixing them. Descriptor tests cover capture, executable, limiter and kernel report; successful retry returns descriptor counts to baseline. - Real compiled CLI/MCP verifier: 15 cases on Debian 12 / TShark 4.0.17, including generated Ethernet/DNS/Bluetooth HCI recordings, field repetition/omission, filters, decode-as, both pass modes, input prefix before filter, output paging/full selection, schemas, errors, persistence, identity and cleanup. - Additional real data: pinned Wireshark 4.0.17 HTTP PCAP and DNS/ICMP PCAPNG; owned HTTP server/curl recording; a real recording of 1,000 owned HTTP requests (1,526,684 bytes / 12,023 frames). Known request URIs and source SHA-256 checked independently. Full packet arrays exactly match the imported implementation; bounded results exactly match their prefixes. - Representative result: `output_window: { matching_packets: 12023, returned_packets: 50, has_more: true }`, with original `frame.number` values and selected fields. - Proof gaps: TShark versions beyond verified 4.0.17/4.2.2, other platforms, USB, BLE ATT and physical hardware are not established by these tests. Fixture Bluetooth HCI is not a hardware claim. Installed global plugins/libraries/configuration are trusted and not fully fingerprinted. - [x] Observed, derived and inferred claims remain distinguishable. - [x] Artifact identity, provenance and failed attempts remain preserved. - [x] Unsupported/incomplete outcomes remain visible. ## Validation performed - `npm run test:focused --` ten capture/CLI/MCP/kernel/capability/effect/schema files — 79 passed on synchronized main. - `REA_TSHARK_COMMAND=/usr/bin/tshark node scripts/verify-packet-capture.mjs` — 15 real CLI/MCP cases passed locally after synchronization; Ubuntu 24.04 CI / TShark 4.2.2 also passed all 15 cases and all 47 provider-boundary tests. - `npm run check`, `npm run docs:check`, `npm run verify:test-discovery` — all passed again on synchronized main. - SDK-converted advertised schemas validated by the final integrated tool-schema suite. Performance: three repetitions per case, warm MCP process, new TShark process each call, two CPU cores, 8 GiB family RSS guard. No filesystem-cache flushing. On the 12,023-frame recording, selected two-field response text went from 1,099,961 to 9,541 bytes; latency from 1.66–2.00 s to 1.22–1.41 s. Explicit full output remains available (1,100,118 bytes; 1.63–1.99 s). Filtered 1,000 HTTP requests return 50 by default (144,124 to 12,137 text bytes; 1.05–1.21 s). The nine-call optimized run peaked at 868.68 MiB family RSS; all guarded work stayed below 8 GiB. For the task of inspecting the first 50 frames, `o200k_base` estimates including one common current capture-tool definition, one request and measured response text are 449,644 before paging versus 7,633 after. The common definition contributes 4,266 tokens to both comparisons. These are tokenizer estimates, not billed usage; other tool catalogs, prompt conversion, agent reasoning and subsequent calls are unmeasured. No cache claim is made; later pages repeat dissection and remain subject to producer limits. ## Compatibility, safety, and release New feature; no previously released capture-tool call changes. Input <=32 MiB, combined producer stdout/stderr <=4 MiB, 30-second deadlines, enforced 1 GiB address space / 64 MiB file / 30 CPU-second ceilings per producer; stricter inherited limits are preserved. Paging bounds delivery but does not bypass producer-output limits. This is not an OS sandbox or an aggregate filesystem/memory quota. Unsupported authority remains refused. ## Before merge - [x] Concrete agreed enhancement and resolved material scope. - [x] Focused outcome and Conventional Commit title. - [x] Original PR linked; no linked issue exists. - [x] Observable behavior and meaningful failure paths covered. - [x] Owning docs/contracts/generated sources updated. - [x] Representative CLI/MCP output included. - [x] Final diff checked for secrets, unrelated changes and unsupported claims. - [x] Final synchronized validation and applicable CI/review findings checked. Final CI: all 38 checks passed for `8a049dfc82171c798601eb9b88606eed003a380c`, including required CI, real TShark, six full test shards, coverage, static/docs/workflow checks and all native package lanes. Automatic Codex review did not execute because repository review credits were exhausted; it supplied no code findings. Own source inspection, regression reproduction and real-provider verification were completed. Merged as `f611d8ce722cd36345e9ff83b9669ef2e7fe57a9`. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
bsakaguchi 2026-10-31 01:04:27 +00:00
Sign in to join this conversation.
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
morluto/rea#5163
No description provided.