morluto/rea

Fork 0

mirror of https://github.com/morluto/rea.git synced 2026-11-05 07:47:29 +00:00

[PR #2130] [CLOSED] feat(captures): inspect recorded packet fields with TShark #5049

New issue

Closed

opened 2026-10-31 01:00:47 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-31 01:00:47 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/2130
Author: @Olorinm
Created: 10/12/2026
Status: ❌ Closed

Base: main ← Head: feat/packet-captures

📝 Commits (5)

a74f033 feat(captures): inspect recorded packet fields with TShark
34878b4 fix(captures): bound dissector resources and identify workspace failures
13249ca fix(captures): preserve completed evidence and retry CLI cleanup
43d9641 fix(captures): preserve stricter inherited resource ceilings
0781d8d fix(captures): bound selectors and preserve actionable producer failures

📊 Changes

49 files changed (+2410 additions, -0 deletions)

View changed files

📝 .agents/skills/reverse-engineer-anything/SKILL.md (+4 -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 29 more files

📄 Description

Summary

Add inspect_packet_capture / inspect-packet-capture to inspect explicitly selected fields in an existing capture through caller-supplied TShark. An analyst can correlate a device/app investigation with recorded network or Bluetooth traffic and keep the result in REA Evidence without opening a binary target.

Problem and expected behavior

Existing web HAR/mitmproxy workflows do not expose packet-capture dissection. This tool accepts a local capture, field names, display filter, decode-as rules, pass mode and optional input-packet limit. Repeated field values remain ordered string arrays and every returned packet retains its original frame number. Missing fields and empty filtered results are not treated as proof of absent device traffic.

No linked issue: this is a focused enhancement proposal. It is independent of the signal-recording proposal #2126 and can be reviewed or merged separately.

Change and scope

One file-analysis contract, optional TShark adapter, shared application validation/Evidence, CLI/MCP registration, capability/catalog entries, guide, canonical README rows in every translation, authored skill guidance and real-provider CI lane. No live capture, interfaces, device commands, installer, arbitrary process flags, automatic protocol guessing or changes to HAR/mitmproxy behavior.

Contract and boundary impact

Semantic owner and earliest changed stage: strict packet-capture schemas; TShark adapter owns producer arguments and selected-field parsing. Output validates frame ordering and field selection before shared Evidence construction.
CLI and MCP/tool-catalog contract: additive named contract with required path/fields. frame.number is always included; optional packet_limit counts input packets before filtering, and two_pass defaults to true (--no-two_pass in CLI requests false).
Provider, bridge, target-format, or platform compatibility: absolute REA_TSHARK_COMMAND, TShark 4.x version gate; Linux with util-linux prlimit is required; unsupported hosts fail before workspace allocation. REA_TSHARK_PRLIMIT_COMMAND can override /usr/bin/prlimit. Known producer JSON is validated; no claim that every 4.x version/format/dissector has been exercised.
Evidence, artifact, provenance, or reconstruction contract: source digest/size/path, configured and resolved executable/limiter paths, digests and arguments, full tool version, exact selections, selected fields, inspection stderr and separate version-probe diagnostics. Export-only _index/_score are omitted. Read scope is explicit; no total packet count is inferred from filtered output. Selectors are bounded before argv expansion: up to 1,024 fields/rules per array, 8,192 UTF-16 units per string and 32 KiB total UTF-8 text/terminator/flag/pointer budget, shared by CLI and MCP.
Process execution, authorization, cleanup, or containment impact: owned process supervision, cancellation, private read-only input, empty personal configuration, disabled name resolution, 30-second command deadline, 32-MiB input and 4-MiB output bounds. Failed cleanup retains ownership and observations for retry; late cancellation preserves a completed observation. The one-shot CLI awaits a close retry without masking the original failure; MCP records completed partial Evidence before error delivery, and bounded post-run identity checks complete before honoring a late abort. Before launch, prlimit enforces soft and hard limits of at most 1 GiB address space, 64 MiB per file, 30 CPU seconds and no core dumps. Stricter inherited soft/hard limits are preserved and effective values are reported. These are per-process/per-file limits, not aggregate quotas or an OS sandbox; the selected limiter, installed libraries/global configuration/plugins are trusted. Workspace failures are distinguished from invalid input. Post-run identity errors identify the private copy/tool/limiter involved and retain captured output. Resource-signal failures retain the signal and effective limits without claiming the signal proves its cause.
Generated metadata, package, or installation impact: source catalog registration; no generated output, dependency or installation changes.

Evidence and regression coverage

Executed real TShark verification synthesizes its own Ethernet/IPv4/UDP/DNS and Bluetooth HCI PCAPs. It checks compiled CLI/MCP parity, advertised schemas, persisted Evidence, source digests, repeated and missing fields, both pass modes, filters, decode-as, a prefix limit before matching packets, invalid requests and cleanup.

Representative output for selected network frames is {"frame.number":["2"],"ip.addr":["192.0.2.1","192.0.2.2"],"udp.port":["40000","5555"]}. Explicit DNS decode-as yields example.test; the HCI fixture yields opcode 0x0c03. Setting input limit 1 before the matching frames correctly returns an empty result with up-to-input-packet-limit scope.

Command-boundary tests additionally cover invalid producer JSON, changed private copies, nonzero exit, overflow, cancellation, cleanup retry and completed observations on late cancellation. Parser cases cover repeated, unordered, missing and malformed frame identities and unexpected fields. Additional regressions distinguish workspace failures, refuse unsupported hosts, and use a synthetic producer to verify real Linux kernel limits and a refused allocation. A second Linux process test confirms lower inherited file/CPU limits are preserved during the actual launch.

Remaining proof gaps: PCAPNG, USB, BLE ATT, other dissectors/formats and physical acquisition. macOS and Windows are explicitly unsupported. The real provider and Linux kernel-limit checks run in the linked fork workflow below; upstream CI remains visible under Checks; the links below are independently executed fork verification.

Observed, derived, and inferred claims remain distinguishable.
Artifact identity, source provenance, and failed attempts remain preserved.
Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

npm run check — passed; existing repository lint warnings remain.
npm run docs:check — passed.
npm run verify:test-discovery — all 921 test files discovered exactly once.
Focused provider/parser/MCP, capability and product-catalog tests — 62 passed on macOS, three Linux-only kernel tests skipped.
Linux workflow on 0781d8dfb — passed: 39 provider/parser/CLI/MCP/resource-limit tests, plus 12 real TShark CLI/MCP cases on Ubuntu 24.04 with TShark 4.2.2. Kernel tests verify refused oversized allocation, lower inherited file/CPU limits, and a real SIGXFSZ termination retaining its effective file ceiling.
git diff --check and staged-diff Gitleaks scan — passed.

Compatibility, safety, and release

Breaking changes or migration steps: none.
Real Hopper/Ghidra, browser, or OS coverage: no changes to those providers. This new adapter supports Linux only; earlier macOS verification does not establish the current bounded integration.
Package/release metadata impact: none.
Security/privacy/containment: selected capture content and diagnostics are preserved, including potentially sensitive fields. Ambient environment is not serialized. Only a private copy is passed to TShark; tool/library/plugin/limiter trust remains explicit. Address-space limits bound per-process expansion before allocation, without claiming an aggregate sandbox.

Review checklist

Concrete enhancement; one focused outcome and Conventional Commit title.
Reason for no linked issue stated above.
Public behavior and meaningful failure paths covered.
Owning docs, contracts and source catalog updated.
Representative CLI/MCP output and executed validation included.
Final diff checked for secrets, unrelated changes and unsupported claims.

_{🔄 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/2130 **Author:** [@Olorinm](https://github.com/Olorinm) **Created:** 10/12/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `feat/packet-captures` --- ### 📝 Commits (5) - [`a74f033`](https://github.com/morluto/rea/commit/a74f0337c27dc70e79dc014dad6589ad0c158005) feat(captures): inspect recorded packet fields with TShark - [`34878b4`](https://github.com/morluto/rea/commit/34878b4f2c9025910fda695916ea288d38aa20ac) fix(captures): bound dissector resources and identify workspace failures - [`13249ca`](https://github.com/morluto/rea/commit/13249ca26ad2f8aba9c841ef49216b3ef3019f2e) fix(captures): preserve completed evidence and retry CLI cleanup - [`43d9641`](https://github.com/morluto/rea/commit/43d9641591262c3ec897a3ffadd825f2b1dbeee5) fix(captures): preserve stricter inherited resource ceilings - [`0781d8d`](https://github.com/morluto/rea/commit/0781d8dfb727631ceb7fd32dfadff7250da1d8f3) fix(captures): bound selectors and preserve actionable producer failures ### 📊 Changes **49 files changed** (+2410 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `.agents/skills/reverse-engineer-anything/SKILL.md` (+4 -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 29 more files_ </details> ### 📄 Description ## Summary Add `inspect_packet_capture` / `inspect-packet-capture` to inspect explicitly selected fields in an existing capture through caller-supplied TShark. An analyst can correlate a device/app investigation with recorded network or Bluetooth traffic and keep the result in REA Evidence without opening a binary target. ## Problem and expected behavior Existing web HAR/mitmproxy workflows do not expose packet-capture dissection. This tool accepts a local capture, field names, display filter, decode-as rules, pass mode and optional input-packet limit. Repeated field values remain ordered string arrays and every returned packet retains its original frame number. Missing fields and empty filtered results are not treated as proof of absent device traffic. No linked issue: this is a focused enhancement proposal. It is independent of the signal-recording proposal #2126 and can be reviewed or merged separately. ## Change and scope One file-analysis contract, optional TShark adapter, shared application validation/Evidence, CLI/MCP registration, capability/catalog entries, guide, canonical README rows in every translation, authored skill guidance and real-provider CI lane. No live capture, interfaces, device commands, installer, arbitrary process flags, automatic protocol guessing or changes to HAR/mitmproxy behavior. ## Contract and boundary impact - Semantic owner and earliest changed stage: strict packet-capture schemas; TShark adapter owns producer arguments and selected-field parsing. Output validates frame ordering and field selection before shared Evidence construction. - CLI and MCP/tool-catalog contract: additive named contract with required path/fields. `frame.number` is always included; optional `packet_limit` counts input packets before filtering, and `two_pass` defaults to true (`--no-two_pass` in CLI requests false). - Provider, bridge, target-format, or platform compatibility: absolute `REA_TSHARK_COMMAND`, TShark 4.x version gate; Linux with util-linux `prlimit` is required; unsupported hosts fail before workspace allocation. `REA_TSHARK_PRLIMIT_COMMAND` can override `/usr/bin/prlimit`. Known producer JSON is validated; no claim that every 4.x version/format/dissector has been exercised. - Evidence, artifact, provenance, or reconstruction contract: source digest/size/path, configured and resolved executable/limiter paths, digests and arguments, full tool version, exact selections, selected fields, inspection stderr and separate version-probe diagnostics. Export-only `_index`/`_score` are omitted. Read scope is explicit; no total packet count is inferred from filtered output. Selectors are bounded before argv expansion: up to 1,024 fields/rules per array, 8,192 UTF-16 units per string and 32 KiB total UTF-8 text/terminator/flag/pointer budget, shared by CLI and MCP. - Process execution, authorization, cleanup, or containment impact: owned process supervision, cancellation, private read-only input, empty personal configuration, disabled name resolution, 30-second command deadline, 32-MiB input and 4-MiB output bounds. Failed cleanup retains ownership and observations for retry; late cancellation preserves a completed observation. The one-shot CLI awaits a close retry without masking the original failure; MCP records completed partial Evidence before error delivery, and bounded post-run identity checks complete before honoring a late abort. Before launch, `prlimit` enforces soft and hard limits of at most 1 GiB address space, 64 MiB per file, 30 CPU seconds and no core dumps. Stricter inherited soft/hard limits are preserved and effective values are reported. These are per-process/per-file limits, not aggregate quotas or an OS sandbox; the selected limiter, installed libraries/global configuration/plugins are trusted. Workspace failures are distinguished from invalid input. Post-run identity errors identify the private copy/tool/limiter involved and retain captured output. Resource-signal failures retain the signal and effective limits without claiming the signal proves its cause. - Generated metadata, package, or installation impact: source catalog registration; no generated output, dependency or installation changes. ## Evidence and regression coverage Executed real TShark verification synthesizes its own Ethernet/IPv4/UDP/DNS and Bluetooth HCI PCAPs. It checks compiled CLI/MCP parity, advertised schemas, persisted Evidence, source digests, repeated and missing fields, both pass modes, filters, decode-as, a prefix limit before matching packets, invalid requests and cleanup. Representative output for selected network frames is `{"frame.number":["2"],"ip.addr":["192.0.2.1","192.0.2.2"],"udp.port":["40000","5555"]}`. Explicit DNS decode-as yields `example.test`; the HCI fixture yields opcode `0x0c03`. Setting input limit 1 before the matching frames correctly returns an empty result with `up-to-input-packet-limit` scope. Command-boundary tests additionally cover invalid producer JSON, changed private copies, nonzero exit, overflow, cancellation, cleanup retry and completed observations on late cancellation. Parser cases cover repeated, unordered, missing and malformed frame identities and unexpected fields. Additional regressions distinguish workspace failures, refuse unsupported hosts, and use a synthetic producer to verify real Linux kernel limits and a refused allocation. A second Linux process test confirms lower inherited file/CPU limits are preserved during the actual launch. Remaining proof gaps: PCAPNG, USB, BLE ATT, other dissectors/formats and physical acquisition. macOS and Windows are explicitly unsupported. The real provider and Linux kernel-limit checks run in the linked fork workflow below; upstream CI remains visible under Checks; the links below are independently executed fork verification. - [x] Observed, derived, and inferred claims remain distinguishable. - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npm run check` — passed; existing repository lint warnings remain. - `npm run docs:check` — passed. - `npm run verify:test-discovery` — all 921 test files discovered exactly once. - Focused provider/parser/MCP, capability and product-catalog tests — 62 passed on macOS, three Linux-only kernel tests skipped. - [Linux workflow on `0781d8dfb`](https://github.com/Olorinm/rea/actions/runs/38243800463) — passed: 39 provider/parser/CLI/MCP/resource-limit tests, plus 12 real TShark CLI/MCP cases on Ubuntu 24.04 with TShark 4.2.2. Kernel tests verify refused oversized allocation, lower inherited file/CPU limits, and a real SIGXFSZ termination retaining its effective file ceiling. - `git diff --check` and staged-diff Gitleaks scan — passed. ## Compatibility, safety, and release - Breaking changes or migration steps: none. - Real Hopper/Ghidra, browser, or OS coverage: no changes to those providers. This new adapter supports Linux only; earlier macOS verification does not establish the current bounded integration. - Package/release metadata impact: none. - Security/privacy/containment: selected capture content and diagnostics are preserved, including potentially sensitive fields. Ambient environment is not serialized. Only a private copy is passed to TShark; tool/library/plugin/limiter trust remains explicit. Address-space limits bound per-process expansion before allocation, without claiming an aggregate sandbox. ## Review checklist - [x] Concrete enhancement; one focused outcome and Conventional Commit title. - [x] Reason for no linked issue stated above. - [x] Public behavior and meaningful failure paths covered. - [x] Owning docs, contracts and source catalog updated. - [x] Representative CLI/MCP output and executed validation included. - [x] Final diff checked for secrets, unrelated changes and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-31 01:00:47 +00:00

closed this issue
added the
pull-request
label

bsakaguchi referenced this issue

2026-11-01 21:42:51 +00:00

[PR #5049] feat(adb): inspect the on-screen view hierarchy #6760

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#5049

No description provided.

Rows
Columns