Aragorn

Direct kernel debugger MCP server for Windows security research. Connects to Windows VM kernels via kdnet and exposes 63 tools over the Model Context Protocol.

This process is the debugger. It spawns kd.exe as a subprocess for kdnet transport, then connects via DebugConnect() for full DbgEng COM access. No WinDbg GUI required.

MCP Client ──stdio/http──► Aragorn ──DebugConnect(TCP)──► kd.exe ──kdnet──► VM kernel

Quick Start

# 1. Install dependencies
pip install -r requirements.txt

# 2. Copy DbgEng DLLs from WinDbg Preview into dbgeng_bin/
#    (dbgeng.dll, dbghelp.dll, dbgmodel.dll, dbgcore.dll, symsrv.dll, srcsrv.dll)

# 3. Configure
cp .env.example .env
# Edit .env: set KD_CONNECTION, KD_EXE_PATH, etc.

# 4. Run (stdio mode — for MCP clients like Claude Code)
python server.py

# Or HTTP mode (for remote/shared access)
python server.py --http

.mcp.json integration

{
  "aragorn": {
    "type": "stdio",
    "command": "python",
    "args": ["path/to/Aragorn/server.py"]
  }
}

Configuration

All settings are via environment variables (or .env file):

DbgEng Binaries

The dbgeng_bin/ directory is gitignored. Copy these DLLs from your WinDbg Preview installation:

C:\Program Files\WindowsApps\Microsoft.WinDbg_*\amd64\
  ├── dbgeng.dll
  ├── dbghelp.dll
  ├── dbgmodel.dll
  ├── dbgcore.dll
  ├── symsrv.dll
  └── srcsrv.dll

VM Agent

The vm_agent/ directory contains a lightweight Flask server that runs inside the target VM. It exposes process execution, file I/O, and driver service management over HTTP. Aragorn's workflow tools (breakpoint_and_run, vm_exec, etc.) use it to coordinate kernel debugging with VM-side actions.

# On the VM:
cd vm_agent
pip install -r requirements.txt
cp .env.example .env
# Edit .env: set VM_AGENT_API_KEY
python server.py

The VM agent is optional — all pure debugger tools work without it. You only need it for the coordinated workflow tools.

Tools

Session & Connection (9)

Multi-Session (6)

Command Execution (3)

Memory (7)

Registers (2)

Stack (1)

Breakpoints (4)

Execution Control (4)

Inspection (4)

Symbols (4)

Events (3)

Kernel Objects (8)

Workflow (8)

Architecture

Aragorn/
├── server.py          # FastMCP entry point, registers all tool modules
├── config.py          # Environment variable configuration
├── debugger.py        # High-level Debugger class (lifecycle, commands, reconnect)
├── dbgeng.py          # Pure ctypes COM interface definitions (6 interfaces)
├── callbacks.py       # IDebugOutputCallbacks + IDebugEventCallbacks
├── sessions.py        # Multi-session registry (parallel VM debugging)
├── vm_client.py       # Async HTTP client to VM agent
├── dbgeng_bin/        # DbgEng DLLs (gitignored, ~15MB)
├── vm_agent/          # REST server for target VM (Flask + psutil)
│   ├── server.py      # VM agent HTTP server
│   ├── requirements.txt
│   └── .env.example
└── tools/             # MCP tool modules (one per domain)
    ├── core.py        # execute, execute_batch, evaluate
    ├── session.py     # connect, disconnect, status, ensure_ready
    ├── multi_session.py  # session_create/connect/destroy/list
    ├── memory.py      # read/write virtual + physical memory, MSR
    ├── registers.py   # read/write registers
    ├── stack.py       # get_stack
    ├── breakpoints.py # set/remove/list breakpoints, exception filters
    ├── execution.py   # continue, step_into, step_over, break_in
    ├── inspection.py  # list modules/threads/processes, switch context
    ├── symbols.py     # resolve symbols, field offsets, disassemble
    ├── events.py      # wait/poll/clear debug events
    ├── kernel.py      # read_struct, PTE, pool, driver/device objects, SSDT, IDT
    └── workflow.py    # breakpoint_and_run, run_and_trace, VM proxy tools

COM Interface Stack

Aragorn wraps six DbgEng COM interfaces via ctypes (no C++ extension needed):

• IDebugClient — Session lifecycle, callback registration
• IDebugControl — Command execution, breakpoints, execution status
• IDebugDataSpaces2 — Virtual/physical memory, address translation
• IDebugRegisters — Register read/write
• IDebugSymbols2 — Symbol resolution, type info, disassembly
• IDebugSystemObjects — Process/thread/module enumeration

All blocking COM operations are wrapped in asyncio.to_thread() for MCP stdio compatibility. Each session gets a dedicated COM thread (DbgEng has thread affinity).

License

WTFPL