92a9591a41
* refactor(pcap): give TShark selection and version admission one owner
The pcap and packet-capture families wrapped the same caller-supplied
TShark with diverging rules. inspect_pcap_* accepted an absolute
REA_TSHARK_COMMAND or tshark from PATH, while inspect_packet_* and the
server availability policy required an absolute REA_TSHARK_COMMAND and
parsed the version banner with a separate regex.
PcapConfiguration now owns the rule: selectWiresharkTool selects an
absolute environment path or the bare name on PATH and refuses relative
values; locateWiresharkTool resolves a PATH selection to the first
absolute PATH entry holding an executable file; parseWiresharkVersion
admits Wireshark 4.x banners for both providers. TsharkCaptureProvider
and the session availability policy consume these facts instead of
reinterpreting REA_TSHARK_COMMAND, so all four tools accept and refuse
the same configurations. inspect_packet_* still resolves, hashes and
rechecks the located executable, and records selection_source in its
tool Evidence.
Host support and resource bounds are unchanged; unifying them is the
next milestone in #3403.
Refs #3403
* fix(pcap): execute the TShark the shared locator selects
resolvePcapTools still returned bare tool names for PATH selections, so
the operating system could run a tool from a relative PATH entry while
the packet tools skipped that entry and selected a different install.
On POSIX hosts, resolve PATH selections through locateWiresharkTool and
run that absolute executable, failing with the existing tshark_missing or
capinfos_missing code when no absolute PATH entry holds the tool. Both
selections are validated before PATH is consulted, so a relative
environment value still reports its own configuration error. Windows
keeps PATH/PATHEXT resolution in the process launcher.
Refs #3403
* chore: restore main's copies of files the merge hook reformatted
The pre-commit oxlint --fix touched two files this PR does not change; keep them identical to main.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
* fix(pcap): share selected tool identity verification
* perf(pcap): retain compact executable identity
* fix(pcap): report missing selected tools clearly
* fix(pcap): read historical capture evidence
* fix(pcap): preserve executable read failures
* test(pcap): cover version refusal and packet-tool availability selection
Address review follow-ups on the shared TShark owner:
- Send a 3.x TShark banner and a non-Wireshark banner through the packet
provider, pinning the capability-unavailable reason for each and that
only the version probe ran before refusal.
- Cover the session availability rule for inspect_packet_capture over
MCP: a PATH-only install and an absolute REA_TSHARK_COMMAND are
available on Linux, a relative REA_TSHARK_COMMAND is refused even when
PATH holds TShark, and no absolute PATH entry reports provider_missing.
- Rename the locator test's missing absolute PATH entry so it no longer
shadows node:path relative.
Refs #3403
* fix(pcap): name the configured path when a selected tool is missing
Resolving the selected executable before launch replaced the runner's
"Cannot run selected tool <path>" refusal with a message that kept the
configured path only in diagnostics, so the public CLI no longer told the
caller which REA_TSHARK_COMMAND or REA_CAPINFOS_COMMAND value to fix and
the pcap CLI boundary test failed. Include the configured command in the
capability-unavailable message and assert it there.
Refs #3403
* test(captures): give the late-cancellation fixture a TShark selection source
The service fixture added on main in 719d56ebf predates the required tool.selection_source field, so its report failed output validation before reaching the late-cancellation path the test covers.
Refs #3403
* fix(pcap): report a probe's pending cleanup when a post-run check fails
When a tool probe returned with its owned process still awaiting cleanup,
a failed post-run executable re-read or identity check threw before run()
reported that cleanup. Probes have no snapshot to carry it, so callers
saw an ordinary error with cleanupIncomplete false while the provider
kept the process and refused the next request.
After the command returns, combine such a failure with the probe's
ProviderCleanupError (cancellation and other command failures keep their
own cleanup outcome). Classify request failures through one
analysisFailure owner shared by run() and executeAdmitted(), and let the
availability probe rethrow any cleanup-incomplete failure instead of
reporting the tool unavailable.
Refs #3403
* fix(pcap): keep a failed executable re-read's cleanup live with the probe's
The combined post-run failure was bound only to the probe's pending
process cleanup. When the executable re-read had also failed to close its
file, the classified failure owned that cleanup, but the combined error's
live cleanupResources omitted the file and could clear cleanupIncomplete
once the process stopped. Bind both the classified failure and the probe
cleanup as dependencies.
Refs #3403
---------
Co-authored-by: Kaoru0822 <208281322+kaoru0822-kitauji@users.noreply.github.com>
Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: morluto <76467478+morluto@users.noreply.github.com>
7.5 KiB
Packet capture summaries
REA summarizes already saved pcap/pcapng files through caller-selected Wireshark
4.x tshark and capinfos. Use inspect_packet_capture for selected fields,
filters and decode-as rules; use this family for address, DNS, SNI, protocol-stack
and URI inventories. It does not acquire traffic or fetch recorded targets.
Supply tools
export REA_TSHARK_COMMAND=/absolute/path/tshark
export REA_CAPINFOS_COMMAND=/absolute/path/capinfos
# Linux only; default /usr/bin/prlimit
export REA_TSHARK_PRLIMIT_COMMAND=/absolute/path/prlimit
rea inspect-pcap-client
rea inspect-pcap-capture /captures/session.pcapng --json
Without explicit tool commands, this family resolves them through PATH and records that selection source. On Linux and macOS it runs the tool found in the first absolute PATH entry holding an executable file, the same selection the packet capture tools make; relative PATH entries are skipped. Windows keeps PATH/PATHEXT resolution in the process launcher. Client inspection reads no capture file; on hosts where PATH/PATHEXT does not expose an absolute candidate, its executable digest and resolved path are reported as unresolved. Otherwise the canonical executable path and SHA-256 are reported. The pcap provider and packet tools share the selected-tool identity check, and changes to a resolved executable during a run fail with artifact-changed Evidence. Capture inspection requires Linux with util-linux prlimit or Windows with owned Job Objects. macOS capture inspection returns a capability gap because the new native memory boundary is unverified; its version probes remain available. Tools and installed libraries/plugins are caller-trusted. An empty private personal Wireshark configuration is used; this is not an OS sandbox.
Inspect only the needed facts
MCP inspect_pcap_capture accepts path and optional detail: "summary".
Complete delivery remains the default. Summary commits and retains the same
complete Evidence, returning identity, capture metadata, observed counts,
retained counts, source coverage and diagnostic lengths without large lists.
Then use its normalized_result.parent_evidence_id with
inspect_analysis_view source kind retained-evidence:
{"kind":"pcap","facet":"endpoints","offset":0,"limit":20}
{"kind":"pcap","facet":"dns-queries","offset":0,"limit":20}
{"kind":"pcap","facet":"dns-addresses","query":"example.com","offset":0,"limit":20}
{"kind":"pcap","facet":"tls-sni","offset":0,"limit":20}
{"kind":"pcap","facet":"diagnostics","stream":"tshark","offset":0,"limit":4096}
Other row facets are protocols, http-uris and unattributed-addresses.
Defaults are offset 0 and limit 64. DNS question pages give address counts;
select one exact retained question to page its addresses. Diagnostic windows
count UTF-16 code units; other windows count rows. Missing/ambiguous selectors
fail. Unknown legacy diagnostics remain unknown, not an observed empty stream.
Portable CLI views use the existing inspect-analysis-view workflow with inline
complete Evidence. Views never reread the source or launch Wireshark and work
after the original file is deleted. Page exhaustion covers the retained facet;
it does not establish network completeness or recover missing traffic.
Interpret provenance and coverage
target.sha256 binds observations to an admitted stable capture snapshot. Both
tools read that copy, which is hashed again after analysis. Capture metadata and
literal field values are producer observations; address/protocol counts and DNS
associations are derivations. Capture Evidence has historical-reference authority.
capture_start and capture_end are RFC 3339 UTC instants derived from
capinfos -S epoch seconds, retaining all producer fractional digits (up to
nanoseconds). Empty captures, malformed timestamps and instants outside years
0000–9999 remain null; host-local timestamps without a zone are not inferred.
Addresses count once per packet, including loopback and nested IP occurrences.
DNS addresses are associated only with one question in the same response packet;
additional records may be included, so this does not prove final resolution.
Ambiguous addresses remain in a separate inventory. Protocol distribution counts
exact nonempty frame.protocols stack strings. Frames for which TShark reports
an empty stack, including zero-length packets, still contribute to the packet
count without adding a protocol row. An all-empty stack inventory can have
complete examined coverage; it does not establish the absence of network traffic.
TLS SNI is recorded handshake metadata,
not process identity or proof of the destination's authenticity.
All examined inventories are retained within the resource budget; no fixed
200/100/50-item truncation is applied. HTTP transport credentials are excluded
without rewriting other URI bytes; ambiguous credential spans cause omission.
Counts preserve distinct observed source URIs before omission or coalescing.
coverage: "partial" records unresolved DNS attribution or URI item loss;
component credential exclusion is also counted explicitly. Diagnostics retain
both tool stderr streams. Recorded fields do not establish decrypted payloads,
causality, process identity, absence of unrecorded traffic or current deployments.
Resources and lifecycle
One inspection is admitted at a time per provider. Concurrent calls return a capacity error; close drains active work before releasing resources. Captures are streamed into a read-only owned snapshot with a 2 GiB disk budget. Native capture commands enforce Linux address-space ceilings of at most 1 GiB, 300 CPU seconds, 64 MiB per file and no core dumps, preserving stricter inherited limits. Windows uses a 1 GiB committed-memory limit for each owned tool tree. These are not aggregate machine or filesystem quotas.
TShark output is bounded at 8 MiB; its known five-level selected-field shape and 128 MiB graph-expansion estimate are checked before allocation. Retained facts have a separate 16 MiB estimate. Capinfos output is limited to 64 KiB. Command wall deadlines are 300 s for dissection, 60 s for metadata and 20 s for probes. Native ownership preparation has its own bounded lifecycle.
Malformed/oversized output returns no partial success. Unvalidated partial JSON is not returned as facts. Cancellation reaches probes, acquisition, commands and projection. Cleanup failure returns a typed error, retains completed Evidence when available, and retains owned resources for retry on close.
Verification scope
Current follow-up verification uses Linux/Node 24.18.0 and Wireshark 4.0.17. Private real recorded corpora are checked against independent raw-frame/IP parsing and Python aggregation, public CLI/stdio MCP parity, SDK schemas, source hashes and retained views. Synthetic native tools separately test malformed output, cancellation, source/snapshot mutation, capacity and cleanup; they do not establish real Wireshark or other-platform behavior.
The original proposal reported Linux 4.6.6, macOS/Windows 4.6.9 verification on its earlier implementation. Those reports do not verify the new final memory boundary. Actual Windows/Bun Wireshark execution is unverified here; macOS capture support needs a separate enforceable-bound decision.
npm run verify:pcap -- --pcap /absolute/saved-capture.pcapng
This verifier exercises built CLI/stdio MCP, schemas, artifact identity and
cleanup. Without --pcap, capture inspection is reported as unverified. Private
captures, keys and provider runtime files are not committed.