@modular-intelligence/wireshark 1.0.0

package/README.md

@@ -0,0 +1,725 @@
+# 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/