Skip to content
This repository has been archived by the owner on Nov 19, 2021. It is now read-only.
/ pyvmidbg Public archive

LibVMI-based debug server, implemented in Python. Building a guest aware, stealth and agentless full-system debugger

License

Notifications You must be signed in to change notification settings

Wenzel/pyvmidbg

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

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:

  • Stubs:
    • GDB
  • Hypervisors:
    • Xen
    • KVM

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

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

  • 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

About

LibVMI-based debug server, implemented in Python. Building a guest aware, stealth and agentless full-system debugger

Topics

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages