netdiag-mcp

English | 日本語

주문형 네트워크 진단을 위한 MCP 서버 — DNS 조회(DNSSEC AD 비트 확인 포함), ping, mtr 기반 경로 보고서, TCP 포트 확인, HTTP 상태/리디렉션 확인, TLS 인증서 검사, WHOIS를 하나의 서버에서 제공합니다.

"X에 연결할 수 없음" / "DNS가 아직 전파되었는지" 리포트를 분류(triage)하기 위해, 일회성 dig/ping/curl을 위해 매번 점프 호스트에 셸로 접속하지 않도록 제작되었습니다.

도구

모든 도구는 읽기 전용이며 단일 대상을 대상으로 합니다(일괄/스윕 모드 없음). 이는 운영자가 수동으로 실행하는 검사를 위한 편의 래퍼이지 스캐닝 도구가 아닙니다. nmap 스타일의 다중 호스트/다중 포트 스캐닝은 의도적으로 범위에서 제외됩니다. 많은 호스트나 포트를 의도적으로 프로빙하는 것은 별개의 더 큰 폭발 반경을 가진 작업이므로 자체 도구와 승인 흐름이 필요합니다.

tcp_port_check, http_check, tls_cert_check는 nc/curl/openssl을 셸로 호출하는 대신 Python 자체의 socket/ssl/httpx 스택을 사용하므로, 이 세 도구는 dig/ping/mtr/whois 바이너리만 설치된 호스트에서도(또는 아무것도 설치되지 않은 호스트에서도 — health_check가 서버 전체를 실패시키지 않고 어떤 것이 누락되었는지 보고) 작동합니다.

dns_lookup/dnssec_check는 transport="dot"/"doh"(dig의 +tls/+https)를 통해 DNS-over-TLS 및 DNS-over-HTTPS를 지원합니다. 이를 위해서는 BIND 9.18+의 dig가 필요합니다. 이전 버전의 dig는 일반 DNS로 자동 대체(fallback)하는 대신 플래그를 완전히 거부하므로, 오래된 바이너리는 암호화된 전송을 통해 확인했다는 잘못된 안도감을 주는 대신 큰 소리로 실패합니다.

IP 주소만 있는 대상에 대한 tls_cert_check/http_check는 SNI 호스팅/CDN 프런트 엣지(예: Cloudflare 뒤)에서 "handshake failure" 또는 유사한 오류로 TLS 핸드셰이크에 실패할 수 있습니다. TLS의 SNI 확장은 호스트 이름만 전달하므로 IP 리터럴은 공유 엣지에서 올바른 인증서로 라우팅할 수 없습니다. 이는 도구 버그가 아닌 정상적인 TLS 동작입니다. 대상이 CDN 프런트 엔드인 경우 호스트 이름으로 확인하세요.

설정

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 socket) 액세스가 필요합니다. Debian/Ubuntu의 mtr-tiny 패키지는 설치 시 mtr-packet 헬퍼에 cap_net_raw를 부여하므로, 추가 설정 없이 권한이 없는 서비스 사용자에게도 일반적으로 작동합니다. 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 목록을 전달하므로(셸 문자열이 절대 아님) 어떤 도구 인수도 셸 구문으로 이스케이프할 수 없습니다.

• 호스트 이름/IP 및 포트 인수는 사용 전에 검증되고 크기/범위가 제한됩니다. 도구 입력은 모델 기반이며 다른 모든 도구 호출 표면과 마찬가지로 신뢰할 수 없는 것으로 취급됩니다.

• tcp_port_check는 호출당 정확히 하나의 host:port에 연결합니다. 설계상 루프나 범위 인수가 없습니다.

개발

라이브 스모크 테스트

단위 테스트는 픽스처에 대해 로직을 확인합니다. 도구가 실제 데이터 반환을 중단했는지(죽은 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

• 인벤토리가 없으므로 모든 대상은 고정된 공개 엔드포인트입니다 — Cloudflare의 1.1.1.1과 IANA의 example.com(문서/테스트용으로 예약됨, RFC 2606). 이 서버는 이 계열의 디바이스 팜 MCP 서버와 달리 구성을 받지 않으며 대상을 검색할 대상이 없습니다.

• tests/test_smoke_probes.py는 오프라인 부분입니다. 등록된 모든 도구에 프로브 사양이 있는지만 확인하므로(그 반대도 마찬가지) CI는 네트워크 액세스 없이도 작동 여부를 알 수 있는 방법을 결정하지 않고 추가된 도구를 잡아냅니다.

라이선스

MIT