[PR #6512] [CLOSED] fix(pcap): report capture summaries unsupported off their verified hosts #7375

Closed
opened 2026-11-01 21:47:25 +00:00 by bsakaguchi · 0 comments
Owner

📋 Pull Request Information

Original PR: https://github.com/morluto/rea/pull/6512
Author: @kittimzhe
Created: 10/23/2026
Status: ❌ Closed

Base: main ← Head: fix/pcap-capture-host-availability


📝 Commits (1)

  • 652e56f fix(pcap): report capture summaries unsupported off their verified hosts

📊 Changes

6 files changed (+64 additions, -12 deletions)

View changed files

📝 src/application/CapabilityInventory.test.ts (+18 -0)
📝 src/application/CapabilityInventory.ts (+10 -0)
📝 src/composition/pcap.ts (+3 -0)
📝 src/pcap/PcapNativeBound.ts (+18 -10)
📝 src/server/createServer.ts (+9 -1)
📝 tests/process-global/hostRestrictedAvailabilityMcp.test.ts (+6 -1)

📄 Description

Fixes #5711

Related: #6179 proposed the same classification before #5793 introduced the host-restriction mechanism. This PR follows that mechanism on current main and adds MCP-level coverage; happy to defer if the maintainers prefer rebasing #6179 instead.

Summary

Target-free discovery advertises inspect_pcap_capture as available: true on hosts whose capture execution refuses: the pcap-provider kind fallback in the availability projection returns available unconditionally, so on macOS the catalog promises a callable operation while the native bound gate rejects the host at execution with capability_unavailable. The host-independent inspect_pcap_client version probe keeps its availability either way.

Problem and expected behavior

  • Smallest trigger: on a non-Linux, non-Windows host with a tshark on PATH, run a target-free binary_session {} and read tool_availability; inspect_pcap_capture reports {"available": true, "reason": "available"} even though calling it returns the typed refusal Packet summaries require an enforceable native memory bound: Linux with util-linux prlimit, or Windows with owned Job Objects. This host's capture boundary remains unsupported. The same over-advertisement appears with no tshark configured.
  • Violated invariant: the same one #5793 established for the other Linux-only integrations — an unavailable tool's machine-readable reason should name the actual blocker, and no configuration can make a host-restricted integration pass its execution host check. The mechanism this adds to is HOST_RESTRICTED_FEATURES / hostUnsupported / verifiedHost from #5793.
  • Expected: inspect_pcap_capture reports unsupported_host with the execution gate's remediation on hosts outside its verified set; Linux and Windows (Job Object bound) stay available; the client probe keeps available on every host; injected pcap services own their availability on any host.

Change and scope

  • src/pcap/PcapNativeBound.ts now owns and exports pcapCaptureHostSupported (linux || win32) and its gate uses it — discovery and execution share the one check, replacing the inline platform pair that previously lived only in the gate.
  • src/composition/pcap.ts re-exports it; src/server/createServer.ts records pcapCapture in verifiedHost and in hostUnsupported through the existing outsideVerifiedHost(options.pcapAnalysis, ...) injection exemption.
  • src/application/CapabilityInventory.ts adds "pcapCapture" to HOST_RESTRICTED_FEATURES and classifies inspect_pcap_capture through hostRestrictedAvailability with the gate's exact remediation text. The enabled argument is true: the pcap family registers on every host, so the remaining unavailability dimension is configuration at execution, which is out of this issue's scope (noted below).
  • inspect_pcap_client is untouched — it stays on the kind fallback and remains available wherever the provider is constructed.
  • Intentionally not included: the no-tshark case still reports available for the family, exactly as before; #5711 asks for the host limitation split, and a configuration-aware availability for the pcap family can follow the pattern #5793 uses for packetCaptureEnabled if the maintainers want it. #6179's approach (a separate pcapCaptureHostSupported policy field) achieves the same classification but predates the hostUnsupported mechanism and conflicts with current main.
  • Contribution scope: ordinary fix within existing boundaries — no maintainer scope decision required ("not applicable").

Contract and boundary impact

  • Semantic owner and earliest changed stage: the target-free availability projection (src/application/CapabilityInventory.ts) plus the shared host gate (src/pcap/PcapNativeBound.ts).
  • CLI and MCP/tool-catalog contract: tool_availability for inspect_pcap_capture changes from available to available: false, reason: "unsupported_host" on hosts outside linux || win32 when no pcap service is injected; the complete tools/list catalog is unchanged; unsupported_host is an existing reason value.
  • Provider, bridge, target-format, or platform compatibility: Linux unchanged (supported); Windows unchanged (supported through the Job Object bound); injected services unchanged.
  • Evidence, artifact, provenance contract: none.
  • Generated metadata: none.

Expected effects:

  • Read existing files or captured data. (the probe reads discovery output and calls the client probe only)
  • Launch or attach to a process.
  • Inject instrumentation or run scripts/code.
  • Change process memory, registers, files, or configuration.
  • Contact network services.
  • Recover protected code or work around protections.
  • Documentation or usability only; no target interaction.
  • Not sure yet; investigation or maintainer guidance needed.

Evidence and regression coverage

  • RED (executed on this machine, current main c106cf20c before the fix): a stdio MCP probe with isolated HOME/XDG state and a stub tshark 4.2.0 on PATH ran target-free binary_session {}; inspect_pcap_capture reported {"available": true, "reason": "available"} — the over-advertisement in #5711. A second probe without any tshark reported the same, so the kind fallback is unconditional.
  • GREEN (executed after the fix): the same probe reports {"available": false, "reason": "unsupported_host", "remediation": "Packet summaries require an enforceable native memory bound: ..."} for inspect_pcap_capture, and inspect_pcap_client stays available with a successful real call returning the stub version banner — the issue's proposed restoration.
  • Tests added: unit coverage in src/application/CapabilityInventory.test.ts (host-unsupported pcap capture vs available client) and MCP boundary coverage in tests/process-global/hostRestrictedAvailabilityMcp.test.ts (inspect_pcap_capture in the host-restricted table with its linux-or-win32 admitted set, plus a win32 x64 emulation row exercising the Job-Object side of the admitted set for every table entry).
  • Base reproduction: the issue's sequence and source analysis were rechecked against current main before fixing; the kind fallback and the gate text are unchanged from the issue's cited revisions.
  • Remaining proof gaps: a real Windows host was not executed here (the boundary test emulates win32 at discovery level only); CI covers Linux. The capture tool's typed execution refusal was documented by the issue and is unchanged by this fix.

For evidence-bearing changes:

  • Observed, derived, and inferred claims remain distinguishable. (executed probes vs source-derived reasoning are labeled in Validation)
  • Artifact identity, source provenance, and failed attempts remain preserved.
  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

  • npm ci — locked dependencies, Node 24.18.0 (.nvmrc), macOS 14 arm64.
  • npm run test:local -- src/application/CapabilityInventory.test.ts — 39 passed (38 existing + 1 new).
  • npm run test:focused -- tests/process-global/hostRestrictedAvailabilityMcp.test.ts — 7 passed (6 existing scenarios + the win32 row; the table entry is asserted inside each platform scenario).
  • npm run test:focused -- tests/boundary/mcp/pcapMcp.test.ts src/pcap/PcapNativeBound.test.ts src/pcap/PcapConfiguration.test.ts — 40 passed.
  • npm run check:fast — typecheck + lint pass (uncached).
  • Probes (RED/GREEN above): local stdio MCP probe against node scripts/rea.mjs mcp with isolated HOME/XDG_*/TMPDIR, before and after the fix.

Compatibility, safety, and release

  • Breaking changes or migration steps: none. The reason change only fires where available was already wrong; supported hosts and injected services are unchanged.
  • Real Hopper/Ghidra, browser, or OS coverage: not applicable — no provider is launched by the change; the probe's stub tshark only answers --version.
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: none.

Author readiness

Human owner: @kittimzhe

  • I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work.
  • I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps.
  • I declare this PR ready for initial maintainer review.

Before merge

  • This PR addresses a concrete problem or an agreed enhancement.
  • Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked: Fixes #5711.
  • Tests cover changed observable behavior and meaningful failure paths. (unit + MCP boundary with platform emulation; win32 side of the admitted set covered)
  • Owning docs, contracts, and generated metadata are updated where needed. (no docs enumerate the pcap tools' discovery reasons; unsupported_host already exists in the output schema and docs)
  • User-visible CLI/MCP changes include representative output. (RED/GREEN probe output quoted in Evidence)
  • I checked the final diff for secrets, unrelated cleanup, 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/6512 **Author:** [@kittimzhe](https://github.com/kittimzhe) **Created:** 10/23/2026 **Status:** ❌ Closed **Base:** `main` ← **Head:** `fix/pcap-capture-host-availability` --- ### 📝 Commits (1) - [`652e56f`](https://github.com/morluto/rea/commit/652e56f75dc52b0e13a631bf0c1a75cfc0adde78) fix(pcap): report capture summaries unsupported off their verified hosts ### 📊 Changes **6 files changed** (+64 additions, -12 deletions) <details> <summary>View changed files</summary> 📝 `src/application/CapabilityInventory.test.ts` (+18 -0) 📝 `src/application/CapabilityInventory.ts` (+10 -0) 📝 `src/composition/pcap.ts` (+3 -0) 📝 `src/pcap/PcapNativeBound.ts` (+18 -10) 📝 `src/server/createServer.ts` (+9 -1) 📝 `tests/process-global/hostRestrictedAvailabilityMcp.test.ts` (+6 -1) </details> ### 📄 Description Fixes #5711 Related: #6179 proposed the same classification before #5793 introduced the host-restriction mechanism. This PR follows that mechanism on current main and adds MCP-level coverage; happy to defer if the maintainers prefer rebasing #6179 instead. ## Summary Target-free discovery advertises `inspect_pcap_capture` as `available: true` on hosts whose capture execution refuses: the `pcap-provider` kind fallback in the availability projection returns available unconditionally, so on macOS the catalog promises a callable operation while the native bound gate rejects the host at execution with `capability_unavailable`. The host-independent `inspect_pcap_client` version probe keeps its availability either way. ## Problem and expected behavior - Smallest trigger: on a non-Linux, non-Windows host with a tshark on PATH, run a target-free `binary_session {}` and read `tool_availability`; `inspect_pcap_capture` reports `{"available": true, "reason": "available"}` even though calling it returns the typed refusal `Packet summaries require an enforceable native memory bound: Linux with util-linux prlimit, or Windows with owned Job Objects. This host's capture boundary remains unsupported.` The same over-advertisement appears with no tshark configured. - Violated invariant: the same one #5793 established for the other Linux-only integrations — an unavailable tool's machine-readable reason should name the actual blocker, and no configuration can make a host-restricted integration pass its execution host check. The mechanism this adds to is `HOST_RESTRICTED_FEATURES` / `hostUnsupported` / `verifiedHost` from #5793. - Expected: `inspect_pcap_capture` reports `unsupported_host` with the execution gate's remediation on hosts outside its verified set; Linux and Windows (Job Object bound) stay available; the client probe keeps `available` on every host; injected pcap services own their availability on any host. ## Change and scope - `src/pcap/PcapNativeBound.ts` now owns and exports `pcapCaptureHostSupported` (`linux || win32`) and its gate uses it — discovery and execution share the one check, replacing the inline platform pair that previously lived only in the gate. - `src/composition/pcap.ts` re-exports it; `src/server/createServer.ts` records `pcapCapture` in `verifiedHost` and in `hostUnsupported` through the existing `outsideVerifiedHost(options.pcapAnalysis, ...)` injection exemption. - `src/application/CapabilityInventory.ts` adds `"pcapCapture"` to `HOST_RESTRICTED_FEATURES` and classifies `inspect_pcap_capture` through `hostRestrictedAvailability` with the gate's exact remediation text. The `enabled` argument is `true`: the pcap family registers on every host, so the remaining unavailability dimension is configuration at execution, which is out of this issue's scope (noted below). - `inspect_pcap_client` is untouched — it stays on the kind fallback and remains available wherever the provider is constructed. - Intentionally not included: the no-tshark case still reports `available` for the family, exactly as before; #5711 asks for the host limitation split, and a configuration-aware availability for the pcap family can follow the pattern #5793 uses for `packetCaptureEnabled` if the maintainers want it. #6179's approach (a separate `pcapCaptureHostSupported` policy field) achieves the same classification but predates the `hostUnsupported` mechanism and conflicts with current main. - Contribution scope: ordinary fix within existing boundaries — no maintainer scope decision required ("not applicable"). ## Contract and boundary impact - Semantic owner and earliest changed stage: the target-free availability projection (`src/application/CapabilityInventory.ts`) plus the shared host gate (`src/pcap/PcapNativeBound.ts`). - CLI and MCP/tool-catalog contract: `tool_availability` for `inspect_pcap_capture` changes from `available` to `available: false, reason: "unsupported_host"` on hosts outside `linux || win32` when no pcap service is injected; the complete `tools/list` catalog is unchanged; `unsupported_host` is an existing reason value. - Provider, bridge, target-format, or platform compatibility: Linux unchanged (supported); Windows unchanged (supported through the Job Object bound); injected services unchanged. - Evidence, artifact, provenance contract: none. - Generated metadata: none. Expected effects: - [x] Read existing files or captured data. *(the probe reads discovery output and calls the client probe only)* - [ ] Launch or attach to a process. - [ ] Inject instrumentation or run scripts/code. - [ ] Change process memory, registers, files, or configuration. - [ ] Contact network services. - [ ] Recover protected code or work around protections. - [ ] Documentation or usability only; no target interaction. - [ ] Not sure yet; investigation or maintainer guidance needed. ## Evidence and regression coverage - RED (executed on this machine, current main `c106cf20c` before the fix): a stdio MCP probe with isolated `HOME`/XDG state and a stub tshark 4.2.0 on PATH ran target-free `binary_session {}`; `inspect_pcap_capture` reported `{"available": true, "reason": "available"}` — the over-advertisement in #5711. A second probe without any tshark reported the same, so the kind fallback is unconditional. - GREEN (executed after the fix): the same probe reports `{"available": false, "reason": "unsupported_host", "remediation": "Packet summaries require an enforceable native memory bound: ..."}` for `inspect_pcap_capture`, and `inspect_pcap_client` stays `available` with a successful real call returning the stub version banner — the issue's proposed restoration. - Tests added: unit coverage in `src/application/CapabilityInventory.test.ts` (host-unsupported pcap capture vs available client) and MCP boundary coverage in `tests/process-global/hostRestrictedAvailabilityMcp.test.ts` (`inspect_pcap_capture` in the host-restricted table with its `linux-or-win32` admitted set, plus a `win32 x64` emulation row exercising the Job-Object side of the admitted set for every table entry). - Base reproduction: the issue's sequence and source analysis were rechecked against current main before fixing; the kind fallback and the gate text are unchanged from the issue's cited revisions. - Remaining proof gaps: a real Windows host was not executed here (the boundary test emulates `win32` at discovery level only); CI covers Linux. The capture tool's typed execution refusal was documented by the issue and is unchanged by this fix. For evidence-bearing changes: - [x] Observed, derived, and inferred claims remain distinguishable. *(executed probes vs source-derived reasoning are labeled in Validation)* - [x] Artifact identity, source provenance, and failed attempts remain preserved. - [x] Unsupported, incomplete, unavailable, or uncertain outcomes remain visible. ## Validation performed - `npm ci` — locked dependencies, Node 24.18.0 (`.nvmrc`), macOS 14 arm64. - `npm run test:local -- src/application/CapabilityInventory.test.ts` — 39 passed (38 existing + 1 new). - `npm run test:focused -- tests/process-global/hostRestrictedAvailabilityMcp.test.ts` — 7 passed (6 existing scenarios + the win32 row; the table entry is asserted inside each platform scenario). - `npm run test:focused -- tests/boundary/mcp/pcapMcp.test.ts src/pcap/PcapNativeBound.test.ts src/pcap/PcapConfiguration.test.ts` — 40 passed. - `npm run check:fast` — typecheck + lint pass (uncached). - Probes (RED/GREEN above): local stdio MCP probe against `node scripts/rea.mjs mcp` with isolated `HOME`/`XDG_*`/`TMPDIR`, before and after the fix. ## Compatibility, safety, and release - Breaking changes or migration steps: none. The reason change only fires where `available` was already wrong; supported hosts and injected services are unchanged. - Real Hopper/Ghidra, browser, or OS coverage: not applicable — no provider is launched by the change; the probe's stub tshark only answers `--version`. - Package or release metadata impact: none. - Security, privacy, process, or containment review: none. ## Author readiness Human owner: @kittimzhe - [ ] I reviewed the final diff and relevant existing code, understand the change and its edge cases, and take responsibility for the complete PR, including AI-assisted work. - [ ] I checked the evidence above, confirmed it supports the current change, and recorded meaningful validation gaps. - [ ] I declare this PR ready for initial maintainer review. ## Before merge - [ ] This PR addresses a concrete problem or an agreed enhancement. - [ ] Material scope and authority questions are resolved, and any required maintainer scope decision covers the final diff. - [x] The PR has one focused outcome and the title follows `type(scope): outcome`. - [x] Related issue is linked: Fixes #5711. - [x] Tests cover changed observable behavior and meaningful failure paths. *(unit + MCP boundary with platform emulation; win32 side of the admitted set covered)* - [x] Owning docs, contracts, and generated metadata are updated where needed. *(no docs enumerate the pcap tools' discovery reasons; `unsupported_host` already exists in the output schema and docs)* - [x] User-visible CLI/MCP changes include representative output. *(RED/GREEN probe output quoted in Evidence)* - [x] I checked the final diff for secrets, unrelated cleanup, and unsupported claims. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>
bsakaguchi 2026-11-01 21:47:25 +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#7375
No description provided.