libmicrovmi

A cross-platform unified interface on top of hypervisor's VMI APIs

Table of Contents

• Overview
• VMI API
• Requirements
• Build
• Example
• Maintainers
• Contributing
• License

Overview

libmicrovmi simply aims to provide a cross-platform unified Virtual Machine Introspection API and the necessary drivers to be compatible with the diversity of hypervisors available today.

The term micro (μ) refers to the library's simplicity as well as the letter U standing for Unified interface.

The grand goal is to be the foundation for a VMI abstraction library that will be

• multi-hypervisor
• multi-emulator
• cross-plaform
• high-level API
  • OS-level semantics
  • stealth breakpoints
  • virtual address translation

Virtual Machine Introspection Apps

• Debugging
  • pyvmidbg
  • icebox
  • rVMI
  • LiveCloudKd
• Dynamic Analysis / Sandboxing
  • DRAKVUF
  • PyREBox
  • PANDA
  • DECAF
• Live Memory Analysis
  • Volatility with the VMIAddressSpace
  • Rekall with the VMIAddressSpace
• OS Hardening
• Cloud Monitoring
• Fuzzing
  • applepie

Drivers

• Xen
• KVM (based on KVM-VMI)
• VirtualBox (based on icebox)
• Hyper-V (based on LiveCloudKd)
• QEMU (based on TCG Plugins)

VMI API

• Query and modify the VM hardware state
  • read/write VCPU registers
  • read/write physical memory
• Subscribe and listen to hardware events
  • mov to/from CR3/CR8
  • mov to/from DRx
  • mov to/from MSR
  • interrupts
  • singlestep (MTF)
  • hypercalls
  • descriptors
  • SLAT (Second Level Address Translation) events
    • r/w/x event on a page
    • dynamically switch to multiple memory views using alternate SLAT pointers
  • Intel Processor Trace packets

• Utilities
  • foreign mapping
  • pagefault injection

For more detailed information, please check the Wiki

Requirements

• Rust stable
• cargo
• clang (bindgen)

Build

To build the library, simply run

cargo build

By default, only the Dummy driver will be available (it does nothing).

To enable a driver, for example xen, enable the corresponding feature (Cargo.toml)

cargo build --features xen

Example

mem-dump

A small binary is available to demonstrate what the libmicrovmi can do: mem-dump

It will dump the raw memory of the specified domain in a domain_name.dump file.

Example with the xen driver:

$ cargo run --features xen --example mem-dump winxp

A memory dump should have been written in winxp.dump.

API example

// select drive type (Dummy, Xen, KVM, ...)
let drv_type = DriverType::Dummy;
// init library
let mut drv: Box<dyn Introspectable> = microvmi::init(drv_type, domain_name);
// pause VM
drv.pause()
    .expect("Failed to pause VM");
// get max physical address
let max_addr = drv.get_max_physical_addr()
                    .expect("Failed to get max physical address");
// read physical memory
let mut buffer: [u8; 4096] = [0; 4096];
let result = drv.read_physical(0x804d7000, &mut buffer);
// resume VM
drv.resume()
    .expect("Failed to resume VM");

References

• LibVMI C library: Simplified Virtual Machine Introspection

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