Wireshark-MCP

---

O que é isso?

Um servidor MCP que encapsula o tshark (e ferramentas opcionais da suíte Wireshark) em uma interface de análise estruturada. Funciona com Claude Desktop, Claude Code, Cursor, VS Code e mais de 18 outros clientes MCP.

You:    "Find all DNS queries going to suspicious domains in this capture."
Claude: [calls wireshark_extract_dns_queries → wireshark_detect_dns_tunnel]
        "Found repeated high-entropy DNS queries consistent with tunneling: ..."

---

Instalação

Pré-requisitos: Python 3.10+ e Wireshark com tshark no PATH.

O Wireshark MCP 3.0 usa a linha estável do SDK Python MCP 2.x (mcp>=2.1.1,<3).

pip install wireshark-mcp
wireshark-mcp install   # choose from detected MCP clients

Reinicie seu cliente de IA — pronto.

Execute wireshark-mcp doctor se algo parecer errado. Consulte docs/manual-configuration.md para configuração manual ou notas específicas por plataforma.

---

Início Rápido

Aponte seu cliente de IA para um arquivo .pcap e tente:

Analyze capture.pcap using the Wireshark MCP tools.
Start with wireshark_open_file, then run wireshark_quick_analysis.
Use wireshark_aggregate for any capture-wide count or distribution.
Write findings to report.md.

---

Ferramentas

52 ferramentas, cada uma apoiada em saída real de tshark — organizadas em categorias:

Categoria	Destaques	Quantidade
Entrada e Fluxo de Trabalho	wireshark_open_file, wireshark_quick_analysis	2
Análise de Pacotes	Lista de pacotes, detalhes, bytes, contexto, acompanhamento de fluxo, busca, informações de arquivo	8
Extração de Dados	Requisições HTTP, consultas DNS, campos arbitrários, exportação de objetos	4
Estatísticas	Agregação/agrupamento/distintos/top-k/intervalos de tempo, hierarquia de protocolos, endpoints, conversas, gráfico de I/O, informações de especialista, tempo de resposta de serviço, gráfico de fluxo	8
Segurança e Anomalias	Varredura de credenciais, varredura de portas, túnel DNS, DoS, beaconing, exfiltração, anomalias de protocolo, YARA	8
Análise de Protocolos	wireshark_analyze_protocol (20 protocolos), saúde TCP, spoofing ARP	3
Descriptografia e Dissecação	Descriptografia TLS/WPA, verificação de descriptografia, decode-as, preferências de protocolo	5
Forense e Enriquecimento	Impressões digitais TLS, varredura de assinatura de arquivo, GeoIP	3
Operações de Arquivo, Captura e Suíte	Captura ao vivo, interfaces, mesclagem, filtro-salvar, edição editcap (cortar/dividir/deduplicar/deslocar tempo), extração de quadros, text2pcap, capacidades	11

Uma ferramenta cobre 20 protocolos em vez de 20 ferramentas cobrindo um cada: wireshark_analyze_protocol recebe um argumento protocol (tls_handshakes, mqtt, modbus, s7comm, zigbee, wifi, rtp, kerberos, …) e aplica os campos e filtros de exibição corretos para ele. Os nomes dos campos são o ponto — s7comm.param.item.dbnum não é algo que quem chama deva adivinhar, e uma suposição errada retorna um resultado vazio que parece uma captura limpa.

O servidor inicia com apenas tshark obrigatório. Ferramentas opcionais (capinfos, mergecap, editcap, dumpcap, text2pcap) são detectadas automaticamente e habilitam recursos extras quando presentes.

Custo de contexto

A lista de ferramentas viaja no prefixo do prompt de toda requisição que seu cliente envia, então seu tamanho é um custo fixo por requisição. A superfície padrão é de ~22 KB — cerca de 9 KB de esquema de parâmetros, 5 KB de descrições e 3 KB de anotações de leitura/escrita — e é idêntica byte a byte entre reinicializações, permitindo que clientes armazenem o prefixo em cache em vez de relê-lo a cada sessão.

Se seu cliente nunca captura tráfego ao vivo ou grava pcaps, --profile anuncia menos:

Perfil	Ferramentas	Payload	Remoções
full (padrão)	52	~22 KB	nada
analysis	40	~17 KB	captura ao vivo, listagem de interfaces, todas as ferramentas de gravação de arquivo
core	32	~14 KB	o acima, além de descriptografia, sobreposições de dissecação e visualizações de baixo nível

wireshark-mcp serve --profile core

Prompts em tempo de execução e recomendações de protocolo respeitam o perfil selecionado. Guias estáticos podem descrever fluxos de trabalho apenas com full, mas o servidor nunca recomenda uma ferramenta excluída durante a descoberta de captura.

Os resultados das ferramentas também são limitados, pois um resultado permanece na conversa pelo restante da sessão. Saída acima de 8000 caracteres é truncada no início e no fim com um marcador, e os parâmetros offset / limit / display_filter da ferramenta são a forma de paginar pelo restante. Aumente ou diminua o limite com:

export WIRESHARK_MCP_MAX_RESULT_CHARS=16000

Cada ferramenta também declara se lê ou escreve, para que clientes possam aprovar automaticamente as 41 ferramentas de análise somente leitura e ainda solicitar confirmação para as 11 que criam arquivos (captura ao vivo, mesclagem, filtro-salvar, editcap, text2pcap, extração de quadros, exportação de objetos).

Na versão 3.0, essas 11 ferramentas falham de forma segura até que WIRESHARK_MCP_ALLOWED_DIRS nomeie diretórios existentes. A vinculação remota HTTP/SSE também permanece apenas em loopback, a menos que --allow-insecure-http seja explicitamente fornecido atrás de um proxy TLS autenticado e confiável. Consulte o guia de migração de segurança 3.0.

---

Documentação

Tópico	Link
Índice de documentação	docs/README.md
Agregação em toda a captura	docs/aggregation.md
Configuração por plataforma (macOS/Linux/Windows)	docs/platform-validation.md
Configuração manual do cliente	docs/manual-configuration.md
Cenários de implantação	docs/deployment-scenarios.md
Migração de segurança 3.0	docs/security-hardening-v3.md
Modelos de prompt	docs/prompt-engineering.md
Arquitetura	docs/architecture.md
Lista de verificação de lançamento	docs/release-checklist.md
Contribuição	CONTRIBUTING.md
Changelog	CHANGELOG.md
Roteiro de recursos	ROADMAP.md
Política de segurança	SECURITY.md

---

Desenvolvimento

pip install -e ".[dev]"
pytest tests/ -v
ruff check src/ tests/

Consulte CONTRIBUTING.md para o guia completo.

---