pyvmidbg
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:
- they have never been designed to deal with malwares, and lack the stealth and robustness required when
analyzing malicious code
- they have an observer effect, by implicitly modifying the process environment being debugged
- this observer effect might be intentional to protect OS features (
Windows PatchGuard/Protected Media Path are disabled)
- modern OS have a high degree of kernel security mechanisms that narrows the debugger's view of the system
(
Windows 10 Virtual Secure Mode)
- 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)
- 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
Current support:
State of hypervisor's VMI support
- Xen
- 2011: Xen 4.1: first hypervisor to support VMI upstream
- 2015: Xen 4.6: best hypervisor for VMI
- libvmi: fully supported
- pyvmidbg: supported
- KVM
- 2017: BitDefender published a set VMI patches on the mailing list
- libvmi: support is ongoing, see
kvm-vmi/libvmi (branch kvmi)
- pyvmidbg: supported
- VirtualBox
- VMware/Hyper-V: no sign of interest as of today
Features
- attach to existing process
- Windows: find
EPROCESS and ETHREADS state
- Linux: pause at
CR3 load
- attach new process (entrypoint):
- Windows: follow first thread creation and break at entrypoint
- Linux: not implemented
- singlestep/continue: wait for the process to be scheduled
- process must have a single thread
- breakin (
CTRL-C)
- software breakpoints
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
high-quality
- starts
cmd.exe in Windows XP nested VM in Xen
- starts
pyvmidbg and target a process named cmd
- connects to stub with
radare2
- set breakpoints on
ntdll!NtOpenFile and ntkrnlpa!NtOpenFile
- 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
- the VM must have 1 VCPU
- no steath breakpoints implemented yet (
int3 into memory)
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
