Wireshark MCP

Ein auf FastMCP basierender MCP-Server, der Wireshark/tshark-Tools für Paketaufzeichnung, Analyse, Bedrohungserkennung und Berichterstellung für KI-Agenten und lokale Tests bereitstellt.

Inhaltsverzeichnis

• Voraussetzungen

• Schnellstart

• Starten des Servers

• Verwendung der Tools (Beispiele)

• Verfügbare Tools (Zusammenfassung)

• Fehlerbehebung

• Mitwirken

Voraussetzungen

• Python: 3.8+ (3.11 empfohlen)

• Wireshark (für das tshark CLI). Installieren Sie unter Windows Wireshark + Npcap.

• Berechtigungen: Die Paketaufzeichnung erfordert unter Windows in der Regel erhöhte Privilegien.

Stellen Sie sicher, dass tshark installiert oder in einem gängigen Pfad verfügbar ist (z. B. C:\Program Files\Wireshark\tshark.exe). Das Projekt enthält einen TsharkWrapper, der den PATH und gängige Windows-Speicherorte durchsucht.

Related MCP server: wireshark-mcp

Schnellstart

Klonen Sie das Repository und erstellen Sie eine virtuelle Umgebung.

Windows (PowerShell):

git clone <your-repo-url>
cd Wireshark_MCP
python -m venv venv
.\venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
pip install -r requirements.txt

Linux / macOS:

git clone <your-repo-url>
cd Wireshark_MCP
python3 -m venv venv
source venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt

Optional: Kopieren Sie config.example.json nach config.json und bearbeiten Sie projektspezifische Einstellungen.

Starten des Servers

Es gibt zwei gängige Modi:

• stdio-Transport — vorgesehen für die direkte Integration mit MCP-fähigen Clients (z. B. Wireshark/IDE-Integrationen). Dies ist der Standard beim Ausführen des Hauptpakets.

• http-Transport — stellt den MCP-Server über eine HTTP-API bereit (nützlich für Tests oder externe Clients).

Empfohlen (Windows): Verwenden Sie den mitgelieferten Runner, der das venv aktiviert und den Server startet:

.\run_server.ps1

Manueller Start (stdio):

.\venv\Scripts\Activate.ps1
python -m wireshark_mcp.server

Start mit HTTP-Transport (Beispielskript). Erstellen Sie run_network_server.py mit:

from wireshark_mcp import server

# Starts FastMCP with HTTP transport on 127.0.0.1:8765
server.main().run(transport="http", host="127.0.0.1", port=8765)

Führen Sie es aus:

python run_network_server.py

Beim Start mit HTTP-Transport sehen Sie Uvicorn-Protokolle wie:

INFO:     Uvicorn running on http://127.0.0.1:8765 (Press CTRL+C to quit)

Verwendung der Tools (Beispiele)

Für Entwicklung und Tests empfehlen wir, die Tool-Module direkt aufzurufen (diese geben strukturierte Python-Objekte zurück). Die MCP-dekorierten Funktionen des Servers geben serialisierte Strings für den MCP-Transport zurück.

Python-Beispiele (innerhalb des aktivierten venv):

# List network interfaces (preferred for testing)
from wireshark_mcp.tools import capture
print(capture.list_network_interfaces())

# Analyze a PCAP file
from wireshark_mcp.tools import analysis
print(analysis.analyze_pcap("/path/to/capture.pcap"))

# Detect threats in a PCAP
from wireshark_mcp.tools import threat_detection
print(threat_detection.detect_threats("/path/to/capture.pcap"))

Wenn Sie die MCP-Tools über die Serverschicht nutzen möchten (MCP-Clients rufen diese auf), stellt der Server die gleichnamigen Tools bereit. Beispiel (Hinweis: diese geben Strings zurück):

from wireshark_mcp import server
print(server.list_network_interfaces())  # returns serialized string

Verfügbare Tools (Zusammenfassung)

Aufzeichnung

• list_network_interfaces — Liste der verfügbaren Aufzeichnungsgeräte

• capture_packets — Live-Paketaufzeichnung (Schnittstelle, Dauer, Paketanzahl, BPF-Filter)

Analyse

• analyze_pcap — Vollständige PCAP-Analyse

• extract_dns_queries — DNS-Abfragen und verdächtige Domains

• extract_ip_addresses — IP-Extraktion und Verkehrsmuster

• get_protocol_statistics — Protokollverteilung

Bedrohungserkennung

• detect_threats — IOC-Extraktion und Risikobewertung

• analyze_malicious_domains — Detaillierte Domain-Analyse

• analyze_suspicious_ips — IP-Reputationsprüfung

• detect_attack_patterns — Signatur-/Mustererkennung

Fehlerbehebung

• analyze_connectivity_issue — Diagnose von Konnektivitätsproblemen

• analyze_vpn_behavior — Vergleich zwischen VPN und Nicht-VPN

• analyze_latency_and_retransmissions — Paketverlust und Neuübertragungen

• analyze_web_performance — Analyse des Webanwendungsverkehrs

Berichterstellung

• generate_analysis_report — Umfassende Berichterstellung

• generate_security_report — Sicherheitsorientierter Bericht

Siehe wireshark_mcp/server.py für genaue Tool-Signaturen und Docstrings.

Fehlerbehebung

• tshark nicht gefunden: Installieren Sie Wireshark und stellen Sie sicher, dass tshark im PATH oder im Standard-Installationsordner vorhanden ist. Der enthaltene TsharkWrapper sucht an gängigen Windows-Speicherorten, wenn tshark nicht im PATH enthalten ist.

• Berechtigungsfehler bei der Aufzeichnung unter Windows: Stellen Sie sicher, dass Npcap installiert ist und führen Sie PowerShell als Administrator aus.

• Wenn ein Tool failed mit einer Fehlermeldung zurückgibt, führen Sie die entsprechende Funktion in wireshark_mcp.tools direkt aus, um Ausnahmen zu untersuchen.

Protokolle: Der Server verwendet Standard-Logging; überprüfen Sie die Konsolenausgabe, in der Sie den Server gestartet haben, für Details.

Mitwirken

• Nehmen Sie Änderungen auf einem Feature-Branch vor, fügen Sie gegebenenfalls Tests hinzu und öffnen Sie einen Pull Request.

• Halten Sie öffentliche APIs in wireshark_mcp.tools stabil; die dekorierten server-Funktionen sind für die MCP-Bereitstellung vorgesehen.

Lizenz

Fügen Sie Ihre bevorzugte Lizenzdatei (z. B. LICENSE) hinzu, bevor Sie sie auf GitHub veröffentlichen.

Wenn Sie möchten, kann ich auch:

• eine kurze CONTRIBUTING.md erstellen,

• Beispielskripte unter einem scripts/-Ordner hinzufügen (HTTP-Runner, Quick-Test-Snippets) oder

• einen lokalen Git-Branch öffnen und diese Änderungen für Sie committen.

Sicherheit & Code-Qualität

Das Projekt wird regelmäßig mit einem statischen Analysetool (SonarQube) gescannt, um Sicherheits-, Zuverlässigkeits- und Wartbarkeitsprobleme aufzudecken. Die untenstehenden Screenshots wurden beim letzten Scan aufgenommen und dienen hier als unterstützender Nachweis für Stakeholder.

Hinweis: Screenshots zeigen den Analyse-Status zum Zeitpunkt der Aufnahme. Die maßgebliche Quelle ist die SonarQube-Projektseite — fügen Sie diesen Link hinzu, wenn Sie diese Artefakte öffentlich veröffentlichen.

Abbildungsreferenzen (legen Sie die Bilddateien in docs/images/ ab):

• docs/images/sonarqube_result.jpeg — Projektzusammenfassung / Gesamtstatus (SonarQube)

• docs/images/snyk_result.jpeg — Zusammenfassung des Abhängigkeits-/Sicherheitsscans (Snyk)

Abbildung 1 — SonarQube Projektzusammenfassung (Bestanden / keine offenen Sicherheits- oder Zuverlässigkeitsprobleme zum Zeitpunkt des Scans).

Abbildung 2 — Snyk-Scan-Ausgabe zur Veranschaulichung der Abhängigkeits-/Sicherheitsprüfungen und -anzahlen.

So fügen Sie die Bilder zu diesem Repository hinzu:

1. Erstellen Sie den Ordner docs/images/ im Repository-Stammverzeichnis.

2. Speichern Sie die Screenshots als sonar_project.png und sonar_summary.png in diesem Ordner.

3. Committen und pushen Sie die Bilder zusammen mit der README:

git add docs/images/sonar_project.png docs/images/sonar_summary.png README.md
git commit -m "docs: add SonarQube screenshots to README"
git push origin <your-branch>

Wenn Sie möchten, laden Sie die Screenshots hier hoch (oder gewähren Sie Zugriff auf die SonarQube-Projekt-URL) und ich werde sie für Sie hinzufügen und committen.