Home

Awesome

pyvmidbg

Slack Build Status Join the chat at https://gitter.im/pyvmidbg/Lobby standard-readme compliant

LibVMI-based GDB server, implemented in Python

Table of Contents

Overview

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.

Project presentation at Insomni'Hack 2019:

Vision

vmidbg

Current support:

State of hypervisor's VMI support

Features

Requirements

Install

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.

Usage

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

Demo

Debugging cmd.exe in Windows XP

Demo link

  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

Debugging mspaint.exe in Windows 10

Debugging mspaint.exe

Limitations

References

Maintainers

@Wenzel

Contributing

PRs accepted.

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

License

GNU General Public License v3.0