Metadata-Version: 2.4
Name: iflow-mcp_mixelpixx-wireshark-mcp-server
Version: 0.1.0
Summary: Comprehensive Wireshark + Nmap MCP server for network analysis with threat intelligence
Author: Wireshark MCP Contributors
License: MIT
Project-URL: Homepage, https://github.com/iflow-mcp/mixelpixx-wireshark-mcp
Project-URL: Documentation, https://github.com/iflow-mcp/mixelpixx-wireshark-mcp#readme
Project-URL: Repository, https://github.com/iflow-mcp/mixelpixx-wireshark-mcp
Project-URL: Issues, https://github.com/iflow-mcp/mixelpixx-wireshark-mcp/issues
Keywords: mcp,wireshark,nmap,network-analysis,packet-capture,threat-intelligence
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: Topic :: System :: Networking :: Monitoring
Classifier: Topic :: Security
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: fastmcp>=0.9.0
Requires-Dist: typing-extensions>=4.0.0
Requires-Dist: python-nmap>=0.7.1
Requires-Dist: dnspython>=2.4.0
Requires-Dist: requests>=2.31.0
Requires-Dist: requests-cache>=1.1.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.21.0; extra == "dev"
Requires-Dist: pytest-mock>=3.12.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: black>=22.0.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Dynamic: license-file

# Wireshark MCP Server

A comprehensive Model Context Protocol (MCP) server that provides AI assistants with professional-grade network analysis capabilities. Combines Wireshark packet analysis with nmap scanning, threat intelligence, and modern MCP features for enhanced network troubleshooting and security analysis.

## Features

### Core Wireshark Capabilities
- **Live Packet Capture**: Real-time network traffic capture from any interface
- **PCAP File Analysis**: Advanced analysis of capture files with filtering
- **Protocol Statistics**: Comprehensive protocol hierarchy and conversation stats
- **Stream Following**: Reconstruct TCP/UDP conversations from captures
- **Data Export**: Export packets to JSON, CSV formats

### Network Scanning (Nmap Integration)
- **Port Scanning**: Multiple scan types (SYN, connect, UDP)
- **Service Detection**: Identify services and versions
- **OS Fingerprinting**: Operating system detection
- **Vulnerability Scanning**: NSE vulnerability detection scripts
- **Quick & Comprehensive Scans**: Flexible scan options

### Security Features
- **Threat Intelligence**: URLhaus and AbuseIPDB integration
- **Malicious IP Detection**: Automatic threat checking
- **Security Audit Workflows**: Guided security analysis prompts
- **Credential Scanning**: Detect cleartext credentials
- **Defense in Depth**: Multiple layers of input validation

### Modern MCP Features
- **MCP Resources**: Dynamic access to interfaces and captures
- **MCP Prompts**: Guided workflows for security audits and troubleshooting
- **Structured JSON Output**: LLM-optimized response formats
- **Rate Limiting**: Prevent abuse of scanning operations
- **Async Operations**: Non-blocking high-performance analysis

## Installation

### Quick Install (PyPI)

```bash
pip install wireshark-mcp-server
```

### Development Install

```bash
# Clone repository
git clone https://github.com/yourusername/wireshark-mcp.git
cd wireshark-mcp

# Install in development mode
pip install -e .

# Or install from requirements
pip install -r requirements.txt
```

## Requirements

### System Requirements
- **Python 3.8+** with pip
- **Wireshark/TShark** installed and in PATH
- **Nmap** (optional, for scanning features)
- **Network capture permissions** (see setup below)

### Installation Commands

#### Ubuntu/Debian
```bash
sudo apt-get update
sudo apt-get install tshark nmap
sudo usermod -aG wireshark $USER
```

#### macOS
```bash
brew install wireshark nmap
```

#### Windows
1. Download and install [Wireshark](https://www.wireshark.org/download.html)
2. Download and install [Nmap](https://nmap.org/download.html)
3. Run as Administrator for packet capture

### Network Permissions

#### Linux (Recommended)
```bash
# Set capabilities on dumpcap (no root needed)
sudo setcap cap_net_raw,cap_net_admin=eip /usr/bin/dumpcap

# Or add user to wireshark group
sudo usermod -aG wireshark $USER
newgrp wireshark  # Apply group without logout
```

## Configuration

### Claude Desktop

Edit your Claude Desktop config:
- **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": {
    "wireshark": {
      "command": "wireshark-mcp-server",
      "env": {
        "ABUSEIPDB_API_KEY": "your_api_key_here"
      }
    }
  }
}
```

### Environment Variables

```bash
# Optional: AbuseIPDB API key for threat intelligence
export ABUSEIPDB_API_KEY="your_api_key_here"

# Optional: VirusTotal API key (future support)
export VIRUSTOTAL_API_KEY="your_api_key_here"
```

## Available Tools

### Network Interface & Capture (5 tools)

**get_network_interfaces()**
- Lists all available network interfaces

**capture_live_packets(interface, count, capture_filter, timeout, format)**
- Captures live packets with BPF filtering
- Supports JSON and text output formats

**analyze_pcap_file(filepath, display_filter, max_packets)**
- Analyzes PCAP files with Wireshark display filters

**get_protocol_statistics(filepath)**
- Generates protocol hierarchy and IP conversations

**get_capture_file_info(filepath)**
- Retrieves capture file metadata

### Stream Analysis (3 tools)

**follow_tcp_stream(filepath, stream_index, format)**
- Reconstructs TCP conversations (ASCII, hex, raw)

**follow_udp_stream(filepath, stream_index, format)**
- Reconstructs UDP conversations

**list_tcp_streams(filepath)**
- Lists all TCP conversations in capture

### Data Export (3 tools)

**export_packets_json(filepath, display_filter, max_packets)**
- Exports packets to structured JSON

**export_packets_csv(filepath, fields, display_filter)**
- Exports custom fields to CSV

**convert_pcap_format(filepath, output_format)**
- Converts between pcap/pcapng formats

### Nmap Scanning (6 tools)

**nmap_port_scan(target, ports, scan_type, format)**
- Scans for open ports (connect, SYN, UDP)

**nmap_service_detection(target, ports)**
- Detects service versions

**nmap_os_detection(target)**
- Identifies operating system (requires root)

**nmap_vulnerability_scan(target, ports)**
- Runs NSE vulnerability scripts

**nmap_quick_scan(target)**
- Fast scan of top 100 ports

**nmap_comprehensive_scan(target)**
- Full scan with all features

### Threat Intelligence (2 tools)

**check_ip_threat_intel(ip_or_filepath, providers)**
- Checks IPs against URLhaus, AbuseIPDB

**scan_capture_for_threats(filepath, providers)**
- Comprehensive threat scan of PCAP file

### MCP Resources

**wireshark://interfaces/**
- Dynamic list of network interfaces

**wireshark://captures/**
- Available PCAP files in common directories

**wireshark://system/info**
- System capabilities and tool availability

**network://help**
- Comprehensive tool documentation

### MCP Prompts

**security_audit**
- Guided security analysis workflow

**network_troubleshooting**
- Network diagnostics workflow

**incident_response**
- Security incident investigation workflow

## Usage Examples

### Basic Network Capture

```
User: "Capture 100 packets from eth0 with HTTP traffic"
AI: Uses capture_live_packets("eth0", 100, "tcp port 80")
```

### Security Analysis Workflow

```
User: "Perform a security audit on suspicious.pcap"
AI:
1. Uses security_audit prompt
2. Analyzes file with get_protocol_statistics()
3. Extracts IPs and checks scan_capture_for_threats()
4. Follows suspicious TCP streams
5. Generates comprehensive report
```

### Scan & Capture Workflow

```
User: "Scan 192.168.1.100 then capture its traffic"
AI:
1. nmap_quick_scan("192.168.1.100")
2. capture_live_packets("eth0", 500, "host 192.168.1.100")
3. analyze_pcap_file() with findings
4. follow_tcp_stream() for interesting connections
```

### Threat Intelligence Check

```
User: "Check if this capture has any malicious IPs"
AI: scan_capture_for_threats("/path/to/capture.pcap", "urlhaus,abuseipdb")
```

## Security

### Input Validation
- IP/CIDR/hostname validation
- Port range validation
- BPF and display filter sanitization
- File path resolution and sandboxing

### Command Injection Prevention
- **shell=False** enforced in ALL subprocess calls
- List-based command construction
- No user input directly in shell commands

### Rate Limiting
- Max 10 nmap scans per hour
- Configurable scan history tracking

### Privilege Management
- Detects when root/sudo required
- Never auto-escalates privileges
- Clear error messages for permission issues

### Audit Logging
- All scans logged with timestamps
- Security-relevant operations tracked
- Validation failures recorded

## Development

### Running Tests

```bash
# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest tests/

# With coverage
pytest --cov=wireshark_mcp --cov-report=html

# Linting
ruff check wireshark_mcp/
black --check wireshark_mcp/

# Type checking
mypy wireshark_mcp/
```

### Project Structure

```
wireshark_mcp/
├── server.py                   # Main server orchestration
├── core/
│   ├── security.py             # Security validation
│   └── output_formatter.py     # Response formatting
├── interfaces/
│   ├── wireshark_interface.py  # TShark wrapper
│   ├── nmap_interface.py       # Nmap wrapper
│   └── threat_intel_interface.py # Threat APIs
├── tools/
│   ├── capture.py              # Capture tools
│   ├── analysis.py             # Analysis tools
│   ├── nmap_scan.py            # Scanning tools
│   ├── network_streams.py      # Stream tools
│   ├── export.py               # Export tools
│   └── threat_intel.py         # Threat tools
├── resources/                  # MCP Resources
└── prompts/                    # MCP Prompts
```

## Troubleshooting

### "TShark not found"
```bash
# Verify installation
tshark --version

# Add to PATH or use absolute path
export PATH=$PATH:/usr/bin
```

### "Permission denied" for capture
```bash
# Linux - set capabilities
sudo setcap cap_net_raw,cap_net_admin=eip /usr/bin/dumpcap

# Or use sudo (not recommended)
sudo wireshark-mcp-server
```

### "Nmap not available"
```bash
# Install nmap
sudo apt-get install nmap  # Debian/Ubuntu
brew install nmap           # macOS

# Verify
nmap --version
```

### Threat Intelligence Not Working
```bash
# Check API key
echo $ABUSEIPDB_API_KEY

# URLhaus requires no key (works by default)
# AbuseIPDB requires free API key from https://www.abuseipdb.com/
```

## License

MIT License - see LICENSE file for details

## Acknowledgments

- Built on the Model Context Protocol (MCP) by Anthropic
- Powered by Wireshark network analysis toolkit
- Integrated with Nmap security scanner
- Threat intelligence from URLhaus and AbuseIPDB

## Support

- **Issues**: [GitHub Issues](https://github.com/yourusername/wireshark-mcp/issues)
- **Documentation**: See `network://help` resource in MCP
- **Security**: Report vulnerabilities via GitHub Security Advisories

## Roadmap

- GeoIP enrichment for IP addresses
- HTTP/TLS credential extraction
- Real-time WebSocket streaming
- VirusTotal integration
- AlienVault OTX integration
- Machine learning traffic classification
- Anomaly detection algorithms
- PCAP merging and splitting tools
- Statistics visualization export

---

**Transform your network analysis with AI-powered Wireshark + Nmap integration**
