# Wireshark MCP Server Container
A containerized [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that provides comprehensive network packet analysis using Wireshark/tshark. Connect it to any MCP-compatible AI client for automated network security analysis, protocol inspection, and traffic forensics.
## How It Works: GitHub-Based PCAP Sync
**This container does not store PCAP files.** Instead, it uses a GitHub repository as the source of truth for your packet captures.
```
┌──────────────┐ ┌─────────────────────────┐ ┌──────────────────┐
│ Your GitHub │ │ Wireshark MCP Container │ │ AI Client │
│ Repository │◄─────►│ │◄─────►│ (Cursor, etc.) │
│ │ sync │ tshark analysis engine │ MCP │ │
│ pcaps/ │ │ /tmp/wireshark_workspace │ │ │
└──────────────┘ └─────────────────────────┘ └──────────────────┘
```
The workflow:
1. **Store PCAPs in GitHub** -- Push `.pcap` / `.pcapng` files to any GitHub repo (public or private).
2. **Configure credentials** -- Provide your GitHub username, PAT, repo URL, and optional path/branch via environment variables or HTTP headers.
3. **Sync on demand** -- Use `wireshark_list_pcaps` to see what's available, then `wireshark_sync_pcap` or `wireshark_sync_all_pcaps` to pull files into the container's temporary workspace.
4. **Analyze** -- Run any of the 19 analysis tools against synced PCAPs.
5. **Clean up** -- Use `wireshark_clean_project` or let the automatic TTL (default 24h) purge stale workspaces.
This design means the container stays stateless and ephemeral -- PCAP data lives in your GitHub repo, and the container only pulls what it needs for the current analysis session.
## Quick Start
### Pull from GHCR
```bash
docker pull ghcr.io/<your-org>/wireshark-mcp-container:latest
```
### Run with Docker
```bash
docker run -d \
-p 3020:3020 \
-e DISABLE_JWT_AUTH=true \
-e GITHUB_USERNAME=your-github-username \
-e GITHUB_PAT=ghp_xxxxxxxxxxxxxxxxxxxx \
-e GITHUB_REPO=https://github.com/your-org/your-pcap-repo \
-e GITHUB_PATH=pcaps \
-e GITHUB_BRANCH=main \
--name wireshark-mcp \
ghcr.io/<your-org>/wireshark-mcp-container:latest
```
### Build Locally
```bash
docker build -t wireshark-mcp:latest -f dockerfile .
docker run -d \
-p 3020:3020 \
--env-file .env \
--name wireshark-mcp \
wireshark-mcp:latest
```
## Configuration
All configuration is done through environment variables. See [`.env.example`](.env.example) for a complete reference.
### Required
| Variable | Description |
|---|---|
| `GITHUB_USERNAME` | Your GitHub username |
| `GITHUB_PAT` | GitHub Personal Access Token (needs `repo` scope for private repos) |
| `GITHUB_REPO` | Full GitHub repo URL (e.g., `https://github.com/org/pcap-repo`) |
### Optional
| Variable | Default | Description |
|---|---|---|
| `GITHUB_PATH` | _(root)_ | Subdirectory in the repo where PCAPs are stored |
| `GITHUB_BRANCH` | `main` | Branch to sync from |
| `PORT` | `3020` | Server port |
| `HOST` | `0.0.0.0` | Bind address |
| `TRANSPORT` | `streamable-http` | MCP transport (`streamable-http` or `stdio`) |
| `DISABLE_JWT_AUTH` | `true` | Set to `false` to enable Azure AD JWT authentication |
| `AZURE_AD_TENANT_ID` | | Required when JWT auth is enabled |
| `AZURE_AD_CLIENT_ID` | | Optional audience validation when JWT auth is enabled |
| `ENABLE_AUTH_LOGGING` | `false` | Log user access to tools |
| `WIRESHARK_PROJECT_TTL` | `86400` | Seconds before stale project workspaces are auto-purged |
### Passing Credentials via HTTP Headers
Instead of environment variables, credentials can be passed per-request via HTTP headers. This is useful when multiple users share a single server instance:
| Header | Maps to |
|---|---|
| `X-GitHub-Username` | `GITHUB_USERNAME` |
| `X-GitHub-PAT` | `GITHUB_PAT` |
| `X-GitHub-Repo` | `GITHUB_REPO` |
| `X-GitHub-Path` | `GITHUB_PATH` |
| `X-GitHub-Branch` | `GITHUB_BRANCH` |
Headers take precedence over environment variables.
## MCP Tools
### PCAP Management
| Tool | Description |
|---|---|
| `wireshark_list_pcaps` | List synced and available PCAPs (local + GitHub) |
| `wireshark_sync_pcap` | Download a single PCAP from GitHub |
| `wireshark_sync_all_pcaps` | Download all PCAPs from GitHub (skips already-synced) |
| `wireshark_remove_pcap` | Remove a local PCAP copy |
| `wireshark_clean_project` | Remove entire project workspace |
### Analysis
| Tool | Description |
|---|---|
| `wireshark_pcap_triage` | Automated first-pass triage (start here) |
| `wireshark_analyze_pcap` | Comprehensive packet analysis |
| `wireshark_protocol_hierarchy` | Protocol distribution breakdown |
| `wireshark_conversations` | TCP/UDP/IP conversation statistics |
| `wireshark_display_filter` | Apply Wireshark display filters |
| `wireshark_follow_stream` | Reconstruct TCP/UDP stream payloads |
| `wireshark_top_talkers` | Identify highest-volume traffic sources |
### Protocol Deep-Dives
| Tool | Description |
|---|---|
| `wireshark_tcp_health` | TCP retransmissions, dup ACKs, health scoring |
| `wireshark_dns_analysis` | DNS queries, NXDOMAIN, tunneling detection |
| `wireshark_http_summary` | HTTP methods, status codes, response times |
| `wireshark_tls_analysis` | TLS versions, ciphers, certificate info |
### Security
| Tool | Description |
|---|---|
| `wireshark_extract_credentials` | Extract plaintext credentials from traffic |
| `wireshark_check_threats` | Check PCAP IPs against threat intelligence |
| `wireshark_check_ip_threat` | Check a single IP against threat feeds |
## Typical Analysis Workflow
```
1. wireshark_list_pcaps → See what's in your GitHub repo
2. wireshark_sync_pcap → Pull a capture file into the container
3. wireshark_pcap_triage → Get an overview and recommendations
4. wireshark_tcp_health → Drill into TCP issues (if flagged)
5. wireshark_display_filter → Filter to specific traffic patterns
6. wireshark_follow_stream → Reconstruct an application conversation
7. wireshark_check_threats → Check IPs against threat intelligence
8. wireshark_clean_project → Clean up when done
```
## GitHub Repository Setup for PCAPs
1. Create a GitHub repository (private recommended for sensitive captures).
2. Create a directory for your PCAP files (e.g., `pcaps/`).
3. Push your `.pcap` or `.pcapng` files to that directory.
4. Create a [Personal Access Token](https://github.com/settings/tokens) with `repo` scope (for private repos) or `public_repo` scope (for public repos).
5. Configure the container with your repo URL, path, and token.
```bash
# Example repo structure
your-pcap-repo/
├── pcaps/
│ ├── incident-2025-01-15.pcap
│ ├── baseline-traffic.pcapng
│ └── suspicious-dns.pcap
└── README.md
```
## Local Development
### Prerequisites
- Python 3.11+
- tshark / Wireshark installed
- pip
### Setup
```bash
pip install -r requirements.txt
# Copy and configure environment
cp .env.example .env
# Edit .env with your GitHub credentials
# Run the server
python server.py
```
### Install tshark
**macOS:**
```bash
brew install wireshark
```
**Ubuntu/Debian:**
```bash
sudo apt-get install tshark
```
## License
ISC
