# 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