Struct VmiCore 

pub struct VmiCore<Driver>
where
    Driver: VmiDriver,
{ /* private fields */ }

The core functionality for Virtual Machine Introspection (VMI).

Implementations

impl<Driver> VmiCore<Driver>

where Driver: VmiDriver,

pub fn driver(&self) -> &Driver

Available on crate features utils and injector only.

Returns the driver used by this VmiCore instance.

pub fn info(&self) -> Result<VmiInfo, VmiError>

Available on crate features utils and injector only.

Retrieves information about the virtual machine.

Examples found in repository

examples/basic.rs (line 26)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let domain_id = 'x: {
        for name in &["win7", "win10", "win11", "ubuntu22"] {
            if let Some(domain_id) = XenStore::new()?.domain_id_from_name(name)? {
                break 'x domain_id;
            }
        }

        panic!("Domain not found");
    };

    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::new(domain_id)?;
    let vmi = VmiCore::new(driver)?;

    // Get the interrupt descriptor table for each vCPU and print it.
    let _pause_guard = vmi.pause_guard()?;
    let info = vmi.info()?;
    for vcpu_id in 0..info.vcpus {
        let registers = vmi.registers(VcpuId(vcpu_id))?;
        let idt = Amd64::interrupt_descriptor_table(&vmi, &registers)?;

        println!("IDT[{vcpu_id}]: {idt:#?}");
    }

    Ok(())
}

impl<Driver> VmiCore<Driver>

where Driver: VmiRead,

pub fn new(driver: Driver) -> Result<VmiCore<Driver>, VmiError>

Available on crate features utils and injector only.

Creates a new VmiCore instance with the given driver.

Both the GFN cache and the V2P cache are enabled by default, each with a capacity of 8192 entries.

Examples found in repository

examples/basic.rs (line 22)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let domain_id = 'x: {
        for name in &["win7", "win10", "win11", "ubuntu22"] {
            if let Some(domain_id) = XenStore::new()?.domain_id_from_name(name)? {
                break 'x domain_id;
            }
        }

        panic!("Domain not found");
    };

    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::new(domain_id)?;
    let vmi = VmiCore::new(driver)?;

    // Get the interrupt descriptor table for each vCPU and print it.
    let _pause_guard = vmi.pause_guard()?;
    let info = vmi.info()?;
    for vcpu_id in 0..info.vcpus {
        let registers = vmi.registers(VcpuId(vcpu_id))?;
        let idt = Amd64::interrupt_descriptor_table(&vmi, &registers)?;

        println!("IDT[{vcpu_id}]: {idt:#?}");
    }

    Ok(())
}

examples/windows-breakpoint-manager.rs (line 543)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    tracing_subscriber::fmt()
        .with_max_level(tracing::Level::DEBUG)
        .init();

    let domain_id = 'x: {
        for name in &["win7", "win10", "win11", "ubuntu22"] {
            if let Some(domain_id) = XenStore::new()?.domain_id_from_name(name)? {
                break 'x domain_id;
            }
        }

        panic!("Domain not found");
    };

    tracing::debug!(?domain_id);

    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::new(domain_id)?;
    let core = VmiCore::new(driver)?;

    // Try to find the kernel information.
    // This is necessary in order to load the profile.
    let kernel_info = {
        let _pause_guard = core.pause_guard()?;
        let regs = core.registers(0.into())?;

        WindowsOs::find_kernel(&core, &regs)?.expect("kernel information")
    };

    // Load the profile.
    // The profile contains offsets to kernel functions and data structures.
    let isr = IsrCache::new("cache")?;
    let entry = isr.entry_from_codeview(kernel_info.codeview)?;
    let profile = entry.profile()?;

    // Create the VMI session.
    tracing::info!("Creating VMI session");
    let terminate_flag = Arc::new(AtomicBool::new(false));
    signal_hook::flag::register(signal_hook::consts::SIGHUP, terminate_flag.clone())?;
    signal_hook::flag::register(signal_hook::consts::SIGINT, terminate_flag.clone())?;
    signal_hook::flag::register(signal_hook::consts::SIGALRM, terminate_flag.clone())?;
    signal_hook::flag::register(signal_hook::consts::SIGTERM, terminate_flag.clone())?;

    let os = WindowsOs::<VmiXenDriver<Amd64>>::new(&profile)?;
    let session = VmiSession::new(&core, &os);

    session.handle(|session| Monitor::new(session, &profile, terminate_flag))?;

    Ok(())
}

examples/windows-dump.rs (line 410)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    tracing_subscriber::fmt()
        .with_max_level(tracing::Level::DEBUG)
        .with_ansi(false)
        .init();

    // First argument is the path to the dump file.
    let args = std::env::args().collect::<Vec<_>>();
    if args.len() != 2 {
        eprintln!("Usage: {} <dump-file>", args[0]);
        std::process::exit(1);
    }

    let dump_file = &args[1];

    // Setup VMI.
    let driver = Driver::new(dump_file)?;
    let core = VmiCore::new(driver)?;

    let registers = core.registers(VcpuId(0))?;

    // Try to find the kernel information.
    // This is necessary in order to load the profile.
    let kernel_info = WindowsOs::find_kernel(&core, &registers)?.expect("kernel information");
    tracing::info!(?kernel_info, "Kernel information");

    // Load the profile.
    // The profile contains offsets to kernel functions and data structures.
    let isr = IsrCache::new("cache")?;
    let entry = isr.entry_from_codeview(kernel_info.codeview)?;
    let profile = entry.profile()?;

    // Create the VMI session.
    tracing::info!("Creating VMI session");
    let os = WindowsOs::<Driver>::with_kernel_base(&profile, kernel_info.base_address)?;
    let session = VmiSession::new(&core, &os);

    let vmi = session.with_registers(&registers);
    let root_directory = vmi.os().object_root_directory()?;

    println!("Kernel Modules:");
    println!("=================================================");
    enumerate_kernel_modules(&vmi)?;

    println!("Object Tree (root directory: {}):", root_directory.va());
    println!("=================================================");
    enumerate_directory_object(&root_directory, 0)?;

    println!("Processes:");
    println!("=================================================");
    enumerate_processes(&vmi)?;

    Ok(())
}

examples/common/mod.rs (line 35)

pub fn create_vmi_session() -> Result<Session, Box<dyn std::error::Error>> {
    tracing_subscriber::fmt()
        .with_max_level(tracing::Level::DEBUG)
        .with_target(false)
        .init();

    let domain_id = 'x: {
        for name in &["win7", "win10", "win11", "ubuntu22"] {
            if let Some(domain_id) = XenStore::new()?.domain_id_from_name(name)? {
                break 'x domain_id;
            }
        }

        panic!("Domain not found");
    };

    tracing::debug!(?domain_id);

    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::new(domain_id)?;
    let core = VmiCore::new(driver)?;

    // Try to find the kernel information.
    // This is necessary in order to load the profile.
    let kernel_info = {
        // Pause the vCPU to get consistent state.
        let _pause_guard = core.pause_guard()?;

        // Get the register state for the first vCPU.
        let registers = core.registers(VcpuId(0))?;

        // On AMD64 architecture, the kernel is usually found using the
        // `MSR_LSTAR` register, which contains the address of the system call
        // handler. This register is set by the operating system during boot
        // and is left unchanged (unless some rootkits are involved).
        //
        // Therefore, we can take an arbitrary registers at any point in time
        // (as long as the OS has booted and the page tables are set up) and
        // use them to find the kernel.
        WindowsOs::find_kernel(&core, &registers)?.expect("kernel information")
    };

    // Load the profile.
    // The profile contains offsets to kernel functions and data structures.
    let isr = IsrCache::new("cache")?;
    let entry = isr.entry_from_codeview(kernel_info.codeview)?;
    let entry = Box::leak(Box::new(entry));
    let profile = entry.profile()?;

    // Create the VMI session.
    tracing::info!("Creating VMI session");
    let os = WindowsOs::<VmiXenDriver<Amd64>>::new(&profile)?;

    // Please don't do this in production code.
    // This is only done for the sake of the example.
    let core = Box::leak(Box::new(core));
    let os = Box::leak(Box::new(os));

    Ok((VmiSession::new(core, os), profile))
}

examples/basic-process-list.rs (line 26)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let domain_id = 'x: {
        for name in &["win7", "win10", "win11", "ubuntu22"] {
            if let Some(domain_id) = XenStore::new()?.domain_id_from_name(name)? {
                break 'x domain_id;
            }
        }

        panic!("Domain not found");
    };

    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::new(domain_id)?;
    let core = VmiCore::new(driver)?;

    // Try to find the kernel information.
    // This is necessary in order to load the profile.
    let kernel_info = {
        // Pause the VM to get consistent state.
        let _pause_guard = core.pause_guard()?;

        // Get the register state for the first vCPU.
        let registers = core.registers(VcpuId(0))?;

        // On AMD64 architecture, the kernel is usually found using the
        // `MSR_LSTAR` register, which contains the address of the system call
        // handler. This register is set by the operating system during boot
        // and is left unchanged (unless some rootkits are involved).
        //
        // Therefore, we can take an arbitrary registers at any point in time
        // (as long as the OS has booted and the page tables are set up) and
        // use them to find the kernel.
        WindowsOs::find_kernel(&core, &registers)?.expect("kernel information")
    };

    // Load the profile.
    // The profile contains offsets to kernel functions and data structures.
    let isr = IsrCache::new("cache")?;
    let entry = isr.entry_from_codeview(kernel_info.codeview)?;
    let profile = entry.profile()?;

    // Create the VMI session.
    tracing::info!("Creating VMI session");
    let os = WindowsOs::<VmiXenDriver<Amd64>>::new(&profile)?;
    let session = VmiSession::new(&core, &os);

    // Pause the VM again to get consistent state.
    let _pause_guard = session.pause_guard()?;

    // Create a new `VmiState` with the current register.
    let registers = session.registers(VcpuId(0))?;
    let vmi = session.with_registers(&registers);

    // Get the list of processes and print them.
    for process in vmi.os().processes()? {
        let process = process?;

        println!(
            "{} [{}] {} (root @ {})",
            process.object()?,
            process.id()?,
            process.name()?,
            process.translation_root()?
        );
    }

    Ok(())
}

pub fn with_gfn_cache(self, size: usize) -> VmiCore<Driver>

Available on crate features utils and injector only.

Enables the Guest Frame Number (GFN) cache.

The GFN cache stores the contents of recently accessed memory pages, indexed by their GFN. This can significantly improve performance when repeatedly accessing the same memory regions, as it avoids redundant reads from the virtual machine.

When enabled, subsequent calls to read_page will first check the cache before querying the driver.

Panics

Panics if size is zero.

pub fn enable_gfn_cache(&mut self)

Available on crate features utils and injector only.

Enables the GFN cache.

See with_gfn_cache for more details.

pub fn disable_gfn_cache(&mut self)

Available on crate features utils and injector only.

Disables the GFN cache.

Subsequent calls to read_page will bypass the cache and read directly from the virtual machine.

pub fn resize_gfn_cache(&mut self, size: usize)

Available on crate features utils and injector only.

Resizes the GFN cache.

This allows you to adjust the cache size dynamically based on your performance needs. A larger cache can improve performance for workloads with high memory locality, but consumes more memory.

Panics

Panics if size is zero.

pub fn flush_gfn_cache_entry(&self, gfn: Gfn) -> Option<VmiMappedPage>

Available on crate features utils and injector only.

Removes a specific entry from the GFN cache.

Returns the removed entry if it was present. This is useful for invalidating cached data that might have become stale.

pub fn flush_gfn_cache(&self)

Available on crate features utils and injector only.

Clears the entire GFN cache.

pub fn with_v2p_cache(self, size: usize) -> VmiCore<Driver>

Available on crate features utils and injector only.

Enables the virtual-to-physical (V2P) address translation cache.

The V2P cache stores the results of recent address translations, mapping virtual addresses (represented by AccessContext) to their corresponding physical addresses (Pa). This can significantly speed up memory access operations, as address translation can be a relatively expensive operation.

When enabled, translate_access_context will consult the cache before performing a full translation.

Panics

Panics if size is zero.

pub fn enable_v2p_cache(&mut self)

Available on crate features utils and injector only.

Enables the V2P cache.

See with_v2p_cache for more details.

pub fn disable_v2p_cache(&mut self)

Available on crate features utils and injector only.

Disables the V2P cache.

Subsequent calls to translate_access_context will bypass the cache and perform a full address translation every time.

pub fn resize_v2p_cache(&mut self, size: usize)

Available on crate features utils and injector only.

Resizes the V2P cache.

This allows dynamic adjustment of the cache size to balance performance and memory usage. A larger cache can lead to better performance if address translations are frequent and exhibit good locality.

Panics

Panics if size is zero.

pub fn flush_v2p_cache_entry(&self, ctx: AccessContext) -> Option<Pa>

Available on crate features utils and injector only.

Removes a specific entry from the V2P cache.

Returns the removed entry if it was present. This can be used to invalidate cached translations that may have become stale due to changes in the guest’s memory mapping.

pub fn flush_v2p_cache(&self)

Available on crate features utils and injector only.

Clears the entire V2P cache.

This method is crucial for maintaining consistency when handling events. The guest operating system can modify page tables or other structures related to address translation between events. Using stale translations can lead to incorrect memory access and unexpected behavior. It is recommended to call this method at the beginning of each VmiHandler::handle_event loop to ensure that you are working with the most up-to-date address mappings.

Examples found in repository

examples/windows-breakpoint-manager.rs (line 514)

    fn handle_event(&mut self, vmi: VmiContext<WindowsOs<Driver>>) -> VmiEventResponse<Amd64> {
        // Flush the V2P cache on every event to avoid stale translations.
        vmi.flush_v2p_cache();

        self.dispatch(&vmi).expect("dispatch")
    }

pub fn with_read_string_length_limit( self, limit_in_bytes: usize, ) -> VmiCore<Driver>

Available on crate features utils and injector only.

Sets a limit on the length of strings read by the read_string methods. If the limit is reached, the string will be truncated.

pub fn read_string_length_limit(&self) -> Option<usize>

Available on crate features utils and injector only.

Returns the current limit on the length of strings read by the read_string methods.

pub fn set_read_string_length_limit(&self, limit: usize)

Available on crate features utils and injector only.

Sets a limit on the length of strings read by the read_string methods.

This method allows you to set a maximum length (in bytes) for strings read from the virtual machine’s memory. When set, string reading operations will truncate their results to this limit. This can be useful for preventing excessively long string reads, which might impact performance or consume too much memory.

If the limit is reached during a string read operation, the resulting string will be truncated to the specified length.

To remove the limit, call this method with None.

pub fn read( &self, ctx: impl Into<AccessContext>, buffer: &mut [u8], ) -> Result<(), VmiError>

Available on crate features utils and injector only.

Reads memory from the virtual machine.

pub fn read_u8(&self, ctx: impl Into<AccessContext>) -> Result<u8, VmiError>

Available on crate features utils and injector only.

Reads a single byte from the virtual machine.

pub fn read_u16(&self, ctx: impl Into<AccessContext>) -> Result<u16, VmiError>

Available on crate features utils and injector only.

Reads a 16-bit unsigned integer from the virtual machine.

pub fn read_u32(&self, ctx: impl Into<AccessContext>) -> Result<u32, VmiError>

Available on crate features utils and injector only.

Reads a 32-bit unsigned integer from the virtual machine.

pub fn read_u64(&self, ctx: impl Into<AccessContext>) -> Result<u64, VmiError>

Available on crate features utils and injector only.

Reads a 64-bit unsigned integer from the virtual machine.

pub fn read_uint( &self, ctx: impl Into<AccessContext>, size: usize, ) -> Result<u64, VmiError>

Available on crate features utils and injector only.

Reads an unsigned integer of the specified size from the virtual machine.

This method reads an unsigned integer of the specified size (in bytes) from the virtual machine. Note that the size must be 1, 2, 4, or 8.

The result is returned as a u64 to accommodate the widest possible integer size.

pub fn read_field( &self, ctx: impl Into<AccessContext>, field: &Field, ) -> Result<u64, VmiError>

Available on crate features utils and injector only.

Reads a field of a structure from the virtual machine.

This method reads a field from the virtual machine. The field is defined by the provided Field structure, which specifies the offset and size of the field within the memory region.

The result is returned as a u64 to accommodate the widest possible integer size.

pub fn read_address( &self, ctx: impl Into<AccessContext>, address_width: usize, ) -> Result<u64, VmiError>

Available on crate features utils and injector only.

Reads an address-sized unsigned integer from the virtual machine.

This method reads an address of the specified width (in bytes) from the given access context. It’s useful when dealing with architectures that can operate in different address modes.

pub fn read_address32( &self, ctx: impl Into<AccessContext>, ) -> Result<u64, VmiError>

Available on crate features utils and injector only.

Reads a 32-bit address from the virtual machine.

pub fn read_address64( &self, ctx: impl Into<AccessContext>, ) -> Result<u64, VmiError>

Available on crate features utils and injector only.

Reads a 64-bit address from the virtual machine.

pub fn read_va( &self, ctx: impl Into<AccessContext>, address_width: usize, ) -> Result<Va, VmiError>

Available on crate features utils and injector only.

Reads a virtual address from the virtual machine.

pub fn read_va32(&self, ctx: impl Into<AccessContext>) -> Result<Va, VmiError>

Available on crate features utils and injector only.

Reads a 32-bit virtual address from the virtual machine.

pub fn read_va64(&self, ctx: impl Into<AccessContext>) -> Result<Va, VmiError>

Available on crate features utils and injector only.

Reads a 64-bit virtual address from the virtual machine.

pub fn read_string_bytes_limited( &self, ctx: impl Into<AccessContext>, limit: usize, ) -> Result<Vec<u8>, VmiError>

Available on crate features utils and injector only.

Reads a null-terminated string of bytes from the virtual machine with a specified limit.

pub fn read_string_bytes( &self, ctx: impl Into<AccessContext>, ) -> Result<Vec<u8>, VmiError>

Available on crate features utils and injector only.

Reads a null-terminated string of bytes from the virtual machine.

pub fn read_string_utf16_bytes_limited( &self, ctx: impl Into<AccessContext>, limit: usize, ) -> Result<Vec<u16>, VmiError>

Available on crate features utils and injector only.

Reads a null-terminated wide string (UTF-16) from the virtual machine with a specified limit.

pub fn read_string_utf16_bytes( &self, ctx: impl Into<AccessContext>, ) -> Result<Vec<u16>, VmiError>

Available on crate features utils and injector only.

Reads a null-terminated wide string (UTF-16) from the virtual machine.

pub fn read_string_limited( &self, ctx: impl Into<AccessContext>, limit: usize, ) -> Result<String, VmiError>

Available on crate features utils and injector only.

Reads a null-terminated string from the virtual machine with a specified limit.

pub fn read_string( &self, ctx: impl Into<AccessContext>, ) -> Result<String, VmiError>

Available on crate features utils and injector only.

Reads a null-terminated string from the virtual machine.

pub fn read_string_utf16_limited( &self, ctx: impl Into<AccessContext>, limit: usize, ) -> Result<String, VmiError>

Available on crate features utils and injector only.

Reads a null-terminated wide string (UTF-16) from the virtual machine with a specified limit.

pub fn read_string_utf16( &self, ctx: impl Into<AccessContext>, ) -> Result<String, VmiError>

Available on crate features utils and injector only.

Reads a null-terminated wide string (UTF-16) from the virtual machine.

pub fn read_struct<T>( &self, ctx: impl Into<AccessContext>, ) -> Result<T, VmiError>

where T: FromBytes + IntoBytes,

Available on crate features utils and injector only.

Reads a struct from the virtual machine.

pub fn translate_address( &self, ctx: impl Into<AddressContext>, ) -> Result<Pa, VmiError>

Available on crate features utils and injector only.

Translates a virtual address to a physical address.

pub fn translate_access_context( &self, ctx: AccessContext, ) -> Result<Pa, VmiError>

Available on crate features utils and injector only.

Translates an access context to a physical address.

pub fn read_page(&self, gfn: Gfn) -> Result<VmiMappedPage, VmiError>

Available on crate features utils and injector only.

Reads a page of memory from the virtual machine.

impl<Driver> VmiCore<Driver>

where Driver: VmiRead + VmiWrite,

pub fn write( &self, ctx: impl Into<AccessContext>, buffer: &[u8], ) -> Result<(), VmiError>

Available on crate features utils and injector only.

Writes memory to the virtual machine.

pub fn write_u8( &self, ctx: impl Into<AccessContext>, value: u8, ) -> Result<(), VmiError>

Available on crate features utils and injector only.

Writes a single byte to the virtual machine.

pub fn write_u16( &self, ctx: impl Into<AccessContext>, value: u16, ) -> Result<(), VmiError>

Available on crate features utils and injector only.

Writes a 16-bit unsigned integer to the virtual machine.

pub fn write_u32( &self, ctx: impl Into<AccessContext>, value: u32, ) -> Result<(), VmiError>

Available on crate features utils and injector only.

Writes a 32-bit unsigned integer to the virtual machine.

pub fn write_u64( &self, ctx: impl Into<AccessContext>, value: u64, ) -> Result<(), VmiError>

Available on crate features utils and injector only.

Writes a 64-bit unsigned integer to the virtual machine.

pub fn write_struct<T>( &self, ctx: impl Into<AccessContext>, value: T, ) -> Result<(), VmiError>

where T: IntoBytes + Immutable,

Available on crate features utils and injector only.

Writes a struct to the virtual machine.

impl<Driver> VmiCore<Driver>

where Driver: VmiQueryProtection,

pub fn memory_access( &self, gfn: Gfn, view: View, ) -> Result<MemoryAccess, VmiError>

Available on crate features utils and injector only.

Retrieves the memory access permissions for a specific guest frame number (GFN).

The returned MemoryAccess indicates the current read, write, and execute permissions for the specified memory page in the given view.

impl<Driver> VmiCore<Driver>

where Driver: VmiSetProtection,

pub fn set_memory_access( &self, gfn: Gfn, view: View, access: MemoryAccess, ) -> Result<(), VmiError>

Available on crate features utils and injector only.

Sets the memory access permissions for a specific guest frame number (GFN).

This method allows you to modify the read, write, and execute permissions for a given memory page in the specified view.

pub fn set_memory_access_with_options( &self, gfn: Gfn, view: View, access: MemoryAccess, options: MemoryAccessOptions, ) -> Result<(), VmiError>

Available on crate features utils and injector only.

Sets the memory access permissions for a specific guest frame number (GFN) with additional options.

In addition to the basic read, write, and execute permissions, this method allows you to specify additional options for the memory access.

impl<Driver> VmiCore<Driver>

where Driver: VmiQueryRegisters,

pub fn registers( &self, vcpu: VcpuId, ) -> Result<<<Driver as VmiDriver>::Architecture as Architecture>::Registers, VmiError>

Available on crate features utils and injector only.

Retrieves the current state of CPU registers for a specified virtual CPU.

This method allows you to access the current values of CPU registers, which is crucial for understanding the state of the virtual machine at a given point in time.

Notes

The exact structure and content of the returned registers depend on the specific architecture of the VM being introspected. Refer to the documentation of your Architecture implementation for details on how to interpret the register values.

Examples found in repository

examples/basic.rs (line 28)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let domain_id = 'x: {
        for name in &["win7", "win10", "win11", "ubuntu22"] {
            if let Some(domain_id) = XenStore::new()?.domain_id_from_name(name)? {
                break 'x domain_id;
            }
        }

        panic!("Domain not found");
    };

    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::new(domain_id)?;
    let vmi = VmiCore::new(driver)?;

    // Get the interrupt descriptor table for each vCPU and print it.
    let _pause_guard = vmi.pause_guard()?;
    let info = vmi.info()?;
    for vcpu_id in 0..info.vcpus {
        let registers = vmi.registers(VcpuId(vcpu_id))?;
        let idt = Amd64::interrupt_descriptor_table(&vmi, &registers)?;

        println!("IDT[{vcpu_id}]: {idt:#?}");
    }

    Ok(())
}

examples/windows-recipe-messagebox.rs (line 74)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (session, _profile) = common::create_vmi_session()?;

    let explorer_pid = {
        // This block is used to drop the pause guard after the PID is found.
        // If the `session.handle()` would be called with the VM paused, no
        // events would be triggered.
        let _pause_guard = session.pause_guard()?;

        let registers = session.registers(VcpuId(0))?;
        let vmi = session.with_registers(&registers);

        let explorer = match common::find_process(&vmi, "explorer.exe")? {
            Some(explorer) => explorer,
            None => {
                tracing::error!("explorer.exe not found");
                return Ok(());
            }
        };

        tracing::info!(
            pid = %explorer.id()?,
            object = %explorer.object()?,
            "found explorer.exe"
        );

        explorer.id()?
    };

    session.handle(|session| {
        UserInjectorHandler::new(
            session,
            recipe_factory(MessageBox::new(
                "Hello, World!",
                "This is a message box from the VMI!",
            )),
        )?
        .with_pid(explorer_pid)
    })?;

    Ok(())
}

examples/windows-recipe-writefile.rs (line 212)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (session, _profile) = common::create_vmi_session()?;

    let explorer_pid = {
        // This block is used to drop the pause guard after the PID is found.
        // If the `session.handle()` would be called with the VM paused, no
        // events would be triggered.
        let _pause_guard = session.pause_guard()?;

        let registers = session.registers(VcpuId(0))?;
        let vmi = session.with_registers(&registers);

        let explorer = match common::find_process(&vmi, "explorer.exe")? {
            Some(explorer) => explorer,
            None => {
                tracing::error!("explorer.exe not found");
                return Ok(());
            }
        };

        tracing::info!(
            pid = %explorer.id()?,
            object = %explorer.object()?,
            "found explorer.exe"
        );

        explorer.id()?
    };

    session.handle(|session| {
        UserInjectorHandler::new(
            session,
            recipe_factory(GuestFile::new(
                "C:\\Users\\John\\Desktop\\test.txt",
                "Hello, World!".as_bytes(),
            )),
        )?
        .with_pid(explorer_pid)
    })?;

    Ok(())
}

examples/windows-recipe-writefile-advanced.rs (line 310)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (session, _profile) = common::create_vmi_session()?;

    let explorer_pid = {
        // This block is used to drop the pause guard after the PID is found.
        // If the `session.handle()` would be called with the VM paused, no
        // events would be triggered.
        let _pause_guard = session.pause_guard()?;

        let registers = session.registers(VcpuId(0))?;
        let vmi = session.with_registers(&registers);

        let explorer = match common::find_process(&vmi, "explorer.exe")? {
            Some(explorer) => explorer,
            None => {
                tracing::error!("explorer.exe not found");
                return Ok(());
            }
        };

        tracing::info!(
            pid = %explorer.id()?,
            object = %explorer.object()?,
            "found explorer.exe"
        );

        explorer.id()?
    };

    let mut content = Vec::new();
    for c in 'A'..='Z' {
        content.extend((0..2049).map(|_| c as u8).collect::<Vec<_>>());
    }

    session.handle(|session| {
        UserInjectorHandler::new(
            session,
            recipe_factory(GuestFile::new(
                "C:\\Users\\John\\Desktop\\test.txt",
                content,
            )),
        )?
        .with_pid(explorer_pid)
    })?;

    Ok(())
}

examples/windows-dump.rs (line 412)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    tracing_subscriber::fmt()
        .with_max_level(tracing::Level::DEBUG)
        .with_ansi(false)
        .init();

    // First argument is the path to the dump file.
    let args = std::env::args().collect::<Vec<_>>();
    if args.len() != 2 {
        eprintln!("Usage: {} <dump-file>", args[0]);
        std::process::exit(1);
    }

    let dump_file = &args[1];

    // Setup VMI.
    let driver = Driver::new(dump_file)?;
    let core = VmiCore::new(driver)?;

    let registers = core.registers(VcpuId(0))?;

    // Try to find the kernel information.
    // This is necessary in order to load the profile.
    let kernel_info = WindowsOs::find_kernel(&core, &registers)?.expect("kernel information");
    tracing::info!(?kernel_info, "Kernel information");

    // Load the profile.
    // The profile contains offsets to kernel functions and data structures.
    let isr = IsrCache::new("cache")?;
    let entry = isr.entry_from_codeview(kernel_info.codeview)?;
    let profile = entry.profile()?;

    // Create the VMI session.
    tracing::info!("Creating VMI session");
    let os = WindowsOs::<Driver>::with_kernel_base(&profile, kernel_info.base_address)?;
    let session = VmiSession::new(&core, &os);

    let vmi = session.with_registers(&registers);
    let root_directory = vmi.os().object_root_directory()?;

    println!("Kernel Modules:");
    println!("=================================================");
    enumerate_kernel_modules(&vmi)?;

    println!("Object Tree (root directory: {}):", root_directory.va());
    println!("=================================================");
    enumerate_directory_object(&root_directory, 0)?;

    println!("Processes:");
    println!("=================================================");
    enumerate_processes(&vmi)?;

    Ok(())
}

examples/common/mod.rs (line 44)

pub fn create_vmi_session() -> Result<Session, Box<dyn std::error::Error>> {
    tracing_subscriber::fmt()
        .with_max_level(tracing::Level::DEBUG)
        .with_target(false)
        .init();

    let domain_id = 'x: {
        for name in &["win7", "win10", "win11", "ubuntu22"] {
            if let Some(domain_id) = XenStore::new()?.domain_id_from_name(name)? {
                break 'x domain_id;
            }
        }

        panic!("Domain not found");
    };

    tracing::debug!(?domain_id);

    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::new(domain_id)?;
    let core = VmiCore::new(driver)?;

    // Try to find the kernel information.
    // This is necessary in order to load the profile.
    let kernel_info = {
        // Pause the vCPU to get consistent state.
        let _pause_guard = core.pause_guard()?;

        // Get the register state for the first vCPU.
        let registers = core.registers(VcpuId(0))?;

        // On AMD64 architecture, the kernel is usually found using the
        // `MSR_LSTAR` register, which contains the address of the system call
        // handler. This register is set by the operating system during boot
        // and is left unchanged (unless some rootkits are involved).
        //
        // Therefore, we can take an arbitrary registers at any point in time
        // (as long as the OS has booted and the page tables are set up) and
        // use them to find the kernel.
        WindowsOs::find_kernel(&core, &registers)?.expect("kernel information")
    };

    // Load the profile.
    // The profile contains offsets to kernel functions and data structures.
    let isr = IsrCache::new("cache")?;
    let entry = isr.entry_from_codeview(kernel_info.codeview)?;
    let entry = Box::leak(Box::new(entry));
    let profile = entry.profile()?;

    // Create the VMI session.
    tracing::info!("Creating VMI session");
    let os = WindowsOs::<VmiXenDriver<Amd64>>::new(&profile)?;

    // Please don't do this in production code.
    // This is only done for the sake of the example.
    let core = Box::leak(Box::new(core));
    let os = Box::leak(Box::new(os));

    Ok((VmiSession::new(core, os), profile))
}

Additional examples can be found in:

• examples/basic-process-list.rs
• examples/windows-breakpoint-manager.rs

impl<Driver> VmiCore<Driver>

where Driver: VmiSetRegisters,

pub fn set_registers( &self, vcpu: VcpuId, registers: <<Driver as VmiDriver>::Architecture as Architecture>::Registers, ) -> Result<(), VmiError>

Available on crate features utils and injector only.

Sets the registers of a virtual CPU.

impl<Driver> VmiCore<Driver>

where Driver: VmiViewControl,

pub fn default_view(&self) -> View

Available on crate features utils and injector only.

Returns the default view for the virtual machine.

The default view typically represents the normal, unmodified state of the VM’s memory.

Examples found in repository

examples/windows-breakpoint-manager.rs (line 261)

    fn memory_access(
        &mut self,
        vmi: &VmiContext<WindowsOs<Driver>>,
    ) -> Result<VmiEventResponse<Amd64>, VmiError> {
        let memory_access = vmi.event().reason().as_memory_access();

        tracing::trace!(
            pa = %memory_access.pa,
            va = %memory_access.va,
            access = %memory_access.access,
        );

        if memory_access.access.contains(MemoryAccess::W) {
            // It is assumed that a write memory access event is caused by a
            // page table modification.
            //
            // The page table entry is marked as dirty in the page table monitor
            // and a singlestep is performed to process the dirty entries.
            self.ptm
                .mark_dirty_entry(memory_access.pa, self.view, vmi.event().vcpu_id());

            Ok(VmiEventResponse::singlestep().with_view(vmi.default_view()))
        }
        else if memory_access.access.contains(MemoryAccess::R) {
            // When the guest tries to read from the memory, a fast-singlestep
            // is performed over the instruction that tried to read the memory.
            // This is done to allow the instruction to read the original memory
            // content.
            Ok(VmiEventResponse::fast_singlestep(vmi.default_view()))
        }
        else {
            panic!("Unhandled memory access: {memory_access:?}");
        }
    }

    #[tracing::instrument(skip_all, fields(pid, process))]
    fn interrupt(
        &mut self,
        vmi: &VmiContext<WindowsOs<Driver>>,
    ) -> Result<VmiEventResponse<Amd64>, VmiError> {
        let tag = match self.bpm.get_by_event(vmi.event(), ()) {
            Some(breakpoints) => {
                // Breakpoints can have multiple tags, but we have set only one
                // tag for each breakpoint.
                let first_breakpoint = breakpoints.into_iter().next().expect("breakpoint");
                first_breakpoint.tag()
            }
            None => {
                if BreakpointController::is_breakpoint(vmi, vmi.event())? {
                    // This breakpoint was not set by us. Reinject it.
                    tracing::warn!("Unknown breakpoint, reinjecting");
                    return Ok(VmiEventResponse::reinject_interrupt());
                }
                else {
                    // We have received a breakpoint event, but there is no
                    // breakpoint instruction at the current memory location.
                    // This can happen if the event was triggered by a breakpoint
                    // we just removed.
                    tracing::warn!("Ignoring old breakpoint event");
                    return Ok(VmiEventResponse::fast_singlestep(vmi.default_view()));
                }
            }
        };

        let process = vmi.os().current_process()?;
        let process_id = process.id()?;
        let process_name = process.name()?;
        tracing::Span::current()
            .record("pid", process_id.0)
            .record("process", process_name);

        match tag {
            "NtCreateFile" => self.NtCreateFile(vmi)?,
            "NtWriteFile" => self.NtWriteFile(vmi)?,
            "PspInsertProcess" => self.PspInsertProcess(vmi)?,
            "MmCleanProcessAddressSpace" => self.MmCleanProcessAddressSpace(vmi)?,
            _ => panic!("Unhandled tag: {tag}"),
        }

        Ok(VmiEventResponse::fast_singlestep(vmi.default_view()))
    }

pub fn create_view( &self, default_access: MemoryAccess, ) -> Result<View, VmiError>

Available on crate features utils and injector only.

Creates a new view with the specified default access permissions.

Views allow for creating different perspectives of the VM’s memory, which can be useful for analysis or isolation purposes. The default access permissions apply to memory pages not explicitly modified within this view.

Examples found in repository

examples/windows-breakpoint-manager.rs (line 123)

    pub fn new(
        session: &VmiSession<WindowsOs<Driver>>,
        profile: &Profile,
        terminate_flag: Arc<AtomicBool>,
    ) -> Result<Self, VmiError> {
        // Capture the current state of the vCPU and get the base address of
        // the kernel.
        //
        // This base address is essential to correctly offset monitored
        // functions.
        //
        // NOTE: `kernel_image_base` tries to find the kernel in the memory
        //       with the help of the CPU registers. On AMD64 architecture,
        //       the kernel image base is usually found using the `MSR_LSTAR`
        //       register, which contains the address of the system call
        //       handler. This register is set by the operating system during
        //       boot and is left unchanged (unless some rootkits are involved).
        //
        //       Therefore, we can take an arbitrary registers at any point
        //       in time (as long as the OS has booted and the page tables are
        //       set up) and use them to find the kernel image base.
        let registers = session.registers(VcpuId(0))?;
        let vmi = session.with_registers(&registers);

        let kernel_image_base = vmi.os().kernel_image_base()?;
        tracing::info!(%kernel_image_base);

        // Get the system process.
        //
        // The system process is the first process created by the kernel.
        // In Windows, it is referenced by the kernel symbol `PsInitialSystemProcess`.
        // To monitor page table entries, we need to locate the translation root
        // of this process.
        let system_process = vmi.os().system_process()?;
        tracing::info!(system_process = %system_process.object()?);

        // Get the translation root of the system process.
        // This is effectively "the CR3 of the kernel".
        //
        // The translation root is the root of the page table hierarchy (also
        // known as the Directory Table Base or PML4).
        let root = system_process.translation_root()?;
        tracing::info!(%root);

        // Load the symbols from the profile.
        let symbols = Symbols::new(profile)?;

        // Enable monitoring of the INT3 and singlestep events.
        //
        // INT3 is used to monitor the execution of specific functions.
        // Singlestep is used to monitor the modifications of page table
        // entries.
        vmi.monitor_enable(EventMonitor::Interrupt(ExceptionVector::Breakpoint))?;
        vmi.monitor_enable(EventMonitor::Singlestep)?;

        // Create a new view for the monitor.
        // This view is used for monitoring function calls and memory accesses.
        let view = vmi.create_view(MemoryAccess::RWX)?;
        vmi.switch_to_view(view)?;

        // Create a new breakpoint controller.
        //
        // The breakpoint controller is used to insert breakpoints for specific
        // functions.
        //
        // From the guest's perspective, these breakpoints are "hidden", since
        // the breakpoint controller will unset the read/write access to the
        // physical memory page where the breakpoint is inserted, while keeping
        // the execute access.
        //
        // This way, the guest will be able to execute the code, but attempts to
        // read or write the memory will trigger the `memory_access` callback.
        //
        // When a vCPU tries to execute the breakpoint instruction:
        // - an `interrupt` callback will be triggered
        // - the breakpoint will be handled (e.g., log the function call)
        // - a fast-singlestep[1] will be performed over the INT3 instruction
        //
        // When a vCPU tries to read from this page (e.g., a PatchGuard check):
        // - `memory_access` callback will be triggered (with the `MemoryAccess::R`
        //   access type)
        // - fast-singlestep[1] will be performed over the instruction that tried to
        //   read the memory
        //
        // This way, the instruction will read the original memory content.
        //
        // [1] Fast-singlestep is a VMI feature that allows to switch the vCPU
        //     to a different view, execute a single instruction, and then
        //     switch back to the original view. In this case, the view is
        //     switched to the `default_view` (which is unmodified).
        let mut bpm = BreakpointManager::new();

        // Create a new page table monitor.
        //
        // The page table monitor is used to monitor the page table entries of
        // the hooked functions.
        //
        // More specifically, it is used to monitor the pages that the breakpoint
        // was inserted into. This is necessary to handle the case when the
        // page containing the breakpoint is paged out (and then paged in
        // again).
        //
        // `PageTableMonitor` works by unsetting the write access to the page
        // tables of the hooked functions. When the page is paged out, the
        // `PRESENT` bit in the page table entry is unset and, conversely, when
        // the page is paged in, the `PRESENT` bit is set again.
        //
        // When that happens:
        // - the `memory_access` callback will be triggered (with the `MemoryAccess::R`
        //   access type)
        // - the callback will mark the page as dirty in the page table monitor
        // - a singlestep will be performed over the instruction that tried to modify
        //   the memory containing the page table entry
        // - the `singlestep` handler will process the dirty page table entries and
        //   inform the breakpoint controller to handle the changes
        let mut ptm = PageTableMonitor::new();

        // Pause the VM to avoid race conditions between inserting breakpoints
        // and monitoring page table entries. The VM resumes when the pause
        // guard is dropped.
        let _pause_guard = vmi.pause_guard()?;

        // Insert breakpoint for the `NtCreateFile` function.
        let va_NtCreateFile = kernel_image_base + symbols.NtCreateFile;
        let cx_NtCreateFile = (va_NtCreateFile, root);
        let bp_NtCreateFile = Breakpoint::new(cx_NtCreateFile, view)
            .global()
            .with_tag("NtCreateFile");
        bpm.insert(&vmi, bp_NtCreateFile)?;
        ptm.monitor(&vmi, cx_NtCreateFile, view, "NtCreateFile")?;
        tracing::info!(%va_NtCreateFile);

        // Insert breakpoint for the `NtWriteFile` function.
        let va_NtWriteFile = kernel_image_base + symbols.NtWriteFile;
        let cx_NtWriteFile = (va_NtWriteFile, root);
        let bp_NtWriteFile = Breakpoint::new(cx_NtWriteFile, view)
            .global()
            .with_tag("NtWriteFile");
        bpm.insert(&vmi, bp_NtWriteFile)?;
        ptm.monitor(&vmi, cx_NtWriteFile, view, "NtWriteFile")?;
        tracing::info!(%va_NtWriteFile);

        // Insert breakpoint for the `PspInsertProcess` function.
        let va_PspInsertProcess = kernel_image_base + symbols.PspInsertProcess;
        let cx_PspInsertProcess = (va_PspInsertProcess, root);
        let bp_PspInsertProcess = Breakpoint::new(cx_PspInsertProcess, view)
            .global()
            .with_tag("PspInsertProcess");
        bpm.insert(&vmi, bp_PspInsertProcess)?;
        ptm.monitor(&vmi, cx_PspInsertProcess, view, "PspInsertProcess")?;

        // Insert breakpoint for the `MmCleanProcessAddressSpace` function.
        let va_MmCleanProcessAddressSpace = kernel_image_base + symbols.MmCleanProcessAddressSpace;
        let cx_MmCleanProcessAddressSpace = (va_MmCleanProcessAddressSpace, root);
        let bp_MmCleanProcessAddressSpace = Breakpoint::new(cx_MmCleanProcessAddressSpace, view)
            .global()
            .with_tag("MmCleanProcessAddressSpace");
        bpm.insert(&vmi, bp_MmCleanProcessAddressSpace)?;
        ptm.monitor(
            &vmi,
            cx_MmCleanProcessAddressSpace,
            view,
            "MmCleanProcessAddressSpace",
        )?;

        Ok(Self {
            terminate_flag,
            view,
            bpm,
            ptm,
        })
    }

pub fn destroy_view(&self, view: View) -> Result<(), VmiError>

Available on crate features utils and injector only.

Destroys a previously created view.

This method removes a view and frees associated resources. It should be called when a view is no longer needed to prevent resource leaks.

pub fn switch_to_view(&self, view: View) -> Result<(), VmiError>

Available on crate features utils and injector only.

Switches to a different view for all virtual CPUs.

This method changes the current active view for all vCPUs, affecting subsequent memory operations across the entire VM. It allows for quick transitions between different memory perspectives globally.

Note the difference between this method and VmiEventResponse::with_view():

• switch_to_view() changes the view for all vCPUs immediately.
• VmiEventResponse::with_view() sets the view only for the specific vCPU that received the event, and the change is applied when the event handler returns.

Use switch_to_view() for global view changes, and VmiEventResponse::with_view() for targeted, event-specific view modifications on individual vCPUs.

Examples found in repository

examples/windows-breakpoint-manager.rs (line 124)

    pub fn new(
        session: &VmiSession<WindowsOs<Driver>>,
        profile: &Profile,
        terminate_flag: Arc<AtomicBool>,
    ) -> Result<Self, VmiError> {
        // Capture the current state of the vCPU and get the base address of
        // the kernel.
        //
        // This base address is essential to correctly offset monitored
        // functions.
        //
        // NOTE: `kernel_image_base` tries to find the kernel in the memory
        //       with the help of the CPU registers. On AMD64 architecture,
        //       the kernel image base is usually found using the `MSR_LSTAR`
        //       register, which contains the address of the system call
        //       handler. This register is set by the operating system during
        //       boot and is left unchanged (unless some rootkits are involved).
        //
        //       Therefore, we can take an arbitrary registers at any point
        //       in time (as long as the OS has booted and the page tables are
        //       set up) and use them to find the kernel image base.
        let registers = session.registers(VcpuId(0))?;
        let vmi = session.with_registers(&registers);

        let kernel_image_base = vmi.os().kernel_image_base()?;
        tracing::info!(%kernel_image_base);

        // Get the system process.
        //
        // The system process is the first process created by the kernel.
        // In Windows, it is referenced by the kernel symbol `PsInitialSystemProcess`.
        // To monitor page table entries, we need to locate the translation root
        // of this process.
        let system_process = vmi.os().system_process()?;
        tracing::info!(system_process = %system_process.object()?);

        // Get the translation root of the system process.
        // This is effectively "the CR3 of the kernel".
        //
        // The translation root is the root of the page table hierarchy (also
        // known as the Directory Table Base or PML4).
        let root = system_process.translation_root()?;
        tracing::info!(%root);

        // Load the symbols from the profile.
        let symbols = Symbols::new(profile)?;

        // Enable monitoring of the INT3 and singlestep events.
        //
        // INT3 is used to monitor the execution of specific functions.
        // Singlestep is used to monitor the modifications of page table
        // entries.
        vmi.monitor_enable(EventMonitor::Interrupt(ExceptionVector::Breakpoint))?;
        vmi.monitor_enable(EventMonitor::Singlestep)?;

        // Create a new view for the monitor.
        // This view is used for monitoring function calls and memory accesses.
        let view = vmi.create_view(MemoryAccess::RWX)?;
        vmi.switch_to_view(view)?;

        // Create a new breakpoint controller.
        //
        // The breakpoint controller is used to insert breakpoints for specific
        // functions.
        //
        // From the guest's perspective, these breakpoints are "hidden", since
        // the breakpoint controller will unset the read/write access to the
        // physical memory page where the breakpoint is inserted, while keeping
        // the execute access.
        //
        // This way, the guest will be able to execute the code, but attempts to
        // read or write the memory will trigger the `memory_access` callback.
        //
        // When a vCPU tries to execute the breakpoint instruction:
        // - an `interrupt` callback will be triggered
        // - the breakpoint will be handled (e.g., log the function call)
        // - a fast-singlestep[1] will be performed over the INT3 instruction
        //
        // When a vCPU tries to read from this page (e.g., a PatchGuard check):
        // - `memory_access` callback will be triggered (with the `MemoryAccess::R`
        //   access type)
        // - fast-singlestep[1] will be performed over the instruction that tried to
        //   read the memory
        //
        // This way, the instruction will read the original memory content.
        //
        // [1] Fast-singlestep is a VMI feature that allows to switch the vCPU
        //     to a different view, execute a single instruction, and then
        //     switch back to the original view. In this case, the view is
        //     switched to the `default_view` (which is unmodified).
        let mut bpm = BreakpointManager::new();

        // Create a new page table monitor.
        //
        // The page table monitor is used to monitor the page table entries of
        // the hooked functions.
        //
        // More specifically, it is used to monitor the pages that the breakpoint
        // was inserted into. This is necessary to handle the case when the
        // page containing the breakpoint is paged out (and then paged in
        // again).
        //
        // `PageTableMonitor` works by unsetting the write access to the page
        // tables of the hooked functions. When the page is paged out, the
        // `PRESENT` bit in the page table entry is unset and, conversely, when
        // the page is paged in, the `PRESENT` bit is set again.
        //
        // When that happens:
        // - the `memory_access` callback will be triggered (with the `MemoryAccess::R`
        //   access type)
        // - the callback will mark the page as dirty in the page table monitor
        // - a singlestep will be performed over the instruction that tried to modify
        //   the memory containing the page table entry
        // - the `singlestep` handler will process the dirty page table entries and
        //   inform the breakpoint controller to handle the changes
        let mut ptm = PageTableMonitor::new();

        // Pause the VM to avoid race conditions between inserting breakpoints
        // and monitoring page table entries. The VM resumes when the pause
        // guard is dropped.
        let _pause_guard = vmi.pause_guard()?;

        // Insert breakpoint for the `NtCreateFile` function.
        let va_NtCreateFile = kernel_image_base + symbols.NtCreateFile;
        let cx_NtCreateFile = (va_NtCreateFile, root);
        let bp_NtCreateFile = Breakpoint::new(cx_NtCreateFile, view)
            .global()
            .with_tag("NtCreateFile");
        bpm.insert(&vmi, bp_NtCreateFile)?;
        ptm.monitor(&vmi, cx_NtCreateFile, view, "NtCreateFile")?;
        tracing::info!(%va_NtCreateFile);

        // Insert breakpoint for the `NtWriteFile` function.
        let va_NtWriteFile = kernel_image_base + symbols.NtWriteFile;
        let cx_NtWriteFile = (va_NtWriteFile, root);
        let bp_NtWriteFile = Breakpoint::new(cx_NtWriteFile, view)
            .global()
            .with_tag("NtWriteFile");
        bpm.insert(&vmi, bp_NtWriteFile)?;
        ptm.monitor(&vmi, cx_NtWriteFile, view, "NtWriteFile")?;
        tracing::info!(%va_NtWriteFile);

        // Insert breakpoint for the `PspInsertProcess` function.
        let va_PspInsertProcess = kernel_image_base + symbols.PspInsertProcess;
        let cx_PspInsertProcess = (va_PspInsertProcess, root);
        let bp_PspInsertProcess = Breakpoint::new(cx_PspInsertProcess, view)
            .global()
            .with_tag("PspInsertProcess");
        bpm.insert(&vmi, bp_PspInsertProcess)?;
        ptm.monitor(&vmi, cx_PspInsertProcess, view, "PspInsertProcess")?;

        // Insert breakpoint for the `MmCleanProcessAddressSpace` function.
        let va_MmCleanProcessAddressSpace = kernel_image_base + symbols.MmCleanProcessAddressSpace;
        let cx_MmCleanProcessAddressSpace = (va_MmCleanProcessAddressSpace, root);
        let bp_MmCleanProcessAddressSpace = Breakpoint::new(cx_MmCleanProcessAddressSpace, view)
            .global()
            .with_tag("MmCleanProcessAddressSpace");
        bpm.insert(&vmi, bp_MmCleanProcessAddressSpace)?;
        ptm.monitor(
            &vmi,
            cx_MmCleanProcessAddressSpace,
            view,
            "MmCleanProcessAddressSpace",
        )?;

        Ok(Self {
            terminate_flag,
            view,
            bpm,
            ptm,
        })
    }

pub fn change_view_gfn( &self, view: View, old_gfn: Gfn, new_gfn: Gfn, ) -> Result<(), VmiError>

Available on crate features utils and injector only.

Changes the mapping of a guest frame number (GFN) in a specific view.

This method allows for remapping a GFN to a different physical frame within a view, enabling fine-grained control over memory layout in different views.

A notable use case for this method is implementing “stealth hooks”:

1. Create a new GFN and copy the contents of the original page to it.
2. Modify the new page by installing a breakpoint (e.g., 0xcc on AMD64) at a strategic location.
3. Use this method to change the mapping of the original GFN to the new one.
4. Set the memory access of the new GFN to non-readable.

When a read access occurs:

• The handler should enable single-stepping.
• Switch to an unmodified view (e.g., default_view) to execute the read instruction, which will read the original non-breakpoint byte.
• Re-enable single-stepping afterwards.

This technique allows for transparent breakpoints that are difficult to detect by the guest OS or applications.

pub fn reset_view_gfn(&self, view: View, gfn: Gfn) -> Result<(), VmiError>

Available on crate features utils and injector only.

Resets the mapping of a guest frame number (GFN) in a specific view to its original state.

This method reverts any custom mapping for the specified GFN in the given view, restoring it to the default mapping.

impl<Driver> VmiCore<Driver>

where Driver: VmiEventControl,

pub fn monitor_enable( &self, option: <<Driver as VmiDriver>::Architecture as Architecture>::EventMonitor, ) -> Result<(), VmiError>

Available on crate features utils and injector only.

Enables monitoring of specific events.

This method allows you to enable monitoring of specific events, such as control register writes, interrupts, or single-step execution. Monitoring events can be useful for tracking specific guest behavior or for implementing custom analysis tools.

The type of event to monitor is defined by the architecture-specific Architecture::EventMonitor type.

When an event occurs, it will be passed to the event callback function for processing.

Examples found in repository

examples/windows-breakpoint-manager.rs (line 118)

    pub fn new(
        session: &VmiSession<WindowsOs<Driver>>,
        profile: &Profile,
        terminate_flag: Arc<AtomicBool>,
    ) -> Result<Self, VmiError> {
        // Capture the current state of the vCPU and get the base address of
        // the kernel.
        //
        // This base address is essential to correctly offset monitored
        // functions.
        //
        // NOTE: `kernel_image_base` tries to find the kernel in the memory
        //       with the help of the CPU registers. On AMD64 architecture,
        //       the kernel image base is usually found using the `MSR_LSTAR`
        //       register, which contains the address of the system call
        //       handler. This register is set by the operating system during
        //       boot and is left unchanged (unless some rootkits are involved).
        //
        //       Therefore, we can take an arbitrary registers at any point
        //       in time (as long as the OS has booted and the page tables are
        //       set up) and use them to find the kernel image base.
        let registers = session.registers(VcpuId(0))?;
        let vmi = session.with_registers(&registers);

        let kernel_image_base = vmi.os().kernel_image_base()?;
        tracing::info!(%kernel_image_base);

        // Get the system process.
        //
        // The system process is the first process created by the kernel.
        // In Windows, it is referenced by the kernel symbol `PsInitialSystemProcess`.
        // To monitor page table entries, we need to locate the translation root
        // of this process.
        let system_process = vmi.os().system_process()?;
        tracing::info!(system_process = %system_process.object()?);

        // Get the translation root of the system process.
        // This is effectively "the CR3 of the kernel".
        //
        // The translation root is the root of the page table hierarchy (also
        // known as the Directory Table Base or PML4).
        let root = system_process.translation_root()?;
        tracing::info!(%root);

        // Load the symbols from the profile.
        let symbols = Symbols::new(profile)?;

        // Enable monitoring of the INT3 and singlestep events.
        //
        // INT3 is used to monitor the execution of specific functions.
        // Singlestep is used to monitor the modifications of page table
        // entries.
        vmi.monitor_enable(EventMonitor::Interrupt(ExceptionVector::Breakpoint))?;
        vmi.monitor_enable(EventMonitor::Singlestep)?;

        // Create a new view for the monitor.
        // This view is used for monitoring function calls and memory accesses.
        let view = vmi.create_view(MemoryAccess::RWX)?;
        vmi.switch_to_view(view)?;

        // Create a new breakpoint controller.
        //
        // The breakpoint controller is used to insert breakpoints for specific
        // functions.
        //
        // From the guest's perspective, these breakpoints are "hidden", since
        // the breakpoint controller will unset the read/write access to the
        // physical memory page where the breakpoint is inserted, while keeping
        // the execute access.
        //
        // This way, the guest will be able to execute the code, but attempts to
        // read or write the memory will trigger the `memory_access` callback.
        //
        // When a vCPU tries to execute the breakpoint instruction:
        // - an `interrupt` callback will be triggered
        // - the breakpoint will be handled (e.g., log the function call)
        // - a fast-singlestep[1] will be performed over the INT3 instruction
        //
        // When a vCPU tries to read from this page (e.g., a PatchGuard check):
        // - `memory_access` callback will be triggered (with the `MemoryAccess::R`
        //   access type)
        // - fast-singlestep[1] will be performed over the instruction that tried to
        //   read the memory
        //
        // This way, the instruction will read the original memory content.
        //
        // [1] Fast-singlestep is a VMI feature that allows to switch the vCPU
        //     to a different view, execute a single instruction, and then
        //     switch back to the original view. In this case, the view is
        //     switched to the `default_view` (which is unmodified).
        let mut bpm = BreakpointManager::new();

        // Create a new page table monitor.
        //
        // The page table monitor is used to monitor the page table entries of
        // the hooked functions.
        //
        // More specifically, it is used to monitor the pages that the breakpoint
        // was inserted into. This is necessary to handle the case when the
        // page containing the breakpoint is paged out (and then paged in
        // again).
        //
        // `PageTableMonitor` works by unsetting the write access to the page
        // tables of the hooked functions. When the page is paged out, the
        // `PRESENT` bit in the page table entry is unset and, conversely, when
        // the page is paged in, the `PRESENT` bit is set again.
        //
        // When that happens:
        // - the `memory_access` callback will be triggered (with the `MemoryAccess::R`
        //   access type)
        // - the callback will mark the page as dirty in the page table monitor
        // - a singlestep will be performed over the instruction that tried to modify
        //   the memory containing the page table entry
        // - the `singlestep` handler will process the dirty page table entries and
        //   inform the breakpoint controller to handle the changes
        let mut ptm = PageTableMonitor::new();

        // Pause the VM to avoid race conditions between inserting breakpoints
        // and monitoring page table entries. The VM resumes when the pause
        // guard is dropped.
        let _pause_guard = vmi.pause_guard()?;

        // Insert breakpoint for the `NtCreateFile` function.
        let va_NtCreateFile = kernel_image_base + symbols.NtCreateFile;
        let cx_NtCreateFile = (va_NtCreateFile, root);
        let bp_NtCreateFile = Breakpoint::new(cx_NtCreateFile, view)
            .global()
            .with_tag("NtCreateFile");
        bpm.insert(&vmi, bp_NtCreateFile)?;
        ptm.monitor(&vmi, cx_NtCreateFile, view, "NtCreateFile")?;
        tracing::info!(%va_NtCreateFile);

        // Insert breakpoint for the `NtWriteFile` function.
        let va_NtWriteFile = kernel_image_base + symbols.NtWriteFile;
        let cx_NtWriteFile = (va_NtWriteFile, root);
        let bp_NtWriteFile = Breakpoint::new(cx_NtWriteFile, view)
            .global()
            .with_tag("NtWriteFile");
        bpm.insert(&vmi, bp_NtWriteFile)?;
        ptm.monitor(&vmi, cx_NtWriteFile, view, "NtWriteFile")?;
        tracing::info!(%va_NtWriteFile);

        // Insert breakpoint for the `PspInsertProcess` function.
        let va_PspInsertProcess = kernel_image_base + symbols.PspInsertProcess;
        let cx_PspInsertProcess = (va_PspInsertProcess, root);
        let bp_PspInsertProcess = Breakpoint::new(cx_PspInsertProcess, view)
            .global()
            .with_tag("PspInsertProcess");
        bpm.insert(&vmi, bp_PspInsertProcess)?;
        ptm.monitor(&vmi, cx_PspInsertProcess, view, "PspInsertProcess")?;

        // Insert breakpoint for the `MmCleanProcessAddressSpace` function.
        let va_MmCleanProcessAddressSpace = kernel_image_base + symbols.MmCleanProcessAddressSpace;
        let cx_MmCleanProcessAddressSpace = (va_MmCleanProcessAddressSpace, root);
        let bp_MmCleanProcessAddressSpace = Breakpoint::new(cx_MmCleanProcessAddressSpace, view)
            .global()
            .with_tag("MmCleanProcessAddressSpace");
        bpm.insert(&vmi, bp_MmCleanProcessAddressSpace)?;
        ptm.monitor(
            &vmi,
            cx_MmCleanProcessAddressSpace,
            view,
            "MmCleanProcessAddressSpace",
        )?;

        Ok(Self {
            terminate_flag,
            view,
            bpm,
            ptm,
        })
    }

pub fn monitor_disable( &self, option: <<Driver as VmiDriver>::Architecture as Architecture>::EventMonitor, ) -> Result<(), VmiError>

Available on crate features utils and injector only.

Disables monitoring of specific events.

This method allows you to disable monitoring of specific events that were previously enabled. It can be used to stop tracking certain hardware events or to reduce the overhead of event processing.

The type of event to disable is defined by the architecture-specific Architecture::EventMonitor type.

pub fn events_pending(&self) -> usize

Available on crate features utils and injector only.

Returns the number of pending events.

This method provides a count of events that have occurred but have not yet been processed.

pub fn event_processing_overhead(&self) -> Duration

Available on crate features utils and injector only.

Returns the time spent processing events by the driver.

This method provides a measure of the overhead introduced by event processing. It can be useful for performance tuning and understanding the impact of VMI operations on overall system performance.

pub fn wait_for_event( &self, timeout: Duration, handler: impl FnMut(&VmiEvent<<Driver as VmiDriver>::Architecture>) -> VmiEventResponse<<Driver as VmiDriver>::Architecture>, ) -> Result<(), VmiError>

Available on crate features utils and injector only.

Waits for an event to occur and processes it with the provided handler.

This method blocks until an event occurs or the specified timeout is reached. When an event occurs, it is passed to the provided callback function for processing.

impl<Driver> VmiCore<Driver>

where Driver: VmiVmControl,

pub fn pause(&self) -> Result<(), VmiError>

Available on crate features utils and injector only.

Pauses the virtual machine.

pub fn resume(&self) -> Result<(), VmiError>

Available on crate features utils and injector only.

Resumes the virtual machine.

pub fn pause_guard(&self) -> Result<VmiPauseGuard<'_, Driver>, VmiError>

Available on crate features utils and injector only.

Pauses the virtual machine and returns a guard that will resume it when dropped.

Examples found in repository

examples/basic.rs (line 25)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let domain_id = 'x: {
        for name in &["win7", "win10", "win11", "ubuntu22"] {
            if let Some(domain_id) = XenStore::new()?.domain_id_from_name(name)? {
                break 'x domain_id;
            }
        }

        panic!("Domain not found");
    };

    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::new(domain_id)?;
    let vmi = VmiCore::new(driver)?;

    // Get the interrupt descriptor table for each vCPU and print it.
    let _pause_guard = vmi.pause_guard()?;
    let info = vmi.info()?;
    for vcpu_id in 0..info.vcpus {
        let registers = vmi.registers(VcpuId(vcpu_id))?;
        let idt = Amd64::interrupt_descriptor_table(&vmi, &registers)?;

        println!("IDT[{vcpu_id}]: {idt:#?}");
    }

    Ok(())
}

examples/windows-recipe-messagebox.rs (line 72)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (session, _profile) = common::create_vmi_session()?;

    let explorer_pid = {
        // This block is used to drop the pause guard after the PID is found.
        // If the `session.handle()` would be called with the VM paused, no
        // events would be triggered.
        let _pause_guard = session.pause_guard()?;

        let registers = session.registers(VcpuId(0))?;
        let vmi = session.with_registers(&registers);

        let explorer = match common::find_process(&vmi, "explorer.exe")? {
            Some(explorer) => explorer,
            None => {
                tracing::error!("explorer.exe not found");
                return Ok(());
            }
        };

        tracing::info!(
            pid = %explorer.id()?,
            object = %explorer.object()?,
            "found explorer.exe"
        );

        explorer.id()?
    };

    session.handle(|session| {
        UserInjectorHandler::new(
            session,
            recipe_factory(MessageBox::new(
                "Hello, World!",
                "This is a message box from the VMI!",
            )),
        )?
        .with_pid(explorer_pid)
    })?;

    Ok(())
}

examples/windows-recipe-writefile.rs (line 210)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (session, _profile) = common::create_vmi_session()?;

    let explorer_pid = {
        // This block is used to drop the pause guard after the PID is found.
        // If the `session.handle()` would be called with the VM paused, no
        // events would be triggered.
        let _pause_guard = session.pause_guard()?;

        let registers = session.registers(VcpuId(0))?;
        let vmi = session.with_registers(&registers);

        let explorer = match common::find_process(&vmi, "explorer.exe")? {
            Some(explorer) => explorer,
            None => {
                tracing::error!("explorer.exe not found");
                return Ok(());
            }
        };

        tracing::info!(
            pid = %explorer.id()?,
            object = %explorer.object()?,
            "found explorer.exe"
        );

        explorer.id()?
    };

    session.handle(|session| {
        UserInjectorHandler::new(
            session,
            recipe_factory(GuestFile::new(
                "C:\\Users\\John\\Desktop\\test.txt",
                "Hello, World!".as_bytes(),
            )),
        )?
        .with_pid(explorer_pid)
    })?;

    Ok(())
}

examples/windows-recipe-writefile-advanced.rs (line 308)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (session, _profile) = common::create_vmi_session()?;

    let explorer_pid = {
        // This block is used to drop the pause guard after the PID is found.
        // If the `session.handle()` would be called with the VM paused, no
        // events would be triggered.
        let _pause_guard = session.pause_guard()?;

        let registers = session.registers(VcpuId(0))?;
        let vmi = session.with_registers(&registers);

        let explorer = match common::find_process(&vmi, "explorer.exe")? {
            Some(explorer) => explorer,
            None => {
                tracing::error!("explorer.exe not found");
                return Ok(());
            }
        };

        tracing::info!(
            pid = %explorer.id()?,
            object = %explorer.object()?,
            "found explorer.exe"
        );

        explorer.id()?
    };

    let mut content = Vec::new();
    for c in 'A'..='Z' {
        content.extend((0..2049).map(|_| c as u8).collect::<Vec<_>>());
    }

    session.handle(|session| {
        UserInjectorHandler::new(
            session,
            recipe_factory(GuestFile::new(
                "C:\\Users\\John\\Desktop\\test.txt",
                content,
            )),
        )?
        .with_pid(explorer_pid)
    })?;

    Ok(())
}

examples/common/mod.rs (line 41)

pub fn create_vmi_session() -> Result<Session, Box<dyn std::error::Error>> {
    tracing_subscriber::fmt()
        .with_max_level(tracing::Level::DEBUG)
        .with_target(false)
        .init();

    let domain_id = 'x: {
        for name in &["win7", "win10", "win11", "ubuntu22"] {
            if let Some(domain_id) = XenStore::new()?.domain_id_from_name(name)? {
                break 'x domain_id;
            }
        }

        panic!("Domain not found");
    };

    tracing::debug!(?domain_id);

    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::new(domain_id)?;
    let core = VmiCore::new(driver)?;

    // Try to find the kernel information.
    // This is necessary in order to load the profile.
    let kernel_info = {
        // Pause the vCPU to get consistent state.
        let _pause_guard = core.pause_guard()?;

        // Get the register state for the first vCPU.
        let registers = core.registers(VcpuId(0))?;

        // On AMD64 architecture, the kernel is usually found using the
        // `MSR_LSTAR` register, which contains the address of the system call
        // handler. This register is set by the operating system during boot
        // and is left unchanged (unless some rootkits are involved).
        //
        // Therefore, we can take an arbitrary registers at any point in time
        // (as long as the OS has booted and the page tables are set up) and
        // use them to find the kernel.
        WindowsOs::find_kernel(&core, &registers)?.expect("kernel information")
    };

    // Load the profile.
    // The profile contains offsets to kernel functions and data structures.
    let isr = IsrCache::new("cache")?;
    let entry = isr.entry_from_codeview(kernel_info.codeview)?;
    let entry = Box::leak(Box::new(entry));
    let profile = entry.profile()?;

    // Create the VMI session.
    tracing::info!("Creating VMI session");
    let os = WindowsOs::<VmiXenDriver<Amd64>>::new(&profile)?;

    // Please don't do this in production code.
    // This is only done for the sake of the example.
    let core = Box::leak(Box::new(core));
    let os = Box::leak(Box::new(os));

    Ok((VmiSession::new(core, os), profile))
}

examples/basic-process-list.rs (line 32)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let domain_id = 'x: {
        for name in &["win7", "win10", "win11", "ubuntu22"] {
            if let Some(domain_id) = XenStore::new()?.domain_id_from_name(name)? {
                break 'x domain_id;
            }
        }

        panic!("Domain not found");
    };

    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::new(domain_id)?;
    let core = VmiCore::new(driver)?;

    // Try to find the kernel information.
    // This is necessary in order to load the profile.
    let kernel_info = {
        // Pause the VM to get consistent state.
        let _pause_guard = core.pause_guard()?;

        // Get the register state for the first vCPU.
        let registers = core.registers(VcpuId(0))?;

        // On AMD64 architecture, the kernel is usually found using the
        // `MSR_LSTAR` register, which contains the address of the system call
        // handler. This register is set by the operating system during boot
        // and is left unchanged (unless some rootkits are involved).
        //
        // Therefore, we can take an arbitrary registers at any point in time
        // (as long as the OS has booted and the page tables are set up) and
        // use them to find the kernel.
        WindowsOs::find_kernel(&core, &registers)?.expect("kernel information")
    };

    // Load the profile.
    // The profile contains offsets to kernel functions and data structures.
    let isr = IsrCache::new("cache")?;
    let entry = isr.entry_from_codeview(kernel_info.codeview)?;
    let profile = entry.profile()?;

    // Create the VMI session.
    tracing::info!("Creating VMI session");
    let os = WindowsOs::<VmiXenDriver<Amd64>>::new(&profile)?;
    let session = VmiSession::new(&core, &os);

    // Pause the VM again to get consistent state.
    let _pause_guard = session.pause_guard()?;

    // Create a new `VmiState` with the current register.
    let registers = session.registers(VcpuId(0))?;
    let vmi = session.with_registers(&registers);

    // Get the list of processes and print them.
    for process in vmi.os().processes()? {
        let process = process?;

        println!(
            "{} [{}] {} (root @ {})",
            process.object()?,
            process.id()?,
            process.name()?,
            process.translation_root()?
        );
    }

    Ok(())
}

Additional examples can be found in:

• examples/windows-breakpoint-manager.rs

pub fn allocate_gfn(&self) -> Result<Gfn, VmiError>

Available on crate features utils and injector only.

Allocates a guest frame number (GFN).

This method allocates a new GFN, with the driver responsible for choosing the specific frame to allocate. It’s useful when you need to allocate new memory pages for the VM without caring about the specific location.

pub fn allocate_gfn_at(&self, gfn: Gfn) -> Result<(), VmiError>

Available on crate features utils and injector only.

Allocates a guest frame number (GFN) at a specific location.

This method allows you to allocate a particular GFN. It’s useful when you need to allocate a specific memory page for the VM.

pub fn free_gfn(&self, gfn: Gfn) -> Result<(), VmiError>

Available on crate features utils and injector only.

Frees a previously allocated guest frame number (GFN).

This method deallocates a GFN that was previously allocated. It’s important to free GFNs when they’re no longer needed to prevent memory leaks in the VM.

pub fn inject_interrupt( &self, vcpu: VcpuId, interrupt: <<Driver as VmiDriver>::Architecture as Architecture>::Interrupt, ) -> Result<(), VmiError>

Available on crate features utils and injector only.

Injects an interrupt into a specific virtual CPU.

This method allows for the injection of architecture-specific interrupts into a given vCPU. It can be used to simulate hardware events or to manipulate the guest’s execution flow for analysis purposes.

The type of interrupt and its parameters are defined by the architecture-specific Architecture::Interrupt type.

Examples found in repository

examples/windows-breakpoint-manager.rs (line 498)

    fn dispatch(
        &mut self,
        vmi: &VmiContext<WindowsOs<Driver>>,
    ) -> Result<VmiEventResponse<Amd64>, VmiError> {
        let event = vmi.event();
        let result = match event.reason() {
            EventReason::MemoryAccess(_) => self.memory_access(vmi),
            EventReason::Interrupt(_) => self.interrupt(vmi),
            EventReason::Singlestep(_) => self.singlestep(vmi),
            _ => panic!("Unhandled event: {:?}", event.reason()),
        };

        // If VMI tries to read from a page that is not present, it will return
        // a page fault error. In this case, we inject a page fault interrupt
        // to the guest.
        //
        // Once the guest handles the page fault, it will retry to execute the
        // instruction that caused the page fault.
        if let Err(VmiError::Translation(pfs)) = result {
            tracing::warn!(?pfs, "Page fault, injecting");
            vmi.inject_interrupt(event.vcpu_id(), Interrupt::page_fault(pfs[0].va, 0))?;
            return Ok(VmiEventResponse::default());
        }

        result
    }

pub fn reset_state(&self) -> Result<(), VmiError>

Available on crate features utils and injector only.

Resets the state of the VMI system.

This method clears all event monitors, caches, and any other stateful data maintained by the VMI system. It’s useful for bringing the VMI system back to a known clean state, which can be necessary when switching between different analysis tasks or recovering from error conditions.