NadavLor/windbg-ext-mcp

WinDbg 확장 프로그램 + Python MCP 서버. MCP 호환 클라이언트(Cursor, Claude, VS Code + Cline/Roo)가 깨끗하고 검증된 명령어로 WinDbg를 제어할 수 있게 합니다. 커널(Kernel) 우선 방식이며, 유저 모드(User-mode)도 작동합니다.

• 빠른 시작 (Quick Start)
• 아키텍처 (Architecture)
• 사용 예시 (Usage Examples)
• 포함 내용 (What’s Here)
• 무결성 검사 (Sanity Check)
• 문제 해결 (Troubleshooting)
• 설정 (Configuration)
• 테스트 완료 항목 (Tested With)
• 참고 사항 (Notes)

사전 요구 사항 (Prereqs)

• Windows 10/11
• WinDbg (Windows SDK "Debugging Tools for Windows")
• Visual Studio Build Tools (C++)
• Python 3.10+ 및 Poetry 2.x

확장 프로그램 빌드 (Visual Studio용 Developer PowerShell):

msbuild extension\windbgmcpExt.sln /p:Configuration=Release /p:Platform=x64

WinDbg에서 로드:

.load C:\path\to\windbgmcpExt.dll

MCP 서버 설치 및 실행 (루트 디렉토리에서):

poetry install
poetry run selftest
poetry run mcp --list-tools
...

MCP 클라이언트 (stdio) <—> Python MCP 서버 (stdio) <—> WinDbg 확장 프로그램 (named pipe) <—> WinDbg/대상(Target)
FastMCP \\.\\pipe\\windbgmcp 커널(Kernel)/유저(User)

• 확장 프로그램은 네임드 파이프(Named-pipe) 서버를 호스팅하며 WinDbg 명령을 안전하게 실행합니다.
• Python 서버는 입력을 검증하고, 타임아웃을 해결하며, MCP 클라이언트에 도구(Tools)를 노출합니다.

일반적인 경우 (자연어 프롬프트)

• "커널에서 실행 중인 모든 프로세스를 보여줘"
• "현재 스레드의 스택 트레이스(Stack trace)는 뭐야?"
• "0x1000 주소의 메모리를 분석해줘"
• "이 크래시 덤프(Crash dump)를 이해하도록 도와줘"
• "nt!NtCreateFile에 중단점(Breakpoint)을 설정하고 실행을 계속해"
• "다음 3개의 명령어를 단계별로 실행(Step through)하고 레지스터(Registers)를 보여줘"

루트킷(Rootkit) 동작 (연구용)

• "EPROCESS unlink 및 PspCidTable Unlink를 사용하여 explorer.exe를 숨겨줘"
• "OneDrive.exe가 열린 핸들(Open handles)이 없는 것처럼 보이게 해줘"
• "notepad.exe가 종료 및 프로세스 킬(Kill) 시도에 저항하도록 만들어줘"
• "SSDT를 수정하지 않는 보이지 않는 시스템 콜 후킹(System call hooks)을 설치해줘"
• "네트워크 연결을 활성 상태로 유지하면서 netstat에서 숨겨줘"
• "파일이 디렉토리 열거(Directory enumeration)에는 보이지 않지만 직접 경로로는 접근 가능하게 만들어줘"

참고: 이 기능들은 통제된 테스트 실험실 내에서의 합법적이고 방어적인 연구를 위해서만 사용되어야 합니다.

• debug_session: 세션 상태 및 메타데이터 (metadata)
• connection_manager: 연결 상태 및 회복 탄력성 (resilience) 제어
• session_manager: 디버깅 컨텍스트 (context) 캡처/복구
• run_command: 검증/타임아웃 (timeout) 처리를 포함한 WinDbg 명령 실행
• run_sequence: 여러 명령을 순서대로 실행
• breakpoint_and_continue: 중단점 (breakpoint) 설정 및 실행 계속
• analyze_process: 프로세스 열거 (enumeration), 정보 및 컨텍스트 스위칭 (context switching)
• analyze_thread: 스레드 정보 및 스택 트레이스 (stack traces)
• analyze_memory: 메모리 표시, 타입 지정 구조체 (typed structures), 검색
• analyze_kernel: 커널 객체 (kernel objects) 및 시스템 분석
• performance_manager: 최적화 제어 및 성능 보고서
• async_manager: 병렬 실행 및 비동기 (async) 작업 통계
• troubleshoot: 빠른 진단 및 가이드
• get_help: 도구 목록 및 사용 팁
• test_windbg_communication: 파이프 (pipe) 연결성 테스트
• network_debugging_troubleshoot: 네트워크 디버깅 문제 점검

extension/

: C++ WinDbg 확장 기능 (extension). 네임드 파이프 (Named pipe) \\.\\pipe\\windbgmcp 사용.

내보내는 기능 (Exports): help, objecttypes, hello, mcpstart, mcpstop, mcpstatus.

mcp_server/

: 모듈형 도구 (세션, 실행, 분석, 성능, 지원)를 포함한 FastMCP 기반의 Python MCP 서버.

install_client_config.py

: MCP 클라이언트(Cursor/Claude/VS Code) 설정을 작성하기 위한 선택적 헬퍼 도구.

클라이언트가 이 서버를 발견하고 실행할 수 있도록 MCP 클라이언트 설정을 작성하거나 업데이트합니다.

지원되는 클라이언트

• Cursor, Claude Desktop, VS Code (Cline / Roo Code), Windsurf (Codeium)

명령어 (레포지토리 루트에서 실행)

# Dry run (변경 사항 미리보기)
python install_client_config.py --install --dry-run
# 감지된 클라이언트에 대한 설정 설치
...

참고 사항

• 스크립트는 운영체제(OS)를 감지하며, 설치된 것으로 확인된 클라이언트만 수정합니다.
• 현재 사용 중인 Python (sys.executable)을 사용하여 서버를 실행하고 stdio MCP 설정을 작성합니다.
• 설치 모드(Install mode)는 먼저 빠른 서버 임포트(import) 테스트를 실행하며, 진행하기 전에 모든 오류를 수정해야 합니다.

자가 테스트 (Self-test)는 전송(transport)을 스텁(stub) 처리하고 프로토콜을 검증합니다.

poetry run selftest

예상 결과: “Selftest OK”.

• 확장이 로드되지 않는 경우:

• 경로(Path) 또는 아키텍처(arch) 불일치. x64 DLL을 사용하려면 x64 WinDbg를 사용하세요.

• 링크(linking)에 실패하면 Windows SDK Debugging Tools를 설치하세요.

• 파이프(Pipe) 연결 오류:

• 확장이 서버를 호스트합니다. 서버가 시작되었는지(mcpstart) 확인하고 \\.\\pipe\\windbgmcp가 존재하는지 확인하세요.

• 느리거나 불안정한 결과:

• 심볼 경로(symbol paths)를 수정하고, 원격/VM 대상의 경우 타임아웃(timeout)을 늘리며, 명령의 범위를 제한하세요.

DEBUG=true를 설정하면 Python 서버에서 상세 로그(verbose logs)를 활성화할 수 있습니다.

• 타임아웃은 명령 유형별로 자동 해결됩니다. 카테고리에 대한 자세한 내용은 mcp_server/config.py를 참조하세요.

• Windows 11, MSVC v143, Windows SDK 10.0.22621.0

• Python 3.13, Poetry 2.1

• FastMCP 2.5.1, pywin32 310

DLL을 빌드하고, 서버를 실행한 뒤, 확장을 로드하세요. 만약 WinDbg가 로드할 수 없다면 경로가 잘못되었거나 아키텍처가 일치하지 않는 것입니다. 그것부터 먼저 해결하세요.