Wireshark MCP 3.0.0 — Trustworthy Analysis and Stable Interfaces / 可信分析与稳定接口

3.0.0 — 2026-09-05

English

Added

• wireshark_aggregate for capture-wide counts, grouped distributions, distinct cardinality, top-k output, and time buckets.
• Stable result contract: envelope_response standardizes scope, coverage, pagination, warnings, truncated, and stderr across statistical aggregation, credential extraction, and threat detection suites.
• Type-invariant output capping: collection types (dict, list) remain structured JSON objects/arrays under character limits with truncated: true, preserving global total and updating next_offset without skipping records.
• MCP is_error synchronization: tool failures (success: false) strictly mirror to MCP protocol-level CallToolResult.is_error = True so clients and orchestrators reliably identify failures, even under output truncation.
• Structured Finding model (Finding, FindingEvidence, FindingConstraints) anchoring findings to specific packet numbers and streams with credential masking (mask_secret).
• Deterministic synthetic PCAP fixture suite (empty.pcap, plaintext_credentials.pcap, syn_scan_burst.pcap, dns_tunnel_candidate.pcap, multivalue_fields.pcap) and real tshark integration test suite (tests/test_real_pcap.py) in CI.
• Real stdio subprocess handshake verification, real listening Streamable HTTP subprocess and in-process lifecycle verification, and python -m wireshark_mcp execution entry point.
• Comprehensive protocol, client, Wireshark, and OS compatibility matrix (docs/compatibility-matrix.md) with explicit verification tiers.
• Hypothesis-driven analysis workflow in wireshark-traffic-analysis skill, prototype tshark-cli-analysis skill, and non-modifying --check validation in scripts/sync_skills.py.
• Stable MCP Python SDK 2.x runtime and an in-memory protocol negotiation test.
• English and Chinese aggregation, architecture, deployment, security migration, roadmap, and release-planning documentation.
• Server guidance for the open → aggregate → packet-level verification workflow.
• Official linux/amd64 and linux/arm64 container image at ghcr.io/bx33661/wireshark-mcp:3.0.0, including tshark, SBOM, and build provenance.
• Agent traffic-analysis evaluation baseline with 12 deterministic scenarios, evidence and coverage checks, forbidden-overclaim checks, and a machine-readable scorer.
• Reproducible MCP-vs-tshark execution benchmark and an accuracy-gated comparator for independently collected Agent runs.
• Numeric sum, min, max, and avg reducers for wireshark_aggregate, including value-quality counters and numeric ordering.

Security

• Fixed CVE-2026-43901 / GHSA-3r68-x3xc-rxpg: all file-creating tools now reject writes unless WIRESHARK_MCP_ALLOWED_DIRS names an existing allowed root.
• Non-loopback SSE and Streamable HTTP binds now require the explicit --allow-insecure-http override.
• Child stdout/stderr, live-capture time, packet count, and storage are bounded; timed-out or cancelled children are killed and reaped across all streaming and non-streaming read paths.
• Streaming stdout loops enforce hard byte bounds (MAX_STDOUT_BYTES = 50MB) and terminate/reap subprocesses on cancellation or buffer overflow.
• Cardinality limits (MAX_AGGREGATE_GROUPS = 10_000, MAX_DISTINCT_PER_GROUP = 5_000, and global budget MAX_TOTAL_DISTINCT_ITEMS = 50_000) prevent aggregate memory exhaustion.
• editcap frame ranges and ring-buffer options use strict grammars to prevent option injection.
• WPA passphrases and TLS key-log paths are redacted from subprocess logs and diagnostics.
• MCP capability responses no longer expose local executable paths.
• Windows file operations reject device namespace paths, reserved device names, and NTFS alternate data streams.
• The client installer preserves malformed JSON configurations instead of replacing them; UTF-8 BOM configs remain supported.
• Runtime dependency floors exclude known-vulnerable Click, Cryptography, PyJWT, python-multipart, and Starlette releases.
• CI now runs code and workflow security analysis; third-party Actions are commit-pinned, checkout credentials are not persisted, publishing verifies the release tag against package metadata, and release data reaches shell scripts only through validated environment variables.

Changed

• Detection semantics overhauled:
  • Subquery failure tracking: subquery failures in threat detection are never interpreted as zero traffic or clean conclusions; partial analysis is explicitly flagged with coverage.status = "partial" and candidate confidence.
  • DoS detection treats failed SYN-ACK subqueries as unknown rather than zero, skipping invalid ratio calculations and eliminating false ratio evidence while reporting observed SYN rates; propagates SYN and subquery truncation states to warnings and coverage.
  • Plaintext credential extraction drops arbitrary len > 20 length thresholds, correctly extracts short/common credentials (admin, 123456), automatically masks secrets, and returns packet/stream anchors.
  • DNS tunnel detection inspects query traffic only (dns.flags.response == 0) and eliminates uncalibrated subjective probability assertions ("HIGH probability"), replacing them with candidate signals, entropy measurements, and query rates.
  • DoS detection computes time-normalized packet rates (pps) across the queried candidate packet timespan (min 1.0s window), notes sub-second burst limitations, and warns on single-sided capture bias.
  • Port scan detection records sample frame numbers and scan coverage constraints.
• Aggregation strictly checks limits on each distinct value insertion and prevents comma-splitting on literal string fields (http.user_agent, file names).
• Package and server metadata moved to 3.0.0; MCP SDK support is mcp>=2.1.1,<3.
• Full, analysis, and core profiles expose 52, 40, and 32 tools. Reduced profiles now remove object export and YARA export as file-writing operations.
• Long aggregate scans stop at the server safety ceiling instead of buffering unbounded output.
• Full-capture aggregation consumes tshark field rows through a bounded accumulator without materializing a complete TSV or packet-row list, bypasses the raw-output cache, and enforces independent one-million-row and 50 MiB stream ceilings.
• Streamed field subprocesses are terminated and reaped on row/byte overflow, timeout, cancellation, and consumer failure while stderr is drained concurrently.
• Success envelopes preserve truncation and stderr metadata across normalization.

Fixed

• Distinct cardinality expands fields with multiple occurrences.
• Time buckets reject non-finite or impractically small widths and skip malformed timestamps safely.
• Ordinary field text containing [Showing is no longer mistaken for a truncation marker.
• Packet-content string filters now escape backslashes as well as quotes.
• Wireshark child processes no longer open transient console windows on Windows.
• Streamable HTTP validation exercises the actual 2026-07-28 stateless request envelope (server/discover, tools/list, and tools/call) and asserts the exact advertised version instead of sending the modern version through the legacy initialize handshake.

Breaking changes

• File-creating tools no longer work without WIRESHARK_MCP_ALLOWED_DIRS.
• Configured allowed roots must already exist and be directories; once configured, they constrain both reads and writes.
• A non-loopback HTTP/SSE bind fails at startup without --allow-insecure-http.
• Live-capture and subprocess-output limits may reject workloads that 2.x allowed to run without bounds.

See the 3.0 security migration guide.

---

中文

新增

• 新增 wireshark_aggregate，支持全量包数、分组分布、去重基数、Top-K 和时间桶。
• 稳定结果契约：envelope_response 统一统计聚合、明文凭据提取和威胁检测工具的 scope、coverage、pagination、warnings、truncated 与 stderr。
• 类型不变的输出截断：集合类型（dict 与 list）在字符上限下保持结构化 JSON 对象/数组，附带 truncated: true，并在分页元数据中保留全局 total 与递增修正 next_offset（offset + returned），避免重试或翻页时漏包。
• MCP 协议级 is_error 同步：工具执行失败（success: false）严格同步为 MCP 协议级 CallToolResult.is_error = True，即使发生严重截断也能保证客户端与 Orchestrator 准确识别失败。
• 结构化 Finding 证据模型（Finding、FindingEvidence、FindingConstraints），将研判结论严格锚定到具体帧号与流序号，并提供敏感凭据脱敏保护（mask_secret）。
• 确定性合成 PCAP 样本集（empty.pcap、plaintext_credentials.pcap、syn_scan_burst.pcap、dns_tunnel_candidate.pcap、multivalue_fields.pcap）与驱动真实系统 tshark 的端到端集成测试（tests/test_real_pcap.py），并纳入 Linux / Windows CI。
• 真实 stdio 子进程握手测试、真实 Streamable HTTP 监听子进程与进程内全生命周期测试，以及 python -m wireshark_mcp 模块化启动入口。
• 全面的协议、客户端、Wireshark 与操作系统兼容性矩阵（docs/compatibility-matrix.md），明确区分“已在 CI/本地实测验证”、“配置支持”与“预期兼容”层级。
• wireshark-traffic-analysis 升级为“假设驱动 + 强制证据锚点”工作流，提供 tshark-cli-analysis 原型 Skill，并支持 scripts/sync_skills.py --check 只读校验。
• 运行时迁移到稳定版 MCP Python SDK 2.x，并增加内存协议协商测试。
• 补齐中英文聚合、架构、部署、安全迁移、路线图和发布文档。
• 服务端明确“打开抓包 → 全量聚合 → 包级核验”的分析路径。
• 官方 linux/amd64 与 linux/arm64 容器镜像 ghcr.io/bx33661/wireshark-mcp:3.0.0，内置 tshark，并附带 SBOM 与构建来源证明。
• 新增 Agent 流量分析评测基线，包含 12 个确定性场景、证据与覆盖检查、禁止性过度结论检查和机器可读评分器。
• 新增可复现的 MCP 与 tshark 执行基准，以及对独立 Agent 运行进行准确率门控的对比工具。
• wireshark_aggregate 增加数值 sum、min、max、avg，同时报告数值质量并支持按数值结果排序。

安全

• 修复 CVE-2026-43901 / GHSA-3r68-x3xc-rxpg：只有 WIRESHARK_MCP_ALLOWED_DIRS 指向现有允许根目录后，写文件工具才可运行。
• SSE 和 Streamable HTTP 监听非回环地址时，必须显式传入 --allow-insecure-http。
• 限制子进程 stdout/stderr、实时抓包时长、包数和存储；流式与非流式读取路径下的超时或取消操作均会强制终止（kill()）并回收（wait()）子进程。
• 流式输出循环增加硬字节上限（MAX_STDOUT_BYTES = 50MB），取消或缓冲区溢出时主动终止并回收子进程。
• 聚合分组上限（MAX_AGGREGATE_GROUPS = 10_000）、组内去重基数上限（MAX_DISTINCT_PER_GROUP = 5_000，单行解析逐项受限）与全局去重总预算（MAX_TOTAL_DISTINCT_ITEMS = 50_000）防止聚合内存耗尽。
• editcap 帧范围和环形缓冲参数使用严格语法，阻止选项注入。
• WPA 口令和 TLS key-log 路径不会出现在子进程日志与诊断中。
• MCP 能力响应不再泄露本机可执行文件路径。
• Windows 文件操作会拒绝设备命名空间、保留设备名和 NTFS Alternate Data Stream 路径。
• 客户端安装器遇到损坏的 JSON 配置时不再覆盖原文件，同时兼容带 UTF-8 BOM 的配置。
• 运行时依赖下限排除了已知存在漏洞的 Click、Cryptography、PyJWT、python-multipart 和 Starlette 版本。
• CI 新增代码与工作流安全扫描；第三方 Action 固定到提交、checkout 不再保留凭据，发布前校验 Git tag 与包元数据，release 数据经校验后的环境变量进入 shell。

变更

• 重构检测语义：
  • 子查询失败跟踪：威胁检测中的子查询失败绝不被解释为零流量或“未发现攻击”的确认结论；检测不完整时显式标记 coverage.status = "partial"，置信度降为候选级别（candidate），并在摘要中警告未执行或失败的检查项。
  • DoS 攻击检测将失败的 SYN-ACK 子查询视为未知而非零，跳过无效比例计算并杜绝虚假比例证据，同时独立报告已观测到的 SYN 速率；将 SYN 主查询及各子查询的截断状态完整传播至 warnings 与 coverage。
  • 明文凭据提取移除 len > 20 长度限制，准确提取常见弱口令（admin、123456 等），自动对口令脱敏，并提供包号/流序号锚点。
  • DNS 隧道检测仅过滤查询流量（dns.flags.response == 0），移除未经校准的“HIGH probability”主观论断，改用可度量的候选特征、信息熵与查询速率。
  • DoS 攻击检测基于匹配候选数据包的最早与最晚时间跨度计算时间归一化包速率（pps，窗口下限 1.0s），提示亚秒级微突发局限，并针对单向流量抓包给出明确偏差警示。
  • 端口扫描检测记录代表性采样帧号与扫描范围约束。
• 聚合分析在去重值逐项插入时严格执行上限校验，并对字面量字符串字段（http.user_agent、文件名等）做逗号防拆分保护。
• 包和服务元数据升级为 3.0.0；MCP SDK 范围为 mcp>=2.1.1,<3。
• full、analysis、core 分别暴露 52、40、32 个工具；精简 profile 现在会移除对象导出和 YARA 导出。
• 聚合长扫描达到服务端上限时提前停止，不再无界缓存。
• 全量聚合通过有界累加器直接逐行消费 tshark 字段输出，不构造完整 TSV 或数据包行列表，不进入原始输出缓存，并分别执行一百万行与 50 MiB 流式上限。
• 流式字段子进程在行数/字节超限、超时、取消或消费异常时都会被终止并回收，同时并发排空 stderr。
• 成功响应在标准化后保留截断状态和 stderr 元数据。

修复

• 去重基数会展开字段的多次 occurrence。
• 时间桶会拒绝非有限或过小的桶宽，并安全跳过异常时间戳。
• 普通字段中的 [Showing 不再被误判为截断标记。
• 数据包内容的字符串过滤器现在同时转义反斜杠和引号。
• Windows 下启动 Wireshark 子进程时不再弹出临时控制台窗口。
• Streamable HTTP 验收改用真实的 2026-07-28 无状态逐请求 envelope，覆盖 server/discover、tools/list 与 tools/call，并严格断言服务端公布的版本；不再把新版版本号错误地送入旧版 initialize 握手。

破坏性变更

• 未配置 WIRESHARK_MCP_ALLOWED_DIRS 时，写文件工具不再工作。
• 允许根目录必须已经存在且确为目录；配置后同时约束读取和写入。
• HTTP/SSE 监听非回环地址时，如无 --allow-insecure-http 会启动失败。
• 2.x 中可无界运行的实时抓包或超大输出，现在可能被安全上限拒绝。

迁移方法见 3.0 安全迁移指南。