feat: Introduce a tool registry and agent system, and refine existing threat detection tools.

Author: bx33661

CHANGELOG.md

@@ -7,6 +7,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.6.0] - 2025-06-27
+
+### Added
+
+#### 🚀 Agentic Workflows — Server-side Orchestrated Analysis
+- `wireshark_security_audit`: One-call comprehensive security audit (8 analysis phases, risk scoring 0-100, structured report with findings and recommendations)
+- `wireshark_quick_analysis`: One-call traffic overview (file info, protocol distribution, top talkers, conversations, hostnames, anomaly summary)
+
+#### 🔍 Progressive Discovery — Dynamic Tool Registration
+- `wireshark_open_file`: New entry-point tool that analyzes pcap content and dynamically activates protocol-specific tools
+- `ToolRegistry` system: Server starts with ~17 core tools; protocol-specific tools activate on demand when matching protocols are detected
+- `PROTOCOL_TOOL_MAP`: Configurable mapping from protocols (HTTP, DNS, TLS, etc.) to relevant tool sets
+
+### Changed
+- Security tools (`wireshark_check_threats`, `wireshark_extract_credentials`) are now contextual — activated via `wireshark_open_file`
+- Protocol tools (`wireshark_extract_tls_handshakes`, `wireshark_analyze_tcp_health`, `wireshark_detect_arp_spoofing`, `wireshark_extract_smtp_emails`, `wireshark_extract_dhcp_info`) are now contextual
+- Threat detection tools (`wireshark_detect_port_scan`, `wireshark_detect_dns_tunnel`, `wireshark_detect_dos_attack`, `wireshark_analyze_suspicious_traffic`) are now contextual
+- Extract tools (`wireshark_extract_http_requests`, `wireshark_extract_dns_queries`, `wireshark_export_objects`, `wireshark_verify_ssl_decryption`) are now contextual
+
 ## [0.4.0] - 2025-06-01
 
 ### Added
@@ -37,6 +56,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Decoding: `wireshark_decode_payload` with auto-detection (Base64, Hex, URL, Gzip, Deflate, Rot13)
 - Visualization: ASCII traffic plot, ASCII protocol hierarchy tree
 
-[Unreleased]: https://github.com/bx33661/Wireshark-MCP/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/bx33661/Wireshark-MCP/compare/v0.6.0...HEAD
+[0.6.0]: https://github.com/bx33661/Wireshark-MCP/compare/v0.4.0...v0.6.0
 [0.4.0]: https://github.com/bx33661/Wireshark-MCP/compare/v0.2.1...v0.4.0
 [0.2.1]: https://github.com/bx33661/Wireshark-MCP/releases/tag/v0.2.1

README.md

@@ -180,9 +180,10 @@ Paste this into your AI client after pointing it at a pcap file:
 ```
 Analyze <path/to/file.pcap> using the Wireshark MCP tools.
 
-- Start with wireshark_get_packet_list to map the traffic.
-- Drill into interesting frames with wireshark_get_packet_details.
-- For TCP/HTTP sessions, use wireshark_follow_stream.
+- Start with wireshark_open_file to load the file and activate relevant tools.
+- Use wireshark_security_audit for a one-call security analysis.
+- Or use wireshark_quick_analysis for a fast traffic overview.
+- Drill into details with wireshark_follow_stream or wireshark_get_packet_details.
 - Never guess — always verify with tools.
 - Write findings to report.md.
 ```
@@ -191,6 +192,21 @@ Analyze <path/to/file.pcap> using the Wireshark MCP tools.
 
 ## Tools
 
+<details>
+<summary><b>⚡ Agentic Workflows</b> — one-call comprehensive analysis (NEW in v0.6)</summary>
+
+<br>
+
+| Tool | Description |
+|---|---|
+| `wireshark_security_audit` | **One-call security audit**: 8-phase analysis (threat intel, credential scan, port scan, DNS tunnel, cleartext, anomalies) with risk scoring (0-100) and recommendations |
+| `wireshark_quick_analysis` | **One-call traffic overview**: file info, protocol distribution, top talkers, conversations, hostnames, anomaly summary, suggested next steps |
+| `wireshark_open_file` | **Smart file opener**: analyzes pcap content and dynamically activates protocol-specific tools (Progressive Discovery) |
+
+> 💡 These tools replace the need to manually chain 5-10 tool calls. Just call one and get a complete report.
+
+</details>
+
 <details>
 <summary><b>Packet Analysis</b> — inspect, navigate, and search packets</summary>
 
@@ -298,6 +314,8 @@ Analyze <path/to/file.pcap> using the Wireshark MCP tools.
 
 </details>
 
+> **Note**: Security, Protocol, and Threat tools are *contextual* — they activate automatically when you call `wireshark_open_file`. The Agentic tools (`security_audit`, `quick_analysis`) are always available.
+
 ---
 
 ## MCP Resources

README_zh.md

@@ -180,9 +180,10 @@ args = ["tool", "run", "wireshark-mcp"]
 ```
 使用 Wireshark MCP 工具分析 <path/to/file.pcap>。
 
-- 先用 wireshark_get_packet_list 获取流量概览
-- 对感兴趣的帧使用 wireshark_get_packet_details 查看详情
-- 对于 TCP/HTTP 会话，使用 wireshark_follow_stream 查看完整对话
+- 先用 wireshark_open_file 加载文件并激活相关工具
+- 使用 wireshark_security_audit 一键安全审计
+- 或用 wireshark_quick_analysis 快速了解流量概况
+- 需要细节时使用 wireshark_follow_stream 或 wireshark_get_packet_details
 - 不要猜测 — 始终用工具验证
 - 将分析结果写入 report.md
 ```
@@ -191,6 +192,21 @@ args = ["tool", "run", "wireshark-mcp"]
 
 ## 工具集
 
+<details>
+<summary><b>⚡ Agentic Workflows</b> — 一键综合分析（v0.6 新增）</summary>
+
+<br>
+
+| 工具 | 描述 |
+|---|---|
+| `wireshark_security_audit` | **一键安全审计**：8 阶段分析（威胁情报、凭证扫描、端口扫描、DNS 隧道、明文协议、异常检测），输出风险评分（0-100）和修复建议 |
+| `wireshark_quick_analysis` | **一键流量概览**：文件信息、协议分布、Top Talkers、会话统计、域名/主机名、异常摘要、下一步建议 |
+| `wireshark_open_file` | **智能打开文件**：分析 pcap 内容并自动激活协议相关工具（Progressive Discovery）|
+
+> 💡 这些工具替代了手动串联 5-10 次 tool call。只需一次调用即可获得完整报告。
+
+</details>
+
 <details>
 <summary><b>数据包分析</b> — 检查、浏览、搜索数据包</summary>
 
@@ -298,6 +314,8 @@ args = ["tool", "run", "wireshark-mcp"]
 
 </details>
 
+> **注意**：安全分析、协议分析、威胁检测工具为*上下文工具* — 调用 `wireshark_open_file` 后自动激活。Agentic 工具（`security_audit`、`quick_analysis`）始终可用。
+
 ---
 
 ## MCP Resources

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "wireshark-mcp"
-version = "0.5.0"
+version = "0.6.0"
 description = "A production-grade Model Context Protocol (MCP) server for Wireshark"
 readme = "README.md"
 keywords = ["mcp", "wireshark", "tshark", "packet-analysis", "network", "pcap", "model-context-protocol", "llm", "security"]

src/wireshark_mcp/__init__.py

@@ -1,4 +1,4 @@
 """
 Wireshark MCP - A Model Context Protocol server for Wireshark.
 """
-__version__ = "0.5.0"
+__version__ = "0.6.0"

src/wireshark_mcp/server.py

@@ -13,36 +13,41 @@
 from .tools.decode import register_decode_tools
 from .tools.extract import register_extract_tools
 from .tools.files import register_files_tools
-from .tools.protocol import register_protocol_tools
-from .tools.security import register_security_tools
+from .tools.agents import register_agent_tools
+from .tools.registry import ToolRegistry, register_open_file_tool
 from .tools.stats import register_stats_tools
-from .tools.threat import register_threat_tools
 from .tools.visualize import register_visualize_tools
 
 logger = logging.getLogger("wireshark_mcp")
 
 
 def _build_server() -> FastMCP:
-    """Build and configure the MCP server with all tools registered."""
+    """Build and configure the MCP server with progressive discovery."""
     # Read allowed directories from environment
     allowed_dirs_env = os.environ.get("WIRESHARK_MCP_ALLOWED_DIRS", "")
     allowed_dirs = [d.strip() for d in allowed_dirs_env.split(",") if d.strip()] or None
 
     mcp = FastMCP("Wireshark MCP", dependencies=["tshark"])
     client = TSharkClient(allowed_dirs=allowed_dirs)
 
-    # Register all tool modules
+    # ── Core tools (always registered) ──────────────────────────────────
     register_capture_tools(mcp, client)
     register_stats_tools(mcp, client)
     register_extract_tools(mcp, client)
     register_files_tools(mcp, client)
-    register_security_tools(mcp, client)
     register_decode_tools(mcp)
     register_visualize_tools(mcp, client)
-    register_protocol_tools(mcp, client)
-    register_threat_tools(mcp, client)
+    register_agent_tools(mcp, client)
 
-    # Register Resources and Prompts
+    # ── Progressive Discovery ───────────────────────────────────────────
+    # Build the contextual tool catalog (not registered yet)
+    registry = ToolRegistry(mcp, client)
+    registry.build_catalog()
+
+    # Register the entry-point tool that activates contextual tools
+    register_open_file_tool(mcp, client, registry)
+
+    # ── Resources and Prompts ───────────────────────────────────────────
     register_resources(mcp)
     register_prompts(mcp)
 
@@ -97,3 +102,4 @@ def main() -> None:
 
 if __name__ == "__main__":
     main()
+