network-forensics-mcp-server

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: ``bash sudo apt-get update sudo apt-get install tshark wireshark-common ``

macOS: ``bash brew install wireshark ``

Windows: Download from wireshark.org

Verify installation: ``bash 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: ``json { "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: ``json { "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: ``json { "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: ``json { "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: ``json { "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

| Variable | Description | Default | |----------|-------------|---------| | MCP_SERVER_NAME | Server name | mcp-network-forensics | | MCP_MAX_FILE_SIZE | Max file size in bytes | 10737418240 (10GB) | | MCP_MAX_PACKETS | Max packets per request | 10000 | | MCP_TIMEOUT | Request timeout in seconds | 300 | | MCP_RESPONSE_BYTES | Maximum inline response bytes | 1048576 | | MCP_EXTRACTION_BYTES | Maximum streamed TShark output bytes | 21474836480 | | MCP_ARTIFACT_BYTES | Maximum bytes exported per object operation | 52428800 | | MCP_MAX_CONCURRENT_JOBS | Maximum disk-heavy background jobs | 2 | | MCP_PLUGIN_MEMORY_BYTES | Address-space limit for optional engine adapters | 2147483648 (2GB) | | MCP_CASE_ROOT | SQLite/artifact/plugin workspace | ~/.mcp-network-forensics | | MCP_ALLOWED_ROOTS | OS path-separator-delimited evidence allowlist | unset | | WIRESHARK_PROFILE | Explicit Wireshark profile | unset | | MCP_NAME_RESOLUTION | Enable name resolution | false | | TSHARK_PATH | Path to tshark binary | auto-detect | | ZEEK_PATH | Path to Zeek binary | auto-detect | | SURICATA_PATH | Path to Suricata binary | auto-detect | | SURICATA_CONFIG | Default Suricata YAML configuration | unset; required by adapter | | YARA_PATH | Path to YARA binary | auto-detect |

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: ``bash 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.