@modular-intelligence/wireshark

v1.0.2

Published

10 days ago

MCP server wrapping tshark for network protocol analysis of PCAP files

Downloads

201

0High
0Medium
0Low

modularintelligence

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:

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

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

Example Output:

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

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

{
  "pcap_path": "/tmp/capture.pcap",
  "stat_type": "conv",
  "timeout": 120
}

Example Output:

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

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

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

Example Output:

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

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

{
  "pcap_path": "/tmp/capture.pcap",
  "protocol": "tcp",
  "stream_index": 0
}

Example Output:

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

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

{
  "pcap_path": "/tmp/capture.pcap",
  "severity": "warn"
}

Example Output:

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

{
  pcap_path: string       // Absolute path to PCAP/PCAPNG file
}

Example Request:

{
  "pcap_path": "/tmp/capture.pcap"
}

Example Output:

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

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

{
  "pcap_path": "/tmp/capture.pcap",
  "query_type": "A"
}

Example Output:

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

brew install wireshark

Linux (Debian/Ubuntu):

sudo apt-get install tshark

Linux (RHEL/CentOS):

sudo yum install wireshark

Verify Installation:

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:

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

Clone or download this repository:

cd /path/to/mi-mcp-servers/packages/wireshark

Install dependencies:

bun install

Build the project:

bun run build

Verify tshark is installed:

which tshark
tshark --version

Run the server:

bun run start

Usage

Running the Server

Start the server with Bun:

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:

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

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

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

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

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

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

No -i (interface) flag allowed
No -w (write) flag allowed
Must provide existing PCAP file path
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/

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

Wireshark/Tshark MCP Server

Overview

Tools

Tshark Analyze

Tshark Statistics

Tshark Extract Fields

Tshark Follow Stream

Tshark Expert Info

Tshark File Info

Tshark DNS Extract

Configuration

Prerequisites

Binary Location

Installation

Prerequisites

Steps

Usage

Running the Server

Claude Desktop Configuration

Claude Code MCP Settings

Example Usage in Claude

Security

Input Validation

What Gets Blocked

Error Handling

Offline Analysis Only

Common Use Cases

Network Forensics

Protocol Analysis

Performance Analysis

Security Research

Display Filter Examples

Limitations

Troubleshooting

License

Resources