Skip to content

fix(pcap): name the host tool to configure in capability refusals - #2507

Merged
morluto merged 2 commits into
mainfrom
fix/pcap-capability-remediation
Oct 13, 2026
Merged

morluto merged 2 commits into
mainfrom
fix/pcap-capability-remediation

Conversation

@kaoru0822-kitauji

@kaoru0822-kitauji kaoru0822-kitauji commented Oct 13, 2026 •

Copy link
Copy Markdown
Collaborator

Summary

Every host-tool refusal in the new inspect_pcap_capture / inspect_pcap_client family (9581e06) told the caller "This analysis is unavailable for the current target. Choose another analysis or target." That includes inspect_pcap_client, which has no target at all. The real cause, such as tshark missing from PATH, a relative REA_TSHARK_COMMAND, the unsupported macOS capture boundary or an unusable Linux prlimit, was available only in details.reason. So an agent following remediation.action would try another target instead of fixing the installation. The sibling inspect_packet_capture adapter (TsharkCaptureProvider) and sigrok/WABT already give these refusals a userMessage. The pcap family never did.

No linked issue: found by a CLI sweep of new commands on a host without Wireshark.

Problem and expected behavior

Smallest trigger, on any host without Wireshark: rea inspect-pcap-client --format json

Before:

{"code":"capability_unavailable","message":"This analysis is unavailable for the current target. Choose another analysis or target.", "remediation":{"action":"This analysis is unavailable for the current target. Choose another analysis or target."}, "details":{"reason":"Cannot run selected tool tshark: spawn tshark ENOENT"}}

After:

{"code":"capability_unavailable","message":"Cannot run selected tool tshark: spawn tshark ENOENT. Supply Wireshark 4.x tshark and capinfos on PATH or through absolute REA_TSHARK_COMMAND and REA_CAPINFOS_COMMAND; REA does not install them.", "remediation":{"action":"<same>"}, ...}

Violated invariant: a host or tool refusal names what to configure. It does not send the caller to another target (the #1224 precedent for pwntools/EVMole/firmware/LLDB, and expectConfigurationRefusal in the CLI harness).

Change and scope

  • src/pcap/PcapConfiguration.ts already owns the tool environment names. It now also owns pcapToolUnavailable, the one constructor for tool refusals. All three tool-refusal sites use it: spawn ENOENT/EACCES/Windows batch and the version probe failure in PcapCommand, and PcapConfigurationFailure in PcapProvider. The reason is unchanged; only userMessage is added. Missing terminal punctuation is completed so the two sentences don't run together.
  • PcapNativeBound: the macOS/unsupported-host refusal uses its own reason as userMessage, because it already states the Linux/Windows requirement. The Linux limiter refusal now includes the underlying cause (e.g. REA_TSHARK_PRLIMIT_COMMAND must be absolute. or ENOENT … realpath '/usr/bin/prlimit') and names REA_TSHARK_PRLIMIT_COMMAND. Before, it gave only a generic sentence.
  • PcapSnapshot: a PrivateRuntimeRootUnavailableError now keeps its retryable flag, as the WABT and source-map adapters already do. Before, a transient workspace refusal was projected as permanent.

Not included: the two TShark adapters (src/captures/TsharkCaptureProvider.ts and src/pcap/) duplicate tool selection and refusal wording. Merging them is a larger ownership decision. The generic projection for non-retryable PrivateRuntimeRootUnavailableError is shared by every runtime-root consumer, so it is left unchanged here.

Contribution scope: not applicable (an ordinary fix within existing boundaries).

Contract and boundary impact

  • Semantic owner and earliest changed stage: the pcap provider's capability refusal construction (src/pcap).

  • Contribution scope fit and linked maintainer decision: not applicable.

  • CLI and MCP/tool-catalog contract: no schema change. Error message/remediation.action text changes for capability_unavailable refusals of inspect_pcap_capture/inspect_pcap_client. Codes, categories and details are unchanged.

  • Provider, bridge, target-format, or platform compatibility: none.

  • Evidence, artifact, provenance, or reconstruction contract: none.

  • Target selection, authority, upstream behavior, and cleanup details: unchanged. Refusals still happen before any capture byte is read.

  • Generated metadata, package, or installation impact: none.

  • Documentation or usability only; no target interaction.

Evidence and regression coverage

  • Tests added or updated:
    • tests/boundary/cli/pcapCli.test.ts: public CLI for both commands with missing tools, plus a relative REA_TSHARK_COMMAND, through the shared expectConfigurationRefusal helper.
    • tests/boundary/pcap/pcapProviderCrossPlatform.test.ts: the unsupported-host refusal states the Linux/Windows requirement (runs on macOS).
    • tests/boundary/pcap/pcapProvider.test.ts (Linux): tool configuration refusals carry the guidance, and a new case covers a relative REA_TSHARK_PRLIMIT_COMMAND.
  • Base reproduction: with the src/pcap changes stashed, the 3 new CLI cases fail (generic message); with them, all 5 pass.
  • User-visible output: see above. Real MCP stdio inspect_pcap_client/inspect_pcap_capture return the same text in error.message.
  • Remaining proof gaps: the Linux-only pcapProvider.test.ts cases (including the prlimit case) did not run locally on macOS; they run in CI. I checked the prlimit message text against dist by importing preparePcapNativeBound with process.platform overridden to linux. Real Wireshark is not installed here, so no real-TShark run.

Validation performed

  • npm run test:focused -- tests/boundary/cli/pcapCli.test.ts — 5 passed (3 failed with the fix stashed)
  • npm run test:focused -- tests/boundary/pcap/*.test.ts tests/boundary/mcp/pcapMcp.test.ts tests/boundary/cli/pcapCli.test.ts — 11 passed, 19 skipped (Linux-only). One failure, pcapProviderCrossPlatform "rejects a path that is not a readable file", fails identically on unmodified main on macOS: the host-boundary refusal precedes the path check there.
  • npm run test:local -- src/pcap/PcapConfiguration.test.ts src/pcap/PcapOutput.test.ts src/domain/analysisErrorProjection.test.ts src/domain/explicitSensitiveFailure.test.ts — 92 passed
  • npm run check:fast, npm run typecheck, npm run format:check — pass
  • Real CLI (scripts/rea.mjs) and real MCP stdio client on macOS without Wireshark: missing tools, a version-less tool (/bin/echo), and version-reporting stubs that reach the macOS boundary refusal. All now print the specific guidance.

Cost: each refusal gains about 100 characters, repeated in message and remediation.action (~200 bytes on a one-off error). In exchange, the agent no longer tries another target after a host refusal.

Compatibility, safety, and release

  • Breaking changes or migration steps: none.
  • Real Hopper/Ghidra, browser, or OS coverage: macOS real CLI/MCP. Linux paths are covered by CI's boundary tests.
  • Package or release metadata impact: none.
  • Security, privacy, process, or containment review: messages repeat caller-selected tool paths that already appear in details.reason, and explicit-value redaction still applies to userMessage.

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, or the reason for not linking one is stated above.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

🤖 Generated with Claude Code

Summary by CodeRabbit

  • Bug Fixes
    • PCAP setup failures now provide clearer guidance for missing or unusable Wireshark tools, including requirements for absolute executable paths.
    • Unsupported memory-limiting options now explain which platform capabilities are required and how to address setup failures.
    • Retryability details are preserved when private runtime setup is unavailable.

kaoru0822-kitauji and others added 2 commits October 13, 2026 05:05
Missing or misconfigured tshark/capinfos, the unsupported macOS capture
boundary and an unusable Linux prlimit were projected with the generic
"unavailable for the current target; choose another target" advice, even
for inspect_pcap_client, which has no target. Route tool refusals through
one pcapToolUnavailable owner that names REA_TSHARK_COMMAND and
REA_CAPINFOS_COMMAND, give host-boundary refusals their own reason, and
keep the private workspace refusal's retryable flag like WABT and source
maps do.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@chatgpt-codex-connector

Copy link
Copy Markdown

Codex usage limits have been reached for code reviews. Please check with the admins of this repo to increase the limits by adding credits.
Repo admins can enable using credits for code reviews in their settings.

@coderabbitai

coderabbitai Bot commented Oct 13, 2026 •

Copy link
Copy Markdown

Review in Change Stack →

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: ASSERTIVE
  • Plan: Advanced
  • Run ID: a9e5366d-01e0-44df-8e45-dd8c22eb07a3
📥 Commits

Reviewing files that changed from the base of the PR and between 8b18171 and b72d828.

📒 Files selected for processing (8)
  • src/pcap/PcapCommand.ts
  • src/pcap/PcapConfiguration.ts
  • src/pcap/PcapNativeBound.ts
  • src/pcap/PcapProvider.ts
  • src/pcap/PcapSnapshot.ts
  • tests/boundary/cli/pcapCli.test.ts
  • tests/boundary/pcap/pcapProvider.test.ts
  • tests/boundary/pcap/pcapProviderCrossPlatform.test.ts

Included review availability: This review used your included allowance. Your plan provides up to 10 included reviews per hour; 8 remain after this review.

📝 Walkthrough

PCAP tool failures now use shared configuration guidance in selected command and provider error paths. Native-bound errors provide platform-specific remediation details, and runtime-root failures preserve retryability. Boundary tests check these messages and error details.

Changes: PCAP capability handling

Layer / File(s) Summary
Tool error mapping and guidance
src/pcap/PcapConfiguration.ts, src/pcap/PcapCommand.ts, src/pcap/PcapProvider.ts, tests/boundary/cli/pcapCli.test.ts, tests/boundary/pcap/pcapProvider.test.ts
A shared helper adds Wireshark tool guidance to selected capability errors. Command and provider error mappings use the helper. Tests check missing or relative tool paths and the resulting refusal messages.
Native-bound and runtime-root errors
src/pcap/PcapNativeBound.ts, src/pcap/PcapSnapshot.ts, tests/boundary/pcap/pcapProvider.test.ts, tests/boundary/pcap/pcapProviderCrossPlatform.test.ts
Native-bound errors include platform or prlimit configuration details. Runtime-root errors preserve retryability. Tests check relative limiter paths and platform-specific refusal messages.

Priority: ⬇️ Low

Estimated code review effort: 2 (Simple) | ~12 minutes

Change: Bug fix

Suggested reviewers: 3ql

Merge Risk: ⚪ Minimal · up to b72d8

The refusal messages provide more actionable configuration guidance. No issue requiring a fix before merge was identified.

Pre-merge checks · Passed 5
Passed Passed checks (5 passed)
Check name Status Explanation
Description check Passed The description follows the required template and clearly documents the problem, expected behavior, scope, contract impact, regression coverage, validation results, compatibility, and remaining proof …
Title check Passed The title is concise and accurately identifies the main change: capability refusals now name the host tool that requires configuration.
Docstring Coverage Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 8…
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
📝 Generate docstrings
  • Commit to this branch
  • Create a new PR
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Warning

Billing warning: we have not been able to collect payment for this subscription for more than 72 hours. Please update the payment method or pay any pending invoices in Billing to avoid service interruption.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

A rabbit checks the capture trail
Wireshark paths must pass the test
prlimit gets its path made clear
Retry details stay in view
Then hops away through leaves and dew

Comment @coderabbitai help to get the list of available commands.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

bug Something isn't working

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants