cerby0n/tshark-mcp

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 (includes tshark)
  • Linux: sudo apt-get install tshark
  • macOS: brew install wireshark

Installation

Docker Setup (Recommended)

1. Build the Docker image:

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

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

Windows example:

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

Linux/Mac example:

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

Local Installation (Alternative)

1. Install dependencies:

npm install

2. Configure Claude Desktop:

{
  "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:

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