Wireshark MCP

AI 에이전트 및 로컬 테스트를 위해 Wireshark/tshark 캡처, 분석, 위협 탐지 및 보고 도구를 제공하는 FastMCP 기반 MCP 서버입니다.

목차

• 전제 조건

• 빠른 시작

• 서버 실행

• 도구 사용 (예시)

• 사용 가능한 도구 (요약)

• 문제 해결

• 기여 방법

전제 조건

• Python: 3.8+ (3.11 권장)

• Wireshark (tshark CLI용). Windows의 경우 Wireshark + Npcap을 설치하세요.

• 권한: 패킷 캡처는 일반적으로 Windows에서 높은 권한이 필요합니다.

tshark가 설치되어 있거나 일반적인 경로(예: C:\Program Files\Wireshark\tshark.exe)에서 사용 가능한지 확인하세요. 이 프로젝트에는 PATH 및 일반적인 Windows 위치를 검색하는 TsharkWrapper가 포함되어 있습니다.

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 — 실시간 패킷 캡처 (interface, duration, packet_count, bpf_filter)

분석

• 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 — 보안 중심 보고서

정확한 도구 서명 및 독스트링은 wireshark_mcp/server.py를 참조하세요.

문제 해결

• tshark를 찾을 수 없음: Wireshark를 설치하고 tshark가 PATH에 있거나 기본 설치 폴더에 있는지 확인하세요. 포함된 TsharkWrapper는 PATH에 tshark가 없을 때 일반적인 Windows 위치를 검색합니다.

• Windows에서 캡처 시 권한 오류: Npcap이 설치되어 있는지 확인하고 PowerShell을 관리자 권한으로 실행하세요.

• 도구가 오류 문자열과 함께 failed를 반환하면 wireshark_mcp.tools에서 해당 함수를 직접 실행하여 예외를 검사하세요.

로그: 서버는 표준 로깅을 사용합니다. 서버를 시작한 콘솔 출력에서 자세한 내용을 확인하세요.

기여 방법

• 기능 브랜치에서 변경 사항을 만들고, 적절한 경우 테스트를 추가한 후 풀 리퀘스트를 여세요.

• wireshark_mcp.tools의 공개 API를 안정적으로 유지하세요. 데코레이션된 server 함수는 MCP 노출용입니다.

라이선스

GitHub에 게시하기 전에 선호하는 라이선스 파일(예: LICENSE)을 추가하세요.

원하신다면 다음 작업도 가능합니다:

• 짧은 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>

원하신다면 여기에 스크린샷을 업로드하거나(또는 SonarQube 프로젝트 URL에 대한 액세스 권한을 부여하면) 제가 직접 추가하고 커밋해 드리겠습니다.