Struct Vmm

pub struct Vmm<'a> { /* private fields */ }

MemProcFS API Base Struct.

The Vmm struct is the base of the MemProcFS API. All API accesses takes place from the Vmm struct and its sub-structs.

The Vmm struct acts as a wrapper around the native MemProcFS VMM API.

Check out the example project for more detailed API usage and additional examples!

Created By

• Vmm::new()
• Vmm::new_from_leechcore()
• Vmm::new_from_virtual_machine()
• plugin sub-system

The Vmm is normally created by Vmm::new() (see example below).

The Vmm object represents memory analysis of a target system. If the target system contains virtual machines additional child Vmm objects representing the individual VMs may be retrieved by calling the function Vmm::new_from_virtual_machine().

The Vmm object is also supplied by the plugin API to any plugins created.

Examples

// Initialize MemProcFS VMM on a Windows system parsing a
// memory dump and virtual machines inside it.
let args = ["-printf", "-v", "-waitinitialize", "-device", "C:\\Dumps\\mem.dmp"].to_vec();
if let Ok(vmm) = Vmm::new("C:\\MemProcFS\\vmm.dll", &args) {
    ...
    // The underlying native vmm is automatically closed 
    // when the vmm object goes out of scope.
};

// Initialize MemProcFS VMM on a Linux system parsing live memory
// retrieved from a PCILeech FPGA hardware device.
let args = ["-device", "fpga"].to_vec();
if let Ok(vmm) = Vmm::new("/home/user/memprocfs/vmm.so", &args) {
    ...
    // The underlying native vmm is automatically closed 
    // when the vmm object goes out of scope.
};

Implementations

impl Vmm<'_>

pub fn new<'a>(vmm_lib_path: &str, args: &Vec<&str>) -> ResultEx<Vmm<'a>>

MemProcFS Initialization Function.

The Vmm struct is the base of the MemProcFS API. All API accesses takes place from the Vmm struct and its sub-structs.

The Vmm struct acts as a wrapper around the native MemProcFS VMM API.

Arguments

• vmm_lib_path - Full path to the native vmm library - i.e. vmm.dll, vmm.so or vmm.dylib depending on platform.
• args - MemProcFS command line arguments as a Vec<&str>.

MemProcFS command line argument documentation is found on the MemProcFS wiki.

Examples

// Initialize MemProcFS VMM on a Windows system parsing a
// memory dump and virtual machines inside it.
let args = ["-printf", "-v", "-waitinitialize", "-device", "C:\\Dumps\\mem.dmp"].to_vec();
if let Ok(vmm) = Vmm::new("C:\\MemProcFS\\vmm.dll", &args) {
    ...
    // The underlying native vmm is automatically closed 
    // when the vmm object goes out of scope.
};

// Initialize MemProcFS VMM on a Linux system parsing live memory
// retrieved from a PCILeech FPGA hardware device.
let args = ["-device", "fpga"].to_vec();
if let Ok(vmm) = Vmm::new("/home/user/memprocfs/vmm.so", &args) {
    ...
    // The underlying native vmm is automatically closed 
    // when the vmm object goes out of scope.
};

pub fn new_from_leechcore<'a>( leechcore_existing: &LeechCore, args: &Vec<&str>, ) -> ResultEx<Vmm<'a>>

MemProcFS Initialization Function.

The Vmm struct is the base of the MemProcFS API. All API accesses takes place from the Vmm struct and its sub-structs.

The Vmm struct acts as a wrapper around the native MemProcFS VMM API.

This function initializes a new Vmm struct from an already existing LeechCore object. The LeechCore object may be dropped at user discretion after the Vmm object has been created without it being affected. The underlying device will be closed when all internal LeechCore references have been dropped.

Arguments

• leechcore_existing - The LeechCore struct to use as underlying device when initializing MemProcFS VMM.
• args - MemProcFS command line arguments as a Vec<&str> not including any -device arguments.

MemProcFS command line argument documentation is found on the MemProcFS wiki.

Examples

// Initialize MemProcFS VMM on a Windows system using an existing
// LeechCore object to parse a memory dump. Note that no '-device'
// argument should be supplied when using Vmm::new_from_leechcore.
let args = ["-printf", "-v", "-waitinitialize"].to_vec();
if let Ok(vmm) = Vmm::new_from_leechcore(&leechcore_existing, &args) {
    ...
    // The underlying native vmm is automatically closed 
    // when the vmm object goes out of scope.
};

pub fn new_from_virtual_machine<'a>( vmm_parent: &'a Vmm<'_>, vm_entry: &VmmMapVirtualMachineEntry, ) -> ResultEx<Vmm<'a>>

Initialize MemProcFS from a host VMM and a child VM.

Initialize a MemProcFS VMM object representing a child virtual machine (VM).

Arguments

• vmm_parent - The host (parent) Vmm.
• vm_entry - The VmmMapVirtualMachineEntry to initialize as a Vmm.

Examples

if let Ok(virtualmachine_all) = vmm.map_virtual_machine() {
    for virtualmachine in &*virtualmachine_all {
        println!("{virtualmachine}");
        if virtualmachine.is_active {
            // for active vms it's possible to create a new vmm object for
            // the vm. it's possible to treat this as any other vmm object
            // to read memory, query processes etc.
            let vmm_vm = match Vmm::new_from_virtual_machine(&vmm, &virtualmachine) {
                Err(_) => continue,
                Ok(r) => r,
            };
            let max_addr = vmm_vm.get_config(CONFIG_OPT_CORE_MAX_NATIVE_ADDRESS).unwrap_or(0);
            println!("vm max native address: {:#x}", max_addr);
        }
    }
}

pub fn get_leechcore(&self) -> ResultEx<LeechCore>

Retrieve the underlying LeechCore native handle.

Examples

let lc = vmm.get_leechcore()?;

pub fn process_from_pid(&self, pid: u32) -> ResultEx<VmmProcess<'_>>

Retrieve a single process by PID.

Arguments

• pid - Process id (PID) of the process to retrieve.

Examples

if let Ok(process) = vmm.process_from_pid(4) {
    println!("{}", process);    
}

pub fn process_from_name(&self, process_name: &str) -> ResultEx<VmmProcess<'_>>

Retrieve a single process by name.

If multiple processes have the same name the first process located by MemProcFS will be returned. If it is important to fetch the correct process retrieve the process list from vmm.list() and iterate.

Arguments

• process_name - Name of the process to retrieve.

Examples

if let Ok(process) = vmm.process_from_name("System") {
    println!("{}", process);    
}

pub fn process_list(&self) -> ResultEx<Vec<VmmProcess<'_>>>

Retrieve all processes.

Examples

// Retrieve all processes (as a Vec).
process_all = vmm.process_list()?
for process in &*process_all {
    println!("{process} ");
}

pub fn process_map(&self) -> ResultEx<HashMap<u32, VmmProcess<'_>>>

Retrieve all processes as a map.

K: PID, V: VmmProcess

Examples

 // Retrieve all processes as (a HashMap).
process_all = vmm.process_map()?;
for process in process_all {
    println!("<{},{}> ", process.0, process.1);
}

pub fn get_config(&self, config_id: u64) -> ResultEx<u64>

Get a numeric configuration value.

Arguments

• config_id - As specified by a CONFIG_OPT_* constant marked as Get. (Optionally or’ed | with process pid for select options).

Examples

println!("max addr: {:#x}", vmm.get_config(CONFIG_OPT_CORE_MAX_NATIVE_ADDRESS).unwrap_or(0));

pub fn set_config(&self, config_id: u64, config_value: u64) -> ResultEx<()>

Set a numeric configuration value.

Arguments

• config_id - As specified by a CONFIG_OPT_* constant marked as Set. (Optionally or’ed | with process pid for select options).
• config_value - The config value to set.

Examples

// The below force MemProcFS to undertake a full refresh - refresing
// processes, memory and other general data structures completely.
let _r = vmm.set_config(CONFIG_OPT_REFRESH_ALL, 1);

pub fn kernel(&self) -> VmmKernel<'_>

Retrieve the kernel convenience struct.

The kernel struct provides easy access to kernel build number, the system process (pid 4) and kernel (nt) debug symbols.

Examples

// Retrieve and print the kernel build number.
println!("{}", vmm.kernel().build());

pub fn log(&self, log_level: &VmmLogLevel, log_message: &str)

Log a message to the MemProcFS logging system.

Arguments

• log_level
• log_message

Examples

vmm.log(&VmmLogLevel::_1Critical, "Test Message Critical!");

pub fn map_memory(&self) -> ResultEx<Vec<VmmMapMemoryEntry>>

Retrieve the physical memory range info map.

Examples

if let Ok(memory_range_all) = vmm.map_memory() {
    for memory_range in &*memory_range_all {
        println!("{memory_range} \t pa={:x} cb={:x}", memory_range.pa, memory_range.cb);
    }
}

pub fn map_net(&self) -> ResultEx<Vec<VmmMapNetEntry>>

Retrieve the network connection info map.

Examples

let net_all vmm.map_net()?;
for net in &*net_all {
    println!("{net}");
}

pub fn map_pfn( &self, pfns: &Vec<u32>, is_extended: bool, ) -> ResultEx<Vec<VmmMapPfnEntry>>

Retrieve the page frame number (PFN) info map.

Arguments

• pfns - The PFNs to retrieve.
• is_extended - Retrieve extended information (more resource intense).

Examples

let pfns: Vec<u32> = (1..=10).collect();
if let Ok(pfn_all) = vmm.map_pfn(&pfns, true) {
    for pfn in &*pfn_all {
        println!("{pfn} \t location={} tp_ex={} pid={:x} va={:x} color={}",
                 pfn.location, pfn.tp_ex, pfn.pid, pfn.va, pfn.color);
    }
}

pub fn map_kdevice(&self) -> ResultEx<Vec<VmmMapKDeviceEntry>>

Retrieve the kernel device map.

Examples

if let Ok(kdevices) = vmm.map_kdevice() {
    println!("Number of devices: {}.", kdevices.len());
    for kdevice in &*kdevices {
        println!("{kdevice} ");
    }
    println!("");
}

pub fn map_kdriver(&self) -> ResultEx<Vec<VmmMapKDriverEntry>>

Retrieve the kernel driver map.

Examples

if let Ok(kdrivers) = vmm.map_kdriver() {
    println!("Number of drivers: {}.", kdrivers.len());
    for kdriver in &*kdrivers {
        println!("{kdriver} ");
    }
    println!("");
}

pub fn map_kobject(&self) -> ResultEx<Vec<VmmMapKObjectEntry>>

Retrieve the kernel named objects map.

Examples

if let Ok(kobjects) = vmm.map_kobject() {
    println!("Number of objects: {}.", kobjects.len());
    for kobject in &*kobjects {
        println!("{kobject} ");
    }
    println!("");
}

pub fn map_pool(&self, is_bigpool_only: bool) -> ResultEx<Vec<VmmMapPoolEntry>>

Retrieve the kernel pool allocation info map.

Arguments

• is_bigpool_only - Retrieve only entries from the big pool (faster).

Examples

if let Ok(pool_all) = vmm.map_pool(false) {
    println!("Number of pool allocations: {}.", pool_all.len());
    let pool_proc_all : Vec<&VmmMapPoolEntry> =
            pool_all.iter().filter(|e| e.tag == 0x636f7250 /* 'Proc' backwards */).collect();
    println!("Number of pool 'Proc' allocations: {}.", pool_all.len());
    for pool_proc in &*pool_proc_all {
        print!("{pool_proc} ");
    }
    println!("");
}

pub fn map_service(&self) -> ResultEx<Vec<VmmMapServiceEntry>>

Retrieve the servives info map.

Examples

let service_all = vmm.map_service()?;
for service in &*service_all {
    println!("{service} ");
}

pub fn map_user(&self) -> ResultEx<Vec<VmmMapUserEntry>>

Retrieve the user map.

Examples

let user_all = vmm.map_user()?;
for user in &*user_all {
    println!("{:x}:: {} :: {} :: {user}", user.va_reg_hive, user.sid, user.user);
}

pub fn map_virtual_machine(&self) -> ResultEx<Vec<VmmMapVirtualMachineEntry>>

Retrieve the virtual machines info map.

Examples

let virtualmachine_all = vmm.map_virtual_machine()?
for virtualmachine in &*virtualmachine_all {
    println!("{virtualmachine}");
    if virtualmachine.is_active {
        // for active vms it's possible to create a new vmm object for
        // the vm. it's possible to treat this as any other vmm object
        // to read memory, query processes etc.
        let vmm_vm = match Vmm::new_from_virtual_machine(&vmm, &virtualmachine) {
            Err(_) => continue,
            Ok(r) => r,
        };
        println!("vm max native address: {:#x} -> {:#x}",
                 CONFIG_OPT_CORE_MAX_NATIVE_ADDRESS,
                 vmm_vm.get_config(CONFIG_OPT_CORE_MAX_NATIVE_ADDRESS).unwrap_or(0));
    }
}

pub fn mem_read(&self, pa: u64, size: usize) -> ResultEx<Vec<u8>>

Read a contigious physical memory chunk.

The physical memory is read without any special flags. The whole chunk must be read successfully for the method to succeed.

If deseriable to provide flags modifying the behavior (such as skipping the built-in data cache or slower paging access) use the method mem_read_ex() instead.

Reading many memory chunks individually may be slow, especially if reading takes place using hardware FPGA devices. In that case it’s better to use the mem_scatter() functionality for better performance.

Arguments

• pa - Physical address to start reading from.
• size - Number of bytes to read.

Examples

// Read 0x100 bytes of data starting at address 0x1000.
// Example assumes: use pretty_hex::*;
if let Ok(data_read) = vmm.mem_read(0x1000, 0x100) {
    println!("{:?}", data_read.hex_dump());
}

pub fn mem_read_ex(&self, pa: u64, size: usize, flags: u64) -> ResultEx<Vec<u8>>

Read a contigious physical memory chunk with flags.

Flags are constants named FLAG_*

Reading many memory chunks individually may be slow, especially if reading takes place using hardware FPGA devices. In that case it’s better to use the mem_scatter() functionality for better performance.

Arguments

• pa - Physical address to start reading from.
• size - Number of bytes to read.
• flags - Any combination of FLAG_*.

Examples

// Read 0x100 bytes of data starting at address 0x1000.
// Force reading the underlying memory device (skip data cache) and
// Zero-Pad if parts of the memory read fail instead of failing.
// Example assumes: use pretty_hex::*;
if let Ok(data_read) = vmm.mem_read_ex(0x1000, 0x100, FLAG_NOCACHE | FLAG_ZEROPAD_ON_FAIL) {
    println!("{:?}", data_read.hex_dump());
}

pub fn mem_read_into( &self, pa: u64, flags: u64, data: &mut [u8], ) -> ResultEx<usize>

Read a contigious physical memory chunk with flags into a pre-existing buffer.

Flags are constants named FLAG_*

Reading many memory chunks individually may be slow, especially if reading takes place using hardware FPGA devices. In that case it’s better to use the mem_scatter() functionality for better performance.

Arguments

• pa - Physical address to start reading from.
• flags - Any combination of FLAG_*.
• data - Pre-allocated buffer to read into.

Examples

// Read 0x100 bytes of data starting at address 0x1000.
// Force reading the underlying memory device (skip data cache) and
// Zero-Pad if parts of the memory read fail instead of failing.
// Example assumes: use pretty_hex::*;
let mut data = [0u8; 0x100];
if let Ok(length) = vmm.mem_read_into(0x1000, FLAG_NOCACHE | FLAG_ZEROPAD_ON_FAIL, &mut data) {
    println!("bytes_read: {length}");
    println!("{:?}", data.hex_dump());
}

pub fn mem_read_as<T>(&self, pa: u64, flags: u64) -> ResultEx<T>

Read a contigious physical memory chunk with flags as a type/struct.

Flags are constants named FLAG_*

Reading many memory chunks individually may be slow, especially if reading takes place using hardware FPGA devices. In that case it’s better to use the mem_scatter() functionality for better performance.

Arguments

• pa - Physical address to start reading from.
• flags - Any combination of FLAG_*.

Examples

// Read the C-struct IMAGE_DOS_HEADER from memory.
// Force reading the underlying memory device (skip data cache).
#[repr(C)]
struct IMAGE_DOS_HEADER {
    e_magic : u16,
	...
    e_lfanew : u32,
}
if let Ok(doshdr) = vmm.mem_read_as::<IMAGE_DOS_HEADER>(pa_kernel32, FLAG_NOCACHE) {
    println!("e_magic:  {:x}", doshdr.e_magic);
    println!("e_lfanew: {:x}", doshdr.e_lfanew);
}

pub fn mem_scatter(&self, flags: u64) -> ResultEx<VmmScatterMemory<'_>>

Create a scatter memory object for efficient physical memory reads.

Check out the VmmScatterMemory struct for more detailed information.

Arguments

• flags - Any combination of FLAG_*.

Examples

let mem_scatter_physical = vmm.mem_scatter(FLAG_NOCACHE | FLAG_ZEROPAD_ON_FAIL)?;

pub fn mem_write(&self, pa: u64, data: &[u8]) -> ResultEx<()>

Write physical memory.

The write is a best effort. Even of the write should fail it’s not certain that an error will be returned. To be absolutely certain that a write has taken place follow up with a read.

Arguments

• pa - Physical address to start writing from.
• data - Byte data to write.

Examples

let data_to_write = [0x56u8, 0x4d, 0x4d, 0x52, 0x55, 0x53, 0x54].to_vec();
let _r = vmm.mem_write(0x1000, &data_to_write);

pub fn mem_write_as<T>(&self, pa: u64, data: &T) -> ResultEx<()>

Write a type/struct to physical memory.

The write is a best effort. Even of the write should fail it’s not certain that an error will be returned. To be absolutely certain that a write has taken place follow up with a read.

Arguments

• pa - Pnhysical address to start writing from.
• data - Data to write. In case of a struct repr(C) is recommended.

Examples

let data_to_write = [0x56, 0x4d, 0x4d, 0x52, 0x55, 0x53, 0x54];
let _r = vmm.mem_write_as(0x1000, &data_to_write);

pub fn vfs_list(&self, path: &str) -> ResultEx<Vec<VmmVfsEntry>>

List a VFS (Virtual File System) directory.

Returns a result containing the individual directory entries - which may be files or directories.

Arguments

• path - VFS path to list directory contents in. Ex: /sys/

Examples

let vfs_list_path = "/sys/";
if let Ok(vfs_all) = vmm.vfs_list(vfs_list_path) {
    println!("VFS directory listing for directory: {vfs_list_path}");
    println!("Number of file/directory entries: {}.", vfs_all.len());
    for vfs in &*vfs_all {
        println!("{vfs}");
    }
}

pub fn vfs_read( &self, filename: &str, size: u32, offset: u64, ) -> ResultEx<Vec<u8>>

Read a VFS (Virtual File System) file.

The read contents are returned as a Vec containing the byte results. If the end of the file is reached the number of read bytes may be shorter than the requested read size.

Arguments

• filename - Full vfs path of the file to read. Ex: /sys/version.txt
• size - Number of bytes to read.
• offset - File offset.

Examples

if let Ok(vfs_file_data) = vmm.vfs_read("/sys/memory/physmemmap.txt", 0x2000, 0) {
    println!("Bytes read from file '/sys/memory/physmemmap.txt': {}.", vfs_file_data.len());
    println!("{:?}", vfs_file_data.hex_dump());
}

pub fn vfs_write(&self, filename: &str, data: Vec<u8>, offset: u64)

Write a VFS (Virtual File System) file.

Writes are undertaken on a best-effort basis. Writing to read-only files will have no meaning. Writing to memory may or may not be possible depending on various factors. If important, it’s recommended to verify the vfs_write() with a vfs_read().

Arguments

• filename - Full VFS path of the file to write. Ex: /conf/config_printf_enable.txt
• data - Byte data to write.
• offset - File offset.

Examples

let vfs_write_data = vec![1u8; 1];
vmm.vfs_write("/conf/config_process_show_terminated.txt", vfs_write_data, 0);

pub fn reg_hive_list(&self) -> ResultEx<Vec<VmmRegHive<'_>>>

Retrieve all registry hives.

Examples

let hive_all = vmm.reg_hive_list()?;
for hive in hive_all {
    println!("{hive} size={} path={}", hive.size, hive.path);
}

pub fn reg_key(&self, path: &str) -> ResultEx<VmmRegKey<'_>>

Retrieve a registry key by its path.

Registry keys may be addressed either by its full path or by hive address and hive path. Both addressing modes are shown in the examples below. Registry keys are case sensitive.

Check out the VmmRegKey struct for more detailed information.

Examples

// Retrieve a regkey by full path.
let regkey = vmm.reg_key("HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\Run")?
println!("{regkey");

// Retrieve a regkey by hive path.
// (SOFTWARE hive example address: 0xffffba061a908000).
let regkey = vmm.reg_key("0xffffba061a908000\\ROOT\\Microsoft\\Windows\\CurrentVersion\\Run")?
println!("{regkey");

pub fn reg_value(&self, path: &str) -> ResultEx<VmmRegValue<'_>>

Retrieve a registry value by its path.

Registry values may be addressed either by its full path or by hive address and hive path. Both addressing modes are shown in the examples below. Registry keys are case sensitive.

Check out the VmmRegValue struct for more detailed information.

Examples

// Retrieve a regvalue by full path.
let regpath = "HKLM\\SOFTWARE\\Microsoft\\Windows\\CurrentVersion\\ProgramFilesDir";
let regvalue = vmm.reg_key(regpath)?
println!("{regkey");

// Retrieve a regvalue by hive path.
// (SOFTWARE hive example address: 0xffffba061a908000).
regpath = "0xffffba061a908000\\ROOT\\Microsoft\\Windows\\CurrentVersion\\ProgramFilesDir";
let regvalue = vmm.reg_key(regpath)?
println!("{regkey");

pub fn search( &self, addr_min: u64, addr_max: u64, num_results_max: u32, flags: u64, ) -> ResultEx<VmmSearch<'_>>

Retrieve a search struct for physical memory.

NB! This does not start the actual search yet.

Check out the VmmSearch struct for more detailed information.

Arguments

• addr_min - Start search at this physical address.
• addr_max - End the search at this physical address. 0 is interpreted as u64::MAX.
• num_results_max - Max number of search hits to search for. Max allowed value is 0x10000.
• flags - Any combination of FLAG_*.

Examples

// Retrieve a VmmSearch for the entire physical memory.
let mut search = vmm.search(0, 0, 0x10000, 0)?

// Retrieve a VmmSearch for physical memory between 4GB and 8GB.
// Also stop at first search hit.
let mut search = vmm.search(0x100000000, 0x200000000, 1, 0)?

pub fn search_yara( &self, rules: Vec<&str>, addr_min: u64, addr_max: u64, num_results_max: u32, flags: u64, ) -> ResultEx<VmmYara<'_>>

Retrieve a yara search struct for physical memory.

NB! This does not start the actual search yet.

Check out the VmmYara struct for more detailed information.

Arguments

• rules - Yara rules to search for.
• addr_min - Start yara search at this physical address.
• addr_max - End the yara search at this physical address. 0 is interpreted as u64::MAX.
• num_results_max - Max number of search hits to search for. Max allowed value is 0x10000.
• flags - Any combination of FLAG_*.

Examples

// Retrieve a VmmYara for the entire physical memory.
let yara_rule = " rule mz_header { strings: $mz = \"MZ\" condition: $mz at 0 } ";
let yara_rules = vec![yara_rule];
let mut yara = vmm.search_yara(yara_rules, 0, 0, 0x10000, 0)?

// Retrieve a VmmYara for physical memory between 4GB and 8GB.
// Also stop at first yara search hit.
let yara_rules = vec!["/tmp/my_yara_rule.yar", "/tmp/my_yara_rule2.yar"];
let mut yara = vmm.search_yara(yara_rules, 0x100000000, 0x200000000, 1, 0)?

Trait Implementations

impl Clone for Vmm<'_>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<'a> Debug for Vmm<'a>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for Vmm<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for Vmm<'_>

fn drop(&mut self)

Executes the destructor for this type.