Analysis Modules

Protocol analysis modules provide the core functionality for parsing and analyzing different network protocols.

Base Module

Base module interface for protocol analyzers.

class mcpcap.modules.base.BaseModule(config)[source]

Bases: ABC

Base class for protocol analysis modules.

__init__(config)[source]

Initialize the module.

Parameters:

config (Config) – Configuration instance

abstract property protocol_name: str

Return the name of the protocol this module analyzes.

analyze_packets(pcap_file)[source]

Analyze packets from a PCAP file (local or remote).

Parameters:

pcap_file (str) – Path to local PCAP file or HTTP URL to remote PCAP file

Return type:

dict[str, Any]

Returns:

A structured dictionary containing packet analysis results

DNS Module

DNS analysis module.

class mcpcap.modules.dns.DNSModule(config)[source]

Bases: BaseModule

Module for analyzing DNS packets in PCAP files.

property protocol_name: str

Return the name of the protocol this module analyzes.

analyze_dns_packets(pcap_file)[source]

Analyze DNS packets from a PCAP file and return comprehensive analysis results.

FILE UPLOAD LIMITATION: This MCP tool cannot process files uploaded through Claude’s web interface. Files must be accessible via URL or local file path.

SUPPORTED INPUT FORMATS: - Remote files: “https://example.com/capture.pcap” - Local files: “/absolute/path/to/capture.pcap”

UNSUPPORTED: - Files uploaded through Claude’s file upload feature - Base64 file content - Relative file paths

Parameters:

pcap_file (str) – HTTP URL or absolute local file path to PCAP file

Return type:

dict[str, Any]

Returns:

A structured dictionary containing DNS packet analysis results

setup_prompts(mcp)[source]

Set up DNS-specific analysis prompts for the MCP server.

Parameters:

mcp (FastMCP) – FastMCP server instance

Return type:

None

DHCP Module

DHCP analysis module.

class mcpcap.modules.dhcp.DHCPModule(config)[source]

Bases: BaseModule

Module for analyzing DHCP packets in PCAP files.

property protocol_name: str

Return the name of the protocol this module analyzes.

analyze_dhcp_packets(pcap_file)[source]

Analyze DHCP packets from a PCAP file and return comprehensive analysis results.

FILE UPLOAD LIMITATION: This MCP tool cannot process files uploaded through Claude’s web interface. Files must be accessible via URL or local file path.

SUPPORTED INPUT FORMATS: - Remote files: “https://example.com/capture.pcap” - Local files: “/absolute/path/to/capture.pcap”

UNSUPPORTED: - Files uploaded through Claude’s file upload feature - Base64 file content - Relative file paths

Parameters:

pcap_file (str) – HTTP URL or absolute local file path to PCAP file

Return type:

dict[str, Any]

Returns:

A structured dictionary containing DHCP packet analysis results

setup_prompts(mcp)[source]

Set up DHCP-specific analysis prompts for the MCP server.

Parameters:

mcp (FastMCP) – FastMCP server instance

Return type:

None

ICMP Module

ICMP analysis module.

class mcpcap.modules.icmp.ICMPModule(config)[source]

Bases: BaseModule

Module for analyzing ICMP packets in PCAP files.

property protocol_name: str

Return the name of the protocol this module analyzes.

analyze_icmp_packets(pcap_file)[source]

Analyze ICMP packets from a PCAP file and return comprehensive analysis results.

FILE UPLOAD LIMITATION: This MCP tool cannot process files uploaded through Claude’s web interface. Files must be accessible via URL or local file path.

SUPPORTED INPUT FORMATS: - Remote files: “https://example.com/capture.pcap” - Local files: “/absolute/path/to/capture.pcap”

UNSUPPORTED: - Files uploaded through Claude’s file upload feature - Base64 file content - Relative file paths

Parameters:

pcap_file (str) – HTTP URL or absolute local file path to PCAP file

Return type:

dict[str, Any]

Returns:

A structured dictionary containing ICMP packet analysis results

setup_prompts(mcp)[source]

Set up ICMP-specific analysis prompts for the MCP server.

Return type:

None

TCP Module

TCP analysis module.

class mcpcap.modules.tcp.TCPModule(config)[source]

Bases: BaseModule

Module for analyzing TCP packets in PCAP files.

property protocol_name: str

Return the name of the protocol this module analyzes.

analyze_tcp_connections(pcap_file, server_ip=None, server_port=None, detailed=False)[source]

Analyze TCP connection states and lifecycle.

This is the core tool for TCP connection analysis, solving 80% of TCP-related issues.

FILE UPLOAD LIMITATION: This MCP tool cannot process files uploaded through Claude’s web interface. Files must be accessible via URL or local file path.

SUPPORTED INPUT FORMATS: - Remote files: “https://example.com/capture.pcap” - Local files: “/absolute/path/to/capture.pcap”

UNSUPPORTED: - Files uploaded through Claude’s file upload feature - Base64 file content - Relative file paths

Parameters:

  • pcap_file (str) – HTTP URL or absolute local file path to PCAP file

  • server_ip (str | None) – Optional filter for server IP address

  • server_port (int | None) – Optional filter for server port

  • detailed (bool) – Whether to return detailed connection information

Returns:

  • summary: Overall connection statistics

  • connections: List of individual connections with states

  • issues: Detected problems

Return type:

A structured dictionary containing TCP connection analysis results including

analyze_tcp_anomalies(pcap_file, server_ip=None, server_port=None)[source]

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.

Parameters:

  • pcap_file (str) – HTTP URL or absolute local file path to PCAP file

  • server_ip (str | None) – Optional filter for server IP address

  • server_port (int | None) – Optional filter for server port

Returns:

  • statistics: Comprehensive TCP metrics (handshakes, flags, RST distribution, etc.)

  • patterns: Observable patterns detected in the traffic

  • summary: High-level summary of findings

Return type:

A structured dictionary containing

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.

analyze_tcp_retransmissions(pcap_file, server_ip=None, threshold=0.02)[source]

Analyze TCP retransmission patterns.

Parameters:

  • pcap_file (str) – HTTP URL or absolute local file path to PCAP file

  • server_ip (str | None) – Optional filter for server IP address

  • threshold (float) – Retransmission rate threshold (default: 2%)

Returns:

  • total_retransmissions: Total number of retransmissions

  • retransmission_rate: Overall retransmission rate

  • by_connection: Per-connection retransmission statistics

  • summary: Worst connections and threshold violations

Return type:

A structured dictionary containing

analyze_traffic_flow(pcap_file, server_ip, server_port=None)[source]

Analyze bidirectional traffic flow characteristics.

Identifies traffic direction, asymmetry, RST sources, and data transfer patterns.

Parameters:

  • pcap_file (str) – HTTP URL or absolute local file path to PCAP file

  • server_ip (str) – Server IP address (required)

  • server_port (int | None) – Optional filter for server port

Returns:

  • client_to_server: Client-to-server traffic statistics

  • server_to_client: Server-to-client traffic statistics

  • analysis: Asymmetry analysis and interpretations

Return type:

A structured dictionary containing

analyze_packets(pcap_file, analysis_type='connections', **kwargs)[source]

Analyze packets with specified analysis type.

Return type:

dict[str, Any]

setup_prompts(mcp)[source]

Set up TCP-specific analysis prompts for the MCP server.

Parameters:

mcp (FastMCP) – FastMCP server instance

Return type:

None

SIP Module

SIP analysis module.

class mcpcap.modules.sip.SIPModule(config)[source]

Bases: BaseModule

Module for analyzing SIP packets in PCAP files.

property protocol_name: str

Return the name of the protocol this module analyzes.

analyze_sip_packets(pcap_file)[source]

Analyze SIP packets from a PCAP file and return structured signaling details.

FILE UPLOAD LIMITATION: This MCP tool cannot process files uploaded through Claude’s web interface. Files must be accessible via URL or local file path.

SUPPORTED INPUT FORMATS: - Remote files: “https://example.com/capture.pcap” - Local files: “/absolute/path/to/capture.pcap”

UNSUPPORTED: - Files uploaded through Claude’s file upload feature - Base64 file content - Relative file paths

Parameters:

pcap_file (str) – HTTP URL or absolute local file path to PCAP file

Return type:

dict[str, Any]

Returns:

A structured dictionary containing SIP packet analysis results

setup_prompts(mcp)[source]

Set up SIP-specific prompts for the MCP server.

Return type:

None

CapInfos Module

CapInfos analysis module.

class mcpcap.modules.capinfos.CapInfosModule(config)[source]

Bases: BaseModule

Module for gathering metadata about capture files.

property protocol_name: str

Return the name of the protocol this module analyzes.

analyze_capinfos(pcap_file)[source]

Return metadata from a PCAP file, similar to Wireshark’s capinfos utility.

IMPORTANT: This tool expects a FILE PATH or URL, not file content. - For local files: “/path/to/capture.pcap” - For remote files: “https://example.com/capture.pcap” - File uploads are NOT supported - save the file locally first

Parameters:

pcap_file (str) – Path to local PCAP file or HTTP URL to remote PCAP file (NOT file content - must be a path or URL)

Returns:

  • File information (size, name, encapsulation type)

  • Packet statistics (count, data size, average sizes)

  • Temporal data (duration, timestamps, rates)

Return type:

A structured dictionary containing PCAP metadata including

setup_prompts(mcp)[source]

Set up prompts for the MCP server.

Parameters:

mcp (FastMCP) – FastMCP server instance

Return type:

None