# Tshark MCP Server

An MCP (Model Context Protocol) server for analyzing pcap files using tshark to detect potential network attacks and security threats.

## Features

- **Automated Attack Detection**: Analyzes pcap files for common attack patterns:
  - Port scanning attempts
  - DDoS indicators (traffic volume anomalies)
  - DNS tunneling and exfiltration
  - HTTP-based attacks (SQL injection, XSS)
  - Failed connection attempts
  - Suspicious IP addresses

- **Custom Queries**: Run custom tshark queries with Wireshark display filters
- **Statistics**: Get comprehensive pcap statistics including protocols and conversations

## Prerequisites

### Option 1: Docker (Recommended - Most Portable)
- **Docker** and **Docker Compose** installed
- No other dependencies needed!

### Option 2: Local Installation
- **Node.js** (v16 or higher)
- **Tshark** installed and available in PATH
  - Windows: Install [Wireshark](https://www.wireshark.org/download.html) (includes tshark)
  - Linux: `sudo apt-get install tshark`
  - macOS: `brew install wireshark`

## Installation

### Docker Setup (Recommended)

1. **Build the Docker image:**
```bash
docker-compose build
```

2. **Place your pcap files in the `pcaps/` directory** (or configure a custom volume in docker-compose.yml)

3. **Configure Claude Desktop** with the Docker container:

Add to your Claude Desktop config file:

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "tshark": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "/path/to/your/pcaps:/pcaps:ro",
        "tshark-mcp-server:latest"
      ]
    }
  }
}
```

**Windows example:**
```json
{
  "mcpServers": {
    "tshark": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "C:\\captures:/pcaps:ro",
        "tshark-mcp-server:latest"
      ]
    }
  }
}
```

**Linux/Mac example:**
```json
{
  "mcpServers": {
    "tshark": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-v",
        "${HOME}/captures:/pcaps:ro",
        "tshark-mcp-server:latest"
      ]
    }
  }
}
```

### Local Installation (Alternative)

1. **Install dependencies:**
```bash
npm install
```

2. **Configure Claude Desktop:**

```json
{
  "mcpServers": {
    "tshark": {
      "command": "node",
      "args": ["/absolute/path/to/tshark-mcp/index.js"]
    }
  }
}
```

## Usage

After configuration, restart Claude Desktop. Your pcap files should be accessible at `/pcaps/` (Docker) or their original paths (local).

### Available Tools

#### 1. `analyze_pcap_attacks`
Automatically analyzes a pcap file for security threats.

**Parameters:**
- `pcap_path` (required): Path to the pcap file

**Example:**
```
# Docker: pcap files are in /pcaps inside container
Analyze /pcaps/traffic.pcap for attacks

# Local installation
Analyze c:\captures\traffic.pcap for attacks
```

The AI will automatically identify suspicious IPs and attack patterns.

#### 2. `query_pcap`
Run custom tshark queries with display filters.

**Parameters:**
- `pcap_path` (required): Path to the pcap file
- `display_filter` (optional): Wireshark display filter
- `fields` (optional): Array of fields to extract

**Examples:**
```
# Docker
Show all HTTP GET requests from /pcaps/traffic.pcap
Query /pcaps/traffic.pcap with filter "ip.src==192.168.1.100 && tcp.port==443"

# Local
Show all HTTP GET requests from traffic.pcap
Extract source IPs and ports from traffic.pcap where tcp.flags.syn==1
```

#### 3. `get_pcap_stats`
Get general statistics about a pcap file.

**Parameters:**
- `pcap_path` (required): Path to the pcap file

**Example:**
```
Get statistics for traffic.pcap
```

## How It Works

### AI-Powered Analysis

When you use `analyze_pcap_attacks`, the server:

1. Runs multiple tshark queries to extract security-relevant data
2. Formats the results for AI analysis
3. The AI (Claude) analyzes the data to:
   - Identify suspicious IP addresses
   - Detect attack patterns
   - Explain potential threats
   - Provide remediation suggestions

### Example Workflow

**User:** "Analyze /pcaps/suspicious.pcap"

**AI Response:**
- Identifies potential attackers by IP
- Explains attack types detected (port scan, DDoS, etc.)
- Lists suspicious domains or URLs
- Recommends next steps

**User:** "Show me all traffic from IP 192.168.1.50"

**AI uses query_pcap:**
- Filters pcap for that specific IP
- Shows relevant packets
- Analyzes behavior

### Docker Benefits

✅ **Portability**: Works on Windows, Linux, and macOS
✅ **No Dependencies**: Tshark is pre-installed in the container
✅ **Isolation**: Secure execution environment
✅ **Easy Updates**: Just rebuild the image
✅ **Consistent**: Same environment everywhere

## Detection Capabilities

The server looks for:

- **Port Scanning**: SYN packets to multiple ports from the same source
- **DDoS Attacks**: Unusual traffic volumes from single sources
- **DNS Anomalies**: Suspicious query patterns, potential tunneling
- **HTTP Attacks**: SQL injection, XSS, directory traversal in URLs
- **Reconnaissance**: Multiple failed connections (RST packets)
- **Protocol Anomalies**: Unusual protocol usage patterns

## Wireshark Display Filter Examples

Common filters you can use with `query_pcap`:

```
ip.addr==192.168.1.1          # Traffic to/from specific IP
tcp.port==80                  # HTTP traffic
http.request.method==POST     # POST requests
dns.qry.name contains "evil"  # DNS queries with "evil"
tcp.flags.syn==1 && tcp.flags.ack==0  # SYN packets (port scan)
icmp.type==8                  # ICMP echo requests (ping)
```

## Troubleshooting

**"tshark: command not found"**
- Ensure tshark is installed and in your PATH
- Restart Claude Desktop after installation

**Permission errors on Linux:**
```bash
sudo dpkg-reconfigure wireshark-common  # Select "Yes"
sudo usermod -a -G wireshark $USER
```
Log out and back in for changes to take effect.

## Security Note

This tool is designed for **defensive security analysis only**. Use it to:
- Analyze your own network traffic
- Investigate security incidents
- Learn about network security
- Detect threats in authorized environments

## License

MIT