MCP Network Forensics

A case-oriented MCP Server for Network Forensics that turns PCAP evidence into a reproducible local investigation: capture manifests, normalized flows/events, IOC pivots, timelines, deterministic findings, stream reconstruction, and quarantined artifacts. TShark remains the dissector backend, not the user-facing workflow.

Features

• Case-centric workflow: Register and hash evidence once, then reuse a local SQLite index
• Evidence provenance: Findings contain capture, frame, stream, and reproduction references
• Deterministic triage: Scan, beacon, DNS tunneling, outbound volume, and lateral-movement heuristics
• Bounded execution: Streaming TShark runner, timeout/cancellation, output budgets, and isolated artifacts
• MCP-native output: Typed tools, pagination, background jobs, and reusable resources
• Optional engine adapters: Offline Zeek JSON logs, Suricata EVE alerts, and YARA artifact matches
• Deep Packet Inspection: Access to all Wireshark dissectors (1000+ protocols)
• Advanced Filtering: Support for all Wireshark display filters
• Protocol Analysis: Automatic statistics and distribution analysis
• Security First: Path validation, size limits, input sanitization
• Memory Efficient: Streaming extraction and indexed warm queries for large files
• Auto-Detection: Automatically finds tshark installation

Performance Model

The first index_capture pass reads the PCAP through a bounded streaming TShark process and writes normalized facts to SQLite. Repeated flow, event, IOC, timeline, and finding queries use that local index and do not launch a new TShark process. Runtime depends on dissectors, storage, and capture shape; benchmark your own evidence corpus rather than relying on fixed timings.

Reproducible Benchmark

Run the executable benchmark against a real PCAP/PCAPNG. It reports registration time, cold indexing time, p50/p95 warm-query latency, peak RSS, and whether the configured file/output/response budgets held. Use a fresh case root for a cold measurement:

python benchmarks/benchmark_case.py /absolute/path/to/large.pcapng \
  --case-root /tmp/mcp-network-forensics-benchmark \
  --queries 10 \
  --max-rss-bytes 2147483648 \
  --json-out /tmp/mcp-network-forensics-benchmark.json

The harness does not fabricate a target size or timing claim. For PCAPs near the 10 GB default file limit, allow sufficient disk space for the SQLite case index and use --force only when intentionally repeating a cold index.

Requirements

• Python 3.9+
• Wireshark/tshark (4.0+) and capinfos installed
• MCP-compatible client (Claude Desktop, VSCode, Cline, etc.)
• Optional: Zeek, Suricata, and YARA installed locally for their adapters

Installation

1. Install Wireshark

Ubuntu/Debian:

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

macOS:

brew install wireshark

Windows: Download from wireshark.org

Verify installation:

tshark --version
capinfos --version  # Optional, for faster packet counting

2. Install MCP Server

# Clone repository
git clone https://github.com/yourusername/mcp-network-forensics.git
cd mcp-network-forensics

# Create virtual environment
python -m venv venv
source venv/bin/activate  # Linux/Mac
# or: venv\Scripts\activate  # Windows

# Install package
pip install -e .

Configuration

Claude Desktop

Edit claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "network-forensics": {
      "command": "python",
      "args": ["-m", "mcp_network_forensics"],
      "env": {
        "MCP_MAX_FILE_SIZE": "10737418240",
        "MCP_MAX_PACKETS": "10000",
        "TSHARK_PATH": "/usr/bin/tshark"
      }
    }
  }
}

VSCode (with Cline extension)

Add to your settings:

{
  "mcpServers": {
    "network-forensics": {
      "command": "python",
      "args": ["-m", "mcp_network_forensics"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

Available Tools

DFIR workflow

1. open_capture(file_path) creates a SHA-256-backed capture manifest.
2. index_capture(capture_id) builds the normalized frame/flow/event index. Set background=true for a job.
3. triage_capture(capture_id) returns ranked findings and top entities.
4. query_flows, query_events, pivot_iocs, and get_entity_timeline perform warm indexed pivots.
5. reconstruct_stream, export_objects, and preview_artifact handle bounded content safely.
6. get_capture_health and inspect_capture_health expose integrity and expert diagnostics.
7. run_zeek_adapter, run_suricata_adapter, and run_yara_adapter invoke optional local engines with fixed offline commands and bounded output. Use parse_zeek_adapter, parse_suricata_adapter, and parse_yara_adapter to normalize existing tool output without executing an engine.

Optional Engine Adapters

Adapters never install tools, open sockets, or accept arbitrary child-process arguments. list_plugins() reports capability state without claiming an engine is installed. Missing binaries return status: "unavailable" with a warning.

• Zeek: zeek -r <pcap> LogAscii::use_json=T Log::default_logdir=<managed-dir>. Normalizes conn, dns, http, ssl, and notice-style JSON records and preserves original fields under fields.
• Suricata: suricata -c <yaml> -r <pcap> -l <managed-dir>. Requires an operator-supplied YAML configuration so EVE output policy is explicit. Normalizes EVE events and exposes alert records with pcap_cnt when present.
• YARA: yara -a <timeout> <rules> --scan-list <managed-list>. Skips symlinks, bounds file count and file size, and normalizes standard RULE PATH matches.

Each adapter returns mcp-network-forensics.plugin-result.v1 with status, records, warnings, truncation state, duration, and network_access: false. Versioned command policies are stored in src/mcp_network_forensics/plugins/manifests/.

Compatibility packet tools remain available below, but they are bounded adapters. Prefer the case workflow for investigation.

Compatibility packet tools

#### analyze_pcap_file Analyze a PCAP file and return summary statistics.

Parameters:

• file_path: Absolute path to PCAP file (required)
• packet_limit: Maximum packets to analyze (default: 1000)
• display_filter: Optional Wireshark display filter

Example:

{
  "file_path": "/home/user/captures/traffic.pcap",
  "packet_limit": 100,
  "display_filter": "ip.addr == 192.168.1.1"
}

#### get_packet_details Get detailed information about a specific packet.

Parameters:

• file_path: Absolute path to PCAP file
• packet_index: Index of packet (0-based)
• include_layers: Include layer information (default: true)

Example:

{
  "file_path": "/home/user/captures/traffic.pcap",
  "packet_index": 0,
  "include_layers": true
}

#### filter_packets Filter packets using Wireshark display filter syntax.

Parameters:

• file_path: Absolute path to PCAP file
• display_filter: Wireshark filter (e.g., "tcp.port == 80", "http", "dns.qry.name contains 'google'")
• max_results: Maximum results to return (default: 100)

Example:

{
  "file_path": "/home/user/captures/traffic.pcap",
  "display_filter": "tcp.flags.syn == 1 and tcp.flags.ack == 0",
  "max_results": 50
}

#### get_protocol_statistics Get protocol distribution statistics.

Parameters:

• file_path: Absolute path to PCAP file
• packet_limit: Maximum packets to analyze (default: 1000)

Example:

{
  "file_path": "/home/user/captures/traffic.pcap",
  "packet_limit": 1000
}

#### extract_unique_ips Extract unique IP addresses from the capture.

Parameters:

• file_path: Absolute path to PCAP file

Example:

{
  "file_path": "/home/user/captures/traffic.pcap"
}

Usage Examples

Basic Analysis

Please analyze this PCAP file and show me the protocol distribution.
File: /home/user/captures/traffic.pcap

Threat Hunting

Find all HTTP requests to external IPs in this capture.
File: /home/user/captures/web.pcap

Network Troubleshooting

Show me all TCP SYN packets without ACK (possible port scan).
File: /home/user/captures/suspicious.pcap

Deep Inspection

Get detailed information about packet 100, including all layers.
File: /home/user/captures/malware.pcap

Security Features

• Path Validation: Only absolute paths allowed, no directory traversal
• File Size Limits: Configurable max file size (default: 10GB)
• Packet Limits: Configurable max packets per request (default: 10,000)
• Filter Validation: Syntax is checked by TShark; valid operators such as >, <, &, and | remain available
• Timeout Protection: Request timeout configuration (default: 300s)
• Response Budgets: Bounded MCP responses, extraction output, stderr, and artifact bytes
• Evidence Roots: Optional MCP_ALLOWED_ROOTS allowlist for input captures
• Plugin Boundary: Plugins must be pre-installed, hash-validated, offline, and manifest-bounded

Environment Variables

Architecture

MCP client
    |
    v
FastMCP tools/resources
    |
Case registry + bounded jobs
    |
Streaming TShark runner
    |
SQLite normalized index + quarantined artifacts
    |
Deterministic triage/detections + optional plugins

Project Structure

mcp-network-forensics/
├── src/mcp_network_forensics/
│   ├── server.py                 # Typed MCP tools/resources
│   ├── core/tshark_runner.py     # Bounded subprocess execution
│   ├── core/jobs.py              # Background jobs/cancellation
│   ├── storage/case_store.py     # SQLite case registry/index
│   ├── storage/artifact_store.py # Quarantined content-addressed objects
│   ├── analysis/triage.py        # Explainable DFIR detections
│   ├── plugins/adapters.py       # Zeek, Suricata, and YARA offline adapters
│   ├── plugins/manifests/         # Versioned command/output policies
│   ├── plugins/runner.py          # Generic manifest-driven plugins
│   ├── capture/                  # Compatibility adapters
│   ├── models/                   # Versioned Pydantic contracts
│   └── utils/                    # Validation and formatting
├── pyproject.toml
├── requirements.txt
├── requirements-dev.txt
└── README.md

Development

Setup Development Environment

pip install -e ".[dev]"

Code Quality

black src
isort src
flake8 src
mypy src
pytest

Coverage is optional when pytest-cov is installed:

pytest --cov=mcp_network_forensics --cov-report=term-missing

Troubleshooting

tshark not found

# Check installation
which tshark  # Linux/Mac
where tshark  # Windows

# Set path manually
export TSHARK_PATH=/usr/bin/tshark  # Linux/Mac
set TSHARK_PATH=C:\Program Files\Wireshark\tshark.exe  # Windows

Timeout errors on large files

Increase timeout or reduce requested scope. Indexing can run in the background and be monitored with get_job_status:

export MCP_TIMEOUT=600
export MCP_MAX_PACKETS=5000

License

MIT License - see LICENSE file for details.

Acknowledgments

• Wireshark - Network protocol analyzer
• Model Context Protocol - MCP specification
• FastMCP - Python MCP SDK

Support

For issues and feature requests, please use the GitHub issue tracker.