Skip to content
LibVMI-based debug server, implemented in Python. Building a guest aware, stealth and agentless full-system debugger
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
vmidbg fix singlestep Apr 5, 2019
.gitignore ignore venv Nov 12, 2018
.travis.yml use cmake to install libvmi Feb 16, 2019
LICENSE Initial commit Nov 11, 2018 fix demo Mar 28, 2019
setup.cfg fix PEP8 Nov 13, 2018 Abstract debug context (#17) Mar 25, 2019


Slack Join the chat at standard-readme compliant

LibVMI-based GDB server, implemented in Python

Table of Contents


This GDB stub allows you to debug a remote process running in a VM with your favorite GDB frontend.

By leveraging virtual machine introspection, the stub remains stealth and requires no modification of the guest.

Why debugging from the hypervisor ?

Operating systems debug API's are problematic:

  1. they have never been designed to deal with malwares, and lack the stealth and robustness required when analyzing malicious code
  2. they have an observer effect, by implicitly modifying the process environment being debugged
  3. this observer effect might be intentional to protect OS features (Windows PatchGuard/Protected Media Path are disabled)
  4. modern OS have a high degree of kernel security mechanisms that narrows the debugger's view of the system (Windows 10 Virtual Secure Mode)
  5. debugging low-level processes and kernel functions interacting directly with the transport protocol used by the debug agent can turn into a infinite recursion hell (eg. debugging TCP connections and having a kernel debug stub communicating via TCP)
  6. in special cases the "Operating System" lacks debugging capabilities (unikernels)

Existing solutions like GDB stubs included in QEMU, VMware or VirtualBox can only pause the VM and debug the kernel, but lack the guest knowledge to track and follow the rest of the processes.




  • intercept process at CR3 load
  • read/write memory
  • get/set registers
  • continue execution
  • singlestep
  • breakin (CTRL-C)
  • insert/remove software breakpoint



virtualenv -p python3 venv
source venv/bin/activate
pip install .

Note: If you don't want to install Xen, vagrant-xen-pyvmidbg provides a Vagrant environment based on KVM, with ready to use Windows and Linux VMs.


vmidbg <port> <vm> [<process>]



  1. starts cmd.exe in Windows XP nested VM in Xen
  2. starts pyvmidbg and target a process named cmd
  3. connects to stub with radare2
  4. set breakpoints on ntdll!NtOpenFile and ntkrnlpa!NtOpenFile
  5. avoid breakpoints from the rest of the system, only hit if cmd.exe is executing






PRs accepted.

Small note: If editing the Readme, please conform to the standard-readme specification.


GNU General Public License v3.0

You can’t perform that action at this time.