[GH-ISSUE #3403] [Design] Give the selected TShark one owner across inspect_pcap_* and inspect_packet_* #1267

New issue

Open

opened 2026-10-16 21:03:34 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-16 21:03:34 +00:00

Owner

Originally created by @555aaditya on GitHub (Oct 14, 2026).
Original GitHub issue: https://github.com/morluto/rea/issues/3403

Before submitting

I searched the open and closed issues and pull requests for a related discussion.
I understand the contribution scope must be reviewed before integration; open questions are welcome here.
This discussion does not include credentials, private samples, or sensitive target data.

Decision needed

Two providers wrap the same caller-supplied TShark and read the same environment variables, but they apply different rules. Should "the selected TShark" have one owner that both src/pcap/ and src/captures/ use? If so, which selection rule should win:

(a) absolute REA_TSHARK_COMMAND, or tshark from PATH resolved to an absolute path, then hashed (what inspect_pcap_* accepts today);
(b) absolute REA_TSHARK_COMMAND only, with hashed identity (what inspect_packet_* requires today)?

Proposed default: (a). It is the backward-compatible option: every configuration accepted today by either family keeps working, and PATH-only installs gain inspect_packet_*. The selected executable is still resolved to an absolute path and hashed before and after each run, so inspect_packet_* keeps its identity checks. I'll open a draft PR implementing milestone 1 with (a) so the change is concrete; switching it to (b) is a small change if you prefer that.

Context and evidence

These are source-derived from main at 322506d0c; I haven't run them against a real TShark. AGENTS.md asks to "give each interpretation and resource a clear owner", but today two owners disagree:

Concern	`src/pcap/` (`inspect_pcap_client`, `inspect_pcap_capture`)	`src/captures/` (`inspect_packet_capture`, `inspect_packet_fields`)
`REA_TSHARK_COMMAND`	Absolute, or PATH fallback (`PcapConfiguration.ts` `resolvePcapTools`)	Absolute required (`TsharkCaptureProvider.ts:139-141`)
Version admission	`/^tshark \(Wireshark\) (\d+)\.\d+\.\d+/iu`, major 4	`/^TShark \(Wireshark\) 4\.[0-9]+\.[0-9]+…/u`
Executable identity	Not hashed	TShark and prlimit hashed, then rechecked after each run
Hosts	Linux (prlimit) and Windows (Job Object, `PcapNativeBound.ts`)	Linux only (`TsharkCaptureProvider.ts:135`)
`REA_TSHARK_PRLIMIT_COMMAND`	Read in `PcapNativeBound.ts`	Read again in `TsharkCaptureProvider.ts`
CPU ceiling	300 s	30 s (`BOUNDED_PRODUCER_LIMITS`)
Runner	`runPcapCommand` (Windows batch handling, Job Object limit)	`runOwnedCommand` behind prlimit
Docs	`docs/pcap-analysis.md`: PATH or absolute; Linux and Windows	`docs/packet-captures.md`: absolute only; Linux only

What a user sees as a result:

With TShark on PATH, inspect_pcap_capture works and inspect_packet_capture refuses.
On Windows, capture summaries work, but field inspection and discovery are refused.
The same variable means different things depending on which tool is called.

Expected interaction with targets

Read existing files or captured data

This is a refactor of existing read-only, file-only capture analysis, with no new target interaction.

Options and tradeoffs

Proposed single owner, for example in src/pcap/ or a small shared module next to src/process/LinuxResourceLimits.ts, providing:

one selection rule: (a) or (b) above;
one version parser for the 4.x banner;
one executable-identity check: realpath plus SHA-256 before and after the run, as src/captures/ does now;
one native bound per host, reusing PcapNativeBound / LinuxResourceLimits. Workload-specific ceilings (summary vs glossary) can stay per operation.

Both providers would then consume the owner's parsed facts and drop their copies.

Open sub-question: should inspect_packet_* gain the Windows Job Object bound that inspect_pcap_* already has, or stay Linux-only for now?

Proposed milestones, each a separate PR:

A shared selection, version and identity owner adopted by both providers, with no host change. The only behaviour change is whichever selection rule is chosen.
A shared native bound, which adds Windows to inspect_packet_* if that's wanted.
Remove the superseded per-provider code and align the two docs.

Verification available so far

I can suggest a sample or manual check.

I'd extend the existing unit and boundary tests so both providers are checked against the same selection and version cases. Real lanes: verify:pcap and verify-packet-capture.mjs on Linux with TShark 4.x. I can't verify Windows Job Object behaviour myself.

Success criteria and open questions

REA_TSHARK_COMMAND (and REA_TSHARK_PRLIMIT_COMMAND) are read and validated in exactly one place, and all four tools accept and refuse the same configurations.
Every tool reports the same TShark identity and version facts.
Open question: the selection rule (a)/(b), and Windows for inspect_packet_*.

References

src/pcap/PcapConfiguration.ts, src/pcap/PcapNativeBound.ts, src/pcap/PcapCommand.ts
src/captures/TsharkCaptureProvider.ts
src/process/LinuxResourceLimits.ts
docs/pcap-analysis.md, docs/packet-captures.md
Related: #2318, #2496, #2507, #2698 (one owner for the prlimit producer budget)

Originally created by @555aaditya on GitHub (Oct 14, 2026). Original GitHub issue: https://github.com/morluto/rea/issues/3403 ### Before submitting - [x] I searched the open and closed issues and pull requests for a related discussion. - [x] I understand the [contribution scope](https://github.com/morluto/rea/blob/main/CONTRIBUTING.md#contribution-scope) must be reviewed before integration; open questions are welcome here. - [x] This discussion does not include credentials, private samples, or sensitive target data. ### Decision needed Two providers wrap the same caller-supplied TShark and read the same environment variables, but they apply different rules. Should "the selected TShark" have one owner that both `src/pcap/` and `src/captures/` use? If so, which selection rule should win: - **(a)** absolute `REA_TSHARK_COMMAND`, or `tshark` from PATH resolved to an absolute path, then hashed (what `inspect_pcap_*` accepts today); - **(b)** absolute `REA_TSHARK_COMMAND` only, with hashed identity (what `inspect_packet_*` requires today)? **Proposed default: (a).** It is the backward-compatible option: every configuration accepted today by either family keeps working, and PATH-only installs gain `inspect_packet_*`. The selected executable is still resolved to an absolute path and hashed before and after each run, so `inspect_packet_*` keeps its identity checks. I'll open a draft PR implementing milestone 1 with (a) so the change is concrete; switching it to (b) is a small change if you prefer that. ### Context and evidence These are source-derived from `main` at 322506d0c; I haven't run them against a real TShark. AGENTS.md asks to "give each interpretation and resource a clear owner", but today two owners disagree: | Concern | `src/pcap/` (`inspect_pcap_client`, `inspect_pcap_capture`) | `src/captures/` (`inspect_packet_capture`, `inspect_packet_fields`) | |---|---|---| | `REA_TSHARK_COMMAND` | Absolute, **or PATH fallback** (`PcapConfiguration.ts` `resolvePcapTools`) | **Absolute required** (`TsharkCaptureProvider.ts:139-141`) | | Version admission | `/^tshark \(Wireshark\) (\d+)\.\d+\.\d+/iu`, major 4 | `/^TShark \(Wireshark\) 4\.[0-9]+\.[0-9]+…/u` | | Executable identity | Not hashed | TShark and prlimit hashed, then rechecked after each run | | Hosts | Linux (prlimit) and **Windows** (Job Object, `PcapNativeBound.ts`) | **Linux only** (`TsharkCaptureProvider.ts:135`) | | `REA_TSHARK_PRLIMIT_COMMAND` | Read in `PcapNativeBound.ts` | Read again in `TsharkCaptureProvider.ts` | | CPU ceiling | 300 s | 30 s (`BOUNDED_PRODUCER_LIMITS`) | | Runner | `runPcapCommand` (Windows batch handling, Job Object limit) | `runOwnedCommand` behind prlimit | | Docs | `docs/pcap-analysis.md`: PATH or absolute; Linux and Windows | `docs/packet-captures.md`: absolute only; Linux only | What a user sees as a result: - With TShark on PATH, `inspect_pcap_capture` works and `inspect_packet_capture` refuses. - On Windows, capture summaries work, but field inspection and discovery are refused. - The same variable means different things depending on which tool is called. ### Expected interaction with targets - [x] Read existing files or captured data This is a refactor of existing read-only, file-only capture analysis, with no new target interaction. ### Options and tradeoffs Proposed single owner, for example in `src/pcap/` or a small shared module next to `src/process/LinuxResourceLimits.ts`, providing: 1. **one selection rule**: (a) or (b) above; 2. **one version parser** for the 4.x banner; 3. **one executable-identity check**: realpath plus SHA-256 before and after the run, as `src/captures/` does now; 4. **one native bound per host**, reusing `PcapNativeBound` / `LinuxResourceLimits`. Workload-specific ceilings (summary vs glossary) can stay per operation. Both providers would then consume the owner's parsed facts and drop their copies. Open sub-question: should `inspect_packet_*` gain the Windows Job Object bound that `inspect_pcap_*` already has, or stay Linux-only for now? Proposed milestones, each a separate PR: 1. A shared selection, version and identity owner adopted by both providers, with no host change. The only behaviour change is whichever selection rule is chosen. 2. A shared native bound, which adds Windows to `inspect_packet_*` if that's wanted. 3. Remove the superseded per-provider code and align the two docs. ### Verification available so far I can suggest a sample or manual check. I'd extend the existing unit and boundary tests so both providers are checked against the same selection and version cases. Real lanes: `verify:pcap` and `verify-packet-capture.mjs` on Linux with TShark 4.x. I can't verify Windows Job Object behaviour myself. ### Success criteria and open questions - `REA_TSHARK_COMMAND` (and `REA_TSHARK_PRLIMIT_COMMAND`) are read and validated in exactly one place, and all four tools accept and refuse the same configurations. - Every tool reports the same TShark identity and version facts. - Open question: the selection rule (a)/(b), and Windows for `inspect_packet_*`. ### References - `src/pcap/PcapConfiguration.ts`, `src/pcap/PcapNativeBound.ts`, `src/pcap/PcapCommand.ts` - `src/captures/TsharkCaptureProvider.ts` - `src/process/LinuxResourceLimits.ts` - `docs/pcap-analysis.md`, `docs/packet-captures.md` - Related: #2318, #2496, #2507, #2698 (one owner for the prlimit producer budget)

~~bsakaguchi referenced this issue 2026-10-16 21:05:48 +00:00~~

[GH-ISSUE #3796] [Tracker] Open feature requests by area (October 2026) #1471

bsakaguchi referenced this issue

2026-10-16 21:05:51 +00:00

[GH-ISSUE #3796] [Tracker] Open feature requests by area (October 2026) #1471

bsakaguchi referenced this issue

2026-10-17 21:01:31 +00:00

[GH-ISSUE #2383] [Tracker] Audit analysis and debugging coverage for the TIOBE top 100 languages (October 2026) #794

bsakaguchi referenced this issue

2026-10-31 00:29:14 +00:00

[GH-ISSUE #1431] [Feature] HarmonyOS/OpenHarmony package and Ark bytecode analysis (ArkDecompiler evaluation) #487

bsakaguchi referenced this issue