<div align="center">

![NetForensicMCP Logo](NetForensicMCP-logo.svg)

**🔍 Advanced Network Forensics & Threat Intelligence Platform 🛡️**

[![Version](https://img.shields.io/badge/version-2.1.0-blue.svg)](https://github.com/kylecui/NetForensicMCP)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
[![Node.js](https://img.shields.io/badge/node.js-%3E%3D16.0.0-brightgreen.svg)](https://nodejs.org/)
[![Wireshark](https://img.shields.io/badge/requires-Wireshark%2Ftshark-orange.svg)](https://www.wireshark.org/)

</div>

# NetForensicMCP v2.1
*（Formerly WireMCP, Now Focused on Offline Forensic Analysis）*

> **English** | [中文](README_zh.md)

NetForensicMCP (formerly WireMCP) is a Model Context Protocol (MCP) server designed to empower Large Language Models (LLMs) with advanced **offline network traffic analysis** and **threat intelligence** capabilities. Built on top of Wireshark's `tshark`, NetForensicMCP provides comprehensive PCAP analysis tools for cybersecurity professionals, threat hunters, and network forensics investigators.

## 🚀 Key Features

### **Core Analysis Engine**
- **Smart Stream Analysis**: Intelligent content chunking to handle large PCAP files without token overflow
- **Threat Intelligence Integration**: Built-in URLhaus blacklist checking with stream correlation
- **Credential Extraction**: Automated detection of plaintext credentials across multiple protocols
- **High-Frequency IP Analysis**: Proactive threat hunting through top communicator identification

### **Advanced Tools**
- **`get_summary_stats`**: Protocol hierarchy statistics for traffic composition overview
- **`get_conversations`**: TCP/UDP conversation analysis with stream indexing
- **`extract_stream_content`**: Precise payload extraction with pagination support
- **`get_stream_info`**: Content size estimation to prevent token overflow
- **`extract_stream_chunks`**: Automated large stream segmentation
- **`get_top_ips`**: High-frequency communicator identification for proactive analysis
- **`check_threats`**: Batch IP threat scanning with stream correlation
- **`extract_credentials`**: Multi-protocol credential detection with context
- **`capture_packets`**: Legacy live traffic capture (preserved for compatibility)

## 🔍 How It Empowers LLMs

NetForensicMCP transforms complex network forensics into LLM-accessible intelligence by:

- **🎯 Threat-Driven Analysis**: Prioritizes high-risk indicators over raw data processing
- **📊 Structured Intelligence**: Converts PCAP data into actionable threat intelligence
- **⚡ Efficient Investigation**: Optimized workflow prevents token exhaustion
- **🔗 Correlation Engine**: Links disparate network events into coherent attack narratives
- **📝 Automated Reporting**: Generates comprehensive security reports with IOCs and recommendations

## 🛡️ Cybersecurity Use Cases

- **🕵️ Threat Hunting**: Proactive identification of APT activities and C2 communications
- **🔍 Incident Response**: Rapid forensic analysis of network evidence
- **📋 Compliance Auditing**: Credential leak detection and security gap identification  
- **🚨 IOC Extraction**: Automated indicator of compromise discovery
- **📖 Attack Reconstruction**: Timeline analysis and attack path visualization

## 📋 Installation

### Prerequisites
- **Operating System**: Windows, macOS, or Linux
- **Wireshark**: [Download here](https://www.wireshark.org/download.html) (tshark must be in PATH)
- **Node.js**: v16+ recommended
- **npm**: For dependency management

### Setup
1. **Clone the repository**:
   ```bash
   git clone https://github.com/kylecui/NetForensicMCP.git
   cd NetForensicMCP
   ```

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

3. **Launch the MCP server**:
   ```bash
   node index.js
   ```

> **Note**: NetForensicMCP auto-detects tshark or falls back to common installation paths on all platforms.

## ⚙️ MCP Client Configuration

### Cursor IDE
Edit `mcp.json` in Cursor → Settings → MCP:

```json
{
  "mcpServers": {
    "netforensicmcp": {
      "command": "node",
      "args": [
        "/ABSOLUTE_PATH_TO/NetForensicMCP/index.js"
      ]
    }
  }
}
```

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

```json
{
  "mcpServers": {
    "wiremcp": {
      "command": "node",
      "args": ["C:\\path\\to\\NetForensicMCP\\index.js"]
    }
  }
}
```

## 🔬 Example Analysis Workflows

### Threat Intelligence Analysis
```bash
# Batch threat scanning with stream correlation
check_threats → extract_credentials → get_top_ips
↓
ip_reputation (parallel) → ioc_detection → domain_analysis
↓
extract_stream_content (targeted) → comprehensive_report
```

### Advanced Forensics
```bash
# Large PCAP investigation
get_summary_stats → get_conversations → get_stream_info
↓
extract_stream_chunks → extract_stream_content (paginated)
↓
correlation_analysis → timeline_reconstruction
```

## 📊 Sample Output

### Threat Analysis Report
```
⚠️  THREATS DETECTED (2):
🚨 192.168.1.100 - Streams: [tcp:0, tcp:2, udp:1]
🚨 10.0.0.50 - Streams: [tcp:5]

📋 RECOMMENDED NEXT STEPS:
1. Use threat intelligence tools to analyze these IPs
2. Extract stream content for streams containing these IPs  
3. Focus investigation on: 192.168.1.100, 10.0.0.50
```

### Stream Content Analysis
```
Content of tcp stream 0 (chars 0-15000 of 45230):
POST /api/upload HTTP/1.1
Host: suspicious-domain.com
Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...

[TRUNCATED - More content available. Use offset=15000 to get the next chunk.]
```

## 🎯 Advanced Features

### Smart Token Management
- **Intelligent Chunking**: Automatic content segmentation prevents API limits
- **Pagination Support**: Seamless navigation through large datasets  
- **Size Estimation**: Proactive content size assessment
- **Parallel Processing**: Efficient batch operations

### Threat Intelligence Integration
- **URLhaus Integration**: Comprehensive malware URL database checking
- **Stream Correlation**: Links threats to specific communication flows
- **IOC Extraction**: Automated indicator discovery and validation
- **Proactive Scanning**: Top communicator threat assessment

## 🛠️ Architecture

NetForensicMCP v2.1 implements an **optimized investigation workflow**:

1. **📡 Reconnaissance Phase**: Low-token traffic overview
2. **🔍 Batch Scanning Phase**: Parallel threat detection  
3. **🧠 Intelligence Phase**: Deep threat correlation
4. **📋 Planning Phase**: Strategic analysis targeting
5. **🎯 Payload Phase**: Precision content extraction
6. **📊 Reporting Phase**: Comprehensive findings synthesis

## 🚀 Roadmap

- **🔌 Extended IOC Sources**: Integration with VirusTotal, AlienVault OTX
- **🤖 ML-Powered Analysis**: Behavioral pattern recognition
- **📈 Timeline Visualization**: Interactive attack reconstruction
- **🔄 Enhanced Automation**: Advanced workflow automation capabilities  
- **📱 Web Dashboard**: Browser-based analysis interface

## 🤝 Contributing

We welcome contributions! Please see our [contribution guidelines](CONTRIBUTING.md) for details.

### Areas for Contribution:
- **Threat Intelligence Sources**: Additional IOC providers
- **Protocol Analyzers**: New credential extraction methods
- **Performance Optimization**: Large PCAP handling improvements
- **Documentation**: Use cases and tutorials

## 📋 Documentation

- **[English README](README.md)** - Complete setup and usage guide
- **[中文说明](README_zh.md)** - 完整的安装和使用指南  
- **[System Prompt Example](system_prompt_example.md)** - Sample LLM prompt for effective analysis
- **[系统提示词示例](system_prompt_example_zh.md)** - LLM 有效分析的示例提示词
- **[Contributing Guide](CONTRIBUTING.md)** - Development and contribution guidelines
- **[Changelog](CHANGELOG.md)** - Version history and updates

## 📄 License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 📋 Changelog

See [CHANGELOG.md](CHANGELOG.md) for detailed version history and release notes.

### Original Attribution
Based on the original [WireMCP project](https://github.com/0xkoda/WireMCP) by **0xkoda** with significant enhancements for offline analysis and threat intelligence integration. We extend our gratitude to the original author for providing the foundational MCP framework and live capture capabilities that made this advanced forensics platform possible.

## 🙏 Acknowledgments

- **0xkoda**: Original WireMCP creator - thank you for the foundational live capture framework
- **Wireshark Team**: For the excellent tshark packet analysis engine
- **Model Context Protocol Community**: For the MCP framework and specifications  
- **URLhaus (abuse.ch)**: For providing comprehensive threat intelligence data
- **Cybersecurity Community**: For continuous feedback and improvement suggestions

---

**⚡ Ready to revolutionize your network forensics? Get started with NetForensicMCP v2.1 today!**