mcpcap

Instructions

Implementation Reference

• src/mcpcap/modules/tcp.py:65-104 (handler)

  Main handler function for the analyze_tcp_anomalies tool. Defines input parameters with type hints serving as schema, includes comprehensive docstring for inputs/outputs, and delegates to analyze_packets with 'anomalies' type.
  def analyze_tcp_anomalies( self, pcap_file: str, server_ip: Optional[str] = None, server_port: Optional[int] = None, ) -> dict[str, Any]: """ Detect TCP traffic patterns through statistical analysis. This tool analyzes TCP traffic to identify observable patterns without making assumptions about root causes. It provides factual metrics and pattern detection that can be used for further investigation. Args: pcap_file: HTTP URL or absolute local file path to PCAP file server_ip: Optional filter for server IP address server_port: Optional filter for server port Returns: A structured dictionary containing: - statistics: Comprehensive TCP metrics (handshakes, flags, RST distribution, etc.) - patterns: Observable patterns detected in the traffic - summary: High-level summary of findings Detected pattern categories: - connection_establishment: Handshake success/failure rates, SYN response ratios - connection_termination: RST distribution, normal vs abnormal closes - reliability: Retransmission rates, packet loss indicators - connection_lifecycle: Connection state transitions The analysis is purely observational - it reports what is seen in the traffic without attempting to diagnose specific issues like "firewall block" or "network congestion". This allows the data to be interpreted in context. """ return self.analyze_packets( pcap_file, analysis_type="anomalies", server_ip=server_ip, server_port=server_port, )
• src/mcpcap/core/server.py:59-62 (registration)

  Registration of TCP module tools, including analyze_tcp_anomalies, in the MCP server.
  self.mcp.tool(module.analyze_tcp_connections) self.mcp.tool(module.analyze_tcp_anomalies) self.mcp.tool(module.analyze_tcp_retransmissions) self.mcp.tool(module.analyze_traffic_flow)
• src/mcpcap/modules/tcp.py:375-407 (helper)

  Core helper function implementing the anomaly detection logic called by the handler via analyze_packets routing.
  def _analyze_anomalies( self, pcap_file: str, tcp_packets: list, all_packets: list ) -> dict[str, Any]: """Detect TCP anomalies using pattern-based analysis. This method collects observable metrics and patterns from the traffic, without making assumptions about root causes. The analysis focuses on factual observations that can be derived from packet-level data. """ # Group packets by connection connections = defaultdict(list) for pkt in tcp_packets: conn_key = self._get_connection_key(pkt) connections[conn_key].append(pkt) # Collect comprehensive statistics stats = self._collect_tcp_statistics(connections, tcp_packets) # Detect observable patterns (not diagnoses) patterns = self._detect_tcp_patterns(stats, connections) return { "file": pcap_file, "analysis_timestamp": datetime.now().isoformat(), "filter": { "server_ip": self._analysis_kwargs.get("server_ip"), "server_port": self._analysis_kwargs.get("server_port"), }, "statistics": stats, "patterns": patterns, "summary": self._generate_pattern_summary(patterns), }
• src/mcpcap/modules/tcp.py:163-169 (helper)

  Dispatch helper that sets analysis type and kwargs, then calls base analyze_packets which routes to _analyze_protocol_file.
  def analyze_packets( self, pcap_file: str, analysis_type: str = "connections", **kwargs ) -> dict[str, Any]: """Analyze packets with specified analysis type.""" self._analysis_type = analysis_type self._analysis_kwargs = kwargs return super().analyze_packets(pcap_file)