npm package: @modular-intelligence/wireshark
Description: MCP server wrapping tshark for network protocol analysis of PCAP files
Latest version: 1.0.2

# Wireshark/Tshark MCP Server

A comprehensive network protocol analysis service that integrates tshark (Wireshark's command-line tool) through the Model Context Protocol. This MCP server enables Claude to perform deep packet inspection, protocol analysis, stream reconstruction, and forensic analysis of network capture (PCAP) files.

## Overview

This server provides powerful offline network traffic analysis capabilities through tshark:

- **Packet Analysis** - Deep inspection of network packets with protocol dissection
- **Statistics Generation** - I/O stats, conversations, endpoints, protocol hierarchies
- **Field Extraction** - Custom extraction of specific protocol fields
- **Stream Following** - Reconstruct TCP/UDP/TLS/HTTP conversations
- **Expert Analysis** - Automated detection of protocol anomalies and issues
- **DNS Analysis** - Extract and analyze DNS queries and responses

Perfect for network forensics, security incident response, protocol debugging, traffic analysis, and network troubleshooting.

**IMPORTANT**: This server performs **offline analysis only**. Live network capture is explicitly blocked for security reasons.

## Tools

| Tool | Description |
|------|-------------|
| `tshark_analyze` | Analyze PCAP file and extract packet details in JSON format |
| `tshark_statistics` | Generate various statistics (I/O, conversations, endpoints, protocols, HTTP, DNS, expert info) |
| `tshark_extract_fields` | Extract specific protocol fields in tab-separated format |
| `tshark_follow_stream` | Follow and reconstruct TCP/UDP/TLS/HTTP streams |
| `tshark_expert_info` | Extract expert information and protocol anomalies |
| `tshark_file_info` | Get detailed PCAP file information and metadata |
| `tshark_dns_extract` | Extract DNS queries and responses with type filtering |

### Tshark Analyze

Analyze PCAP files and extract detailed packet information in structured JSON format.

**Input Parameters:**
```typescript
{
  pcap_path: string       // Absolute path to PCAP/PCAPNG file
  display_filter: string  // Wireshark display filter (optional)
  max_packets: number     // Maximum packets to process (1-100000, default: 10000)
  decode_as: string       // Protocol decode override (optional, e.g., "tcp.port==8080,http")
  timeout: number         // Analysis timeout in seconds (10-600, default: 120)
}
```

**Example Request:**
```json
{
  "pcap_path": "/tmp/capture.pcap",
  "display_filter": "tcp.port == 443",
  "max_packets": 1000,
  "timeout": 120
}
```

**Example Output:**
```json
{
  "file": "/tmp/capture.pcap",
  "packets_analyzed": 156,
  "results": [
    {
      "frame_number": 1,
      "timestamp": "2024-01-15 10:30:45.123456",
      "source": "192.168.1.100",
      "destination": "93.184.216.34",
      "protocol": "tls",
      "length": 74,
      "info": ""
    },
    {
      "frame_number": 2,
      "timestamp": "2024-01-15 10:30:45.234567",
      "source": "93.184.216.34",
      "destination": "192.168.1.100",
      "protocol": "tls",
      "length": 1434,
      "info": ""
    }
  ],
  "summary": "Analyzed 156 packets from /tmp/capture.pcap with filter: tcp.port == 443"
}
```

**Common Display Filters:**
- `tcp.port == 80` - HTTP traffic
- `dns` - All DNS traffic
- `http.request` - HTTP requests only
- `ip.addr == 192.168.1.1` - Traffic to/from specific IP
- `tcp.flags.syn == 1` - TCP SYN packets
- `!(arp or icmp)` - Exclude ARP and ICMP

### Tshark Statistics

Generate various types of statistics from PCAP files.

**Input Parameters:**
```typescript
{
  pcap_path: string          // Absolute path to PCAP/PCAPNG file
  stat_type: string          // "io", "conv", "endpoints", "protocols", "http", "dns", or "expert"
  display_filter: string     // Wireshark display filter (optional)
  timeout: number            // Analysis timeout in seconds (10-600, default: 120)
}
```

**Statistic Types:**
- `io` - I/O statistics (packets/bytes over time)
- `conv` - TCP conversations between endpoints
- `endpoints` - IP endpoint statistics
- `protocols` - Protocol hierarchy
- `http` - HTTP-specific statistics
- `dns` - DNS-specific statistics
- `expert` - Expert information summary

**Example Request:**
```json
{
  "pcap_path": "/tmp/capture.pcap",
  "stat_type": "conv",
  "timeout": 120
}
```

**Example Output:**
```json
{
  "stat_type": "conv",
  "data": {
    "conversations": [
      {
        "line": "192.168.1.100:54321 <-> 93.184.216.34:443  1234 packets  987654 bytes"
      }
    ],
    "total": 1
  },
  "summary": "TCP conversations found: 1"
}
```

### Tshark Extract Fields

Extract specific protocol fields from packets for custom analysis.

**Input Parameters:**
```typescript
{
  pcap_path: string          // Absolute path to PCAP/PCAPNG file
  fields: string[]           // Protocol fields to extract (1-20 fields)
  display_filter: string     // Wireshark display filter (optional)
  max_packets: number        // Maximum packets to process (1-100000, default: 10000)
  timeout: number            // Analysis timeout in seconds (10-600, default: 120)
}
```

**Common Fields:**
- `ip.src`, `ip.dst` - Source and destination IP addresses
- `tcp.srcport`, `tcp.dstport` - TCP ports
- `http.host`, `http.request.uri` - HTTP host and URI
- `dns.qry.name`, `dns.resp.name` - DNS query/response names
- `frame.time`, `frame.len` - Frame timestamp and length
- `tcp.flags`, `tcp.seq` - TCP flags and sequence numbers

**Example Request:**
```json
{
  "pcap_path": "/tmp/capture.pcap",
  "fields": ["ip.src", "ip.dst", "tcp.srcport", "tcp.dstport"],
  "display_filter": "tcp",
  "max_packets": 5000
}
```

**Example Output:**
```json
{
  "fields": ["ip.src", "ip.dst", "tcp.srcport", "tcp.dstport"],
  "rows": [
    ["192.168.1.100", "93.184.216.34", "54321", "443"],
    ["93.184.216.34", "192.168.1.100", "443", "54321"],
    ["192.168.1.100", "1.1.1.1", "54322", "53"]
  ],
  "total_rows": 3
}
```

### Tshark Follow Stream

Follow and reconstruct complete network streams (TCP/UDP/TLS/HTTP).

**Input Parameters:**
```typescript
{
  pcap_path: string       // Absolute path to PCAP/PCAPNG file
  protocol: string        // "tcp", "udp", "tls", or "http"
  stream_index: number    // Stream index (0-based)
  timeout: number         // Analysis timeout in seconds (10-600, default: 120)
}
```

**Example Request:**
```json
{
  "pcap_path": "/tmp/capture.pcap",
  "protocol": "tcp",
  "stream_index": 0
}
```

**Example Output:**
```json
{
  "protocol": "tcp",
  "stream_index": 0,
  "content": "GET / HTTP/1.1\r\nHost: example.com\r\n\r\nHTTP/1.1 200 OK\r\n...",
  "client_bytes": 145,
  "server_bytes": 2048
}
```

### Tshark Expert Info

Extract expert information and protocol anomalies detected by Wireshark's analysis engine.

**Input Parameters:**
```typescript
{
  pcap_path: string       // Absolute path to PCAP/PCAPNG file
  severity: string        // "chat", "note", "warn", or "error" (optional, minimum level)
  timeout: number         // Analysis timeout in seconds (10-600, default: 120)
}
```

**Severity Levels:**
- `chat` - Informational messages
- `note` - Notable events
- `warn` - Warnings (potential issues)
- `error` - Errors (definite problems)

**Example Request:**
```json
{
  "pcap_path": "/tmp/capture.pcap",
  "severity": "warn"
}
```

**Example Output:**
```json
{
  "findings": [
    {
      "severity": "warn",
      "group": "sequence",
      "protocol": "tcp",
      "summary": "TCP Retransmission detected",
      "count": 1
    },
    {
      "severity": "error",
      "group": "checksum",
      "protocol": "ip",
      "summary": "IP checksum error",
      "count": 1
    }
  ],
  "total_by_severity": {
    "error": 1,
    "warn": 1,
    "note": 0,
    "chat": 0
  }
}
```

### Tshark File Info

Get comprehensive information about PCAP file metadata and contents.

**Input Parameters:**
```typescript
{
  pcap_path: string       // Absolute path to PCAP/PCAPNG file
}
```

**Example Request:**
```json
{
  "pcap_path": "/tmp/capture.pcap"
}
```

**Example Output:**
```json
{
  "file_path": "/tmp/capture.pcap",
  "file_size": 12345678,
  "capture_duration": "123.456789 seconds",
  "total_packets": 5432,
  "data_bytes": 12000000,
  "avg_packet_size": 2209,
  "first_packet_time": "2024-01-15 10:30:00.000000",
  "last_packet_time": "2024-01-15 10:32:03.456789",
  "protocols_found": ["eth", "ip", "tcp", "http", "tls", "dns"],
  "encapsulation": "Ethernet"
}
```

### Tshark DNS Extract

Extract and analyze DNS queries and responses from network traffic.

**Input Parameters:**
```typescript
{
  pcap_path: string       // Absolute path to PCAP/PCAPNG file
  query_type: string      // "A", "AAAA", "MX", "NS", "TXT", "CNAME", "SOA", "PTR", "SRV", "ANY", "all"
  timeout: number         // Analysis timeout in seconds (10-600, default: 120)
}
```

**Query Types:**
- `A` - IPv4 address records
- `AAAA` - IPv6 address records
- `MX` - Mail exchange records
- `NS` - Nameserver records
- `TXT` - Text records
- `CNAME` - Canonical name records
- `SOA` - Start of authority records
- `PTR` - Pointer records (reverse DNS)
- `SRV` - Service records
- `ANY` - Any record type
- `all` - All DNS queries (default)

**Example Request:**
```json
{
  "pcap_path": "/tmp/capture.pcap",
  "query_type": "A"
}
```

**Example Output:**
```json
{
  "queries": [
    {
      "name": "example.com",
      "type": "A",
      "responses": ["A: 93.184.216.34"]
    },
    {
      "name": "www.example.com",
      "type": "A",
      "responses": ["CNAME: example.com", "A: 93.184.216.34"]
    }
  ],
  "unique_domains": ["example.com", "www.example.com"],
  "total_queries": 2
}
```

## Configuration

### Prerequisites

This server requires tshark (Wireshark command-line tool) to be installed:

**macOS:**
```bash
brew install wireshark
```

**Linux (Debian/Ubuntu):**
```bash
sudo apt-get install tshark
```

**Linux (RHEL/CentOS):**
```bash
sudo yum install wireshark
```

**Verify Installation:**
```bash
which tshark
tshark --version
```

### Binary Location

The server expects tshark at `/opt/homebrew/bin/tshark` (macOS Homebrew default). For other systems, modify `TSHARK_PATH` in `src/cli-executor.ts`:

```typescript
const TSHARK_PATH = "/usr/bin/tshark";  // Linux
// or
const TSHARK_PATH = "/opt/homebrew/bin/tshark";  // macOS Homebrew
```

## Installation

### Prerequisites

- Bun runtime (version 1.x or later) or Node.js 18+
- tshark/Wireshark installed and accessible
- PCAP files for analysis (this server does NOT perform live capture)

### Steps

1. Clone or download this repository:
```bash
cd /path/to/mi-mcp-servers/packages/wireshark
```

2. Install dependencies:
```bash
bun install
```

3. Build the project:
```bash
bun run build
```

4. Verify tshark is installed:
```bash
which tshark
tshark --version
```

5. Run the server:
```bash
bun run start
```

## Usage

### Running the Server

Start the server with Bun:

```bash
bun run src/index.ts
```

The server implements the Model Context Protocol (MCP) and communicates via stdio transport.

### Claude Desktop Configuration

Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "wireshark": {
      "command": "bun",
      "args": [
        "run",
        "/path/to/mi-mcp-servers/packages/wireshark/src/index.ts"
      ]
    }
  }
}
```

### Claude Code MCP Settings

Configure in `.mcp.json` or settings UI:

```json
{
  "servers": {
    "wireshark": {
      "transport": "stdio",
      "command": "bun",
      "args": [
        "run",
        "/path/to/mi-mcp-servers/packages/wireshark/src/index.ts"
      ]
    }
  }
}
```

### Example Usage in Claude

**Request:**
"Analyze the first 1000 packets from /tmp/capture.pcap and show me HTTP traffic only"

**Claude will call:**
```json
{
  "tool": "tshark_analyze",
  "input": {
    "pcap_path": "/tmp/capture.pcap",
    "display_filter": "http",
    "max_packets": 1000
  }
}
```

**Request:**
"Extract all DNS queries from /tmp/dns-traffic.pcap"

**Claude will call:**
```json
{
  "tool": "tshark_dns_extract",
  "input": {
    "pcap_path": "/tmp/dns-traffic.pcap",
    "query_type": "all"
  }
}
```

**Request:**
"Show me protocol statistics for /tmp/network.pcap"

**Claude will call:**
```json
{
  "tool": "tshark_statistics",
  "input": {
    "pcap_path": "/tmp/network.pcap",
    "stat_type": "protocols"
  }
}
```

**Request:**
"Follow the first TCP stream in /tmp/capture.pcap"

**Claude will call:**
```json
{
  "tool": "tshark_follow_stream",
  "input": {
    "pcap_path": "/tmp/capture.pcap",
    "protocol": "tcp",
    "stream_index": 0
  }
}
```

## Security

This server implements comprehensive security measures to ensure safe offline analysis:

### Input Validation

**PCAP Path Validation**
- Must be absolute path (starts with `/`)
- No path traversal (`..`, `./`)
- No null bytes
- Must have valid extension: `.pcap`, `.pcapng`, `.cap`
- File must exist and be a regular file (not directory)
- File size must be under 2GB
- File cannot be empty

**Display Filter Validation**
- Maximum length: 512 characters
- Valid characters: alphanumeric, `.`, `_`, `-`, `!`, `=`, `<`, `>`, `&`, `|`, `(`, `)`, `[`, `]`, `"`, `'`, `,`, `:`, `/`, spaces
- Blocks dangerous patterns: `exec(`, `system(`, `shell(`, backticks, `$(`, `${`
- Prevents command injection

**Field List Validation**
- Valid characters: alphanumeric, `.`, `_`, `-`, `,`
- Maximum field name length: 100 characters
- Minimum 1 field, maximum 20 fields
- No empty field names

**Blocked Flags**
- `-i`, `--interface` - Live capture blocked
- `-w`, `--write` - File writing blocked
- `-b`, `--ring-buffer` - Ring buffer blocked

**Packet Limits**
- Minimum: 1 packet
- Maximum: 100,000 packets per analysis
- Default: 10,000 packets

### What Gets Blocked

The server explicitly rejects:
- Live network capture (no `-i` flag)
- File writing operations (no `-w` flag)
- Relative file paths
- Path traversal attempts
- Files larger than 2GB
- Empty PCAP files
- Invalid file extensions
- Shell metacharacters in filters
- Overly long display filters (>512 chars)
- Too many fields (>20)
- Dangerous command injection patterns

### Error Handling

- File not found returns clear error message
- Invalid filter syntax caught and reported
- Timeout errors handled gracefully
- Parse errors reported with context
- Tool execution errors captured

### Offline Analysis Only

**IMPORTANT**: This server is designed for **offline PCAP analysis only**. Live network capture is explicitly disabled for security reasons:

1. No `-i` (interface) flag allowed
2. No `-w` (write) flag allowed
3. Must provide existing PCAP file path
4. Cannot capture live traffic

This design ensures:
- No unauthorized network monitoring
- No sensitive traffic capture
- Safe execution in restricted environments
- Compliance with security policies

## Common Use Cases

### Network Forensics
- Analyze captured traffic from security incidents
- Extract IOCs (IPs, domains, URLs)
- Reconstruct attack chains
- Identify malicious payloads

### Protocol Analysis
- Debug custom protocols
- Analyze protocol compliance
- Identify protocol issues
- Study protocol behavior

### Performance Analysis
- Identify retransmissions
- Analyze latency patterns
- Find bandwidth bottlenecks
- Study connection patterns

### Security Research
- Analyze malware traffic
- Study C2 communications
- Identify data exfiltration
- Research vulnerabilities

## Display Filter Examples

```
# HTTP
http.request.method == "POST"
http.host contains "example"
http.response.code == 404

# DNS
dns.qry.name contains "malware"
dns.flags.response == 1
dns.qry.type == 1  # A records

# TCP
tcp.flags.syn == 1 && tcp.flags.ack == 0  # SYN packets
tcp.analysis.retransmission  # Retransmissions
tcp.port == 443  # HTTPS

# IP
ip.addr == 192.168.1.1
ip.src == 10.0.0.0/8
ip.ttl < 64

# TLS/SSL
tls.handshake.type == 1  # Client Hello
ssl.record.version == 0x0303  # TLS 1.2

# Combined
(http || dns) && ip.src == 192.168.1.100
tcp.port == 443 && !(tcp.flags.syn == 1)
```

## Limitations

- **File Size**: Maximum 2GB PCAP files
- **Packet Count**: Maximum 100,000 packets per analysis
- **Filter Length**: Maximum 512 characters
- **Field Count**: Maximum 20 fields for extraction
- **Timeout**: Maximum 600 seconds (10 minutes) per operation
- **Live Capture**: Not supported (offline analysis only)
- **File Writing**: Not supported (read-only operations)

## Troubleshooting

**"tshark command not found"**
- Install Wireshark/tshark: `brew install wireshark` or `apt-get install tshark`
- Update `TSHARK_PATH` in `src/cli-executor.ts`

**"PCAP file not found"**
- Use absolute paths only (start with `/`)
- Verify file exists: `ls -l /path/to/file.pcap`
- Check file permissions

**"Analysis timed out"**
- Reduce `max_packets` parameter
- Use more specific display filters
- Increase `timeout` parameter (max 600 seconds)

**"Invalid display filter"**
- Verify filter syntax in Wireshark first
- Check for unsupported characters
- Reduce filter complexity

**"File too large"**
- Split PCAP files: `editcap -c 100000 input.pcap output.pcap`
- Use display filters to reduce data
- Maximum supported: 2GB

## License

ISC License - see LICENSE file for details

## Resources

- **Wireshark**: https://www.wireshark.org/
- **Tshark Documentation**: https://www.wireshark.org/docs/man-pages/tshark.html
- **Display Filters**: https://wiki.wireshark.org/DisplayFilters
- **Protocol Fields**: https://www.wireshark.org/docs/dfref/