Wireshark MCP — Packet Intelligence Platform
README.md
# Wireshark MCP — Packet Intelligence Platform 🦈🌐
Evidence-driven network packet analysis and forensics platform built with Wireshark, TShark, Python, FastMCP, and React.
[](https://www.python.org/)
[](https://modelcontextprotocol.io)
[](https://react.dev)
[](LICENSE)
[]()
[]()
> [!NOTE]
> **Project Status**: Under Active Development
> - Phase 0 — Complete
> - Phase 1 — Complete
> - Phase 2 — Complete
> - Phase 3 — Complete / Gate G3 Approved
> - Phase 4 — Complete / Gate G4 Approved (Pending Review)
> - Phase 5 — Next
---
## 📌 Table of Contents
- [Overview](#-overview)
- [Project Governance & Verification Baseline](#-project-governance--verification-baseline)
- [Key Features](#-key-features)
- [Architecture & Core Data Contract](#-architecture--core-data-contract)
- [Detection Engine & Confidence Model](#-detection-engine--confidence-model)
- [TCP Stream Reassembly & Evidence Correlation](#-tcp-stream-reassembly--evidence-correlation)
- [Artifact Deduplication & Forensic Provenance](#-artifact-deduplication--forensic-provenance)
- [Prerequisites & Installation](#-prerequisites--installation)
- [MCP Client Configuration](#-mcp-client-configuration)
- [Documentation Structure](#-documentation-structure)
- [Testing Instructions](#-testing-instructions)
- [Current Roadmap](#-current-roadmap)
- [Known Limitations](#-known-limitations)
- [License](#-license)
---
## 🔍 Overview
The **Wireshark MCP — Packet Intelligence Platform** wraps `tshark`'s command-line packet inspection engine into structured, typed Model Context Protocol (MCP) tools and REST API services. Through standard `stdio` MCP transport or HTTP REST endpoints, AI assistants (Claude, Cursor, Gemini) and security analysts can inspect PCAP/PCAPNG files, reassemble TCP/UDP streams, extract payload artifacts, identify CTF flags, detect network threat anomalies, and generate formal engineering reports.
---
## 📋 Project Governance & Verification Baseline
- **Current Status**: Phase 4 Completed & Verified (Gate G4 Verdict: **PASSED (Pending Review)**)
- **Automated Test Baseline**: 106 total test cases | 106 passed | 0 failed | 100% pass rate
- **Traceability**: All requirements (`FR-001` through `FR-018`, `NFR-001` through `NFR-012`) are tracked in [`docs/01_requirements/REQUIREMENTS_TRACEABILITY_MATRIX.md`](file:///home/sosuke/Desktop/wireshark-mcp/docs/01_requirements/REQUIREMENTS_TRACEABILITY_MATRIX.md).
---
## ✨ Key Features
- 📦 **PCAP / PCAPNG Ingestion & Validation**: Safe path validation, magic byte header checking, 100MB file limits, and typed exception handling (`PcapNotFoundError`, `InvalidPcapError`, `PcapOversizedError`).
- 🚩 **Rule-Based Threat & Secret Detector**: Pattern matching for CTF flags (`picoCTF`, `HTB`, `THM`, `flag{}`, `CTF{}`), credentials (`Authorization`, API keys), RFC1918 internal traffic, and Base64 payloads.
- 🚨 **Heuristic Anomaly Detectors**: Subroutines for TCP port scans, SYN floods, C2 periodic beaconing, ICMP floods, and large data transfer flows.
- 🔄 **TCP Stream Sequence Reassembly**: Reassembles out-of-order segments by `tcp.seq`, filters duplicate retransmissions, trims partial sequence overlaps, and explicitly marks sequence gaps (`[MISSING_BYTES: N bytes...]`).
- 🔗 **Multi-Packet Evidence Binding**: Every finding binds exact frame numbers (`packet_nums`), timestamps, source/destination endpoints, and protocol contexts.
- 🛡 **Artifact Content Deduplication**: Payload object exporter hashes content using SHA-256 and deduplicates identical files via the canonical `ExtractedObject` model while retaining occurrence counts and provenance.
- 📑 **Formal PDF & Markdown Reports**: Generates 6-page ReportLab engineering audit PDFs and editable Markdown reports with table of contents and full metadata.
---
## 🏗 Architecture & Core Data Contract
The platform uses a single authoritative data model (`AnalysisResult` in `models/analysis_result.py`) to exchange structured data between the analysis engine, MCP tools, REST API, frontend, and reporting system.
```text
wireshark-mcp/
├── server.py # FastMCP stdio entry point
├── api_server.py # FastAPI REST API server
├── frontend/ # React 19 + Vite + Tailwind v4 SOC Web Frontend
├── config/ # Environment settings & flag_patterns.yaml
├── core/
│ ├── tshark_engine.py # Subprocess wrapper with timeout & argument isolation
│ ├── pcap_loader.py # PCAP validation & file loading
│ └── filter_engine.py # Display filter validation & preset builder
├── tools/ # Tool implementations (capture_info, flag_detector, anomaly_detector, stream_analyzer, http_extractor)
├── models/ # Dataclasses (AnalysisResult, Finding, ExtractedObject, Packet)
├── reports/ # ReportLab PDF & Markdown report generators
├── utils/ # Validators, parsers, and module logger
├── tests/ # 106 automated unit, integration, and audit tests
├── docs/ # Project documentation structure (00..06)
├── scripts/ # ReportLab PDF generation scripts
├── .env.example # Environment configuration template
└── requirements.txt # Python dependencies
```
---
## 🎯 Detection Engine & Confidence Model
Findings are categorized into explicit confidence levels per SRS Section 9:
| Confidence Level | Definition | Example / Trigger Rule |
| :--- | :--- | :--- |
| `CONFIRMED` | Fully validated match with zero ambiguity. | Explicit CTF flags (`picoCTF{...}`, `HTB{...}`). |
| `SUSPICIOUS_CANDIDATE` | Matched pattern requires analyst review. | Credentials in passive capture (`Authorization: Basic`), generic curly-braces (`{...}`), private-to-public IP traffic. |
| `INFORMATIONAL_INDICATOR` | Contextual indicator or dummy placeholder. | RFC1918 internal traffic (`192.168.x.x`), placeholder strings (`password=hunter2`), Base64 blobs. |
| `HEURISTIC_ANOMALY` | Alert generated by statistical/threshold rule. | TCP port scan, SYN flood, C2 beaconing, large data exfiltration. |
---
## 🔄 TCP Stream Reassembly & Evidence Correlation
1. **Segment Sequence Reassembly (`tools/stream_analyzer.py`)**:
- Sorts TCP payload segments by sequence number (`tcp.seq`).
- Filters out duplicate retransmissions (`seq_end <= next_expected_seq`).
- Trims overlapping sequence segment ranges (`seq < next_expected_seq`).
- Inserts explicit gap markers when missing sequence bytes occur:
`[MISSING_BYTES: N bytes from seq X to Y]`
- Never silently fabricates missing byte sequences.
2. **Evidence Correlation (`tools/flag_detector.py`, `tools/anomaly_detector.py`)**:
- All findings retain lists of frame numbers (`packet_nums`) rather than single packet references.
- Secondary TCP stream scanning catches CTF flags or credentials split across multiple TCP packets.
---
## 🛡 Artifact Deduplication & Forensic Provenance
- **Canonical `ExtractedObject` Model (`models/extracted_object.py`)**:
- Encapsulates exported payload objects with SHA-256 `content_hash`, `filename`, `media_type`, `size_bytes`, `occurrence_count`, `source_ips`, `dest_ips`, and `packet_nums`.
- **Occurrence Retention**:
- Exported payload files with identical SHA-256 hashes are merged into a single record with `occurrence_count > 1`.
- Calling `add_occurrence()` appends new frame numbers and IP endpoints without erasing forensic context.
---
## ⚙️ Prerequisites & Installation
### Prerequisites
- **Python 3.11+**
- **Wireshark / TShark 4.x+**
#### Linux (Ubuntu/Debian)
```bash
sudo apt update
sudo apt install -y tshark wireshark-common
```
#### macOS
```bash
brew install wireshark
```
### Installation
1. **Clone the repository:**
```bash
git clone https://github.com/tejaswipandey3931l-coder/wireshark-mcp.git
cd wireshark-mcp
```
2. **Set up Python Virtual Environment:**
```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```
3. **Initialize Environment Configuration:**
```bash
cp .env.example .env
```
---
## 🔌 MCP Client Configuration
Add to your `claude_desktop_config.json` or Cursor MCP settings:
```json
{
"mcpServers": {
"wireshark": {
"command": "/absolute/path/to/wireshark-mcp/.venv/bin/python",
"args": [
"/absolute/path/to/wireshark-mcp/server.py"
]
}
}
}
```
---
## 📚 Documentation Structure
- [`docs/00_project_governance/`](file:///home/sosuke/Desktop/wireshark-mcp/docs/00_project_governance/): Project governance rules & workflow guidelines.
- [`docs/01_requirements/`](file:///home/sosuke/Desktop/wireshark-mcp/docs/01_requirements/): Requirements Traceability Matrix (`REQUIREMENTS_TRACEABILITY_MATRIX.md`) and SRS summary.
- [`docs/02_architecture/`](file:///home/sosuke/Desktop/wireshark-mcp/docs/02_architecture/): System Architecture & Data Flow diagrams.
- [`docs/03_implementation/`](file:///home/sosuke/Desktop/wireshark-mcp/docs/03_implementation/): Phase implementation roadmaps (`PHASE_0_REPOSITORY_AUDIT.md` through `PHASE_8_RELEASE_HARDENING.md`).
- [`docs/04_verification/`](file:///home/sosuke/Desktop/wireshark-mcp/docs/04_verification/): Test strategy & acceptance criteria.
- [`docs/05_reports/`](file:///home/sosuke/Desktop/wireshark-mcp/docs/05_reports/): Formal Phase reports (`PHASE_1_REPORT.md` through `PHASE_4_REPORT.pdf`).
---
## 🧪 Testing Instructions
Run the automated pytest suite:
```bash
.venv/bin/pytest tests/ -v --tb=short
```
Expected output baseline:
```text
======================= 106 passed in 189.06s (0:03:09) ========================
```
---
## 🗺 Current Roadmap
- [x] **Phase 0** — Repository Audit & Baseline Mapping
- [x] **Phase 1** — Canonical Result Model Definition (Gate G1 Passed)
- [x] **Phase 2** — Ingestion & Parser Hardening (Gate G2 Passed)
- [x] **Phase 3** — Detection Engine & Ruleset Refinement (Gate G3 Passed)
- [x] **Phase 4** — Evidence Correlation & Deduplication (Gate G4 Passed - Pending Review)
- [ ] **Phase 5** — Formal Reporting & Report Redesign
- [ ] **Phase 6** — REST API, Web UI & MCP Tool Integration
- [ ] **Phase 7** — Security, Performance & Scalability Hardening
- [ ] **Phase 8** — Final Verification, Documentation & Release Hardening
---
## ⚠️ Known Limitations
1. **Encrypted HTTPS Traffic**: Encrypted TLS sessions require an SSL keylog file (`SSLKEYLOGFILE`) for payload decryption; without keylogs, reassembly operates on ciphertext bytes.
2. **Proprietary Protocols**: Non-standard application protocols without TShark dissectors fall back to raw TCP/UDP payload pattern scanning.
3. **Accuracy Scope**: Baseline metrics represent unit-level benchmark evaluations on controlled test corpora; large-scale real-world evaluation remains in progress.
---
## 📄 License
Licensed under the **MIT License** — see [`LICENSE`](file:///home/sosuke/Desktop/wireshark-mcp/LICENSE) for details.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo issues