SharkMCP

Un server MCP che espone sharkd — l'interfaccia programmatica di Wireshark — come set di strumenti per LLM. Carica file PCAP/PCAPNG e analizzali con linguaggio naturale.

Requisiti

• Python 3.10+
• Wireshark (fornisce sharkd)

Installazione

git clone https://github.com/weirdmachine64/sharkmcp.git
cd sharkmcp
pip install -e .

Oppure esegui direttamente dal repository senza installare:

uvx --from git+https://github.com/weirdmachine64/sharkmcp sharkmcp

Configurazione

Aggiungi al tuo .mcp.json:

{
  "mcpServers": {
    "sharkmcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/weirdmachine64/sharkmcp", "sharkmcp"],
      "env": {
        "SHARKMCP_TIMEOUT": "300"
      }
    }
  }
}

Variabile d'ambiente	Default	Descrizione
SHARKMCP_SHARKD_BIN	sharkd	Percorso del binario sharkd
SHARKMCP_TIMEOUT	300	Timeout per richiesta in secondi

Strumenti

Ogni PCAP caricato ottiene un sottoprocesso sharkd dedicato. I risultati di scansioni costose (conversazioni, informazioni esperte, oggetti esportati) vengono memorizzati nella cache in modo che le chiamate di follow-up paginate siano servite senza ripetere la scansione.

Sessione

Strumento	Descrizione
load_pcap(path, alias?)	Carica un file PCAP/PCAPNG
list_pcaps()	Elenca tutti i PCAP caricati
unload_pcap(alias)	Termina la sessione e libera memoria

Panoramica

Strumento	Descrizione
pcap_summary(alias)	Conteggio frame, durata, dimensione file, protocolli rilevati
server_info(alias)	Tutti i tipi di tap disponibili, protocolli follow, tipi di campo

Ispezione dei pacchetti

Strumento	Descrizione
list_packets(alias, filter?, columns?, refs?)	Elenco frame paginato con filtro di visualizzazione
packet_detail(alias, frame, include_bytes?, include_hidden?)	Albero protocollare completo per un frame
extract_fields(alias, fields, filter?)	Estrai campi arbitrari per pacchetto come tabella

Utilità

Strumento	Descrizione
validate(alias, filter?, field?)	Convalida un filtro di visualizzazione e/o un nome campo
complete(alias, field?, pref?)	Autocompletamento di nomi campo o preferenze per prefisso
get_preference(alias, preference?)	Legge le preferenze del dissector
set_preference(alias, name, value)	Imposta una preferenza del dissector per questa sessione
set_frame_comment(alias, frame, comment)	Annota un frame (a livello di sessione)

Struttura del traffico

Strumento	Descrizione
protocol_hierarchy(alias, filter?)	Albero protocollare annidato con conteggi frame/byte
io_stats(alias, interval_ms?, filter?)	Conteggi frame e byte per intervallo
iograph(alias, graphs, interval_ms?, filters?)	Grafico del traffico multi-linea; supporta packets, bytes, bits, sum:<campo>, avg:<campo>, min:<campo>, max:<campo>, load:<campo>, frames:<campo>
follow_stream(alias, protocol, filter)	Ricostruisci un flusso (tcp, udp, tls, http, http2, quic, sip, dccp, websocket)

Conversazioni e topologia

Strumento	Descrizione
conversations(alias, type?, sort_by?)	Tabella delle conversazioni — byte/frame per coppia di peer
endpoints(alias, type?, sort_by?)	Tabella degli endpoint — tx/rx per host

Tipi di livello supportati per entrambi: tcp, udp, ip, ipv6, eth, sctp, dccp, mptcp, wifi, bluetooth, zigbee, fc, fddi, usb e altri.

Statistiche di protocollo

Strumento	Descrizione
expert_info(alias, filter?)	Rilevamento anomalie per frame — errori, avvisi, note, chat
protocol_stats(alias, protocol)	Statistiche aggregate per dns, http, http_requests, http_server, sip, dhcp, h225, http2, rtsp
service_response_time(alias, protocol)	Latenza richiesta/risposta per smb, smb2, snmp, ldap, diameter, rpc, gtp e altri
response_time_delay(alias, protocol)	Ritardo andata-ritorno per radius, h225_ras, megaco, mgcp
sequence_diagram(alias, type?)	Dati del diagramma di flusso per tcp, icmp, icmpv6, any

Media e VoIP

Strumento	Descrizione
voip_calls(alias, filter?)	Elenco chiamate SIP/H.323 con stato e partecipanti
rtp_streams(alias, stream_spec?)	Inventario dei flussi RTP; passa stream_spec per jitter/perdita per flusso
multicast_streams(alias, filter?)	Statistiche flussi multicast UDP

Esportazione e oggetti

Strumento	Descrizione
export_objects(alias, type?)	Elenca oggetti estraibili (http, imf, smb, tftp, dicom, ftp-data)
download_object(alias, token)	Scarica un oggetto, chiavi di sessione TLS (ssl-secrets) o audio RTP (rtp:<specifica>) come base64

Uscita di emergenza

Strumento	Descrizione
tap(alias, specs, filter?, skip?, limit?)	Esegui direttamente qualsiasi tap sharkd — fino a 16 specifiche in una scansione PCAP. Usa server_info per scoprire identificatori validi.

Esempio

> load_pcap("/captures/traffic.pcap", alias="traffic")
> protocol_hierarchy("traffic")
> expert_info("traffic", limit=20)
> conversations("traffic", type="tcp", sort_by="bytes")
> extract_fields("traffic", ["dns.qry.name", "dns.a"], filter="dns")
> follow_stream("traffic", "http", "tcp.stream eq 0")
> export_objects("traffic", type="http")
> download_object("traffic", "eo:http_0")

Architettura

    LLM
     │  MCP (stdio)
     ▼
 SharkMCP server
     │  JSON-RPC 2.0 (stdin/stdout)
     ├─ sharkd [pcap-1]
     ├─ sharkd [pcap-2]
     └─ sharkd [pcap-N]

Un sottoprocesso sharkd per ogni PCAP caricato. Le sessioni sono isolate — le query concorrenti su alias diversi non si bloccano mai a vicenda.