Skip to content

Commit 3b73c5d

Browse files
bx33661bx33661
committed
update doc
1 parent 4d9442c commit 3b73c5d

1 file changed

Lines changed: 181 additions & 84 deletions

File tree

‎README.md‎

Lines changed: 181 additions & 84 deletions
Original file line numberDiff line numberDiff line change
@@ -1,127 +1,224 @@
1-
# Wireshark MCP
1+
<div align="center">
22

3-
Simple [MCP Server](https://modelcontextprotocol.io/introduction) to allow vibe packet analysis in Wireshark.
3+
<br>
44

5-
[English](README.md) | [中文](README_zh.md)
5+
<img src="Logo.png" width="120" alt="Wireshark MCP">
6+
7+
<h1>Wireshark MCP</h1>
8+
9+
<p><strong>Give your AI assistant a packet analyzer.</strong><br>
10+
Drop a <code>.pcap</code> file, ask questions in plain English — get answers backed by real <code>tshark</code> data.</p>
11+
12+
<p>
13+
<a href="https://github.com/bx33661/Wireshark-MCP/actions/workflows/ci.yml">
14+
<img src="https://github.com/bx33661/Wireshark-MCP/actions/workflows/ci.yml/badge.svg" alt="CI">
15+
</a>
16+
<a href="https://pypi.org/project/wireshark-mcp/">
17+
<img src="https://img.shields.io/pypi/v/wireshark-mcp?label=PyPI&color=0066cc" alt="PyPI">
18+
</a>
19+
<a href="https://pypi.org/project/wireshark-mcp/">
20+
<img src="https://img.shields.io/pypi/pyversions/wireshark-mcp?label=Python" alt="Python">
21+
</a>
22+
<a href="LICENSE">
23+
<img src="https://img.shields.io/badge/License-MIT-green.svg" alt="MIT License">
24+
</a>
25+
</p>
26+
27+
<p>
28+
<a href="README.md">English</a> ·
29+
<a href="README_zh.md">中文</a> ·
30+
<a href="CHANGELOG.md">Changelog</a> ·
31+
<a href="CONTRIBUTING.md">Contributing</a>
32+
</p>
33+
34+
<br>
35+
36+
</div>
37+
38+
---
39+
40+
## What is this?
41+
42+
Wireshark MCP is an [MCP Server](https://modelcontextprotocol.io/introduction) that wraps `tshark` into structured tools, letting AI assistants like Claude or Cursor perform deep packet analysis without you touching the command line.
43+
44+
```
45+
You: "Find all DNS queries going to suspicious domains in this capture."
46+
Claude: [calls wireshark_extract_dns_queries → wireshark_check_threats]
47+
"Found 3 queries to domains flagged by URLhaus: ..."
48+
```
49+
50+
---
651

752
## Prerequisites
853

9-
- [Python](https://www.python.org/downloads/) (**3.10 or higher**)
10-
- [Wireshark](https://www.wireshark.org/) (ensure `tshark` is in your PATH)
11-
- Supported MCP Client (pick one you like)
12-
- [Claude Code](https://www.anthropic.com/code)
13-
- [Claude](https://claude.ai/download)
14-
- [Cursor](https://cursor.com)
15-
- [VS Code](https://code.visualstudio.com/) with generic MCP client extension
16-
- [Other MCP Clients](https://modelcontextprotocol.io/clients#example-clients)
54+
- **Python 3.10+**
55+
- **Wireshark** installed with `tshark` available in your PATH
56+
- Any [MCP-compatible client](https://modelcontextprotocol.io/clients): Claude Desktop, Claude Code, Cursor, VS Code, etc.
1757

18-
## Installation
58+
---
1959

20-
Install the latest version of the Wireshark MCP package:
60+
## Installation
2161

2262
```sh
2363
pip install wireshark-mcp
2464
```
2565

26-
Or install directly from source:
66+
<details>
67+
<summary>Install from source</summary>
2768

2869
```sh
2970
pip install git+https://github.com/bx33661/Wireshark-MCP.git
3071
```
3172

73+
</details>
74+
75+
---
76+
3277
## Configuration
3378

34-
Add the server to your MCP client configuration (e.g., `claude_desktop_config.json`):
79+
Add to your MCP client config (e.g. `claude_desktop_config.json`):
3580

3681
```json
3782
{
3883
"mcpServers": {
3984
"wireshark": {
4085
"command": "uv",
41-
"args": [
42-
"tool",
43-
"run",
44-
"wireshark-mcp"
45-
]
86+
"args": ["tool", "run", "wireshark-mcp"]
4687
}
4788
}
4889
}
4990
```
5091

51-
_Note_: You can also run it directly with `python -m wireshark_mcp` if installed in your environment.
92+
> You can also run directly with `python -m wireshark_mcp`.
5293
53-
## Prompt Engineering
94+
---
5495

55-
LLMs are good at general analysis but can struggle with the specifics of packet dissection. Below is a minimal example prompt strategy:
96+
## Quick Start
97+
98+
Paste this into your AI client after pointing it at a pcap file:
99+
100+
```
101+
Analyze <path/to/file.pcap> using the Wireshark MCP tools.
56102
57-
```md
58-
Your task is to analyze a pcap file using Wireshark MCP tools.
59-
- Start by getting a packet list summary to understand the traffic flow (`wireshark_get_packet_list`).
60-
- If you see interesting packets, get full details for that specific frame (`wireshark_get_packet_details`).
61-
- For TCP/HTTP flows, use `wireshark_follow_stream` to see the full conversation.
62-
- Use `wireshark_extract_http_requests` or `wireshark_extract_dns_queries` for quick high-level overviews.
63-
- NEVER try to guess packet contents; always verify with the tools.
64-
- Create a report.md with your findings.
103+
- Start with wireshark_get_packet_list to map the traffic.
104+
- Drill into interesting frames with wireshark_get_packet_details.
105+
- For TCP/HTTP sessions, use wireshark_follow_stream.
106+
- Never guess — always verify with tools.
107+
- Write findings to report.md.
65108
```
66109

67-
## Available Tools
68-
69-
### Packet Analysis (extract.py)
70-
- `wireshark_get_packet_list(pcap_file, limit=20, offset=0, display_filter="", custom_columns="")`:
71-
Get summary list of packets. Supports custom columns (e.g., "ip.src,http.host") to replace default view.
72-
- `wireshark_get_packet_details(pcap_file, frame_number, layers="")`:
73-
Get full JSON details for a single packet. Supports layer filtering (e.g., "ip,tcp,http") to significantly reduce token usage.
74-
- `wireshark_get_packet_bytes(pcap_file, frame_number)`:
75-
**[New]** Get raw Hex/ASCII dump (Packet Bytes view).
76-
- `wireshark_get_packet_context(pcap_file, frame_number, count=5)`:
77-
**[New]** View packets surrounding a specific frame (before and after) to understand context.
78-
- `wireshark_follow_stream(...)`: Reassemble and view complete stream content with pagination and search.
79-
- `wireshark_search_packets(pcap_file, match_pattern, search_type="string", limit=50, scope="bytes")`:
80-
**[Enhanced]** Find packets.
81-
* `scope="bytes"`: Search in raw payload (Hex/String).
82-
* `scope="details"`: Search in decoded text/fields (Regex supported).
83-
- `wireshark_read_packets(...)`: [DEPRECATED] Use `get_packet_details` instead.
84-
85-
### Data Extraction (extract.py)
86-
- `wireshark_extract_fields(pcap_file, fields, display_filter="", limit=100, offset=0)`: Extract specific fields as tabular data.
87-
- `wireshark_extract_http_requests(pcap_file, limit=100)`: Convenience tool for HTTP method, URI, host.
88-
- `wireshark_extract_dns_queries(pcap_file, limit=100)`: Convenience tool for DNS queries.
89-
- `wireshark_list_ips(pcap_file, type="both")`: List all unique IP addresses (src, dst, or both).
90-
- `wireshark_export_objects(pcap_file, protocol, dest_dir)`: Extract embedded files (http, smb, etc.) from traffic.
91-
- `wireshark_verify_ssl_decryption(pcap_file, keylog_file)`: Verify TLS decryption using a keylog file.
92-
93-
### Statistics (stats.py)
94-
- `wireshark_stats_protocol_hierarchy(pcap_file)`: Get Protocol Hierarchy Statistics (PHS).
95-
- `wireshark_stats_endpoints(pcap_file, type="ip")`: List all endpoints and their traffic stats.
96-
- `wireshark_stats_conversations(pcap_file, type="ip")`: Show communication pairs and their stats.
97-
- `wireshark_stats_io_graph(pcap_file, interval=1)`: Get traffic volume over time (I/O Graph).
98-
- `wireshark_stats_expert_info(pcap_file)`: Get Expert Information (anomalies, warnings).
99-
- `wireshark_stats_service_response_time(pcap_file, protocol="http")`: Service Response Time (SRT) statistics.
100-
101-
### File Operations (files.py & capture.py)
102-
- `wireshark_get_file_info(pcap_file)`: Get detailed metadata about a capture file (capinfos).
103-
- `wireshark_merge_pcaps(output_file, input_files)`: Merge multiple capture files into one.
104-
- `wireshark_list_interfaces()`: List available network interfaces for capture.
105-
- `wireshark_capture(interface, output_file, duration_seconds=10, packet_count=0, capture_filter="", ring_buffer="")`: Capture live network traffic.
106-
- `wireshark_filter_save(input_file, output_file, display_filter)`: Filter packets from a pcap and save to a new file.
107-
108-
### Security (security.py)
109-
- `wireshark_check_threats(pcap_file)`: Check captured IPs against URLhaus threat intelligence.
110-
- `wireshark_extract_credentials(pcap_file)`: Scan for plaintext credentials (HTTP Auth, FTP, Telnet).
111-
112-
### Decoding (decode.py)
113-
- `wireshark_decode_payload(data, encoding="auto")`: Decode common encodings (Base64, Hex, URL, Gzip, Deflate, Rot13, etc.) with smart auto-detection.
114-
115-
### Visualization (visualize.py)
116-
- `wireshark_plot_traffic(pcap_file, interval=1)`: Generate ASCII bar chart of traffic volume over time.
117-
- `wireshark_plot_protocols(pcap_file)`: Generate ASCII tree view of protocol hierarchy.
110+
---
111+
112+
## Tools
113+
114+
<details>
115+
<summary><b>Packet Analysis</b> — inspect, navigate, and search packets</summary>
116+
117+
<br>
118+
119+
| Tool | Description |
120+
|---|---|
121+
| `wireshark_get_packet_list` | Paginated packet list with display filter and custom column support |
122+
| `wireshark_get_packet_details` | Full JSON dissection of a single frame, with optional layer filtering to cut token usage |
123+
| `wireshark_get_packet_bytes` | Raw Hex + ASCII dump (Wireshark's "Packet Bytes" pane) |
124+
| `wireshark_get_packet_context` | View N packets before and after a frame for contextual debugging |
125+
| `wireshark_follow_stream` | Reassemble a full TCP / UDP / HTTP stream with pagination and search |
126+
| `wireshark_search_packets` | Pattern search across raw bytes or decoded fields (Regex supported) |
127+
128+
</details>
129+
130+
<details>
131+
<summary><b>Data Extraction</b> — pull structured data from captures</summary>
132+
133+
<br>
134+
135+
| Tool | Description |
136+
|---|---|
137+
| `wireshark_extract_fields` | Extract any tshark fields as a table |
138+
| `wireshark_extract_http_requests` | HTTP method, URI, and host for every request |
139+
| `wireshark_extract_dns_queries` | All DNS queries in the capture |
140+
| `wireshark_list_ips` | All unique source, destination, or both IP addresses |
141+
| `wireshark_export_objects` | Extract embedded files (HTTP, SMB, TFTP, etc.) |
142+
| `wireshark_verify_ssl_decryption` | Confirm TLS decryption using a keylog file |
143+
144+
</details>
145+
146+
<details>
147+
<summary><b>Statistics</b> — traffic patterns and anomaly detection</summary>
148+
149+
<br>
150+
151+
| Tool | Description |
152+
|---|---|
153+
| `wireshark_stats_protocol_hierarchy` | Protocol Hierarchy Statistics — see what protocols dominate |
154+
| `wireshark_stats_endpoints` | All endpoints sorted by traffic volume |
155+
| `wireshark_stats_conversations` | Communication pairs with byte/packet counts |
156+
| `wireshark_stats_io_graph` | Traffic volume over time (spot DDoS, scans, bursts) |
157+
| `wireshark_stats_expert_info` | Wireshark's expert analysis: errors, warnings, notes |
158+
| `wireshark_stats_service_response_time` | SRT stats for HTTP, DNS, and other protocols |
159+
160+
</details>
161+
162+
<details>
163+
<summary><b>File Operations & Live Capture</b></summary>
164+
165+
<br>
166+
167+
| Tool | Description |
168+
|---|---|
169+
| `wireshark_get_file_info` | File metadata via `capinfos` (duration, packet count, link type) |
170+
| `wireshark_merge_pcaps` | Merge multiple captures into one file |
171+
| `wireshark_filter_save` | Apply a display filter and save matching packets to a new file |
172+
| `wireshark_list_interfaces` | List available network interfaces |
173+
| `wireshark_capture` | Start a live capture (duration, packet count, BPF filter, ring buffer) |
174+
175+
</details>
176+
177+
<details>
178+
<summary><b>Security Analysis</b></summary>
179+
180+
<br>
181+
182+
| Tool | Description |
183+
|---|---|
184+
| `wireshark_check_threats` | Cross-reference captured IPs against [URLhaus](https://urlhaus.abuse.ch/) threat intelligence |
185+
| `wireshark_extract_credentials` | Detect plaintext credentials in HTTP Basic Auth, FTP, and Telnet |
186+
187+
</details>
188+
189+
<details>
190+
<summary><b>Decoding & Visualization</b></summary>
191+
192+
<br>
193+
194+
| Tool | Description |
195+
|---|---|
196+
| `wireshark_decode_payload` | Auto-detect and decode Base64, Hex, URL encoding, Gzip, Deflate, Rot13, and more |
197+
| `wireshark_plot_traffic` | ASCII bar chart of traffic over time — spot DDoS or scan patterns instantly |
198+
| `wireshark_plot_protocols` | ASCII protocol tree — visual overview of what's in the capture |
199+
200+
</details>
201+
202+
---
118203

119204
## Development
120205

121-
To test the MCP server itself:
206+
**Test with the MCP Inspector** (opens a local web UI to call tools interactively):
122207

123208
```sh
124209
npx -y @modelcontextprotocol/inspector uv run wireshark-mcp
125210
```
126211

127-
This will open a web interface where you can interact with the tools directly.
212+
**Run the test suite:**
213+
214+
```sh
215+
pytest tests/
216+
```
217+
218+
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development setup guide.
219+
220+
---
221+
222+
<div align="center">
223+
<sub><a href="LICENSE">MIT License</a> · <a href="https://github.com/bx33661/Wireshark-MCP/issues">Report a Bug</a></sub>
224+
</div>

0 commit comments

Comments
 (0)