Wireshark MCP — Packet Intelligence Platform
Wraps Wireshark's tshark packet inspection engine to analyze PCAP/PCAPNG capture files. Provides tools for packet inspection, TCP/UDP stream reassembly with gap detection, payload artifact extraction with SHA-256 deduplication, rule-based CTF flag and credential detection, heuristic anomaly detection (port scans, SYN floods, C2 beaconing, ICMP floods, large transfers), and generation of PDF/Markdown forensic reports.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Wireshark MCP — Packet Intelligence Platform 🦈🌐
Evidence-driven network packet analysis and forensics platform built with Wireshark, TShark, Python, FastMCP, and React.
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
Related MCP server: Wireshark MCP
🔍 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-001throughFR-018,NFR-001throughNFR-012) are tracked indocs/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
ExtractedObjectmodel 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.
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 |
| Fully validated match with zero ambiguity. | Explicit CTF flags ( |
| Matched pattern requires analyst review. | Credentials in passive capture ( |
| Contextual indicator or dummy placeholder. | RFC1918 internal traffic ( |
| Alert generated by statistical/threshold rule. | TCP port scan, SYN flood, C2 beaconing, large data exfiltration. |
🔄 TCP Stream Reassembly & Evidence Correlation
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.
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
ExtractedObjectModel (models/extracted_object.py):Encapsulates exported payload objects with SHA-256
content_hash,filename,media_type,size_bytes,occurrence_count,source_ips,dest_ips, andpacket_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)
sudo apt update
sudo apt install -y tshark wireshark-commonmacOS
brew install wiresharkInstallation
Clone the repository:
git clone https://github.com/tejaswipandey3931l-coder/wireshark-mcp.git cd wireshark-mcpSet up Python Virtual Environment:
python -m venv .venv source .venv/bin/activate pip install -r requirements.txtInitialize Environment Configuration:
cp .env.example .env
🔌 MCP Client Configuration
Add to your claude_desktop_config.json or Cursor MCP settings:
{
"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/: Project governance rules & workflow guidelines.docs/01_requirements/: Requirements Traceability Matrix (REQUIREMENTS_TRACEABILITY_MATRIX.md) and SRS summary.docs/02_architecture/: System Architecture & Data Flow diagrams.docs/03_implementation/: Phase implementation roadmaps (PHASE_0_REPOSITORY_AUDIT.mdthroughPHASE_8_RELEASE_HARDENING.md).docs/04_verification/: Test strategy & acceptance criteria.docs/05_reports/: Formal Phase reports (PHASE_1_REPORT.mdthroughPHASE_4_REPORT.pdf).
🧪 Testing Instructions
Run the automated pytest suite:
.venv/bin/pytest tests/ -v --tb=shortExpected output baseline:
======================= 106 passed in 189.06s (0:03:09) ========================🗺 Current Roadmap
Phase 0 — Repository Audit & Baseline Mapping
Phase 1 — Canonical Result Model Definition (Gate G1 Passed)
Phase 2 — Ingestion & Parser Hardening (Gate G2 Passed)
Phase 3 — Detection Engine & Ruleset Refinement (Gate G3 Passed)
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
Encrypted HTTPS Traffic: Encrypted TLS sessions require an SSL keylog file (
SSLKEYLOGFILE) for payload decryption; without keylogs, reassembly operates on ciphertext bytes.Proprietary Protocols: Non-standard application protocols without TShark dissectors fall back to raw TCP/UDP payload pattern scanning.
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 for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Enrich, search, assess, and manage threat intelligence through 80+ typed MCP tools.
Zero-log MCP server with 49 tools for AI guardrails, secret scanning, MCP linting & EU compliance.
491Zero-config MCP security scanner for AI-generated apps. 25K+ vulnerability patterns.
Audit your MCP servers for poisoned tools and leaked secrets, and check AI-generated code for flaws.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI-assisted network packet analysis using Wireshark's TShark tool. It provides tools for pcap file overview, session extraction, protocol filtering, and statistical analysis through a standardized interface.1MIT
- AlicenseCqualityBmaintenanceAn MCP server that enables LLMs to analyze pcap files by providing tools for packet dissection, stream following, and data extraction via tshark. It supports protocol hierarchy analysis, credential scanning, and threat intelligence checks on captured network traffic.54582 PyPI379MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server for offline network forensic analysis and threat intelligence, enabling LLMs to analyze PCAP files, extract streams, detect threats, and identify credentials using tshark.6MIT
- AlicenseNot gradedqualityCmaintenanceBridges AI assistants and network packet analysis by exposing Wireshark/TShark functionality through MCP, enabling PCAP investigation, protocol discovery, packet filtering, stream analysis, and live capture.MIT