mcpcap 0.2.1__py3-none-any.whl

mcpcap/__init__.py

@@ -0,0 +1,38 @@
+"""mcpcap - A modular Python MCP Server for analyzing PCAP files.
+
+mcpcap provides a comprehensive solution for analyzing network packet captures (PCAP files)
+through the Model Context Protocol (MCP). It enables LLMs to perform network traffic analysis
+with support for DNS protocol analysis and extensible architecture for additional protocols.
+
+Key Features:
+    - Modular architecture for easy protocol extension
+    - Robust DNS packet analysis with error handling
+    - MCP integration for seamless LLM interaction
+    - Security-focused analysis prompts and indicators
+    - Support for both .pcap and .pcapng file formats
+
+Example:
+    Start the MCP server with a directory containing PCAP files::
+
+        $ mcpcap --pcap-path /path/to/pcap/files
+
+    Then connect with an MCP client to analyze DNS traffic.
+"""
+
+# Dynamic version detection
+try:
+    # First try to import from _version.py (created by setuptools-scm in built packages)
+    from ._version import version as __version__
+except ImportError:
+    try:
+        # Fall back to setuptools_scm for development environments
+        from setuptools_scm import get_version
+
+        __version__ = get_version(root="..", relative_to=__file__)
+    except (ImportError, LookupError):
+        # Final fallback for cases where setuptools_scm isn't available
+        __version__ = "dev-unknown"
+
+from .cli import main
+
+__all__ = ["main", "__version__"]

mcpcap/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '0.2.1'
+__version_tuple__ = version_tuple = (0, 2, 1)
+
+__commit_id__ = commit_id = None

mcpcap/cli.py

@@ -0,0 +1,54 @@
+"""CLI entry point for mcpcap.
+
+This module provides the command-line interface for mcpcap, handling argument parsing
+and server initialization.
+"""
+
+import argparse
+
+from .core import Config, MCPServer
+
+
+def main():
+    """Main function to parse arguments and start the MCP server.
+
+    Parses command-line arguments, initializes the configuration and MCP server,
+    and handles graceful shutdown and error conditions.
+
+    Returns:
+        int: Exit code (0 for success, 1 for error)
+
+    Raises:
+        ValueError: If the provided PCAP path is invalid
+        KeyboardInterrupt: If the user interrupts the server
+        Exception: For any unexpected errors during server operation
+    """
+    parser = argparse.ArgumentParser(description="PCAP DNS Analyzer MCP Server")
+    parser.add_argument(
+        "--pcap-path", required=True, help="Path to directory containing PCAP files"
+    )
+
+    args = parser.parse_args()
+
+    try:
+        # Initialize configuration
+        config = Config(args.pcap_path)
+
+        # Create and start MCP server
+        server = MCPServer(config)
+        server.run()
+        return 0
+
+    except ValueError as e:
+        print(f"Error: {e}")
+        return 1
+    except KeyboardInterrupt:
+        print("\\nServer stopped by user")
+        return 0
+    except Exception as e:
+        print(f"Unexpected error: {e}")
+        return 1
+
+
+if __name__ == "__main__":
+    exit(main())

mcpcap/core/__init__.py

@@ -0,0 +1,6 @@
+"""Core components for mcpcap."""
+
+from .config import Config
+from .server import MCPServer
+
+__all__ = ["MCPServer", "Config"]

mcpcap/core/config.py

@@ -0,0 +1,52 @@
+"""Configuration management for mcpcap."""
+
+import os
+
+
+class Config:
+    """Configuration management for mcpcap server."""
+
+    def __init__(self, pcap_path: str):
+        """Initialize configuration.
+
+        Args:
+            pcap_path: Path to directory containing PCAP files
+        """
+        self.pcap_path = pcap_path
+        self._validate_pcap_path()
+
+    def _validate_pcap_path(self) -> None:
+        """Validate that the PCAP path exists and is a directory."""
+        if not os.path.exists(self.pcap_path):
+            raise ValueError(f"PCAP directory '{self.pcap_path}' does not exist")
+
+        if not os.path.isdir(self.pcap_path):
+            raise ValueError(f"'{self.pcap_path}' is not a directory")
+
+    def get_pcap_file_path(self, pcap_file: str) -> str:
+        """Get full path to a PCAP file.
+
+        Args:
+            pcap_file: Filename or relative path to PCAP file
+
+        Returns:
+            Full path to the PCAP file
+        """
+        if os.path.isabs(pcap_file):
+            return pcap_file
+        return os.path.join(self.pcap_path, pcap_file)
+
+    def list_pcap_files(self) -> list[str]:
+        """List all PCAP files in the configured directory.
+
+        Returns:
+            List of PCAP filenames
+        """
+        try:
+            return [
+                f
+                for f in os.listdir(self.pcap_path)
+                if f.endswith((".pcap", ".pcapng"))
+            ]
+        except Exception:
+            return []

mcpcap/core/server.py

@@ -0,0 +1,41 @@
+"""MCP server setup and configuration."""
+
+from fastmcp import FastMCP
+
+from ..modules.dns import DNSModule
+from ..resources.references import setup_resources
+from .config import Config
+
+
+class MCPServer:
+    """MCP server for PCAP analysis."""
+
+    def __init__(self, config: Config):
+        """Initialize MCP server.
+
+        Args:
+            config: Configuration instance
+        """
+        self.config = config
+        self.mcp = FastMCP("PCAP DNS Analyzer")
+
+        # Initialize modules
+        self.dns_module = DNSModule(config)
+
+        # Register tools
+        self._register_tools()
+
+        # Setup resources and prompts
+        setup_resources(self.mcp)
+        self.dns_module.setup_prompts(self.mcp)
+
+    def _register_tools(self) -> None:
+        """Register all available tools with the MCP server."""
+        # Register DNS module tools
+        self.mcp.tool(self.dns_module.list_dns_packets)
+        self.mcp.tool(self.dns_module.list_pcap_files)
+
+    def run(self) -> None:
+        """Start the MCP server."""
+        print(f"Starting MCP server with PCAP directory: {self.config.pcap_path}")
+        self.mcp.run()

mcpcap/modules/__init__.py

@@ -0,0 +1,6 @@
+"""Protocol analysis modules for mcpcap."""
+
+from .base import BaseModule
+from .dns import DNSModule
+
+__all__ = ["BaseModule", "DNSModule"]

mcpcap/modules/base.py

@@ -0,0 +1,36 @@
+"""Base module interface for protocol analyzers."""
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from ..core.config import Config
+
+
+class BaseModule(ABC):
+    """Base class for protocol analysis modules."""
+
+    def __init__(self, config: Config):
+        """Initialize the module.
+
+        Args:
+            config: Configuration instance
+        """
+        self.config = config
+
+    @abstractmethod
+    def analyze_packets(self, pcap_file: str) -> dict[str, Any]:
+        """Analyze packets in a PCAP file.
+
+        Args:
+            pcap_file: Path to the PCAP file
+
+        Returns:
+            Analysis results as a dictionary
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def protocol_name(self) -> str:
+        """Return the name of the protocol this module analyzes."""
+        pass

mcpcap/modules/dns.py

@@ -0,0 +1,349 @@
+"""DNS analysis module."""
+
+import os
+from datetime import datetime
+from typing import Any
+
+from fastmcp import FastMCP
+from scapy.all import DNS, IP, TCP, UDP, IPv6, rdpcap
+
+from .base import BaseModule
+
+
+class DNSModule(BaseModule):
+    """Module for analyzing DNS packets in PCAP files."""
+
+    @property
+    def protocol_name(self) -> str:
+        """Return the name of the protocol this module analyzes."""
+        return "DNS"
+
+    def list_dns_packets(self, pcap_file: str = "example.pcap") -> dict[str, Any]:
+        """
+        Analyze DNS packets from a PCAP file and return a summary of each packet.
+
+        Args:
+            pcap_file: Path to the PCAP file to analyze (defaults to 'example.pcap')
+
+        Returns:
+            A structured dictionary containing DNS packet analysis results
+        """
+        # Get full path to PCAP file
+        full_path = self.config.get_pcap_file_path(pcap_file)
+
+        # Check if file exists
+        if not os.path.exists(full_path):
+            # List available PCAP files for help
+            available_files = self.config.list_pcap_files()
+            return {
+                "error": f"PCAP file '{pcap_file}' not found",
+                "available_files": available_files,
+                "pcap_directory": self.config.pcap_path,
+            }
+
+        return self.analyze_packets(full_path)
+
+    def list_pcap_files(self) -> str:
+        """
+        List all available PCAP files in the default directory.
+
+        Returns:
+            A list of available PCAP files that can be analyzed
+        """
+        files = self.config.list_pcap_files()
+        if files:
+            return f"Available PCAP files in {self.config.pcap_path}:\\n" + "\\n".join(
+                f"- {f}" for f in sorted(files)
+            )
+        else:
+            return f"No PCAP files found in {self.config.pcap_path}"
+
+    def analyze_packets(self, pcap_file: str) -> dict[str, Any]:
+        """Analyze DNS packets in a PCAP file.
+
+        Args:
+            pcap_file: Full path to the PCAP file
+
+        Returns:
+            Analysis results as a dictionary
+        """
+        try:
+            packets = rdpcap(pcap_file)
+            dns_packets = [pkt for pkt in packets if pkt.haslayer(DNS)]
+
+            if not dns_packets:
+                return {
+                    "file": pcap_file,
+                    "total_packets": len(packets),
+                    "dns_packets_found": 0,
+                    "message": "No DNS packets found in this capture",
+                }
+
+            packet_details = []
+            for i, pkt in enumerate(dns_packets, 1):
+                packet_info = self._analyze_dns_packet(pkt, i)
+                packet_details.append(packet_info)
+
+            # Generate statistics
+            stats = self._generate_statistics(packet_details)
+
+            result = {
+                "file": pcap_file,
+                "analysis_timestamp": datetime.now().isoformat(),
+                "total_packets_in_file": len(packets),
+                "dns_packets_found": len(dns_packets),
+                "statistics": stats,
+                "packets": packet_details,
+            }
+
+            return result
+
+        except Exception as e:
+            return {
+                "error": f"Error reading PCAP file '{pcap_file}': {str(e)}",
+                "file": pcap_file,
+            }
+
+    def _analyze_dns_packet(self, pkt: Any, packet_number: int) -> dict[str, Any]:
+        """Analyze a single DNS packet.
+
+        Args:
+            pkt: Scapy packet object
+            packet_number: Packet sequence number
+
+        Returns:
+            Dictionary containing packet analysis
+        """
+        dns_layer = pkt[DNS]
+
+        # Extract IP information
+        src_ip = dst_ip = "unknown"
+        if pkt.haslayer(IP):
+            src_ip = pkt[IP].src
+            dst_ip = pkt[IP].dst
+        elif pkt.haslayer(IPv6):
+            src_ip = pkt[IPv6].src
+            dst_ip = pkt[IPv6].dst
+
+        # Extract protocol (UDP/TCP)
+        protocol = "unknown"
+        if pkt.haslayer(UDP):
+            protocol = "UDP"
+        elif pkt.haslayer(TCP):
+            protocol = "TCP"
+
+        # Extract DNS questions
+        questions = []
+        if dns_layer.qd:
+            for q in dns_layer.qd:
+                try:
+                    name = (
+                        q.qname.decode().rstrip(".")
+                        if hasattr(q.qname, "decode")
+                        else str(q.qname).rstrip(".")
+                    )
+                    questions.append(
+                        {
+                            "name": name,
+                            "type": getattr(q, "qtype", 0),
+                            "class": getattr(q, "qclass", 0),
+                        }
+                    )
+                except (AttributeError, UnicodeDecodeError) as e:
+                    # Skip malformed questions but log the issue
+                    questions.append(
+                        {
+                            "name": f"<parsing_error: {str(e)}>",
+                            "type": getattr(q, "qtype", 0),
+                            "class": getattr(q, "qclass", 0),
+                        }
+                    )
+
+        # Extract DNS answers
+        answers = []
+        if dns_layer.an:
+            for a in dns_layer.an:
+                try:
+                    # Safely extract the resource record name
+                    if hasattr(a, "rrname"):
+                        if hasattr(a.rrname, "decode"):
+                            name = a.rrname.decode().rstrip(".")
+                        else:
+                            name = str(a.rrname).rstrip(".")
+                    else:
+                        name = "<unknown>"
+
+                    answer_data = {
+                        "name": name,
+                        "type": getattr(a, "type", 0),
+                        "class": getattr(a, "rclass", 0),
+                        "ttl": getattr(a, "ttl", 0),
+                    }
+
+                    # Handle different answer types
+                    if hasattr(a, "rdata"):
+                        try:
+                            if a.type == 1:  # A record
+                                answer_data["address"] = str(a.rdata)
+                            elif a.type == 28:  # AAAA record
+                                answer_data["address"] = str(a.rdata)
+                            elif a.type == 5:  # CNAME
+                                answer_data["cname"] = str(a.rdata).rstrip(".")
+                            elif a.type == 15:  # MX
+                                answer_data["mx"] = str(a.rdata)
+                            else:
+                                answer_data["data"] = str(a.rdata)
+                        except Exception as rdata_error:
+                            answer_data["data"] = (
+                                f"<rdata_parsing_error: {str(rdata_error)}>"
+                            )
+
+                    answers.append(answer_data)
+
+                except (AttributeError, UnicodeDecodeError) as e:
+                    # Skip malformed answers but include error info
+                    answers.append(
+                        {
+                            "name": f"<parsing_error: {str(e)}>",
+                            "type": getattr(a, "type", 0),
+                            "class": getattr(a, "rclass", 0),
+                            "ttl": getattr(a, "ttl", 0),
+                            "data": "<malformed_record>",
+                        }
+                    )
+
+        return {
+            "packet_number": packet_number,
+            "timestamp": datetime.fromtimestamp(float(pkt.time)).isoformat(),
+            "source_ip": src_ip,
+            "destination_ip": dst_ip,
+            "protocol": protocol,
+            "dns_id": dns_layer.id,
+            "flags": {
+                "is_response": bool(dns_layer.qr),
+                "authoritative": bool(dns_layer.aa),
+                "truncated": bool(dns_layer.tc),
+                "recursion_desired": bool(dns_layer.rd),
+                "recursion_available": bool(dns_layer.ra),
+            },
+            "questions": questions,
+            "answers": answers,
+            "summary": pkt.summary(),
+        }
+
+    def _generate_statistics(self, packet_details: list) -> dict[str, Any]:
+        """Generate statistics from analyzed packets.
+
+        Args:
+            packet_details: List of analyzed packet dictionaries
+
+        Returns:
+            Dictionary containing statistics
+        """
+        query_count = sum(1 for p in packet_details if not p["flags"]["is_response"])
+        response_count = sum(1 for p in packet_details if p["flags"]["is_response"])
+        unique_domains = set()
+        for p in packet_details:
+            for q in p["questions"]:
+                unique_domains.add(q["name"])
+
+        return {
+            "queries": query_count,
+            "responses": response_count,
+            "unique_domains_queried": len(unique_domains),
+            "unique_domains": list(unique_domains),
+        }
+
+    def setup_prompts(self, mcp: FastMCP) -> None:
+        """Set up DNS-specific analysis prompts for the MCP server.
+
+        Args:
+            mcp: FastMCP server instance
+        """
+
+        @mcp.prompt
+        def security_analysis():
+            """Prompt for analyzing DNS traffic from a security perspective"""
+            return """You are a cybersecurity analyst examining DNS traffic. Focus your analysis on:
+
+1. **Threat Detection:**
+   - Look for suspicious domain patterns (DGA, long random strings)
+   - Identify potential DNS tunneling (unusually long queries, high TXT record volume)
+   - Spot potential C2 communication patterns
+   - Check for queries to known malicious domains
+
+2. **Behavioral Analysis:**
+   - Identify unusual query frequencies or patterns
+   - Look for reconnaissance activities (PTR lookups, zone transfers)
+   - Check for DNS cache poisoning attempts
+   - Monitor for subdomain enumeration
+
+3. **Infrastructure Assessment:**
+   - Identify DNS servers being used
+   - Check for DNS over non-standard ports
+   - Look for failed queries (NXDOMAIN) patterns
+   - Assess query distribution across time
+
+Provide specific examples and recommend follow-up investigations for any suspicious findings."""
+
+        @mcp.prompt
+        def network_troubleshooting():
+            """Prompt for troubleshooting DNS-related network issues"""
+            return """You are a network engineer troubleshooting DNS issues. Focus on:
+
+1. **Performance Issues:**
+   - Identify slow DNS responses (high latency)
+   - Look for timeouts and retransmissions
+   - Check for load balancing issues
+   - Analyze response times across different servers
+
+2. **Connectivity Problems:**
+   - Find failed DNS queries and their causes
+   - Identify unreachable DNS servers
+   - Look for network path issues
+   - Check for DNS server failures
+
+3. **Configuration Issues:**
+   - Verify proper DNS server assignments
+   - Check for mismatched recursion settings
+   - Look for incorrect domain configurations
+   - Identify forwarding problems
+
+4. **Capacity Planning:**
+   - Analyze query volumes and patterns
+   - Identify peak usage times
+   - Look for resource exhaustion indicators
+   - Assess server response capabilities
+
+Provide actionable recommendations for resolving identified issues."""
+
+        @mcp.prompt
+        def forensic_investigation():
+            """Prompt for forensic analysis of DNS traffic"""
+            return """You are conducting a digital forensics investigation involving DNS traffic. Approach this systematically:
+
+1. **Timeline Reconstruction:**
+   - Create a chronological sequence of DNS events
+   - Correlate DNS queries with potential incident timeframes
+   - Identify patterns in query timing and frequency
+   - Map DNS activity to user/system behavior
+
+2. **Evidence Collection:**
+   - Document all suspicious or anomalous DNS queries
+   - Preserve query-response pairs for analysis
+   - Record DNS server interactions and responses
+   - Note any encrypted or tunneled DNS traffic
+
+3. **Attribution and Tracking:**
+   - Trace DNS queries to source systems/users
+   - Identify external domains contacted
+   - Map communication patterns and relationships
+   - Document potential data exfiltration via DNS
+
+4. **Impact Assessment:**
+   - Determine scope of DNS-related compromise
+   - Assess potential data exposure through DNS
+   - Identify systems that may be affected
+   - Evaluate ongoing security risks
+
+Present findings with timestamps, evidence preservation notes, and clear documentation suitable for legal proceedings."""

mcpcap/resources/__init__.py

@@ -0,0 +1,5 @@
+"""Resources for mcpcap analysis."""
+
+from .references import setup_resources
+
+__all__ = ["setup_resources"]

mcpcap/resources/references.py

@@ -0,0 +1,90 @@
+"""Reference resources for DNS analysis."""
+
+from fastmcp import FastMCP
+
+
+def setup_resources(mcp: FastMCP) -> None:
+    """Set up reference resources for the MCP server.
+
+    Args:
+        mcp: FastMCP server instance
+    """
+
+    @mcp.resource("dns-record-types://reference")
+    def get_dns_record_types() -> str:
+        """Reference guide for DNS record types"""
+        return """
+# DNS Record Types Reference
+
+## Common Record Types:
+- **A (1)**: IPv4 address record
+- **AAAA (28)**: IPv6 address record
+- **CNAME (5)**: Canonical name (alias)
+- **MX (15)**: Mail exchange record
+- **NS (2)**: Name server record
+- **PTR (12)**: Pointer record (reverse DNS)
+- **SOA (6)**: Start of authority
+- **TXT (16)**: Text record
+- **SRV (33)**: Service record
+
+## Security-Related Types:
+- **DNSKEY (48)**: DNS public key
+- **RRSIG (46)**: Resource record signature
+- **DS (43)**: Delegation signer
+- **NSEC (47)**: Next secure record
+"""
+
+    @mcp.resource("dns-flags://reference")
+    def get_dns_flags_reference() -> str:
+        """Reference guide for DNS flags and their meanings"""
+        return """
+# DNS Flags Reference
+
+## Header Flags:
+- **QR**: Query/Response (0=Query, 1=Response)
+- **AA**: Authoritative Answer
+- **TC**: Truncated (message was truncated)
+- **RD**: Recursion Desired
+- **RA**: Recursion Available
+- **Z**: Reserved (must be zero)
+- **AD**: Authenticated Data
+- **CD**: Checking Disabled
+
+## Response Codes (RCODE):
+- **0**: No error
+- **1**: Format error
+- **2**: Server failure
+- **3**: Name error (domain doesn't exist)
+- **4**: Not implemented
+- **5**: Refused
+"""
+
+    @mcp.resource("suspicious-domains://indicators")
+    def get_suspicious_domain_indicators() -> str:
+        """Common indicators of suspicious or malicious domains"""
+        return """
+# Suspicious Domain Indicators
+
+## Common Patterns:
+- Long random-looking subdomains
+- Domains with excessive hyphens or numbers
+- Recently registered domains
+- Domains using punycode (internationalized domains)
+- DGA (Domain Generation Algorithm) patterns
+
+## Suspicious TLDs (often abused):
+- .tk, .ml, .ga, .cf (free TLDs)
+- .bit (blockchain domains)
+- Newly introduced gTLDs
+
+## Behavioral Indicators:
+- High frequency of DNS queries
+- Queries to non-existent domains (NXDOMAIN)
+- Unusual query patterns or timing
+- Queries for infrastructure domains (.arpa, .root-servers.net)
+
+## DNS Tunneling Indicators:
+- Unusually long DNS queries
+- High volume of TXT record queries
+- Queries with encoded data in subdomain names
+"""

mcpcap-0.2.1.dist-info/METADATA

@@ -0,0 +1,198 @@
+Metadata-Version: 2.4
+Name: mcpcap
+Version: 0.2.1
+Summary: A modular Python MCP Server for analyzing PCAP files
+Author: mcpcap contributors
+License: MIT
+Project-URL: Homepage, https://github.com/danohn/mcpcap
+Project-URL: Repository, https://github.com/danohn/mcpcap
+Project-URL: Issues, https://github.com/danohn/mcpcap/issues
+Keywords: pcap,network,analysis,mcp,dns
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: System :: Networking :: Monitoring
+Classifier: Topic :: Security
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastmcp
+Requires-Dist: scapy
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Requires-Dist: pytest-cov; extra == "test"
+Requires-Dist: setuptools-scm[toml]; extra == "test"
+Provides-Extra: dev
+Requires-Dist: setuptools-scm[toml]; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: sphinx>=7.0; extra == "docs"
+Requires-Dist: sphinx-rtd-theme; extra == "docs"
+Requires-Dist: myst-parser; extra == "docs"
+Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
+Requires-Dist: sphinx-copybutton; extra == "docs"
+Requires-Dist: linkify-it-py; extra == "docs"
+Dynamic: license-file
+
+# mcpcap
+
+![mcpcap logo](https://raw.githubusercontent.com/danohn/mcpcap/main/readme-assets/logo.png)
+
+A modular Python MCP (Model Context Protocol) Server for analyzing PCAP files. mcpcap enables LLMs to read and analyze network packet captures from local or remote sources, providing structured JSON responses about network traffic.
+
+## Overview
+
+mcpcap uses a modular architecture to analyze different network protocols found in PCAP files. Each module focuses on a specific protocol, allowing for targeted analysis and easy extensibility. The server leverages the powerful scapy library for packet parsing and analysis.
+
+### Key Features
+
+- **Modular Architecture**: Easily extensible to support new protocols
+- **Local & Remote PCAP Support**: Read files from local directories or HTTP servers
+- **Scapy Integration**: Leverages scapy's comprehensive packet parsing capabilities
+- **MCP Server**: Integrates seamlessly with LLM clients via Model Context Protocol
+- **JSON Responses**: Structured data format for easy LLM consumption
+
+## Installation
+
+mcpcap requires Python 3.10 or greater.
+
+### Using pip
+
+```bash
+pip install mcpcap
+```
+
+### Using uv
+
+```bash
+uv add mcpcap
+```
+
+### Using uvx (for one-time usage)
+
+```bash
+uvx mcpcap
+```
+
+## Quick Start
+
+1. **Start the MCP Server**:
+
+   ```bash
+   mcpcap --pcap-path /path/to/pcap/files
+   ```
+
+2. **Connect your LLM client** to the MCP server
+
+3. **Ask questions** about your network traffic:
+   - "What domain was queried the most in the DNS traffic?"
+   - "Show me all DNS queries for example.com"
+   - "What are the top 5 queried domains?"
+
+## Modules
+
+### DNS Module
+
+The DNS module analyzes Domain Name System packets in PCAP files.
+
+**Capabilities**:
+
+- Extract DNS queries and responses
+- Identify queried domains and subdomains
+- Analyze query types (A, AAAA, MX, etc.)
+- Track query frequency and patterns
+- Identify DNS servers used
+
+**Example Usage**:
+
+```python
+# LLM can ask: "What domains were queried in this PCAP?"
+# mcpcap will return structured JSON with DNS query information
+```
+
+## Configuration
+
+### PCAP Sources
+
+**Local Directory**:
+
+```bash
+mcpcap --pcap-path /local/path/to/pcaps
+```
+
+**Remote HTTP Server**:
+
+```bash
+mcpcap --pcap-url http://example.com/pcaps/
+```
+
+### Module Selection
+
+```bash
+mcpcap --modules dns --pcap-path /path/to/files
+```
+
+## Example
+
+An example PCAP file (`example.pcap`) containing DNS traffic is included with the project to help you get started.
+
+## Architecture
+
+mcpcap's modular design makes it easy to extend support for new protocols:
+
+1. **Core Engine**: Handles PCAP file loading and basic packet processing
+2. **Protocol Modules**: Individual modules for specific protocols (DNS, etc.)
+3. **MCP Interface**: Translates between LLM queries and packet analysis results
+4. **Output Formatter**: Converts analysis results to structured JSON
+
+### Adding New Modules
+
+New protocol modules can be added by:
+
+1. Implementing the module interface
+2. Defining scapy display filters for the protocol
+3. Creating analysis functions specific to the protocol
+4. Registering the module with the core engine
+
+Future modules might include:
+
+- BGP (Border Gateway Protocol)
+- HTTP/HTTPS traffic analysis
+- TCP connection tracking
+- And more!
+
+## Remote Access
+
+mcpcap supports reading PCAP files from remote HTTP servers without authentication. Future versions may include support for Basic Authentication and other security mechanisms.
+
+## Contributing
+
+Contributions are welcome! Whether you want to:
+
+- Add support for new protocols
+- Improve existing modules
+- Enhance the MCP interface
+- Add new features
+
+Please feel free to open issues and submit pull requests.
+
+## License
+
+MIT
+
+## Requirements
+
+- Python 3.10+
+- scapy
+- MCP server dependencies (automatically installed)
+
+## Support
+
+For questions, issues, or feature requests, please open an issue on GitHub.

mcpcap-0.2.1.dist-info/RECORD

@@ -0,0 +1,17 @@
+mcpcap/__init__.py,sha256=rJwCpBXkhIvmsqHFpeR33Vg8kuipNPJ2JdlAjsTk7I4,1408
+mcpcap/_version.py,sha256=vYqoJTG51NOUmYyL0xt8asRK8vUT4lGAdal_EZ59mvw,704
+mcpcap/cli.py,sha256=8afFamCifC44vMAAi1gNqr2c6CdBgXk33IoRgqmSH2A,1416
+mcpcap/core/__init__.py,sha256=WM5GTl06ZwwqHTPiKaYB-9hwOOXe3hyHG16FshwSsjE,127
+mcpcap/core/config.py,sha256=0LmnzHWWOwtHrikW2o5C9N0SLVvNuCzkNYTQQEys27U,1476
+mcpcap/core/server.py,sha256=1wGGhTMLPspeH45NoVvhcnjUcLWyD6kY1u9tpt4jos4,1140
+mcpcap/modules/__init__.py,sha256=iIeoZuLA-EOv0OS8WU8qDCitXJnarq9F0hA5-Y97zis,140
+mcpcap/modules/base.py,sha256=3h8lGt6d6ob4SbgP6THC5PnTeMRcKfTGoJ9ZlZsQje0,826
+mcpcap/modules/dns.py,sha256=NSBVfx1KWgEDFcvOpvrxIVPAXXE-SvK2E4HS3vqvlVk,12627
+mcpcap/resources/__init__.py,sha256=BPXV29wIG360w9Y9iNpQdA93H2PhT3a6CrnMZX2aaaU,109
+mcpcap/resources/references.py,sha256=HCciAutgLHodlifC8goAZcWpvup3DfbVZ1rxPaXKggA,2516
+mcpcap-0.2.1.dist-info/licenses/LICENSE,sha256=Ltj0zxftQyBYQMNva935v0i5QXQQOF8ygE8dQxGEtjk,1063
+mcpcap-0.2.1.dist-info/METADATA,sha256=24bkSs35339PMi70HVhJziGIcm9XeurIsMT2fFrufCI,5523
+mcpcap-0.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mcpcap-0.2.1.dist-info/entry_points.txt,sha256=ck69gPBEopmU6mzQy9P6o6ssMr89bQbrvv51IaJ50Gc,39
+mcpcap-0.2.1.dist-info/top_level.txt,sha256=YkRkVGjuM3nI7cVB1l8zIAeqiS_5_vrzbUcHNkH3OXE,7
+mcpcap-0.2.1.dist-info/RECORD,,

mcpcap-0.2.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mcpcap-0.2.1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+mcpcap = mcpcap:main

mcpcap-0.2.1.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 danohn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcpcap-0.2.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+mcpcap