mcpcap 0.4.6__py3-none-any.whl → 0.5.0__py3-none-any.whl

mcpcap/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.4.6'
-__version_tuple__ = version_tuple = (0, 4, 6)
+__version__ = version = '0.5.0'
+__version_tuple__ = version_tuple = (0, 5, 0)
 
 __commit_id__ = commit_id = None

mcpcap/cli.py

@@ -20,27 +20,16 @@ def main():
         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="mcpcap MCP Server")
 
-    # PCAP source options (mutually exclusive)
-    source_group = parser.add_mutually_exclusive_group(required=True)
-    source_group.add_argument(
-        "--pcap-path", help="Path to PCAP file or directory containing PCAP files"
-    )
-    source_group.add_argument(
-        "--pcap-url",
-        help="HTTP URL to PCAP file (direct link) or directory containing PCAP files",
-    )
-
     # Analysis options
     parser.add_argument(
         "--modules",
-        help="Comma-separated list of modules to load (default: dns)",
-        default="dns",
+        help="Comma-separated list of modules to load (default: dns,dhcp,icmp)",
+        default="dns,dhcp,icmp",
     )
     parser.add_argument(
         "--max-packets",
@@ -52,13 +41,11 @@ def main():
 
     try:
         # Parse modules and automatically set protocols to match
-        modules = args.modules.split(",") if args.modules else ["dns"]
+        modules = args.modules.split(",") if args.modules else ["dns", "dhcp", "icmp"]
         protocols = modules  # Protocols automatically match loaded modules
 
         # Initialize configuration
         config = Config(
-            pcap_path=args.pcap_path,
-            pcap_url=args.pcap_url,
             modules=modules,
             protocols=protocols,
             max_packets=args.max_packets,

mcpcap/core/config.py

@@ -1,18 +1,11 @@
 """Configuration management for mcpcap."""
 
-import os
-from urllib.parse import urljoin, urlparse
-
-import requests
-
 
 class Config:
     """Configuration management for mcpcap server."""
 
     def __init__(
         self,
-        pcap_path: str | None = None,
-        pcap_url: str | None = None,
         modules: list[str] | None = None,
         protocols: list[str] | None = None,
         max_packets: int | None = None,
@@ -20,211 +13,17 @@ class Config:
         """Initialize configuration.
 
         Args:
-            pcap_path: Path to directory containing PCAP files
-            pcap_url: HTTP server URL containing PCAP files
             modules: List of modules to load
             protocols: List of protocols to analyze
             max_packets: Maximum number of packets to analyze per file
         """
-        self.pcap_path = pcap_path
-        self.pcap_url = pcap_url
-        self.modules = modules or ["dns"]
-        self.protocols = protocols or ["dns"]
+        self.modules = modules or ["dns", "dhcp"]
+        self.protocols = protocols or ["dns", "dhcp"]
         self.max_packets = max_packets
-        self.is_remote = pcap_url is not None
-        self.is_direct_file_url = False  # Will be set during validation
-        self.is_direct_file_path = (
-            False  # Will be set during validation for local files
-        )
 
         self._validate_configuration()
 
     def _validate_configuration(self) -> None:
         """Validate the configuration parameters."""
-        if not self.pcap_path and not self.pcap_url:
-            raise ValueError("Either --pcap-path or --pcap-url must be specified")
-
-        if self.pcap_path and self.pcap_url:
-            raise ValueError("Cannot specify both --pcap-path and --pcap-url")
-
-        if self.pcap_path:
-            self._validate_pcap_path()
-
-        if self.pcap_url:
-            self._validate_pcap_url()
-
         if self.max_packets is not None and self.max_packets <= 0:
             raise ValueError("max_packets must be a positive integer")
-
-    def _validate_pcap_path(self) -> None:
-        """Validate that the PCAP path exists and is either a directory or a PCAP file."""
-        if not os.path.exists(self.pcap_path):
-            raise ValueError(f"PCAP path '{self.pcap_path}' does not exist")
-
-        if os.path.isfile(self.pcap_path):
-            # Check if it's a PCAP file
-            if not self.pcap_path.lower().endswith((".pcap", ".pcapng", ".cap")):
-                raise ValueError(
-                    f"File '{self.pcap_path}' is not a supported PCAP file (.pcap/.pcapng/.cap)"
-                )
-            self.is_direct_file_path = True
-        elif os.path.isdir(self.pcap_path):
-            self.is_direct_file_path = False
-        else:
-            raise ValueError(f"'{self.pcap_path}' is neither a file nor a directory")
-
-    def _validate_pcap_url(self) -> None:
-        """Validate that the PCAP URL is accessible."""
-        try:
-            parsed = urlparse(self.pcap_url)
-            if not parsed.scheme or not parsed.netloc:
-                raise ValueError(f"Invalid URL format: {self.pcap_url}")
-
-            # Determine if this is a direct file URL or directory URL
-            self.is_direct_file_url = self._is_direct_file_url()
-
-            # Test connectivity with a HEAD request
-            response = requests.head(self.pcap_url, timeout=10)
-            if response.status_code >= 400:
-                raise ValueError(
-                    f"Cannot access PCAP URL: {self.pcap_url} (HTTP {response.status_code})"
-                )
-
-        except requests.RequestException as e:
-            raise ValueError(
-                f"Cannot connect to PCAP URL '{self.pcap_url}': {str(e)}"
-            ) from e
-
-    def _is_direct_file_url(self) -> bool:
-        """Determine if the URL points directly to a PCAP file."""
-        parsed = urlparse(self.pcap_url)
-        path = parsed.path.lower()
-
-        # Check if URL ends with a PCAP file extension
-        return (
-            path.endswith(".pcap") or path.endswith(".pcapng") or path.endswith(".cap")
-        )
-
-    def get_pcap_file_path(self, pcap_file: str) -> str:
-        """Get full path or URL to a PCAP file.
-
-        Args:
-            pcap_file: Filename or relative path to PCAP file
-
-        Returns:
-            Full path or URL to the PCAP file
-        """
-        if self.is_remote:
-            # If it's already a full URL, return as-is
-            if pcap_file.startswith("http"):
-                return pcap_file
-
-            # If this is a direct file URL, return the URL directly
-            if self.is_direct_file_url:
-                return self.pcap_url
-
-            # Otherwise, treat as directory and join with filename
-            return urljoin(self.pcap_url.rstrip("/") + "/", pcap_file)
-        else:
-            # Local file handling
-            if os.path.isabs(pcap_file):
-                return pcap_file
-
-            # If this is a direct file path, return it directly
-            if self.is_direct_file_path:
-                return self.pcap_path
-
-            # Otherwise, join with directory
-            return os.path.join(self.pcap_path, pcap_file)
-
-    def list_pcap_files(self) -> list[str]:
-        """List all PCAP files in the configured directory or remote URL.
-
-        Returns:
-            List of PCAP filenames
-        """
-        if self.is_remote:
-            return self._list_remote_pcap_files()
-        else:
-            if self.is_direct_file_path:
-                # Return just the filename from the direct file path
-                return [os.path.basename(self.pcap_path)]
-            else:
-                # List files in directory
-                try:
-                    return [
-                        f
-                        for f in os.listdir(self.pcap_path)
-                        if f.endswith((".pcap", ".pcapng", ".cap"))
-                    ]
-                except Exception:
-                    return []
-
-    def _list_remote_pcap_files(self) -> list[str]:
-        """List PCAP files from a remote HTTP server.
-
-        Returns:
-            List of PCAP filenames found on the remote server
-        """
-        # If this is a direct file URL, return just that filename
-        if self.is_direct_file_url:
-            filename = os.path.basename(urlparse(self.pcap_url).path)
-            return [filename] if filename else []
-
-        # Otherwise try to parse directory listing
-        try:
-            response = requests.get(self.pcap_url, timeout=30)
-            response.raise_for_status()
-
-            # Parse HTML to find .pcap and .pcapng files
-            # This is a simple implementation that looks for href attributes
-            import re
-
-            pcap_files = []
-
-            # Look for links to .pcap, .pcapng, and .cap files
-            pattern = r'href=["\']([^"\']*\.(?:pcap|pcapng|cap))["\']'
-            matches = re.findall(pattern, response.text, re.IGNORECASE)
-
-            for match in matches:
-                # Extract just the filename, not the full path
-                filename = os.path.basename(match)
-                if filename and filename not in pcap_files:
-                    pcap_files.append(filename)
-
-            return sorted(pcap_files)
-
-        except requests.RequestException:
-            return []
-
-    def download_pcap_file(self, pcap_file: str, local_path: str) -> str:
-        """Download a remote PCAP file to local storage.
-
-        Args:
-            pcap_file: Name of the PCAP file to download
-            local_path: Local path to save the file
-
-        Returns:
-            Local path to the downloaded file
-        """
-        if not self.is_remote:
-            raise ValueError("Cannot download file: not using remote source")
-
-        url = self.get_pcap_file_path(pcap_file)
-
-        try:
-            response = requests.get(url, timeout=60, stream=True)
-            response.raise_for_status()
-
-            os.makedirs(os.path.dirname(local_path), exist_ok=True)
-
-            with open(local_path, "wb") as f:
-                for chunk in response.iter_content(chunk_size=8192):
-                    f.write(chunk)
-
-            return local_path
-
-        except requests.RequestException as e:
-            raise ValueError(
-                f"Failed to download PCAP file '{pcap_file}': {str(e)}"
-            ) from e

mcpcap/core/server.py

@@ -4,6 +4,7 @@ from fastmcp import FastMCP
 
 from ..modules.dhcp import DHCPModule
 from ..modules.dns import DNSModule
+from ..modules.icmp import ICMPModule
 from .config import Config
 
 
@@ -25,6 +26,8 @@ class MCPServer:
             self.modules["dns"] = DNSModule(config)
         if "dhcp" in self.config.modules:
             self.modules["dhcp"] = DHCPModule(config)
+        if "icmp" in self.config.modules:
+            self.modules["icmp"] = ICMPModule(config)
 
         # Register tools
         self._register_tools()
@@ -38,25 +41,21 @@ class MCPServer:
         # Register tools for each loaded module
         for module_name, module in self.modules.items():
             if module_name == "dns":
-                self.mcp.tool(module.list_dns_packets)
+                self.mcp.tool(module.analyze_dns_packets)
             elif module_name == "dhcp":
-                self.mcp.tool(module.list_dhcp_packets)
-
-        # Register shared list_pcap_files tool (same for all modules)
-        if self.modules:
-            # Use the first available module for listing PCAP files
-            first_module = next(iter(self.modules.values()))
-            self.mcp.tool(first_module.list_pcap_files)
+                self.mcp.tool(module.analyze_dhcp_packets)
+            elif module_name == "icmp":
+                self.mcp.tool(module.analyze_icmp_packets)
 
     def run(self) -> None:
         """Start the MCP server."""
         import sys
 
         # Log to stderr to avoid breaking MCP JSON-RPC protocol
-        source = (
-            self.config.pcap_url if self.config.is_remote else self.config.pcap_path
+        enabled_modules = ", ".join(self.config.modules)
+        print(
+            f"Starting mcpcap MCP server with modules: {enabled_modules}",
+            file=sys.stderr,
         )
-        source_type = "remote URL" if self.config.is_remote else "directory"
-        print(f"Starting MCP server with PCAP {source_type}: {source}", file=sys.stderr)
 
         self.mcp.run()

mcpcap/modules/base.py

@@ -1,5 +1,7 @@
 """Base module interface for protocol analyzers."""
 
+import os
+import tempfile
 from abc import ABC, abstractmethod
 from typing import Any
 
@@ -17,20 +19,115 @@ class BaseModule(ABC):
         """
         self.config = config
 
+    @property
     @abstractmethod
-    def analyze_packets(self, pcap_file: str) -> dict[str, Any]:
-        """Analyze packets in a PCAP file.
+    def protocol_name(self) -> str:
+        """Return the name of the protocol this module analyzes."""
+        pass
+
+    @abstractmethod
+    def _analyze_protocol_file(self, pcap_file: str) -> dict[str, Any]:
+        """Analyze a local PCAP file for this protocol.
+
+        This method should be implemented by each module to perform
+        the actual protocol-specific analysis.
 
         Args:
-            pcap_file: Path to the PCAP file
+            pcap_file: Path to local PCAP file
 
         Returns:
-            Analysis results as a dictionary
+            Analysis results dictionary
         """
         pass
 
-    @property
-    @abstractmethod
-    def protocol_name(self) -> str:
-        """Return the name of the protocol this module analyzes."""
-        pass
+    def analyze_packets(self, pcap_file: str) -> dict[str, Any]:
+        """Analyze packets from a PCAP file (local or remote).
+
+        Args:
+            pcap_file: Path to local PCAP file or HTTP URL to remote PCAP file
+
+        Returns:
+            A structured dictionary containing packet analysis results
+        """
+        # Check if this is a remote URL or local file
+        if pcap_file.startswith(("http://", "https://")):
+            return self._handle_remote_analysis(pcap_file)
+        else:
+            return self._handle_local_analysis(pcap_file)
+
+    def _handle_remote_analysis(self, pcap_url: str) -> dict[str, Any]:
+        """Handle remote PCAP file analysis."""
+        try:
+            # Download remote file to temporary location
+            with tempfile.NamedTemporaryFile(suffix=".pcap", delete=False) as tmp_file:
+                temp_path = tmp_file.name
+
+            local_path = self._download_pcap_file(pcap_url, temp_path)
+            result = self._analyze_protocol_file(local_path)
+
+            # Clean up temporary file
+            try:
+                os.unlink(local_path)
+            except OSError:
+                pass  # Ignore cleanup errors
+
+            return result
+
+        except Exception as e:
+            return {
+                "error": f"Failed to download PCAP file '{pcap_url}': {str(e)}",
+                "pcap_url": pcap_url,
+            }
+
+    def _handle_local_analysis(self, pcap_file: str) -> dict[str, Any]:
+        """Handle local PCAP file analysis."""
+        # Validate file exists
+        if not os.path.exists(pcap_file):
+            return {
+                "error": f"PCAP file not found: {pcap_file}",
+                "pcap_file": pcap_file,
+            }
+
+        # Validate file extension
+        if not pcap_file.lower().endswith((".pcap", ".pcapng", ".cap")):
+            return {
+                "error": f"File '{pcap_file}' is not a supported PCAP file (.pcap/.pcapng/.cap)",
+                "pcap_file": pcap_file,
+            }
+
+        try:
+            return self._analyze_protocol_file(pcap_file)
+        except Exception as e:
+            return {
+                "error": f"Failed to analyze PCAP file '{pcap_file}': {str(e)}",
+                "pcap_file": pcap_file,
+            }
+
+    def _download_pcap_file(self, pcap_url: str, local_path: str) -> str:
+        """Download a remote PCAP file to local storage.
+
+        Args:
+            pcap_url: URL of the PCAP file to download
+            local_path: Local path to save the file
+
+        Returns:
+            Local path to the downloaded file
+        """
+        import requests
+
+        try:
+            response = requests.get(pcap_url, timeout=60, stream=True)
+            response.raise_for_status()
+
+            os.makedirs(os.path.dirname(local_path), exist_ok=True)
+
+            with open(local_path, "wb") as f:
+                for chunk in response.iter_content(chunk_size=8192):
+                    f.write(chunk)
+
+            return local_path
+
+        except requests.RequestException as e:
+            raise ValueError(
+                f"Failed to download PCAP file '{pcap_url}': {str(e)}"
+            ) from e

mcpcap/modules/dhcp.py

@@ -1,7 +1,5 @@
 """DHCP analysis module."""
 
-import os
-import tempfile
 from typing import Any
 
 from fastmcp import FastMCP
@@ -18,129 +16,20 @@ class DHCPModule(BaseModule):
         """Return the name of the protocol this module analyzes."""
         return "DHCP"
 
-    def list_dhcp_packets(self, pcap_file: str = "") -> dict[str, Any]:
+    def analyze_dhcp_packets(self, pcap_file: str) -> dict[str, Any]:
         """
-        Analyze DHCP packets from a PCAP file and return a summary of each packet.
+        Analyze DHCP packets from a PCAP file and return comprehensive analysis results.
 
         Args:
-            pcap_file: Path to the PCAP file to analyze. Leave empty for direct URL remotes
-                      or when using the first available file in local directories.
+            pcap_file: Path to local PCAP file or HTTP URL to remote PCAP file
 
         Returns:
             A structured dictionary containing DHCP packet analysis results
         """
-        # Handle remote files
-        if self.config.is_remote:
-            # For direct file URLs, always use the URL file (ignore pcap_file parameter)
-            if self.config.is_direct_file_url:
-                available_files = self.config.list_pcap_files()
-                if not available_files:
-                    return {
-                        "error": "No PCAP file found at the provided URL",
-                        "pcap_url": self.config.pcap_url,
-                    }
-                pcap_file = available_files[0]  # Use the actual filename from URL
-            elif not pcap_file:
-                # For directory URLs, if no file specified, use the first available
-                available_files = self.config.list_pcap_files()
-                if not available_files:
-                    return {
-                        "error": "No PCAP files found at the provided URL",
-                        "pcap_url": self.config.pcap_url,
-                        "available_files": [],
-                    }
-                pcap_file = available_files[0]
-
-            # Download remote file to temporary location
-            try:
-                with tempfile.NamedTemporaryFile(
-                    suffix=".pcap", delete=False
-                ) as tmp_file:
-                    temp_path = tmp_file.name
-
-                local_path = self.config.download_pcap_file(pcap_file, temp_path)
-                result = self.analyze_packets(local_path)
-
-                # Clean up temporary file
-                try:
-                    os.unlink(local_path)
-                except OSError:
-                    pass  # Ignore cleanup errors
-
-                return result
-
-            except Exception as e:
-                # List available PCAP files for help
-                available_files = self.config.list_pcap_files()
-                return {
-                    "error": f"Failed to download PCAP file '{pcap_file}': {str(e)}",
-                    "pcap_url": self.config.pcap_url,
-                    "available_files": available_files,
-                }
-
-        else:
-            # Handle local files
-            if not pcap_file:
-                # If no file specified, use the first available file
-                available_files = self.config.list_pcap_files()
-                if not available_files:
-                    return {
-                        "error": "No PCAP files found in directory",
-                        "pcap_directory": self.config.pcap_path,
-                        "available_files": [],
-                    }
-                pcap_file = available_files[0]
+        return self.analyze_packets(pcap_file)
 
-            full_path = self.config.get_pcap_file_path(pcap_file)
-
-            # Check if local file exists
-            if not os.path.exists(full_path):
-                available_files = self.config.list_pcap_files()
-                return {
-                    "error": f"PCAP file '{pcap_file}' not found",
-                    "file_path": full_path,
-                    "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 configured directory or remote URL.
-
-        Returns:
-            A list of available PCAP files that can be analyzed
-        """
-        files = self.config.list_pcap_files()
-        source = (
-            self.config.pcap_url if self.config.is_remote else self.config.pcap_path
-        )
-
-        if files:
-            if self.config.is_remote and self.config.is_direct_file_url:
-                return f"Direct PCAP file URL: {source}\\n- {files[0]}"
-            elif not self.config.is_remote and self.config.is_direct_file_path:
-                return f"Direct PCAP file path: {source}\\n- {files[0]}"
-            else:
-                source_type = "remote server" if self.config.is_remote else "directory"
-                return (
-                    f"Available PCAP files in {source_type} {source}:\\n"
-                    + "\\n".join(f"- {f}" for f in sorted(files))
-                )
-        else:
-            source_type = "remote server" if self.config.is_remote else "directory"
-            return f"No PCAP files found in {source_type} {source}"
-
-    def analyze_packets(self, pcap_file: str) -> dict[str, Any]:
-        """Analyze DHCP packets in a PCAP file.
-
-        Args:
-            pcap_file: Path to the PCAP file to analyze
-
-        Returns:
-            Dictionary containing DHCP packet analysis results
-        """
+    def _analyze_protocol_file(self, pcap_file: str) -> dict[str, Any]:
+        """Perform the actual DHCP packet analysis on a local PCAP file."""
         try:
             packets = rdpcap(pcap_file)
             dhcp_packets = [pkt for pkt in packets if pkt.haslayer(BOOTP)]