WinRM-MCP

winrm-mcp는 Windows 호스트에서 Windows 게스트 VM을 WinRM으로 제어하기 위한 MCP(Model Context Protocol) 서버입니다.

이 서버는 Codex 또는 MCP Client에서 호출되며, 게스트 VM에 파일을 복사하거나, PowerShell/CMD 명령을 실행하거나, 분석 대상 프로그램을 실행하고, KDNET 커널 디버깅 준비 작업을 자동화하는 데 사용됩니다.

Features

이 프로젝트는 다음 기능을 제공합니다.

• 게스트 VM에서 PowerShell 스크립트 실행
• 게스트 VM에서 CMD 명령 실행
• 호스트에서 게스트로 파일 복사
• 게스트에서 호스트로 파일 복사
• SHA256 기반 파일 무결성 검증
• 파일 복사 검증용 test_file_copy() 도구
• 게스트에서 실행 파일 또는 스크립트 실행
• 현재 디렉터리를 유지하는 논리 쉘 세션
• 게스트 VM 재부팅
• KDNET 설정 자동화
• KD-MCP와 연동하기 위한 상태 파일 생성

Architecture

WinRM-MCP는 게스트 VM 안에서 실행하는 프로그램이 아닙니다.

WinRM-MCP는 호스트 Windows에서 실행되고, 게스트 Windows는 WinRM 서비스로 요청을 받는 구조입니다.

Host Windows
  ├─ Codex / MCP Client
  ├─ winrm-mcp
  ├─ kd-mcp
  └─ kd.exe / WinDbg

Guest Windows VM
  ├─ WinRM Service
  ├─ Analysis Target
  └─ KDNET Target Configuration

즉, 게스트에서는 WinRM 서비스를 활성화해야 하고, 호스트에서는 이 MCP 서버를 실행해야 합니다.

Requirements

호스트에는 다음이 필요합니다.

• Windows 10/11 또는 Windows Server
• Python 3.10 이상
• MCP Client 또는 Codex
• 게스트 WinRM 엔드포인트에 접근 가능한 네트워크 연결

게스트에는 다음이 필요합니다.

• Windows 10/11 또는 Windows Server
• 관리자 계정
• WinRM 서비스 활성화
• 호스트에서 접근 가능한 방화벽 규칙

KDNET까지 사용할 경우, 게스트가 Windows 네트워크 커널 디버깅을 지원해야 합니다.

Enable WinRM on Guest

게스트 VM에서 관리자 PowerShell을 열고 다음 명령을 실행합니다.

Enable-PSRemoting -Force

네트워크 프로필이 Public이면 WinRM 방화벽 예외가 실패할 수 있습니다. 이 경우 게스트에서 네트워크 프로필을 Private으로 변경한 뒤 다시 실행합니다.

Get-NetConnectionProfile
Set-NetConnectionProfile -NetworkCategory Private
Enable-PSRemoting -Force

호스트에서 연결을 확인합니다.

Test-WSMan <guest-ip>

정상이라면 WSMan 응답 정보가 출력됩니다.

Install

호스트 Windows에서 레포지토리를 클론한 뒤 설치합니다.

git clone https://github.com/haoylle/26_WinRM-MCP.git
cd 26_WinRM-MCP
.\scripts\install.ps1

설치 후 examples/config.yaml을 복사하여 실제 설정 파일을 만듭니다.

Copy-Item .\examples\config.yaml .\config.yaml

Configuration

config.yaml은 WinRM 연결 정보, 출력 제한, 파일 복사 청크 크기, KDNET 설정을 포함합니다.

예시는 다음과 같습니다.

guest:
  host: "192.168.122.50"
  username: "Administrator"
  password: null
  transport: "ntlm"
  scheme: "http"
  port: 5985
  server_cert_validation: "ignore"
  operation_timeout_sec: 60
  read_timeout_sec: 90
  allow_unencrypted: true
  path: "/wsman"

limits:
  max_stdout_chars: 200000
  copy_chunk_bytes: 2048
  command_timeout_sec: 300

kdnet:
  host_ip: "192.168.122.1"
  port: 50000
  key: "1.2.3.4"
  state_file: "C:\\mcp-state\\kd-session.json"
  bcdedit_path: "bcdedit.exe"

server.py의 기본 copy_chunk_bytes 값은 8192입니다. 하지만 config.yaml에 값이 있으면 설정 파일 값이 우선 적용됩니다.

파일 복사가 불안정하면 2048처럼 작은 값으로 낮추는 것이 좋습니다. 반대로 전송이 안정적이면 8192 이상으로 올려 청크 수를 줄일 수 있습니다.

비밀번호는 config.yaml에 직접 저장하는 것보다 환경 변수로 지정하는 방식을 권장합니다.

$env:WINRM_PASSWORD = "guest-admin-password"
$env:WINRM_MCP_CONFIG = "C:\\path\\to\\26_WinRM-MCP\\config.yaml"

MCP Client Configuration

MCP Client 설정 예시는 다음과 같습니다.

{
  "mcpServers": {
    "winrm": {
      "command": "C:\\tools\\26_WinRM-MCP\\.venv\\Scripts\\winrm-mcp.exe",
      "env": {
        "WINRM_MCP_CONFIG": "C:\\tools\\26_WinRM-MCP\\config.yaml",
        "WINRM_PASSWORD": "replace-with-guest-admin-password"
      }
    }
  }
}

Codex를 호스트에서 실행한다면, 위 MCP 서버도 호스트에서 실행되도록 설정해야 합니다.

Tools

health_check

설정 파일을 읽고 게스트 VM에 WinRM 연결이 가능한지 확인합니다.

내부적으로 PowerShell 버전, 사용자 이름, 호스트 이름을 조회합니다.

run_ps

게스트 VM에서 PowerShell 스크립트를 실행합니다.

예시는 다음과 같습니다.

Get-ComputerInfo | Select-Object WindowsProductName, WindowsVersion

run_cmd

게스트 VM에서 cmd.exe /c 명령을 실행합니다.

예시는 다음과 같습니다.

whoami && hostname

open_shell / session_run / close_shell

MCP 요청/응답 방식에 맞춘 논리 쉘 세션을 제공합니다.

완전한 대화형 터미널은 아니지만, 현재 디렉터리를 유지하면서 여러 명령을 순차적으로 실행할 수 있습니다.

copy_to_guest

호스트 파일을 게스트 VM으로 복사합니다.

파일은 Base64 청크로 나누어 WinRM을 통해 전송됩니다. 복사 후 verify_hash=true이면 로컬 파일과 원격 파일의 SHA256 해시를 비교합니다.

정상 결과 예시는 다음과 같습니다.

{
  "ok": true,
  "hash_ok": true
}

hash_ok가 false이면 파일이 손상되었을 수 있으므로 실행하지 않는 것이 좋습니다.

test_file_copy

파일 복사 기능을 검증하는 테스트 도구입니다.

32KB 임시 파일을 생성하여 게스트에 복사하고, SHA256 검증 후 임시 파일을 삭제합니다.

정상 결과 예시는 다음과 같습니다.

{
  "ok": true,
  "hash_ok": true
}

copy_from_guest

게스트 VM의 파일을 호스트로 복사합니다.

이 기능도 copy_chunk_bytes 설정을 사용하여 파일을 청크 단위로 읽어옵니다.

start_process

게스트 VM에서 실행 파일 또는 스크립트를 시작합니다.

wait=true이면 프로세스 종료까지 기다리고, 가능한 경우 ExitCode를 반환합니다.

reboot

게스트 VM을 WinRM을 통해 재부팅합니다.

재부팅 후에는 WinRM 연결이 잠시 끊길 수 있습니다.

query_debug_settings

게스트 VM에서 현재 부팅 디버깅 설정을 조회합니다.

내부적으로 bcdedit /enum {current} 및 bcdedit /dbgsettings를 실행합니다.

configure_kdnet

게스트 VM에서 KDNET 커널 디버깅 설정을 적용합니다.

성공하면 호스트에 state_file을 생성합니다. 이 파일은 KD-MCP의 start_from_state가 읽어 커널 디버거 연결에 사용합니다.

KD-MCP Workflow

WinRM-MCP와 KD-MCP를 함께 사용할 때의 일반적인 순서는 다음과 같습니다.

1. winrm-mcp: configure_kdnet
2. winrm-mcp: reboot
3. kd-mcp: start_from_state
4. kd-mcp: kd_command

두 레포지토리는 동일한 state_file, port, key 값을 사용해야 합니다.

Troubleshooting

WinRM connection fails

호스트에서 다음 명령으로 게스트 WinRM 연결을 확인합니다.

Test-WSMan <guest-ip>

게스트 네트워크가 Public이면 방화벽 예외가 적용되지 않을 수 있습니다.

File hash mismatch

파일 복사 후 호스트와 게스트의 SHA256이 다르면 복사 중 손상된 것입니다.

이 경우 다음을 확인합니다.

• copy_to_guest 결과의 hash_ok
• 호스트/게스트 파일 크기
• copy_chunk_bytes 설정
• MCP 서버 재시작 여부

복사 결과가 hash_ok=true가 아니면 파일을 실행하지 않는 것이 좋습니다.

Executable is not valid for this OS platform

실행 파일이 손상되었거나 현재 OS와 맞지 않는 형식일 때 발생할 수 있습니다.

먼저 호스트 파일과 게스트 파일의 SHA256을 비교해야 합니다.

Get-FileHash .\target.exe -Algorithm SHA256

Security Notes

이 프로젝트는 실험실 VM, 취약점 분석 환경, 커널 디버깅 환경을 대상으로 합니다.

신뢰할 수 없는 네트워크에 WinRM을 노출하지 않는 것이 좋습니다.

가능하면 다음 방식을 사용합니다.

• WinRM over HTTPS
• 비밀번호 환경 변수 사용
• 방화벽 접근 제한
• 명령 실행 전 검토
• 공유 환경에서는 allowed_command_prefixes 설정

License

MIT License