Struct VmiState 

pub struct VmiState<'a, Os>
where
    Os: VmiOs,
{ /* private fields */ }

A VMI state.

The state combines access to a VmiSession with Architecture::Registers to provide unified access to VMI operations in the context of a specific virtual machine state.

Implementations

impl<'a, Os> VmiState<'a, Os>

where Os: VmiOs,

pub fn new( session: &'a VmiSession<'a, Os>, registers: &'a <<Os as VmiOs>::Architecture as Architecture>::Registers, ) -> VmiState<'a, Os>

Available on crate features injector and utils only.

Creates a new VMI state.

pub fn with_registers( &'a self, registers: &'a <<Os as VmiOs>::Architecture as Architecture>::Registers, ) -> VmiState<'a, Os>

Available on crate features injector and utils only.

Creates a new VMI state with the specified registers.

pub fn without_os(&self) -> VmiState<'a, NoOS<<Os as VmiOs>::Driver>>

Available on crate features injector and utils only.

Creates a new VMI state without an OS-specific implementation.

pub fn session(&self) -> &VmiSession<'a, Os>

Available on crate features injector and utils only.

Returns the VMI session.

pub fn registers( &self, ) -> &'a <<Os as VmiOs>::Architecture as Architecture>::Registers

Available on crate features injector and utils only.

Returns the CPU registers associated with the current event.

pub fn os(&self) -> VmiOsState<'a, Os>

Available on crate features injector and utils only.

Returns a wrapper providing access to OS-specific operations.

Examples found in repository

examples/windows-dump.rs (line 103)

fn enumerate_kernel_modules(vmi: &VmiState<WindowsOs<Driver>>) -> Result<(), VmiError> {
    for module in vmi.os().modules()? {
        let module = module?;

        let module_va = module.va();
        let base_address = module.base_address()?; // `KLDR_DATA_TABLE_ENTRY.DllBase`
        let size = module.size()?; // `KLDR_DATA_TABLE_ENTRY.SizeOfImage`
        let name = module.name()?; // `KLDR_DATA_TABLE_ENTRY.BaseDllName`
        let full_name = match module.full_name() {
            // `KLDR_DATA_TABLE_ENTRY.FullDllName`
            Ok(full_name) => full_name,
            Err(err) => handle_error(err)?,
        };

        println!("Module @ {module_va}");
        println!("    Base Address: {base_address}");
        println!("    Size: {size}");
        println!("    Name: {name}");
        println!("    Full Name: {full_name}");
    }

    Ok(())
}

// Enumerate entries in a `_OBJECT_DIRECTORY`.
fn enumerate_directory_object(
    directory_object: &WindowsDirectoryObject<Driver>,
    level: usize,
) -> Result<(), VmiError> {
    for object in directory_object.iter()? {
        // Print the indentation.
        for _ in 0..level {
            print!("    ");
        }

        // Retrieve the `_OBJECT_DIRECTORY_ENTRY.Object`.
        let object = match object {
            Ok(object) => object,
            Err(err) => {
                println!("{}", handle_error(err)?);
                continue;
            }
        };

        let object_va = object.va();

        // Determine the object type.
        let type_kind = match object.type_kind() {
            Ok(Some(typ)) => format!("{typ:?}"),
            Ok(None) => String::from("<unknown>"),
            Err(err) => handle_error(err)?,
        };

        print!("{type_kind}: ");

        // Retrieve the full name of the object.
        let name = match object.full_path() {
            Ok(Some(name)) => name,
            Ok(None) => String::from("<unnamed>"),
            Err(err) => handle_error(err)?,
        };

        println!("{name} (Object: {object_va})");

        // If the entry is a directory, recursively enumerate it.
        if let Ok(Some(next)) = object.as_directory() {
            enumerate_directory_object(&next, level + 1)?;
        }
    }

    Ok(())
}

// Enumerate entries in a `_HANDLE_TABLE`.
fn enumerate_handle_table(process: &WindowsProcess<Driver>) -> Result<(), VmiError> {
    const OBJ_PROTECT_CLOSE: u32 = 0x00000001;
    const OBJ_INHERIT: u32 = 0x00000002;
    const OBJ_AUDIT_OBJECT_CLOSE: u32 = 0x00000004;

    static LABEL_PROTECTED: [&str; 2] = ["", " (Protected)"];
    static LABEL_INHERIT: [&str; 2] = ["", " (Inherit)"];
    static LABEL_AUDIT: [&str; 2] = ["", " (Audit)"];

    // Get the handle table from `_EPROCESS.ObjectTable`.
    let handle_table = match process.handle_table() {
        Ok(Some(handle_table)) => handle_table,
        Ok(None) => {
            println!("        (No handle table)");
            return Ok(());
        }
        Err(err) => {
            tracing::error!(%err, "Failed to get handle table");
            return Ok(());
        }
    };

    // Iterate over `_HANDLE_TABLE_ENTRY` items.
    for handle_entry in handle_table.iter()? {
        let (handle, entry) = match handle_entry {
            Ok(entry) => entry,
            Err(err) => {
                println!("Failed to get handle entry: {}", handle_error(err)?);
                continue;
            }
        };

        let attributes = match entry.attributes() {
            Ok(attributes) => attributes,
            Err(err) => {
                println!("Failed to get attributes: {}", handle_error(err)?);
                continue;
            }
        };

        let granted_access = match entry.granted_access() {
            Ok(granted_access) => granted_access,
            Err(err) => {
                println!("Failed to get granted access: {}", handle_error(err)?);
                continue;
            }
        };

        let object = match entry.object() {
            Ok(Some(object)) => object,
            Ok(None) => {
                // [`WindowsHandleTable::iter`] should only return entries with
                // valid objects, so this should not happen.
                println!("<NULL>");
                continue;
            }
            Err(err) => {
                println!("Failed to get object: {}", handle_error(err)?);
                continue;
            }
        };

        let type_name = match object.type_name() {
            Ok(type_name) => type_name,
            Err(err) => handle_error(err)?,
        };

        let full_path = match object.full_path() {
            Ok(Some(path)) => path,
            Ok(None) => String::from("<no-path>"),
            Err(err) => handle_error(err)?,
        };

        println!(
            "        {:04x}: Object: {:x} GrantedAccess: {:08x}{}{}{} Entry: {}",
            handle,
            object.va().0,
            granted_access,
            LABEL_PROTECTED[((attributes & OBJ_PROTECT_CLOSE) != 0) as usize],
            LABEL_INHERIT[((attributes & OBJ_INHERIT) != 0) as usize],
            LABEL_AUDIT[((attributes & OBJ_AUDIT_OBJECT_CLOSE) != 0) as usize],
            entry.va(),
        );

        println!("            Type: {type_name}, Path: {full_path}");
    }

    Ok(())
}

// Enumerate VADs in a process.
fn enumerate_regions(process: &WindowsProcess<Driver>) -> Result<(), VmiError> {
    for region in process.regions()? {
        let region = region?;

        let region_va = region.va();
        let start = region.start()?;
        let end = region.end()?;
        let protection = region.protection()?;
        let kind = region.kind()?;

        print!("        Region @ {region_va}: {start}-{end} {protection:?}");

        match &kind {
            VmiOsRegionKind::Private => println!(" Private"),
            VmiOsRegionKind::MappedImage(mapped) => {
                let path = match mapped.path() {
                    Ok(Some(path)) => path,
                    Ok(None) => String::from("<Pagefile>"),
                    Err(err) => handle_error(err)?,
                };

                println!(" Mapped (Exe): {path}");
            }
            VmiOsRegionKind::MappedData(mapped) => {
                let path = match mapped.path() {
                    Ok(Some(path)) => path,
                    Ok(None) => String::from("<Pagefile>"),
                    Err(err) => handle_error(err)?,
                };

                println!(" Mapped: {path}");
            }
        }
    }

    Ok(())
}

// Enumerate threads in a process.
fn enumerate_threads(process: &WindowsProcess<Driver>) -> Result<(), VmiError> {
    for thread in process.threads()? {
        let thread = thread?;

        let tid = thread.id()?;
        let object = thread.object()?;

        println!("        Thread @ {object}, TID: {tid}");
    }

    Ok(())
}

// Print process information in a `_PEB.ProcessParameters`.
fn print_process_parameters(process: &WindowsProcess<Driver>) -> Result<(), VmiError> {
    let peb = match process.peb() {
        Ok(Some(peb)) => peb,
        Ok(None) => {
            println!("        (No PEB)");
            return Ok(());
        }
        Err(err) => {
            println!("Failed to get PEB: {}", handle_error(err)?);
            return Ok(());
        }
    };

    let current_directory = match peb.current_directory() {
        Ok(current_directory) => current_directory,
        Err(err) => handle_error(err)?,
    };

    let dll_path = match peb.dll_path() {
        Ok(dll_path) => dll_path,
        Err(err) => handle_error(err)?,
    };

    let image_path_name = match peb.image_path_name() {
        Ok(image_path_name) => image_path_name,
        Err(err) => handle_error(err)?,
    };

    let command_line = match peb.command_line() {
        Ok(command_line) => command_line,
        Err(err) => handle_error(err)?,
    };

    println!("        Current Directory:    {current_directory}");
    println!("        DLL Path:             {dll_path}");
    println!("        Image Path Name:      {image_path_name}");
    println!("        Command Line:         {command_line}");

    Ok(())
}

// Enumerate processes in the system.
fn enumerate_processes(vmi: &VmiState<WindowsOs<Driver>>) -> Result<(), VmiError> {
    for process in vmi.os().processes()? {
        let process = process?;

        let pid = process.id()?; // `_EPROCESS.UniqueProcessId`
        let object = process.object()?; // `_EPROCESS` pointer
        let name = process.name()?; // `_EPROCESS.ImageFileName`
        let session = process.session()?; // `_EPROCESS.Session`

        println!("Process @ {object}, PID: {pid}");
        println!("    Name: {name}");
        if let Some(session) = session {
            println!("    Session: {}", session.id()?); // `_MM_SESSION_SPACE.SessionId`
        }

        println!("    Threads:");
        enumerate_threads(&process)?;

        println!("    Regions:");
        enumerate_regions(&process)?;

        println!("    PEB:");
        print_process_parameters(&process)?;

        println!("    Handles:");
        enumerate_handle_table(&process)?;
    }

    Ok(())
}

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/windows-recipe-messagebox.rs (line 76)

fn main() -> Result<(), Error> {
    let session = 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 paused = session.pause_guard()?;

        let vmi = paused.state();

        let explorer = match vmi.os().find_process("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 216)

fn main() -> Result<(), Error> {
    let session = 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 paused = session.pause_guard()?;

        let vmi = paused.state();

        let explorer = match vmi.os().find_process("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 314)

fn main() -> Result<(), Error> {
    let session = 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 paused = session.pause_guard()?;

        let vmi = paused.state();

        let explorer = match vmi.os().find_process("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/basic-process-list.rs (line 57)

fn main() -> Result<(), Error> {
    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::try_from_env()?
        .context("invalid VMI_XEN_DOMAIN environment variable")?;
    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 paused = session.pause_guard()?;

    // Create a new `VmiState` with the boot CPU registers.
    let vmi = paused.state();

    // 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(())
}

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

    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 access_context(&self, address: Va) -> AccessContext

Available on crate features injector and utils only.

Creates an address context for a given virtual address.

pub fn address_context(&self, address: Va) -> AddressContext

Available on crate features injector and utils only.

Creates an address context for a given virtual address.

pub fn translation_root(&self, va: Va) -> Pa

Available on crate features injector and utils only.

Returns the physical address of the root of the current page table hierarchy for a given virtual address.

impl<'a, Os> VmiState<'a, Os>

where Os: VmiOs, <Os as VmiOs>::Driver: VmiRead,

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

Available on crate features injector and utils only.

Returns the return address from the current stack frame.

pub fn return_from_function( &self, value: u64, ) -> Result<<<<Os as VmiOs>::Architecture as Architecture>::Registers as Registers>::GpRegisters, VmiError>

Available on crate features injector and utils only.

Builds the general-purpose registers that make the current function return value to its caller without executing its body.

Examples found in repository

examples/windows-reactor/netio.rs (line 553)

pub fn KfdIsLayerEmpty<Driver>(
    vmi: &VmiContext<WindowsOs<Driver>>,
) -> Result<Action<<WindowsOs<Driver> as VmiOs>::Architecture>, VmiError>
where
    Driver: VmiRead,
    Driver::Architecture: ArchAdapter<Driver>,
{
    //
    // BOOLEAN
    // NTAPI
    // KfdIsLayerEmpty (
    //     _In_ UINT16 layerId
    //     );
    //

    let layerId = FwpsLayer(vmi.os().function_argument(0)? as u16);

    if !matches!(
        layerId,
        FwpsLayer::ALE_AUTH_CONNECT_V4
            | FwpsLayer::ALE_AUTH_CONNECT_V6
            | FwpsLayer::ALE_FLOW_ESTABLISHED_V4
            | FwpsLayer::ALE_FLOW_ESTABLISHED_V6
    ) {
        tracing::trace!(?layerId, "passing through");
        return Ok(Action::default());
    }

    tracing::trace!(?layerId, "overriding");

    let registers = vmi.return_from_function(0)?; // Return FALSE

    Ok(Action::Response(
        VmiEventResponse::default().with_registers(registers),
    ))
}

pub fn translate_address(&self, va: Va) -> Result<Pa, VmiError>

Available on crate features injector and utils only.

Translates a virtual address to a physical address.

pub fn read(&self, address: Va, buffer: &mut [u8]) -> Result<(), VmiError>

Available on crate features injector and utils only.

Reads memory from the virtual machine.

Examples found in repository

examples/windows-reactor/ncrypt.rs (line 94)

pub fn SslGenerateSessionKeys<Driver>(
    vmi: &VmiContext<WindowsOs<Driver>>,
) -> Result<Action<<WindowsOs<Driver> as VmiOs>::Architecture>, VmiError>
where
    Driver: VmiRead,
    Driver::Architecture: ArchAdapter<Driver>,
{
    //
    // SECURITY_STATUS
    // WINAPI
    // SslGenerateSessionKeys(
    //     _In_ NCRYPT_PROV_HANDLE hSslProvider,
    //     _In_ NCRYPT_KEY_HANDLE hMasterKey,
    //     _Out_ NCRYPT_KEY_HANDLE *phReadKey,
    //     _Out_ NCRYPT_KEY_HANDLE *phWriteKey,
    //     _In_ PNCryptBufferDesc pParameterList,
    //     _In_ DWORD dwFlags
    //     );
    //

    let hMasterKey = vmi.os().function_argument(1)?;
    let pParameterList = vmi.os().function_argument(4)?;

    let mut client_random = vec![0u8; 32];

    let parameter_list = vmi.read_struct::<NCryptBufferDesc>(Va(pParameterList))?;
    for i in 0..parameter_list.cBuffers {
        let offset = (i as u64) * size_of::<NCryptBuffer>() as u64;
        let buffer = vmi.read_struct::<NCryptBuffer>(Va(parameter_list.pBuffers + offset))?;

        if buffer.BufferType == NCRYPTBUFFER_SSL_CLIENT_RANDOM {
            vmi.read(Va(buffer.pvBuffer), &mut client_random)?;
            break;
        }
    }

    let master_key = vmi.read_struct::<NCRYPT_SSL_KEY>(Va(hMasterKey))?;
    let subkey = vmi.read_struct::<SSL_MASTER_KEY>(Va(master_key.hSubKey))?;

    tracing::info!(
        client_random = hex::encode(client_random),
        secret = hex::encode(subkey.rgbMasterKey),
    );

    Ok(Action::default())
}

pub fn read_u8(&self, address: Va) -> Result<u8, VmiError>

Available on crate features injector and utils only.

Reads a single byte from the virtual machine.

pub fn read_u16(&self, address: Va) -> Result<u16, VmiError>

Available on crate features injector and utils only.

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

pub fn read_u32(&self, address: Va) -> Result<u32, VmiError>

Available on crate features injector and utils only.

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

Examples found in repository

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

fn recipe_factory<Driver>(data: GuestFile) -> Recipe<WindowsOs<Driver>, GuestFile>
where
    Driver: VmiFullDriver<Architecture = Amd64>,
{
    recipe![
        Recipe::<WindowsOs<Driver>>::new(data),
        //
        // Step 1:
        // - Create a file
        //
        {
            tracing::info!(
                target_path = data![target_path],
                "step 1: kernel32!CreateFileA()"
            );

            const GENERIC_WRITE: u64 = 0x40000000;
            const CREATE_ALWAYS: u64 = 2;
            const FILE_ATTRIBUTE_NORMAL: u64 = 0x80;

            inject! {
                kernel32!CreateFileA(
                    &data![target_path],        // lpFileName
                    GENERIC_WRITE,              // dwDesiredAccess
                    0,                          // dwShareMode
                    0,                          // lpSecurityAttributes
                    CREATE_ALWAYS,              // dwCreationDisposition
                    FILE_ATTRIBUTE_NORMAL,      // dwFlagsAndAttributes
                    0                           // hTemplateFile
                )
            }
        },
        //
        // Step 2:
        // - Verify the file handle
        // - Write the content to the file
        //
        {
            let return_value = registers!().rax;

            const INVALID_HANDLE_VALUE: u64 = 0xffff_ffff_ffff_ffff;

            if return_value == INVALID_HANDLE_VALUE {
                tracing::error!(
                    return_value = %Hex(return_value),
                    "step 2: kernel32!CreateFileA() failed"
                );

                return Ok(RecipeControlFlow::Break);
            }

            tracing::info!(
                handle = %Hex(data![handle]),
                "step 2: kernel32!WriteFile()"
            );

            // Save the handle.
            data![handle] = return_value;

            // Allocate a value on the stack to store the output parameter.
            data![bytes_written_ptr] = copy_to_stack!(0u64)?;

            inject! {
                kernel32!WriteFile(
                    data![handle],              // hFile
                    data![content],             // lpBuffer
                    data![content].len(),       // nNumberOfBytesToWrite
                    data![bytes_written_ptr],   // lpNumberOfBytesWritten
                    0                           // lpOverlapped
                )
            }
        },
        //
        // Step 3:
        // - Verify that the `WriteFile()` call succeeded
        // - Close the file handle
        //
        {
            let return_value = registers!().rax;

            // Check if the `WriteFile()` call failed.
            if return_value == 0 {
                tracing::error!(
                    return_value = %Hex(return_value),
                    "step 3: kernel32!WriteFile() failed"
                );

                // Don't exit, we want to close the handle.
                // return Ok(RecipeControlFlow::Break);
            }

            // Read the number of bytes written.
            let number_of_bytes_written = vmi!().read_u32(data![bytes_written_ptr])?;
            tracing::info!(number_of_bytes_written, "step 3: kernel32!WriteFile()");

            tracing::info!(
                handle = %Hex(data![handle]),
                "step 3: kernel32!CloseHandle()"
            );

            inject! {
                kernel32!CloseHandle(
                    data![handle]               // hObject
                )
            }
        },
    ]
}

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

pub fn recipe_factory<Driver>(data: GuestFile) -> Recipe<WindowsOs<Driver>, GuestFile>
where
    Driver: VmiFullDriver<Architecture = Amd64>,
{
    recipe![
        Recipe::<WindowsOs<Driver>>::new(data),
        //
        // Step 1:
        // - Create a file.
        //
        {
            tracing::info!(
                target_path = data![target_path],
                "step 1: kernel32!CreateFileA()"
            );

            const GENERIC_WRITE: u64 = 0x40000000;
            const CREATE_ALWAYS: u64 = 2;
            const FILE_ATTRIBUTE_NORMAL: u64 = 0x80;

            inject! {
                kernel32!CreateFileA(
                    &data![target_path],        // lpFileName
                    GENERIC_WRITE,              // dwDesiredAccess
                    0,                          // dwShareMode
                    0,                          // lpSecurityAttributes
                    CREATE_ALWAYS,              // dwCreationDisposition
                    FILE_ATTRIBUTE_NORMAL,      // dwFlagsAndAttributes
                    0                           // hTemplateFile
                )
            }
        },
        //
        // Step 2:
        // - Verify the file handle
        // - Write the first chunk to the file
        //
        {
            let return_value = registers!().rax;

            const INVALID_HANDLE_VALUE: u64 = 0xffff_ffff_ffff_ffff;

            if return_value == INVALID_HANDLE_VALUE {
                tracing::error!(
                    return_value = %Hex(return_value),
                    "step 2: kernel32!CreateFileA() failed"
                );

                return Ok(RecipeControlFlow::Break);
            }

            tracing::info!(
                handle = %Hex(data![handle]),
                "step 2: kernel32!WriteFile()"
            );

            // Save the handle.
            data![handle] = return_value;

            // Allocate a value on the stack to store the output parameter.
            data![bytes_written_ptr] = copy_to_stack!(0u64)?;

            // Get the first chunk of content.
            let content = &data![content];
            let chunk_size = usize::min(content.len(), data![chunk_size]);
            let chunk = content[..chunk_size].to_vec();

            inject! {
                kernel32!WriteFile(
                    data![handle],              // hFile
                    chunk,                      // lpBuffer
                    chunk.len() as u64,         // nNumberOfBytesToWrite
                    data![bytes_written_ptr],   // lpNumberOfBytesWritten
                    0                           // lpOverlapped
                )
            }
        },
        //
        // Step 3:
        // - Verify that the `WriteFile()` call succeeded
        // - Write the next chunk to the file
        // - Repeat this step until all content is written
        //
        {
            let return_value = registers!().rax;

            if return_value == 0 {
                tracing::error!(
                    return_value = %Hex(return_value),
                    "step 3: kernel32!WriteFile() failed"
                );

                return Ok(RecipeControlFlow::Break);
            }

            // Read the number of bytes written and update the total.
            let number_of_bytes_written = vmi!().read_u32(data![bytes_written_ptr])?;
            data![bytes_written_total] += number_of_bytes_written;

            let bytes_written_total = data![bytes_written_total];
            let content = &data![content];

            // If all content is written, move to the next step.
            if bytes_written_total >= content.len() as u32 {
                return Ok(RecipeControlFlow::Continue);
            }

            // Get the next chunk of content.
            let remaining = content.len() - bytes_written_total as usize;
            let chunk_size = usize::min(remaining, data![chunk_size]);
            let chunk = &content[bytes_written_total as usize..];
            let chunk = chunk[..chunk_size].to_vec();

            // Allocate a value on the stack to store the output parameter.
            data![bytes_written_ptr] = copy_to_stack!(0u64)?;

            inject! {
                kernel32!WriteFile(
                    data![handle],              // hFile
                    chunk,                      // lpBuffer
                    chunk.len() as u64,         // nNumberOfBytesToWrite
                    data![bytes_written_ptr],   // lpNumberOfBytesWritten
                    0                           // lpOverlapped
                )
            }?;

            Ok(RecipeControlFlow::Repeat)
        },
        //
        // Step 4:
        // - Verify that the last `WriteFile()` call succeeded
        // - Close the file handle
        //
        {
            let return_value = registers!().rax;

            if return_value == 0 {
                tracing::error!(
                    return_value = %Hex(return_value),
                    "step 4: kernel32!WriteFile() failed"
                );

                // Don't exit, we want to close the handle.
                // return Ok(RecipeControlFlow::Break);
            }

            // Read the number of bytes written.
            let number_of_bytes_written = vmi!().read_u32(data![bytes_written_ptr])?;
            tracing::info!(number_of_bytes_written, "step 4: kernel32!WriteFile()");

            tracing::info!(
                handle = %Hex(data![handle]),
                "step 4: kernel32!CloseHandle()"
            );

            inject! {
                kernel32!CloseHandle(
                    data![handle]               // hObject
                )
            }
        },
    ]
}

pub fn read_u64(&self, address: Va) -> Result<u64, VmiError>

Available on crate features injector and utils only.

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

pub fn read_uint(&self, address: Va, size: usize) -> Result<u64, VmiError>

Available on crate features injector and utils 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, base_address: Va, field: &Field, ) -> Result<u64, VmiError>

Available on crate features injector and utils 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, address: Va) -> Result<u64, VmiError>

Available on crate features injector and utils only.

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

pub fn read_address_native(&self, address: Va) -> Result<u64, VmiError>

Available on crate features injector and utils only.

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

pub fn read_address32(&self, address: Va) -> Result<u64, VmiError>

Available on crate features injector and utils only.

Reads a 32-bit address from the virtual machine.

pub fn read_address64(&self, address: Va) -> Result<u64, VmiError>

Available on crate features injector and utils only.

Reads a 64-bit address from the virtual machine.

pub fn read_va(&self, address: Va) -> Result<Va, VmiError>

Available on crate features injector and utils only.

Reads a virtual address from the virtual machine.

pub fn read_va_native(&self, address: Va) -> Result<Va, VmiError>

Available on crate features injector and utils only.

Reads a virtual address from the virtual machine.

pub fn read_va32(&self, address: Va) -> Result<Va, VmiError>

Available on crate features injector and utils only.

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

pub fn read_va64(&self, address: Va) -> Result<Va, VmiError>

Available on crate features injector and utils only.

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

pub fn read_string_bytes_limited( &self, address: Va, limit: usize, ) -> Result<Vec<u8>, VmiError>

Available on crate features injector and utils only.

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

pub fn read_string_bytes(&self, address: Va) -> Result<Vec<u8>, VmiError>

Available on crate features injector and utils only.

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

pub fn read_string_utf16_bytes_limited( &self, address: Va, limit: usize, ) -> Result<Vec<u16>, VmiError>

Available on crate features injector and utils only.

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

pub fn read_string_utf16_bytes(&self, address: Va) -> Result<Vec<u16>, VmiError>

Available on crate features injector and utils only.

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

pub fn read_string_limited( &self, address: Va, limit: usize, ) -> Result<String, VmiError>

Available on crate features injector and utils only.

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

pub fn read_string(&self, address: Va) -> Result<String, VmiError>

Available on crate features injector and utils only.

Reads a null-terminated string from the virtual machine.

pub fn read_string_utf16_limited( &self, address: Va, limit: usize, ) -> Result<String, VmiError>

Available on crate features injector and utils only.

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

pub fn read_string_utf16(&self, address: Va) -> Result<String, VmiError>

Available on crate features injector and utils only.

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

pub fn read_struct<T>(&self, address: Va) -> Result<T, VmiError>

where T: IntoBytes + FromBytes,

Available on crate features injector and utils only.

Reads a struct from the virtual machine.

Examples found in repository

examples/windows-reactor/ncrypt.rs (line 88)

pub fn SslGenerateSessionKeys<Driver>(
    vmi: &VmiContext<WindowsOs<Driver>>,
) -> Result<Action<<WindowsOs<Driver> as VmiOs>::Architecture>, VmiError>
where
    Driver: VmiRead,
    Driver::Architecture: ArchAdapter<Driver>,
{
    //
    // SECURITY_STATUS
    // WINAPI
    // SslGenerateSessionKeys(
    //     _In_ NCRYPT_PROV_HANDLE hSslProvider,
    //     _In_ NCRYPT_KEY_HANDLE hMasterKey,
    //     _Out_ NCRYPT_KEY_HANDLE *phReadKey,
    //     _Out_ NCRYPT_KEY_HANDLE *phWriteKey,
    //     _In_ PNCryptBufferDesc pParameterList,
    //     _In_ DWORD dwFlags
    //     );
    //

    let hMasterKey = vmi.os().function_argument(1)?;
    let pParameterList = vmi.os().function_argument(4)?;

    let mut client_random = vec![0u8; 32];

    let parameter_list = vmi.read_struct::<NCryptBufferDesc>(Va(pParameterList))?;
    for i in 0..parameter_list.cBuffers {
        let offset = (i as u64) * size_of::<NCryptBuffer>() as u64;
        let buffer = vmi.read_struct::<NCryptBuffer>(Va(parameter_list.pBuffers + offset))?;

        if buffer.BufferType == NCRYPTBUFFER_SSL_CLIENT_RANDOM {
            vmi.read(Va(buffer.pvBuffer), &mut client_random)?;
            break;
        }
    }

    let master_key = vmi.read_struct::<NCRYPT_SSL_KEY>(Va(hMasterKey))?;
    let subkey = vmi.read_struct::<SSL_MASTER_KEY>(Va(master_key.hSubKey))?;

    tracing::info!(
        client_random = hex::encode(client_random),
        secret = hex::encode(subkey.rgbMasterKey),
    );

    Ok(Action::default())
}

examples/windows-reactor/netio.rs (line 383)

pub fn KfdClassify<Driver>(
    vmi: &VmiContext<WindowsOs<Driver>>,
) -> Result<Action<<WindowsOs<Driver> as VmiOs>::Architecture>, VmiError>
where
    Driver: VmiRead,
    Driver::Architecture: ArchAdapter<Driver>,
{
    //
    // PVOID
    // NTAPI
    // KfdClassify (
    //     _In_ UINT16 layerId,
    //     _In_ const FWPS_INCOMING_VALUES* inFixedValues,
    //     _In_ const FWPS_INCOMING_METADATA_VALUES* inContext,
    //     _In_ PVOID packet,
    //     _In_ const FWPP_SHIM_PROVIDER_CONTEXT* shimProvContext,
    //     _Inout_ FWPS_CLASSIFY_OUT* classifyOut
    //     );
    //

    let layerId = FwpsLayer(vmi.os().function_argument(0)? as u16);
    let inFixedValues = Va(vmi.os().function_argument(1)?);
    let inContext = Va(vmi.os().function_argument(2)?);

    let (
        protocol_index,
        local_address_index,
        local_port_index,
        remote_address_index,
        remote_port_index,
    ) = match layerId.network_5tuple_indexes() {
        Some(indexes) => indexes,
        None => return Ok(Action::default()),
    };

    let incoming_values = vmi.read_struct::<FWPS_INCOMING_VALUES0>(inFixedValues)?;
    let incoming = Va(incoming_values.incomingValue);

    const SIZEOF_VALUE: u64 = size_of::<FWPS_INCOMING_VALUE0>() as u64;

    //
    // Protocol.
    //

    let protocol =
        vmi.read_struct::<FWPS_INCOMING_VALUE0>(incoming + protocol_index * SIZEOF_VALUE)?;

    if protocol.value.ty != FwpDataType::UINT8 {
        tracing::debug!(
            protocol_type = ?protocol.value.ty,
            expected = ?FwpDataType::UINT8,
            "unexpected protocol type"
        );
        return Ok(Action::default());
    }

    //
    // Local Address.
    //

    let local_address =
        vmi.read_struct::<FWPS_INCOMING_VALUE0>(incoming + local_address_index * SIZEOF_VALUE)?;

    if local_address.value.ty != FwpDataType::UINT32 {
        tracing::debug!(
            local_address_type = ?local_address.value.ty,
            expected = ?FwpDataType::UINT32,
            "unexpected local address type"
        );
        return Ok(Action::default());
    }

    //
    // Local Port.
    //

    let local_port =
        vmi.read_struct::<FWPS_INCOMING_VALUE0>(incoming + local_port_index * SIZEOF_VALUE)?;

    if local_port.value.ty != FwpDataType::UINT16 {
        tracing::debug!(
            local_port_type = ?local_port.value.ty,
            expected = ?FwpDataType::UINT16,
            "unexpected local port type"
        );
        return Ok(Action::default());
    }

    //
    // Remote Address.
    //

    let remote_address =
        vmi.read_struct::<FWPS_INCOMING_VALUE0>(incoming + remote_address_index * SIZEOF_VALUE)?;

    if remote_address.value.ty != FwpDataType::UINT32 {
        tracing::debug!(
            remote_address_type = ?remote_address.value.ty,
            expected = ?FwpDataType::UINT32,
            "unexpected remote address type"
        );
        return Ok(Action::default());
    }

    //
    // Remote Port.
    //

    let remote_port =
        vmi.read_struct::<FWPS_INCOMING_VALUE0>(incoming + remote_port_index * SIZEOF_VALUE)?;

    if remote_port.value.ty != FwpDataType::UINT16 {
        tracing::debug!(
            remote_port_type = ?remote_port.value.ty,
            expected = ?FwpDataType::UINT16,
            "unexpected remote port type"
        );
        return Ok(Action::default());
    }

    let protocol = IpProtocol(protocol.value.data as u8);
    let local_address = local_address.value.data as u32;
    let local_port = local_port.value.data as u16;
    let remote_address = remote_address.value.data as u32;
    let remote_port = remote_port.value.data as u16;

    let local_ip = IpAddr::from(local_address.to_be_bytes());
    let remote_ip = IpAddr::from(remote_address.to_be_bytes());

    // Fetch the most valuable information that can't be obtained
    // from the pcap: the process ID that initiated the connection.
    let context = vmi.read_struct::<FWPS_INCOMING_METADATA_VALUES0>(inContext)?;
    let metadata_values = FwpsMetadataFields::from_bits_retain(context.currentMetadataValues);
    let pid = if metadata_values.contains(FwpsMetadataFields::PROCESS_ID) {
        Some(context.processId)
    }
    else {
        None
    };

    tracing::info!(
        ?protocol,
        %local_ip,
        local_port,
        %remote_ip,
        remote_port,
        pid,
    );

    Ok(Action::default())
}

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

Available on crate features injector and utils only.

Reads memory from the virtual machine.

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

Available on crate features injector and utils only.

Reads a single byte from the virtual machine.

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

Available on crate features injector and utils only.

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

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

Available on crate features injector and utils only.

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

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

Available on crate features injector and utils only.

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

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

Available on crate features injector and utils 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_in( &self, ctx: impl Into<AccessContext>, field: &Field, ) -> Result<u64, VmiError>

Available on crate features injector and utils 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_in( &self, ctx: impl Into<AccessContext>, ) -> Result<u64, VmiError>

Available on crate features injector and utils only.

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

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

Available on crate features injector and utils only.

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

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

Available on crate features injector and utils only.

Reads a 32-bit address from the virtual machine.

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

Available on crate features injector and utils only.

Reads a 64-bit address from the virtual machine.

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

Available on crate features injector and utils only.

Reads a virtual address from the virtual machine.

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

Available on crate features injector and utils only.

Reads a virtual address from the virtual machine.

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

Available on crate features injector and utils only.

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

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

Available on crate features injector and utils only.

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

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

Available on crate features injector and utils only.

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

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

Available on crate features injector and utils only.

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

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

Available on crate features injector and utils only.

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

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

Available on crate features injector and utils only.

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

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

Available on crate features injector and utils only.

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

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

Available on crate features injector and utils only.

Reads a null-terminated string from the virtual machine.

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

Available on crate features injector and utils only.

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

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

Available on crate features injector and utils only.

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

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

where T: IntoBytes + FromBytes,

Available on crate features injector and utils only.

Reads a struct from the virtual machine.

impl<'a, Os> VmiState<'a, Os>

where Os: VmiOs, <Os as VmiOs>::Driver: VmiRead + VmiWrite,

pub fn write(&self, address: Va, buffer: &[u8]) -> Result<(), VmiError>

Available on crate features injector and utils only.

Writes memory to the virtual machine.

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

Available on crate features injector and utils only.

Writes memory to the virtual machine.

pub fn write_u8(&self, address: Va, value: u8) -> Result<(), VmiError>

Available on crate features injector and utils only.

Writes a single byte to the virtual machine.

pub fn write_u16(&self, address: Va, value: u16) -> Result<(), VmiError>

Available on crate features injector and utils only.

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

pub fn write_u32(&self, address: Va, value: u32) -> Result<(), VmiError>

Available on crate features injector and utils only.

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

pub fn write_u64(&self, address: Va, value: u64) -> Result<(), VmiError>

Available on crate features injector and utils only.

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

pub fn write_struct<T>(&self, address: Va, value: T) -> Result<(), VmiError>

where T: FromBytes + IntoBytes + Immutable,

Available on crate features injector and utils only.

Writes a struct to the virtual machine.

impl<'a, Os> VmiState<'a, Os>

where Os: VmiOs, <Os as VmiOs>::Driver: VmiSetRegisters,

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

Available on crate features injector and utils only.

Sets the registers of a virtual CPU.

Methods from Deref<Target = VmiSession<'a, Os>>

pub fn with_registers( &'a self, registers: &'a <<Os as VmiOs>::Architecture as Architecture>::Registers, ) -> VmiState<'a, Os>

Available on crate features injector and utils only.

Creates a new VMI state with the specified registers.

Examples found in repository

examples/windows-dump.rs (line 430)

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/windows-breakpoint-manager.rs (line 89)

    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 without_os(&self) -> VmiSession<'a, NoOS<<Os as VmiOs>::Driver>>

Available on crate features injector and utils only.

Creates a new VMI session without an OS-specific implementation.

pub fn core(&self) -> &'a VmiCore<<Os as VmiOs>::Driver>

Available on crate features injector and utils only.

Returns the VMI core.

pub fn underlying_os(&self) -> &'a Os

Available on crate features injector and utils only.

Returns the underlying OS-specific implementation.

pub fn wait_for_event( &self, timeout: Duration, handler: &mut impl VmiHandler<Os>, ) -> Result<(), VmiError>

Available on crate features injector and utils 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.

pub fn handle<Handler>( &self, handler_factory: impl FnOnce(&VmiSession<'_, Os>) -> Result<Handler, VmiError>, ) -> Result<Option<<Handler as VmiHandler<Os>>::Output>, VmiError>

where Handler: VmiHandler<Os>,

Available on crate features injector and utils only.

Enters the main event handling loop that processes VMI events until finished.

Examples found in repository

examples/windows-recipe-messagebox.rs (lines 93-102)

fn main() -> Result<(), Error> {
    let session = 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 paused = session.pause_guard()?;

        let vmi = paused.state();

        let explorer = match vmi.os().find_process("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 (lines 233-242)

fn main() -> Result<(), Error> {
    let session = 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 paused = session.pause_guard()?;

        let vmi = paused.state();

        let explorer = match vmi.os().find_process("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 (lines 336-345)

fn main() -> Result<(), Error> {
    let session = 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 paused = session.pause_guard()?;

        let vmi = paused.state();

        let explorer = match vmi.os().find_process("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-breakpoint-manager.rs (line 556)

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

    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::try_from_env()?
        .context("invalid VMI_XEN_DOMAIN environment variable")?;
    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-reactor/main.rs (lines 353-355)

fn main() -> Result<(), Error> {
    let filter = EnvFilter::default()
        .add_directive(tracing::Level::DEBUG.into())
        .add_directive("reqwest=warn".parse()?)
        .add_directive("rustls=warn".parse()?);

    tracing_subscriber::fmt()
        .with_env_filter(filter)
        .with_target(false)
        .init();

    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::try_from_env()?
        .context("invalid VMI_XEN_DOMAIN environment variable")?;
    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 registers = core.registers(VcpuId(0))?;

        WindowsOs::find_kernel(&core, &registers)?.context("cannot find kernel information")?
    };

    // Load the kernel profile.
    // The profile contains offsets to kernel functions and data structures.
    tracing::info!(codeview = ?kernel_info.codeview, "loading kernel profile");
    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);

    let handler = NetIo::default();

    //
    // The following `let ncrypt_* = ...` lines demonstrate how to manually
    // resolve a module, load its profile (symbols) and add it to the resolver
    // via `with_module(_in_process)`.
    //
    // Note that this is not strictly necessary, as `ModuleResolver::resolve()`
    // will automatically resolve modules if they are not explicitly added.
    //
    // Manually resolving modules can be useful in cases where you want to deal
    // with the resolved information (base address, profile) in other places.
    //

    let ncrypt_resolved = {
        let paused = session.pause_guard()?;
        let vmi = paused.state();

        // Calling `resolve_user_module(&vmi, &isr, "ncrypt.dll", "lsass.exe")`
        // would also work, but this demonstrates how to use a custom predicate.
        //
        // Also, `match_lsass` is more strict, because it specifically looks
        // for "lsass.exe" in SessionId 0 (therefore, avoiding potential false
        // positives or potential malicious processes).
        vmi::utils::resolver::resolve_user_module(&vmi, &isr, "ncrypt.dll", match_lsass)?
            .context("ncrypt.dll not found in lsass.exe")?
    };

    let ncrypt_entry = isr
        .entry_from_codeview(ncrypt_resolved.debug_signature)
        .context("cannot find symbols for ncrypt.dll")?;

    let ncrypt_profile = ncrypt_entry
        .profile()
        .context("cannot load profile for ncrypt.dll")?;

    // The `SymbolCache` holds the resolved `isr::Entry` items.
    let mut cache = SymbolCache::default();
    let modules = ModuleResolver::default()
        // `with_kernel` MUST be called if `Event` variants reference kernel
        // symbols - like `NtWriteFile` in this example.
        //
        // This is because the "kernel" module is always optional.
        .with_kernel(kernel_info.base_address, profile)
        .with_module_in_process(
            Module::NcryptDll,
            ncrypt_resolved.process,
            ncrypt_resolved.image_base,
            ncrypt_profile,
        )
        // This will automatically resolve the `netio.sys` module and load
        // its profile.
        //
        // Note that if we hadn't called `with_module_in_process` for
        // `ncrypt.dll`, it would also be automatically resolved here.
        .resolve(&session, &isr, &mut cache)?;

    // Finally, we collect the events according to the resolved information
    // and the metadata.
    //
    // For example, if some module/event is marked as `optional` and the
    // resolver fails to resolve it, then it will simply not be included
    // in the `events`.
    let events = modules.into_events()?;

    // And we're ready to create the reactor!
    session.handle(|session| {
        Ok(Reactor::new(session, handler, events)?.with_termination_flag(terminate_flag))
    })?;

    Ok(())
}

pub fn handle_with_timeout<Handler>( &self, timeout: Duration, handler_factory: impl FnOnce(&VmiSession<'_, Os>) -> Result<Handler, VmiError>, ) -> Result<Option<<Handler as VmiHandler<Os>>::Output>, VmiError>

where Handler: VmiHandler<Os>,

Available on crate features injector and utils only.

Enters the main event handling loop that processes VMI events until finished, with a timeout for each event.

pub fn pause_guard(&self) -> Result<VmiSessionPauseGuard<'_, Os>, VmiError>

Available on crate features injector and utils only.

Pauses the virtual machine, snapshots the boot CPU registers, and returns a guard that resumes the VM when dropped.

Examples found in repository

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

fn main() -> Result<(), Error> {
    let session = 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 paused = session.pause_guard()?;

        let vmi = paused.state();

        let explorer = match vmi.os().find_process("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<(), Error> {
    let session = 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 paused = session.pause_guard()?;

        let vmi = paused.state();

        let explorer = match vmi.os().find_process("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<(), Error> {
    let session = 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 paused = session.pause_guard()?;

        let vmi = paused.state();

        let explorer = match vmi.os().find_process("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/basic-process-list.rs (line 51)

fn main() -> Result<(), Error> {
    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::try_from_env()?
        .context("invalid VMI_XEN_DOMAIN environment variable")?;
    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 paused = session.pause_guard()?;

    // Create a new `VmiState` with the boot CPU registers.
    let vmi = paused.state();

    // 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(())
}

examples/windows-reactor/main.rs (line 302)

fn main() -> Result<(), Error> {
    let filter = EnvFilter::default()
        .add_directive(tracing::Level::DEBUG.into())
        .add_directive("reqwest=warn".parse()?)
        .add_directive("rustls=warn".parse()?);

    tracing_subscriber::fmt()
        .with_env_filter(filter)
        .with_target(false)
        .init();

    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::try_from_env()?
        .context("invalid VMI_XEN_DOMAIN environment variable")?;
    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 registers = core.registers(VcpuId(0))?;

        WindowsOs::find_kernel(&core, &registers)?.context("cannot find kernel information")?
    };

    // Load the kernel profile.
    // The profile contains offsets to kernel functions and data structures.
    tracing::info!(codeview = ?kernel_info.codeview, "loading kernel profile");
    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);

    let handler = NetIo::default();

    //
    // The following `let ncrypt_* = ...` lines demonstrate how to manually
    // resolve a module, load its profile (symbols) and add it to the resolver
    // via `with_module(_in_process)`.
    //
    // Note that this is not strictly necessary, as `ModuleResolver::resolve()`
    // will automatically resolve modules if they are not explicitly added.
    //
    // Manually resolving modules can be useful in cases where you want to deal
    // with the resolved information (base address, profile) in other places.
    //

    let ncrypt_resolved = {
        let paused = session.pause_guard()?;
        let vmi = paused.state();

        // Calling `resolve_user_module(&vmi, &isr, "ncrypt.dll", "lsass.exe")`
        // would also work, but this demonstrates how to use a custom predicate.
        //
        // Also, `match_lsass` is more strict, because it specifically looks
        // for "lsass.exe" in SessionId 0 (therefore, avoiding potential false
        // positives or potential malicious processes).
        vmi::utils::resolver::resolve_user_module(&vmi, &isr, "ncrypt.dll", match_lsass)?
            .context("ncrypt.dll not found in lsass.exe")?
    };

    let ncrypt_entry = isr
        .entry_from_codeview(ncrypt_resolved.debug_signature)
        .context("cannot find symbols for ncrypt.dll")?;

    let ncrypt_profile = ncrypt_entry
        .profile()
        .context("cannot load profile for ncrypt.dll")?;

    // The `SymbolCache` holds the resolved `isr::Entry` items.
    let mut cache = SymbolCache::default();
    let modules = ModuleResolver::default()
        // `with_kernel` MUST be called if `Event` variants reference kernel
        // symbols - like `NtWriteFile` in this example.
        //
        // This is because the "kernel" module is always optional.
        .with_kernel(kernel_info.base_address, profile)
        .with_module_in_process(
            Module::NcryptDll,
            ncrypt_resolved.process,
            ncrypt_resolved.image_base,
            ncrypt_profile,
        )
        // This will automatically resolve the `netio.sys` module and load
        // its profile.
        //
        // Note that if we hadn't called `with_module_in_process` for
        // `ncrypt.dll`, it would also be automatically resolved here.
        .resolve(&session, &isr, &mut cache)?;

    // Finally, we collect the events according to the resolved information
    // and the metadata.
    //
    // For example, if some module/event is marked as `optional` and the
    // resolver fails to resolve it, then it will simply not be included
    // in the `events`.
    let events = modules.into_events()?;

    // And we're ready to create the reactor!
    session.handle(|session| {
        Ok(Reactor::new(session, handler, events)?.with_termination_flag(terminate_flag))
    })?;

    Ok(())
}

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

    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,
        })
    }

Methods from Deref<Target = VmiCore<<Os as VmiOs>::Driver>>

pub fn driver(&self) -> &Driver

Available on crate features injector and utils only.

Returns the driver used by this VmiCore instance.

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

Available on crate features injector and utils only.

Retrieves information about the virtual machine.

Examples found in repository

examples/basic.rs (line 17)

fn main() -> Result<(), Error> {
    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::try_from_env()?
        .context("invalid VMI_XEN_DOMAIN environment variable")?;
    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(())
}

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

Available on crate features injector and utils 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 injector and utils only.

Clears the entire GFN cache.

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

Available on crate features injector and utils 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 injector and utils 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 510)

    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 read_string_length_limit(&self) -> Option<usize>

Available on crate features injector and utils 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 injector and utils 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 injector and utils only.

Reads memory from the virtual machine.

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

Available on crate features injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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 injector and utils only.

Reads a struct from the virtual machine.

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

Available on crate features injector and utils only.

Translates a virtual address to a physical address.

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

Available on crate features injector and utils only.

Translates an access context to a physical address.

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

Available on crate features injector and utils only.

Reads a page of memory from the virtual machine.

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

Available on crate features injector and utils only.

Writes memory to the virtual machine.

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

Available on crate features injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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 injector and utils only.

Writes a struct to the virtual machine.

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

Available on crate features injector and utils 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.

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

Available on crate features injector and utils 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 injector and utils 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.

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

Available on crate features injector and utils 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 19)

fn main() -> Result<(), Error> {
    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::try_from_env()?
        .context("invalid VMI_XEN_DOMAIN environment variable")?;
    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-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/basic-process-list.rs (line 26)

fn main() -> Result<(), Error> {
    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::try_from_env()?
        .context("invalid VMI_XEN_DOMAIN environment variable")?;
    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 paused = session.pause_guard()?;

    // Create a new `VmiState` with the boot CPU registers.
    let vmi = paused.state();

    // 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(())
}

examples/common/mod.rs (line 32)

pub fn create_vmi_session() -> Result<VmiSession<'static, WindowsOs<VmiXenDriver<Amd64>>>, Error> {
    let filter = EnvFilter::default()
        .add_directive(tracing::Level::DEBUG.into())
        .add_directive("reqwest=warn".parse()?)
        .add_directive("rustls=warn".parse()?);

    tracing_subscriber::fmt()
        .with_env_filter(filter)
        .with_target(false)
        .init();

    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::try_from_env()?
        .context("invalid VMI_XEN_DOMAIN environment variable")?;
    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)?.context("cannot find kernel information")?
    };

    // Load the profile.
    // The profile contains offsets to kernel functions and data structures.
    tracing::info!(codeview = ?kernel_info.codeview, "loading kernel profile");
    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))
}

examples/windows-reactor/main.rs (line 264)

fn main() -> Result<(), Error> {
    let filter = EnvFilter::default()
        .add_directive(tracing::Level::DEBUG.into())
        .add_directive("reqwest=warn".parse()?)
        .add_directive("rustls=warn".parse()?);

    tracing_subscriber::fmt()
        .with_env_filter(filter)
        .with_target(false)
        .init();

    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::try_from_env()?
        .context("invalid VMI_XEN_DOMAIN environment variable")?;
    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 registers = core.registers(VcpuId(0))?;

        WindowsOs::find_kernel(&core, &registers)?.context("cannot find kernel information")?
    };

    // Load the kernel profile.
    // The profile contains offsets to kernel functions and data structures.
    tracing::info!(codeview = ?kernel_info.codeview, "loading kernel profile");
    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);

    let handler = NetIo::default();

    //
    // The following `let ncrypt_* = ...` lines demonstrate how to manually
    // resolve a module, load its profile (symbols) and add it to the resolver
    // via `with_module(_in_process)`.
    //
    // Note that this is not strictly necessary, as `ModuleResolver::resolve()`
    // will automatically resolve modules if they are not explicitly added.
    //
    // Manually resolving modules can be useful in cases where you want to deal
    // with the resolved information (base address, profile) in other places.
    //

    let ncrypt_resolved = {
        let paused = session.pause_guard()?;
        let vmi = paused.state();

        // Calling `resolve_user_module(&vmi, &isr, "ncrypt.dll", "lsass.exe")`
        // would also work, but this demonstrates how to use a custom predicate.
        //
        // Also, `match_lsass` is more strict, because it specifically looks
        // for "lsass.exe" in SessionId 0 (therefore, avoiding potential false
        // positives or potential malicious processes).
        vmi::utils::resolver::resolve_user_module(&vmi, &isr, "ncrypt.dll", match_lsass)?
            .context("ncrypt.dll not found in lsass.exe")?
    };

    let ncrypt_entry = isr
        .entry_from_codeview(ncrypt_resolved.debug_signature)
        .context("cannot find symbols for ncrypt.dll")?;

    let ncrypt_profile = ncrypt_entry
        .profile()
        .context("cannot load profile for ncrypt.dll")?;

    // The `SymbolCache` holds the resolved `isr::Entry` items.
    let mut cache = SymbolCache::default();
    let modules = ModuleResolver::default()
        // `with_kernel` MUST be called if `Event` variants reference kernel
        // symbols - like `NtWriteFile` in this example.
        //
        // This is because the "kernel" module is always optional.
        .with_kernel(kernel_info.base_address, profile)
        .with_module_in_process(
            Module::NcryptDll,
            ncrypt_resolved.process,
            ncrypt_resolved.image_base,
            ncrypt_profile,
        )
        // This will automatically resolve the `netio.sys` module and load
        // its profile.
        //
        // Note that if we hadn't called `with_module_in_process` for
        // `ncrypt.dll`, it would also be automatically resolved here.
        .resolve(&session, &isr, &mut cache)?;

    // Finally, we collect the events according to the resolved information
    // and the metadata.
    //
    // For example, if some module/event is marked as `optional` and the
    // resolver fails to resolve it, then it will simply not be included
    // in the `events`.
    let events = modules.into_events()?;

    // And we're ready to create the reactor!
    session.handle(|session| {
        Ok(Reactor::new(session, handler, events)?.with_termination_flag(terminate_flag))
    })?;

    Ok(())
}

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

    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,
        })
    }

    #[tracing::instrument(skip_all)]
    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(breakpoint) => 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()))
    }

    #[tracing::instrument(skip_all)]
    fn singlestep(
        &mut self,
        vmi: &VmiContext<WindowsOs<Driver>>,
    ) -> Result<VmiEventResponse<Amd64>, VmiError> {
        // Get the page table modifications by processing the dirty page table
        // entries.
        let ptm_events = self.ptm.process_dirty_entries(vmi, vmi.event().vcpu_id())?;

        // Let the breakpoint controller handle the page table modifications.
        self.bpm.handle_ptm_events(vmi, ptm_events)?;

        // Disable singlestep and switch back to our view.
        Ok(VmiEventResponse::default().with_view(self.view))
    }

    #[tracing::instrument(skip_all)]
    fn NtCreateFile(&mut self, vmi: &VmiContext<WindowsOs<Driver>>) -> Result<(), VmiError> {
        //
        // NTSTATUS
        // NtCreateFile (
        //     _Out_ PHANDLE FileHandle,
        //     _In_ ACCESS_MASK DesiredAccess,
        //     _In_ POBJECT_ATTRIBUTES ObjectAttributes,
        //     _Out_ PIO_STATUS_BLOCK IoStatusBlock,
        //     _In_opt_ PLARGE_INTEGER AllocationSize,
        //     _In_ ULONG FileAttributes,
        //     _In_ ULONG ShareAccess,
        //     _In_ ULONG CreateDisposition,
        //     _In_ ULONG CreateOptions,
        //     _In_reads_bytes_opt_(EaLength) PVOID EaBuffer,
        //     _In_ ULONG EaLength
        //     );
        //

        let ObjectAttributes = Va(vmi.os().function_argument(2)?);

        let object_attributes = vmi.os().object_attributes(ObjectAttributes)?;
        let object_name = match object_attributes.object_name()? {
            Some(object_name) => object_name,
            None => {
                tracing::warn!(%ObjectAttributes, "No object name found");
                return Ok(());
            }
        };

        tracing::info!(%object_name);

        Ok(())
    }

    #[tracing::instrument(skip_all)]
    fn NtWriteFile(&mut self, vmi: &VmiContext<WindowsOs<Driver>>) -> Result<(), VmiError> {
        //
        // NTSTATUS
        // NtWriteFile (
        //     _In_ HANDLE FileHandle,
        //     _In_opt_ HANDLE Event,
        //     _In_opt_ PIO_APC_ROUTINE ApcRoutine,
        //     _In_opt_ PVOID ApcContext,
        //     _Out_ PIO_STATUS_BLOCK IoStatusBlock,
        //     _In_reads_bytes_(Length) PVOID Buffer,
        //     _In_ ULONG Length,
        //     _In_opt_ PLARGE_INTEGER ByteOffset,
        //     _In_opt_ PULONG Key
        //     );
        //

        let FileHandle = vmi.os().function_argument(0)?;

        let file_object = match vmi
            .os()
            .current_process()?
            .lookup_object::<WindowsFileObject<_>>(FileHandle)?
        {
            Some(file_object) => file_object,
            None => {
                tracing::warn!(FileHandle = %Hex(FileHandle), "No object found");
                return Ok(());
            }
        };

        let path = file_object.full_path()?;
        tracing::info!(%path);

        Ok(())
    }

    #[tracing::instrument(skip_all)]
    fn PspInsertProcess(&mut self, vmi: &VmiContext<WindowsOs<Driver>>) -> Result<(), VmiError> {
        //
        // NTSTATUS
        // PspInsertProcess (
        //     _In_ PEPROCESS NewProcess,
        //     _In_ PEPROCESS Parent,
        //     _In_ ULONG DesiredAccess,
        //     _In_ ULONG CreateFlags,
        //     ...
        //     );
        //

        let NewProcess = vmi.os().function_argument(0)?;
        let Parent = vmi.os().function_argument(1)?;

        let process = vmi.os().process(ProcessObject(Va(NewProcess)))?;
        let process_id = process.id()?;

        let parent_process = vmi.os().process(ProcessObject(Va(Parent)))?;
        let parent_process_id = parent_process.id()?;

        // We rely heavily on the 2nd argument to be the parent process object.
        // If that ever changes, this assertion should catch it.
        //
        // So far it is verified that it works for Windows 7 up to Windows 11
        // (23H2, build 22631).
        debug_assert_eq!(parent_process_id, process.parent_id()?);

        let name = process.name()?;
        let image_base = process.image_base()?;
        let peb = process.peb()?;

        tracing::info!(
            %process_id,
            name,
            %image_base,
            ?peb,
        );

        Ok(())
    }

    #[tracing::instrument(skip_all)]
    fn MmCleanProcessAddressSpace(
        &mut self,
        vmi: &VmiContext<WindowsOs<Driver>>,
    ) -> Result<(), VmiError> {
        //
        // VOID
        // MmCleanProcessAddressSpace (
        //     _In_ PEPROCESS Process
        //     );
        //

        let Process = vmi.os().function_argument(0)?;

        let process = vmi.os().process(ProcessObject(Va(Process)))?;
        let process_id = process.id()?;

        let name = process.name()?;
        let image_base = process.image_base()?;

        tracing::info!(%process_id, name, %image_base);

        Ok(())
    }

    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(pf)) = result {
            tracing::warn!(?pf, "Page fault, injecting");
            vmi.inject_interrupt(event.vcpu_id(), Interrupt::page_fault(pf.va, 0))?;
            return Ok(VmiEventResponse::default());
        }

        result
    }
}

impl<Driver> VmiHandler<WindowsOs<Driver>> for Monitor<Driver>
where
    Driver: VmiFullDriver<Architecture = Amd64>,
{
    type Output = ();

    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")
    }

    fn poll(&self) -> Option<Self::Output> {
        self.terminate_flag.load(Ordering::Relaxed).then_some(())
    }
}

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

    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::try_from_env()?
        .context("invalid VMI_XEN_DOMAIN environment variable")?;
    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(())
}

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

Available on crate features injector and utils only.

Sets the registers of a virtual CPU.

pub fn default_view(&self) -> View

Available on crate features injector and utils 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 262)

    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(breakpoint) => 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 injector and utils 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 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 destroy_view(&self, view: View) -> Result<(), VmiError>

Available on crate features injector and utils 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 injector and utils 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 125)

    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 injector and utils 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 injector and utils 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.

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

Available on crate features injector and utils 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 119)

    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 injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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.

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

Available on crate features injector and utils only.

Pauses the virtual machine.

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

Available on crate features injector and utils only.

Resumes the virtual machine.

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

Available on crate features injector and utils only.

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

Examples found in repository

examples/basic.rs (line 16)

fn main() -> Result<(), Error> {
    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::try_from_env()?
        .context("invalid VMI_XEN_DOMAIN environment variable")?;
    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 533)

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

    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::try_from_env()?
        .context("invalid VMI_XEN_DOMAIN environment variable")?;
    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/basic-process-list.rs (line 23)

fn main() -> Result<(), Error> {
    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::try_from_env()?
        .context("invalid VMI_XEN_DOMAIN environment variable")?;
    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 paused = session.pause_guard()?;

    // Create a new `VmiState` with the boot CPU registers.
    let vmi = paused.state();

    // 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(())
}

examples/common/mod.rs (line 29)

pub fn create_vmi_session() -> Result<VmiSession<'static, WindowsOs<VmiXenDriver<Amd64>>>, Error> {
    let filter = EnvFilter::default()
        .add_directive(tracing::Level::DEBUG.into())
        .add_directive("reqwest=warn".parse()?)
        .add_directive("rustls=warn".parse()?);

    tracing_subscriber::fmt()
        .with_env_filter(filter)
        .with_target(false)
        .init();

    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::try_from_env()?
        .context("invalid VMI_XEN_DOMAIN environment variable")?;
    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)?.context("cannot find kernel information")?
    };

    // Load the profile.
    // The profile contains offsets to kernel functions and data structures.
    tracing::info!(codeview = ?kernel_info.codeview, "loading kernel profile");
    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))
}

examples/windows-reactor/main.rs (line 263)

fn main() -> Result<(), Error> {
    let filter = EnvFilter::default()
        .add_directive(tracing::Level::DEBUG.into())
        .add_directive("reqwest=warn".parse()?)
        .add_directive("rustls=warn".parse()?);

    tracing_subscriber::fmt()
        .with_env_filter(filter)
        .with_target(false)
        .init();

    // Setup VMI.
    let driver = VmiXenDriver::<Amd64>::try_from_env()?
        .context("invalid VMI_XEN_DOMAIN environment variable")?;
    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 registers = core.registers(VcpuId(0))?;

        WindowsOs::find_kernel(&core, &registers)?.context("cannot find kernel information")?
    };

    // Load the kernel profile.
    // The profile contains offsets to kernel functions and data structures.
    tracing::info!(codeview = ?kernel_info.codeview, "loading kernel profile");
    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);

    let handler = NetIo::default();

    //
    // The following `let ncrypt_* = ...` lines demonstrate how to manually
    // resolve a module, load its profile (symbols) and add it to the resolver
    // via `with_module(_in_process)`.
    //
    // Note that this is not strictly necessary, as `ModuleResolver::resolve()`
    // will automatically resolve modules if they are not explicitly added.
    //
    // Manually resolving modules can be useful in cases where you want to deal
    // with the resolved information (base address, profile) in other places.
    //

    let ncrypt_resolved = {
        let paused = session.pause_guard()?;
        let vmi = paused.state();

        // Calling `resolve_user_module(&vmi, &isr, "ncrypt.dll", "lsass.exe")`
        // would also work, but this demonstrates how to use a custom predicate.
        //
        // Also, `match_lsass` is more strict, because it specifically looks
        // for "lsass.exe" in SessionId 0 (therefore, avoiding potential false
        // positives or potential malicious processes).
        vmi::utils::resolver::resolve_user_module(&vmi, &isr, "ncrypt.dll", match_lsass)?
            .context("ncrypt.dll not found in lsass.exe")?
    };

    let ncrypt_entry = isr
        .entry_from_codeview(ncrypt_resolved.debug_signature)
        .context("cannot find symbols for ncrypt.dll")?;

    let ncrypt_profile = ncrypt_entry
        .profile()
        .context("cannot load profile for ncrypt.dll")?;

    // The `SymbolCache` holds the resolved `isr::Entry` items.
    let mut cache = SymbolCache::default();
    let modules = ModuleResolver::default()
        // `with_kernel` MUST be called if `Event` variants reference kernel
        // symbols - like `NtWriteFile` in this example.
        //
        // This is because the "kernel" module is always optional.
        .with_kernel(kernel_info.base_address, profile)
        .with_module_in_process(
            Module::NcryptDll,
            ncrypt_resolved.process,
            ncrypt_resolved.image_base,
            ncrypt_profile,
        )
        // This will automatically resolve the `netio.sys` module and load
        // its profile.
        //
        // Note that if we hadn't called `with_module_in_process` for
        // `ncrypt.dll`, it would also be automatically resolved here.
        .resolve(&session, &isr, &mut cache)?;

    // Finally, we collect the events according to the resolved information
    // and the metadata.
    //
    // For example, if some module/event is marked as `optional` and the
    // resolver fails to resolve it, then it will simply not be included
    // in the `events`.
    let events = modules.into_events()?;

    // And we're ready to create the reactor!
    session.handle(|session| {
        Ok(Reactor::new(session, handler, events)?.with_termination_flag(terminate_flag))
    })?;

    Ok(())
}

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

Available on crate features injector and utils 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 injector and utils 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 injector and utils 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 injector and utils 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 494)

    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(pf)) = result {
            tracing::warn!(?pf, "Page fault, injecting");
            vmi.inject_interrupt(event.vcpu_id(), Interrupt::page_fault(pf.va, 0))?;
            return Ok(VmiEventResponse::default());
        }

        result
    }

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

Available on crate features injector and utils 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.

Trait Implementations

impl<Os> Clone for VmiState<'_, Os>

where Os: VmiOs,

fn clone(&self) -> VmiState<'_, Os>

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl<Os> Copy for VmiState<'_, Os>

where Os: VmiOs,

impl<'a, Os> Deref for VmiState<'a, Os>

where Os: VmiOs,

type Target = VmiSession<'a, Os>

The resulting type after dereferencing.

fn deref(&self) -> &<VmiState<'a, Os> as Deref>::Target

Dereferences the value.