netdiag-mcp

English | 日本語

MCP-сервер для сетевой диагностики по требованию — DNS-запросы (с проверкой DNSSEC AD-bit), ping, трассировка маршрута на основе mtr, проверка TCP-портов, проверка HTTP-статусов/редиректов, проверка TLS-сертификатов и WHOIS — всё с одного сервера.

Создан для разбора жалоб вида «не могу достучаться до X» / «DNS ещё не распространился» без необходимости заходить по SSH на каждый хост ради разового dig/ping/curl.

Инструменты

Все инструменты доступны только для чтения и работают с одной целью (без пакетного режима и массового перебора) — это удобная обёртка над командами, которые оператор и так выполнил бы вручную, а не сканер. Массовое сканирование множества хостов или портов в стиле nmap сознательно вынесено за рамки: массовый перебор хостов или портов — это действие с гораздо более высоким радиусом поражения, которое заслуживает отдельного инструмента и отдельного процесса согласования.

tcp_port_check, http_check и tls_cert_check используют собственный стек Python (socket/ssl/httpx), а не вызывают внешние nc/curl/openssl, поэтому эти три инструмента работают даже на хосте, где установлены только dig/ping/mtr/whois (или вообще ничего — health_check сообщит, чего не хватает, не роняя весь сервер).

dns_lookup/dnssec_check поддерживают DNS-over-TLS и DNS-over-HTTPS через transport="dot"/"doh" (флаги +tls/+https у dig). Для этого нужен dig из BIND 9.18+ — более старый dig просто отвергнет флаг, а не станет молча делать обычный DNS-запрос, так что устаревший бинарник приведёт к явной ошибке, а не к ложному ощущению, что проверка прошла по шифрованному каналу.

tls_cert_check/http_check по «голому» IP-адресу могут завершиться ошибкой рукопожатия TLS («handshake failure» или похожей) на ресурсах, которые стоят за SNI-ориентированными или CDN-фронтендами (например, за Cloudflare) — расширение SNI в TLS передаёт только имена хостов, поэтому IP-литерал не может привести к нужному сертификату на общем edge-сервере. Это нормальное поведение TLS, а не баг инструмента; при работе с такими ресурсами указывайте имя хоста.

Установка

1. Системные зависимости

dns_lookup, dnssec_check, ping_host, traceroute_path и whois_lookup вызывают внешние бинарники dig, ping, mtr и whois соответственно. Установите те из них, которые вам нужны:

# Debian/Ubuntu
sudo apt install dnsutils iputils-ping mtr-tiny whois

mtr требует доступа к raw-сокетам. Пакет mtr-tiny в Debian/Ubuntu выдаёт cap_net_raw хелперу mtr-packet при установке, так что обычно всё работает и для непривилегированного сервисного пользователя — если traceroute_path сообщает об ошибке прав на сокет, проверьте вывод getcap "$(command -v mtr-packet)". Без этой возможности traceroute_path завершится чистой ошибкой ToolError, а не уронит сервер.

2. Установка

pip install netdiag-mcp
# or
uv tool install netdiag-mcp

3. Claude Code (вручную)

claude mcp add netdiag -- netdiag-mcp

Никаких переменных окружения не требуется.

CLI

netdiag-mcp --version   # print version
netdiag-mcp --check     # report which wrapped binaries are present (exit 0 when all are)

Замечания по безопасности

• Каждый вызов внешнего бинарника передаёт список аргументов (argv), а не строку для shell, так что ни один аргумент инструмента не может выйти за пределы и выполнить произвольную команду.

• Аргументы «хост/IP» и «порт» проходят валидацию и ограничение по диапазону значений перед использованием — входные данные инструментов считаются недоверенными, как и в любом другом интерфейсе вызова инструментов.

• tcp_port_check подключается ровно к одному хосту и одному порту за вызов; никаких циклов по спискам или диапазонам — это сделано намеренно.

Разработка

Живой смоук-тест

Модульные тесты проверяют логику на фикстурах; они не способны заметить, что инструмент перестал возвращать реальные данные (умер бинарник dig/ping/mtr/whois, сломалось хранилище доверенных TLS-сертификатов, сеть блокирует исходящий ICMP). scripts/smoke_test.py запускает каждый зарегистрированный инструмент против реальных публичных конечных точек и падает при пустом, некорректном или ошибочном ответе:

uv run python scripts/smoke_test.py
uv run python scripts/smoke_test.py --only ping --traceback

• Никакого инвентаря целей — каждая цель это фиксированная публичная конечная точка: 1.1.1.1 от Cloudflare и example.com от IANA (зарезервированы для тестирования и документации, см. RFC 2606). Сервер не имеет конфигурации и не из чего строить список целей, в отличие от MCP-серверов для управления парком устройств.

• tests/test_smoke_probes.py — офлайн-часть: проверяет только, что у каждого зарегистрированного инструмента есть соответствующий пробник (и наоборот), так что CI поймает инструмент, добавленный без решения о том, как проверять его работу, не требуя доступа в сеть.

Лицензия

MIT