Wireshark MCP — Packet Intelligence Platform 🦈🌐

Evidence-driven network packet analysis and forensics platform built with Wireshark, TShark, Python, FastMCP, and React.

📌 Table of Contents

• Overview

• Project Governance & Verification Baseline

• Key Features

• Architecture & Core Data Contract

• Detection Engine & Confidence Model

• TCP Stream Reassembly & Evidence Correlation

• Artifact Deduplication & Forensic Provenance

• Prerequisites & Installation

• MCP Client Configuration

• Documentation Structure

• Testing Instructions

• Current Roadmap

• Known Limitations

• License

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-001 through FR-018, NFR-001 through NFR-012) are tracked in 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.

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:

🔄 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)

sudo apt update
sudo apt install -y tshark wireshark-common

macOS

brew install wireshark

Installation

1. Clone the repository:

   git clone https://github.com/tejaswipandey3931l-coder/wireshark-mcp.git
   cd wireshark-mcp

2. Set up Python Virtual Environment:

   python -m venv .venv
   source .venv/bin/activate
   pip install -r requirements.txt

3. Initialize 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.md through PHASE_8_RELEASE_HARDENING.md).

• docs/04_verification/: Test strategy & acceptance criteria.

• docs/05_reports/: Formal Phase reports (PHASE_1_REPORT.md through PHASE_4_REPORT.pdf).

🧪 Testing Instructions

Run the automated pytest suite:

.venv/bin/pytest tests/ -v --tb=short

Expected 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

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 for details.