Wireshark MCP

MCP-сервер на базе FastMCP, предоставляющий инструменты для захвата, анализа, обнаружения угроз и создания отчетов Wireshark/tshark для ИИ-агентов и локального тестирования.

Оглавление

• Предварительные требования

• Быстрый старт

• Запуск сервера

• Использование инструментов (примеры)

• Доступные инструменты (сводка)

• Устранение неполадок

• Участие в разработке

Предварительные требования

• Python: 3.8+ (рекомендуется 3.11)

• Wireshark (для CLI tshark). В Windows установите Wireshark + Npcap.

• Права доступа: Захват пакетов обычно требует повышенных привилегий в Windows.

Убедитесь, что tshark установлен или доступен по стандартному пути (например, C:\Program Files\Wireshark\tshark.exe). Проект включает TsharkWrapper, который ищет его в PATH и стандартных местах установки в Windows.

Related MCP server: wireshark-mcp

Быстрый старт

Клонируйте репозиторий и создайте виртуальное окружение.

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

Опционально: скопируйте config.example.json в config.json и отредактируйте настройки, специфичные для проекта.

Запуск сервера

Существует два основных режима:

• Транспорт stdio — предназначен для прямой интеграции с клиентами, поддерживающими MCP (например, интеграции с Wireshark/IDE). Это режим по умолчанию при запуске основного пакета.

• Транспорт http — предоставляет MCP-сервер через HTTP API (полезно для тестирования или внешних клиентов).

Рекомендуется (Windows): используйте прилагаемый скрипт запуска, который активирует venv и запускает сервер:

.\run_server.ps1

Ручной запуск (stdio):

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

Запуск с HTTP-транспортом (пример скрипта). Создайте run_network_server.py с содержимым:

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)

Запустите его:

python run_network_server.py

При запуске с HTTP-транспортом вы увидите логи Uvicorn, например:

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

Использование инструментов (примеры)

Для разработки и тестирования мы рекомендуем вызывать модули инструментов напрямую (они возвращают структурированные объекты Python). Функции сервера, декорированные для MCP, возвращают сериализованные строки для транспорта MCP.

Примеры Python (внутри активированного 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"))

Если вы хотите использовать инструменты MCP через уровень сервера (их будут вызывать MCP-клиенты), сервер предоставляет инструменты с теми же именами. Пример (обратите внимание: они возвращают строки):

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

Доступные инструменты (сводка)

Захват

• list_network_interfaces — список доступных устройств захвата

• capture_packets — захват пакетов в реальном времени (интерфейс, длительность, количество пакетов, BPF-фильтр)

Анализ

• analyze_pcap — полный анализ pcap

• extract_dns_queries — DNS-запросы и подозрительные домены

• extract_ip_addresses — извлечение IP-адресов и шаблоны трафика

• get_protocol_statistics — распределение протоколов

Обнаружение угроз

• detect_threats — извлечение IOC и оценка рисков

• analyze_malicious_domains — глубокий анализ доменов

• analyze_suspicious_ips — проверка репутации IP

• detect_attack_patterns — обнаружение сигнатур/шаблонов атак

Устранение неполадок

• analyze_connectivity_issue — диагностика целевого соединения

• analyze_vpn_behavior — сравнение VPN и не-VPN трафика

• analyze_latency_and_retransmissions — потеря пакетов и повторные передачи

• analyze_web_performance — анализ трафика веб-приложений

Отчетность

• generate_analysis_report — создание комплексного отчета

• generate_security_report — отчет, сфокусированный на безопасности

Точные сигнатуры инструментов и docstrings смотрите в wireshark_mcp/server.py.

Устранение неполадок

• tshark не найден: установите Wireshark и убедитесь, что tshark находится в PATH или в папке установки по умолчанию. Включенный TsharkWrapper ищет его в стандартных местах Windows, если tshark отсутствует в PATH.

• Ошибки прав доступа при захвате в Windows: убедитесь, что установлен Npcap, и запускайте PowerShell от имени администратора.

• Если инструмент возвращает failed со строкой ошибки, запустите эквивалентную функцию в wireshark_mcp.tools напрямую, чтобы изучить исключения.

Логи: Сервер использует стандартное логирование; проверяйте вывод консоли, где вы запустили сервер, для получения подробной информации.

Участие в разработке

• Вносите изменения в ветку функций (feature branch), добавляйте тесты, где это уместно, и открывайте pull request.

• Поддерживайте стабильность публичных API в wireshark_mcp.tools; декорированные функции server предназначены для работы с MCP.

Лицензия

Добавьте предпочитаемый файл лицензии (например, LICENSE) перед публикацией на GitHub.

Если хотите, я также могу:

• создать краткий CONTRIBUTING.md,

• добавить примеры скриптов в папку scripts/ (HTTP-запуск, фрагменты для быстрого тестирования), или

• открыть локальную ветку Git и зафиксировать эти изменения за вас.

Безопасность и качество кода

Проект регулярно сканируется инструментом статического анализа (SonarQube) для выявления проблем безопасности, надежности и удобства сопровождения. Скриншоты ниже были сделаны во время последнего сканирования и включены сюда в качестве подтверждающих данных для заинтересованных сторон.

Примечание: скриншоты показывают состояние анализа на момент их создания. Авторитетным источником является страница проекта SonarQube — включите эту ссылку, если публикуете эти артефакты публично.

Ссылки на рисунки (разместите файлы изображений в docs/images/):

• docs/images/sonarqube_result.jpeg — сводка проекта / общий статус (SonarQube)

• docs/images/snyk_result.jpeg — сводка сканирования зависимостей/безопасности (Snyk)

Рисунок 1 — Сводка проекта SonarQube (Пройдено / на момент сканирования нет открытых проблем безопасности или надежности).

Рисунок 2 — Результат сканирования Snyk, иллюстрирующий проверки зависимостей/безопасности и их количество.

Как добавить изображения в этот репозиторий:

1. Создайте папку docs/images/ в корне репозитория.

2. Сохраните скриншоты как sonar_project.png и sonar_summary.png в эту папку.

3. Зафиксируйте и отправьте изображения вместе с 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>

Если хотите, загрузите скриншоты сюда (или предоставьте доступ к URL проекта SonarQube), и я добавлю и зафиксирую их за вас.