ntoseye¶

ntoseye is a Windows debugger for Linux and macOS. It debugs the Windows kernel and user-mode processes on virtual and physical machines, and analyzes crash dumps offline, using WinDbg’s command language.

Debugging via REPL	Debugging via VS Code + DAP

ntoseye is available under the MIT license.

Using ntoseye¶

If you are new to ntoseye, install it, attach to a VM with the Quickstart, and then work through Your first session, which goes from attaching to stepping through code. If you already know WinDbg, Coming from WinDbg lists what carries over and what is different.

The command reference documents every REPL command, and .hh <command> shows the same text in the REPL. To control the debugger from code, start with the Python SDK.

Debugging from the host¶

ntoseye runs outside the machine it debugs and connects to it through one of four backends:

Backend	Connects over	Needs in Windows	Stops and steps
`kd`	KDCOM, on a VM serial port	Kernel debugging	Yes
`kdnet`	KDNET, on the network	Kernel network debugging	Yes
`gdb`	The hypervisor’s GDB stub	Nothing	Yes
`memory`	The VM’s memory	Nothing	No

KDNET can connect to any physical or virtual machine that Windows can debug. With gdb and memory, Windows runs with its debugger disabled and does not know that it is being debugged. When the VM runs on the same host, ntoseye reads guest memory directly from the VM process where it can, instead of through the debugger transport. Choosing a backend compares the backends in full.

Because ntoseye reads memory itself, it can show things that the Windows debugger cannot:

The secure kernel and trustlets that virtualization-based security isolates in VTL1.
Where each processor was when it stopped inside the Windows hypervisor.
The guests that the Windows hypervisor runs, such as a Windows Sandbox, with their own kernel’s symbols.

Symbols and source¶

ntoseye downloads symbols from Microsoft’s symbol server into a cache with the symstore layout, which WinDbg, IDA, and Ghidra also read.

For your own drivers, private PDBs and local source add source lines, local variables, and source breakpoints, and driver replacement loads a rebuilt driver from the host without copying it into the guest.

Platform support¶

Windows	x64	x86	ARM64
11	Yes		Yes
10	Yes	No	Yes
8.1	Yes	No
8	Untested	No
7 SP1	Yes	No
7 RTM	Untested	No
Vista SP2	Yes	No
Vista SP1	Untested	No
Vista RTM	Untested	No
XP SP3		No
XP SP2	Yes	No
XP SP1		No
XP RTM	Untested	No
2000		No

ntoseye runs on Linux (x86-64 and ARM64) and on macOS on Apple Silicon.

It sets up and works directly with KVM/QEMU and VMware Workstation on Linux and UTM on macOS. Any other machine, physical or virtual, connects over KDNET.

Get involved¶

The source code is on GitHub and builds with Cargo:

git clone https://github.com/dmaivel/ntoseye.git
cd ntoseye
cargo build --release

Report bugs on the issue tracker, and ask questions or show what you have built in Discussions.