Struct WindowsOs 

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

Available on crate feature os-windows only.

VMI operations for the Windows operating system.

WindowsOs provides methods and utilities for introspecting a Windows-based virtual machine. It encapsulates Windows-specific knowledge and operations, allowing for high-level interactions with the guest OS structures and processes.

Usage

Create an instance of WindowsOs using a Profile that contains information about the specific Windows version being introspected:

use isr::cache::IsrCache;
use vmi::{
    VcpuId, VmiCore,
    arch::amd64::Amd64,
    driver::{VmiQueryRegisters, VmiRead, VmiVmControl},
    os::windows::WindowsOs,
};

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

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

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

// Load the profile using the ISR library.
let isr = IsrCache::new("cache")?;
let entry = isr.entry_from_codeview(kernel_info.codeview)?;
let profile = entry.profile()?;

// Create a new `WindowsOs` instance.
let os = WindowsOs::<Driver>::new(&profile)?;

Important Notes

• Many methods of this struct require pausing the VM to ensure consistency. Use pause_guard when performing operations that might be affected by concurrent changes in the guest OS.

• The behavior and accuracy of some methods may vary depending on the Windows version being introspected. Always ensure your Profile matches the guest OS version.

Examples

Retrieving information about the current process:

let process = vmi.os().current_process()?;
let process_id = process.id()?;
let process_name = process.name()?;
println!("Current process: {} (PID: {})", process_name, process_id);

Enumerating all processes:

for process in vmi.os().processes()? {
    let process = process?;
    println!("Process: {} (PID: {})", process.name()?, process.id()?);
}

Safety

While this struct doesn’t use unsafe code directly, many of its methods interact with raw memory of the guest OS. Incorrect usage can lead to invalid memory access or misinterpretation of data. Always ensure you’re working with the correct memory regions and OS structures.

Implementations

impl<Driver> WindowsOs<Driver>

where Driver: VmiRead, <Driver as VmiDriver>::Architecture: ArchAdapter<Driver>,

pub const NtCurrentProcess32: u64 = 0xffff_ffff

32-bit current process pseudo-handle (-1).

pub const NtCurrentProcess64: u64 = 0xffff_ffff_ffff_ffff

64-bit current process pseudo-handle (-1).

pub const NtCurrentThread32: u64 = 0xffff_fffe

32-bit current thread pseudo-handle (-2).

pub const NtCurrentThread64: u64 = 0xffff_ffff_ffff_fffe

64-bit current thread pseudo-handle (-2).

pub fn new(profile: &Profile<'_>) -> Result<WindowsOs<Driver>, VmiError>

Creates a new WindowsOs instance.

Examples found in repository

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

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

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

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

    tracing::debug!(?domain_id);

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

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

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

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

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

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

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

    Ok(())
}

examples/common/mod.rs (line 66)

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

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

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

    tracing::debug!(?domain_id);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    // Pause the VM again to get consistent state.
    let 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 304)

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();

    let domain_id = match std::env::var("VMI_XEN_DOMAIN_ID") {
        Ok(domain_id) => XenDomainId(
            domain_id
                .parse()
                .context("invalid VMI_XEN_DOMAIN_ID environment variable")?,
        ),
        Err(_) => {
            let domain_name = std::env::var("VMI_XEN_DOMAIN_NAME")
                .context("invalid VMI_XEN_DOMAIN_NAME environment variable")?;

            tracing::info!(%domain_name, "resolving domain ID");

            match XenStore::new()?.domain_id_from_name(&domain_name)? {
                Some(domain_id) => domain_id,
                None => return Err(anyhow::anyhow!("domain not found: {domain_name}")),
            }
        }
    };

    // Setup VMI.
    tracing::info!(%domain_id, "setting up VMI");
    let driver = VmiXenDriver::<Amd64>::new(domain_id)?;
    let core = VmiCore::new(driver)?;

    // Try to find the kernel information.
    // This is necessary in order to load the profile.
    let kernel_info = {
        let _pause_guard = core.pause_guard()?;
        let 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_process = ncrypt_resolved
        .process
        .context("resolved ncrypt.dll is not associated with a process")?;

    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_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 with_kernel_base( profile: &Profile<'_>, kernel_base: Va, ) -> Result<WindowsOs<Driver>, VmiError>

Creates a new WindowsOs instance with a known kernel base address.

Examples found in repository

examples/windows-dump.rs (line 427)

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

pub fn offsets(vmi: VmiState<'_, WindowsOs<Driver>>) -> &Offsets

Returns a reference to the Windows-specific memory offsets.

pub fn symbols(vmi: VmiState<'_, WindowsOs<Driver>>) -> &Symbols

Returns a reference to the Windows-specific symbols.

pub fn find_kernel( vmi: &VmiCore<Driver>, registers: &<<Driver as VmiDriver>::Architecture as Architecture>::Registers, ) -> Result<Option<WindowsKernelInformation>, VmiError>

Locates the Windows kernel in memory based on the CPU registers. This function is architecture-specific.

On AMD64, the kernel is located by taking the MSR_LSTAR value and reading the virtual memory page by page backwards until the MZ header is found.

Examples found in repository

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

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

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

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

    tracing::debug!(?domain_id);

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

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

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

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

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

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

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

    Ok(())
}

examples/windows-dump.rs (line 416)

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

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

    let dump_file = &args[1];

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

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

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

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

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

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

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

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

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

    Ok(())
}

examples/common/mod.rs (line 54)

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

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

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

    tracing::debug!(?domain_id);

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    // Pause the VM again to get consistent state.
    let 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 286)

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();

    let domain_id = match std::env::var("VMI_XEN_DOMAIN_ID") {
        Ok(domain_id) => XenDomainId(
            domain_id
                .parse()
                .context("invalid VMI_XEN_DOMAIN_ID environment variable")?,
        ),
        Err(_) => {
            let domain_name = std::env::var("VMI_XEN_DOMAIN_NAME")
                .context("invalid VMI_XEN_DOMAIN_NAME environment variable")?;

            tracing::info!(%domain_name, "resolving domain ID");

            match XenStore::new()?.domain_id_from_name(&domain_name)? {
                Some(domain_id) => domain_id,
                None => return Err(anyhow::anyhow!("domain not found: {domain_name}")),
            }
        }
    };

    // Setup VMI.
    tracing::info!(%domain_id, "setting up VMI");
    let driver = VmiXenDriver::<Amd64>::new(domain_id)?;
    let core = VmiCore::new(driver)?;

    // Try to find the kernel information.
    // This is necessary in order to load the profile.
    let kernel_info = {
        let _pause_guard = core.pause_guard()?;
        let 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_process = ncrypt_resolved
        .process
        .context("resolved ncrypt.dll is not associated with a process")?;

    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_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 kernel_build_number( vmi: VmiState<'_, WindowsOs<Driver>>, ) -> Result<u32, VmiError>

Returns the kernel build number.

Notes

The value is cached after the first read.

Implementation Details

Corresponds to NtBuildNumber symbol.

pub fn kernel_information_string_ex( vmi: VmiState<'_, WindowsOs<Driver>>, ) -> Result<Option<String>, VmiError>

Returns the kernel information string.

Notes

The kernel information string is cached after the first read.

Implementation Details

Corresponds to NtBuildLab symbol.

pub fn is_kernel_handle( vmi: VmiState<'_, WindowsOs<Driver>>, handle: u64, ) -> Result<bool, VmiError>

Checks if the given handle is a kernel handle.

A kernel handle is a handle with the highest bit set.

pub fn lowest_user_address( _vmi: VmiState<'_, WindowsOs<Driver>>, ) -> Result<Va, VmiError>

Returns the lowest user-mode address.

This method returns a constant value (0x10000) representing the lowest address that can be used by user-mode applications in Windows.

Notes

• Windows creates a NO_ACCESS VAD (Virtual Address Descriptor) for the first 64KB of virtual memory. This means the VA range 0-0x10000 is off-limits for usage.

• This behavior is consistent across all Windows versions from XP through recent Windows 11, and applies to x86, x64, and ARM64 architectures.

• Many Windows APIs leverage this fact to determine whether an input argument is a pointer or not. Here are two notable examples:

  1. The FindResource() function accepts an lpName parameter of type LPCTSTR, which can be either:

     • A pointer to a valid string

     • A value created by MAKEINTRESOURCE(ID)

       This allows FindResource() to accept WORD values (unsigned shorts) with a maximum value of 0xFFFF, distinguishing them from valid memory addresses.

  2. The AddAtom() function similarly accepts an lpString parameter of type LPCTSTR. This parameter can be:

     • A pointer to a null-terminated string (max 255 bytes)
     • An integer atom converted using the MAKEINTATOM(ID) macro

  In both cases, the API can distinguish between valid pointers (which will be above 0x10000) and integer values (which will be below 0x10000), allowing for flexible parameter usage without ambiguity.

pub fn highest_user_address( vmi: VmiState<'_, WindowsOs<Driver>>, ) -> Result<Va, VmiError>

Returns the highest user-mode address.

This method reads the highest user-mode address from the Windows kernel. The value is cached after the first read for performance.

Notes

This value is cached after the first read.

Implementation Details

Corresponds to MmHighestUserAddress symbol.

pub fn is_valid_user_address( vmi: VmiState<'_, WindowsOs<Driver>>, address: Va, ) -> Result<bool, VmiError>

Checks if a given address is a valid user-mode address.

This method determines whether the provided address falls within the range of valid user-mode addresses in Windows.

pub fn unloaded_modules<'a>( vmi: VmiState<'a, WindowsOs<Driver>>, ) -> Result<impl Iterator<Item = Result<WindowsUnloadedDriver<'a, Driver>, VmiError>> + use<'a, Driver>, VmiError>

Returns an iterator over recently unloaded drivers.

Walks the kernel’s fixed-size circular buffer of unloaded driver records, newest first. The iterator stops at the first empty slot or after the buffer’s 50-entry capacity has been visited.

Implementation Details

Corresponds to MmUnloadedDrivers and MmLastUnloadedDriver.

pub fn number_of_processors( vmi: VmiState<'_, WindowsOs<Driver>>, ) -> Result<u16, VmiError>

Returns the number of active processors in the system.

Implementation Details

Corresponds to KeNumberProcessors.

pub fn current_kpcr(vmi: VmiState<'_, WindowsOs<Driver>>) -> Va

Returns the virtual address of the current Kernel Processor Control Region (KPCR).

The KPCR is a per-processor data structure in Windows that contains critical information about the current processor state. This method returns the virtual address of the KPCR for the current processor.

pub fn kprcb<'a>( vmi: VmiState<'a, WindowsOs<Driver>>, vcpu_id: VcpuId, ) -> Result<WindowsKernelProcessorBlock<'a, Driver>, VmiError>

Returns a Kernel Processor Control Block (KPRCB) for the specified processor.

The KPRCB is an opaque, per-processor structure embedded within the KPCR.

Implementation Details

Corresponds to KiProcessorBlock symbol, offset by the processor ID.

pub fn current_kprcb<'a>( vmi: VmiState<'a, WindowsOs<Driver>>, ) -> Result<WindowsKernelProcessorBlock<'a, Driver>, VmiError>

Returns the Kernel Processor Control Block (KPRCB) for the processor whose register state is currently loaded.

Unlike kprcb, which indexes the KiProcessorBlock array by processor ID, this resolves the PRCB from the current KPCR (gs-relative on AMD64) through KPCR.Prcb.

Implementation Details

Corresponds to KPCR.Prcb.

pub fn exception_record( vmi: VmiState<'_, WindowsOs<Driver>>, address: Va, ) -> Result<WindowsExceptionRecord, VmiError>

Returns information from an exception record at the specified address.

This method reads and parses an EXCEPTION_RECORD structure from memory, providing detailed information about an exception that has occurred in the system. The returned WindowsExceptionRecord contains data such as the exception code, flags, and related memory addresses.

pub fn last_status( vmi: VmiState<'_, WindowsOs<Driver>>, ) -> Result<Option<u32>, VmiError>

Returns the last status value for the current thread.

In Windows, the last status value is typically used to store error codes or success indicators from system calls. This method reads this value from the Thread Environment Block (TEB) of the current thread, providing insight into the outcome of recent operations performed by the thread.

Returns None if the TEB is not available.

Notes

LastStatusValue is a NTSTATUS value, whereas LastError is a Win32 error code. The two values are related but not identical. You can obtain the Win32 error code by calling VmiOs::last_error.

Implementation Details

Corresponds to NtCurrentTeb()->LastStatusValue.

pub fn idle_process<'a>( vmi: VmiState<'a, WindowsOs<Driver>>, ) -> Result<WindowsProcess<'a, Driver>, VmiError>

Returns the idle process (PID 0).

The idle process is a special system process that runs when no other threads are ready to execute on a processor.

Notes

This value is cached after the first read.

Implementation Details

Corresponds to PsIdleProcess symbol.

pub fn idle_thread<'a>( vmi: VmiState<'a, WindowsOs<Driver>>, ) -> Result<WindowsThread<'a, Driver>, VmiError>

Returns the idle thread for the current processor.

The idle thread is a per-processor thread that runs when no other threads are scheduled on that processor.

Implementation Details

Corresponds to KPCR.Prcb.IdleThread.

pub fn object<'a>( vmi: VmiState<'a, WindowsOs<Driver>>, va: Va, ) -> Result<WindowsObject<'a, Driver>, VmiError>

Returns the Windows object.

pub fn object_type<'a>( vmi: VmiState<'a, WindowsOs<Driver>>, kind: WindowsObjectTypeKind, ) -> Result<WindowsObjectType<'a, Driver>, VmiError>

Returns a Windows object type for the given object kind.

Notes

The object type is cached after the first read.

Implementation Details

• File corresponds to IoFileObjectType.
• Job corresponds to PsJobType.
• Key corresponds to CmKeyObjectType.
• Process corresponds to PsProcessType.
• Thread corresponds to PsThreadType.
• Token corresponds to SeTokenObjectType.
• Other types are not supported.

pub fn object_root_directory<'a>( vmi: VmiState<'a, WindowsOs<Driver>>, ) -> Result<WindowsDirectoryObject<'a, Driver>, VmiError>

Returns the root directory object for the Windows kernel.

Notes

The object root directory is cached after the first read.

Implementation Details

Corresponds to ObpRootDirectoryObject symbol.

pub fn object_header_cookie( vmi: VmiState<'_, WindowsOs<Driver>>, ) -> Result<Option<u8>, VmiError>

Returns the object header cookie used for obfuscating object types. Returns None if the cookie is not present in the kernel image.

Notes

Windows 10 introduced a security feature that obfuscates the type of kernel objects by XORing the TypeIndex field in the object header with a random cookie value. This method fetches that cookie, which is essential for correctly interpreting object headers in memory.

The cookie is cached after the first read.

Implementation Details

Corresponds to ObHeaderCookie symbol.

pub fn object_attributes<'a>( vmi: VmiState<'a, WindowsOs<Driver>>, object_attributes: Va, ) -> Result<WindowsObjectAttributes<'a, Driver>, VmiError>

Returns the Windows object attributes.

pub fn lookup_object<'a>( vmi: VmiState<'a, WindowsOs<Driver>>, path: impl AsRef<str>, ) -> Result<Option<WindowsObject<'a, Driver>>, VmiError>

Resolves an absolute object-namespace path to a named object.

Descends from the root directory (object_root_directory) one component at a time.

Returns Ok(None) when a component does not exist, or when an intermediate component resolves to something other than a Directory. The final component may be any object type.

Does not follow SymbolicLink objects.

pub fn hives<'a>( vmi: VmiState<'a, WindowsOs<Driver>>, ) -> Result<impl Iterator<Item = Result<WindowsHive<'a, Driver>, VmiError>> + use<'a, Driver>, VmiError>

Returns an iterator over all loaded registry hives.

This method returns an iterator over all loaded registry hives. It reads the CmpHiveListHead symbol from the kernel image and iterates over the linked list of _CMHIVE structures representing each hive.

pub fn lookup_key<'a>( vmi: VmiState<'a, WindowsOs<Driver>>, path: impl AsRef<str>, ) -> Result<Option<WindowsKeyNode<'a, Driver>>, VmiError>

Resolves an absolute registry path against the loaded hive set.

Picks the hive whose HiveRootPath is the longest component-aligned case-insensitive prefix of path, strips that prefix, and forwards the remainder to WindowsHive::lookup.

Returns Ok(None) when no hive root prefixes the path or when the descent does not find the key.

Hives with an empty HiveRootPath match any input at depth zero, so they only win when no loaded hive owns a real prefix.

Does not follow HIVE_EXIT links into other hives.

pub fn read_fast_ref( vmi: VmiState<'_, WindowsOs<Driver>>, va: Va, ) -> Result<Va, VmiError>

Reads an _EX_FAST_REF and returns the referenced object’s virtual address, with the low reference-count bits masked off.

pub fn read_ansi_string_bytes( vmi: VmiState<'_, WindowsOs<Driver>>, va: Va, ) -> Result<Vec<u8>, VmiError>

Reads string of bytes from an _ANSI_STRING structure.

This method reads a native _ANSI_STRING structure which contains an ASCII/ANSI string. The structure is read according to the current OS’s architecture (32-bit or 64-bit).

pub fn read_ansi_string32_bytes( vmi: VmiState<'_, WindowsOs<Driver>>, va: Va, ) -> Result<Vec<u8>, VmiError>

Reads string of bytes from a 32-bit version of _ANSI_STRING structure.

This method is specifically for reading _ANSI_STRING structures in 32-bit processes or WoW64 processes where pointers are 32 bits.

pub fn read_ansi_string64_bytes( vmi: VmiState<'_, WindowsOs<Driver>>, va: Va, ) -> Result<Vec<u8>, VmiError>

Reads string of bytes from a 64-bit version of _ANSI_STRING structure.

This method is specifically for reading _ANSI_STRING structures in 64-bit processes where pointers are 64 bits.

pub fn read_ansi_string( vmi: VmiState<'_, WindowsOs<Driver>>, va: Va, ) -> Result<String, VmiError>

Reads string from an _ANSI_STRING structure.

This method reads a native _ANSI_STRING structure which contains an ASCII/ANSI string. The structure is read according to the current OS’s architecture (32-bit or 64-bit).

pub fn read_ansi_string32( vmi: VmiState<'_, WindowsOs<Driver>>, va: Va, ) -> Result<String, VmiError>

Reads string from a 32-bit version of _ANSI_STRING structure.

This method is specifically for reading _ANSI_STRING structures in 32-bit processes or WoW64 processes where pointers are 32 bits.

pub fn read_ansi_string64( vmi: VmiState<'_, WindowsOs<Driver>>, va: Va, ) -> Result<String, VmiError>

Reads string from a 64-bit version of _ANSI_STRING structure.

This method is specifically for reading _ANSI_STRING structures in 64-bit processes where pointers are 64 bits.

pub fn read_unicode_string_bytes( vmi: VmiState<'_, WindowsOs<Driver>>, va: Va, ) -> Result<Vec<u16>, VmiError>

Reads string from a _UNICODE_STRING structure.

This method reads a native _UNICODE_STRING structure which contains a UTF-16 string. The structure is read according to the current OS’s architecture (32-bit or 64-bit).

pub fn read_unicode_string32_bytes( vmi: VmiState<'_, WindowsOs<Driver>>, va: Va, ) -> Result<Vec<u16>, VmiError>

Reads string from a 32-bit version of _UNICODE_STRING structure.

This method is specifically for reading _UNICODE_STRING structures in 32-bit processes or WoW64 processes where pointers are 32 bits.

pub fn read_unicode_string64_bytes( vmi: VmiState<'_, WindowsOs<Driver>>, va: Va, ) -> Result<Vec<u16>, VmiError>

Reads string from a 64-bit version of _UNICODE_STRING structure.

This method is specifically for reading _UNICODE_STRING structures in 64-bit processes where pointers are 64 bits.

pub fn read_unicode_string( vmi: VmiState<'_, WindowsOs<Driver>>, va: Va, ) -> Result<String, VmiError>

Reads string from a _UNICODE_STRING structure.

This method reads a native _UNICODE_STRING structure which contains a UTF-16 string. The structure is read according to the current OS’s architecture (32-bit or 64-bit).

pub fn read_unicode_string32( vmi: VmiState<'_, WindowsOs<Driver>>, va: Va, ) -> Result<String, VmiError>

Reads string from a 32-bit version of _UNICODE_STRING structure.

This method is specifically for reading _UNICODE_STRING structures in 32-bit processes or WoW64 processes where pointers are 32 bits.

pub fn read_unicode_string64( vmi: VmiState<'_, WindowsOs<Driver>>, va: Va, ) -> Result<String, VmiError>

Reads string from a 64-bit version of _UNICODE_STRING structure.

This method is specifically for reading _UNICODE_STRING structures in 64-bit processes where pointers are 64 bits.

pub fn read_ansi_string_bytes_in( vmi: VmiState<'_, WindowsOs<Driver>>, ctx: impl Into<AccessContext>, ) -> Result<Vec<u8>, VmiError>

Reads string of bytes from an _ANSI_STRING structure.

This method reads a native _ANSI_STRING structure which contains an ASCII/ANSI string. The structure is read according to the current OS’s architecture (32-bit or 64-bit).

pub fn read_ansi_string32_bytes_in( vmi: VmiState<'_, WindowsOs<Driver>>, ctx: impl Into<AccessContext>, ) -> Result<Vec<u8>, VmiError>

Reads string of bytes from a 32-bit version of _ANSI_STRING structure.

This method is specifically for reading _ANSI_STRING structures in 32-bit processes or WoW64 processes where pointers are 32 bits.

pub fn read_ansi_string64_bytes_in( vmi: VmiState<'_, WindowsOs<Driver>>, ctx: impl Into<AccessContext>, ) -> Result<Vec<u8>, VmiError>

Reads string of bytes from a 64-bit version of _ANSI_STRING structure.

This method is specifically for reading _ANSI_STRING structures in 64-bit processes where pointers are 64 bits.

pub fn read_ansi_string_in( vmi: VmiState<'_, WindowsOs<Driver>>, ctx: impl Into<AccessContext>, ) -> Result<String, VmiError>

Reads string from an _ANSI_STRING structure.

This method reads a native _ANSI_STRING structure which contains an ASCII/ANSI string. The structure is read according to the current OS’s architecture (32-bit or 64-bit).

pub fn read_ansi_string32_in( vmi: VmiState<'_, WindowsOs<Driver>>, ctx: impl Into<AccessContext>, ) -> Result<String, VmiError>

Reads string from a 32-bit version of _ANSI_STRING structure.

This method is specifically for reading _ANSI_STRING structures in 32-bit processes or WoW64 processes where pointers are 32 bits.

pub fn read_ansi_string64_in( vmi: VmiState<'_, WindowsOs<Driver>>, ctx: impl Into<AccessContext>, ) -> Result<String, VmiError>

Reads string from a 64-bit version of _ANSI_STRING structure.

This method is specifically for reading _ANSI_STRING structures in 64-bit processes where pointers are 64 bits.

pub fn read_unicode_string_bytes_in( vmi: VmiState<'_, WindowsOs<Driver>>, ctx: impl Into<AccessContext>, ) -> Result<Vec<u16>, VmiError>

Reads string from a _UNICODE_STRING structure.

This method reads a native _UNICODE_STRING structure which contains a UTF-16 string. The structure is read according to the current OS’s architecture (32-bit or 64-bit).

pub fn read_unicode_string32_bytes_in( vmi: VmiState<'_, WindowsOs<Driver>>, ctx: impl Into<AccessContext>, ) -> Result<Vec<u16>, VmiError>

Reads string from a 32-bit version of _UNICODE_STRING structure.

This method is specifically for reading _UNICODE_STRING structures in 32-bit processes or WoW64 processes where pointers are 32 bits.

pub fn read_unicode_string64_bytes_in( vmi: VmiState<'_, WindowsOs<Driver>>, ctx: impl Into<AccessContext>, ) -> Result<Vec<u16>, VmiError>

Reads string from a 64-bit version of _UNICODE_STRING structure.

This method is specifically for reading _UNICODE_STRING structures in 64-bit processes where pointers are 64 bits.

pub fn read_unicode_string_in( vmi: VmiState<'_, WindowsOs<Driver>>, ctx: impl Into<AccessContext>, ) -> Result<String, VmiError>

Reads string from a _UNICODE_STRING structure.

This method reads a native _UNICODE_STRING structure which contains a UTF-16 string. The structure is read according to the current OS’s architecture (32-bit or 64-bit).

pub fn read_unicode_string32_in( vmi: VmiState<'_, WindowsOs<Driver>>, ctx: impl Into<AccessContext>, ) -> Result<String, VmiError>

Reads string from a 32-bit version of _UNICODE_STRING structure.

This method is specifically for reading _UNICODE_STRING structures in 32-bit processes or WoW64 processes where pointers are 32 bits.

pub fn read_unicode_string64_in( vmi: VmiState<'_, WindowsOs<Driver>>, ctx: impl Into<AccessContext>, ) -> Result<String, VmiError>

Reads string from a 64-bit version of _UNICODE_STRING structure.

This method is specifically for reading _UNICODE_STRING structures in 64-bit processes where pointers are 64 bits.

pub fn linked_list<'a>( vmi: VmiState<'a, WindowsOs<Driver>>, list_head: Va, offset: u64, ) -> Result<impl Iterator<Item = Result<Va, VmiError>> + use<'a, Driver>, VmiError>

Returns an iterator over a doubly-linked list of LIST_ENTRY structures.

This method is used to iterate over a doubly-linked list of LIST_ENTRY structures in memory. It returns an iterator that yields the virtual addresses of each LIST_ENTRY structure in the list.

pub fn lock_pfn( vmi: VmiState<'_, WindowsOs<Driver>>, pfn: Gfn, ) -> Result<Option<u16>, VmiError>

where Driver: VmiWrite,

Increments the reference count of a Page Frame Number (PFN).

pub fn unlock_pfn( vmi: VmiState<'_, WindowsOs<Driver>>, pfn: Gfn, ) -> Result<Option<u16>, VmiError>

where Driver: VmiWrite,

Decrements the reference count of a Page Frame Number (PFN).

Trait Implementations

impl<Driver, T, Bridge> InjectorExecutionAdapter<KernelMode, T, Bridge> for WindowsOs<Driver>

where Driver: VmiDriver<Architecture = Amd64> + VmiRead + VmiWrite + VmiSetProtection + VmiQueryRegisters + VmiEventControl + VmiViewControl + VmiVmControl, Bridge: BridgeDispatch<WindowsOs<Driver>, u64>,

type Handler = KernelInjectorHandler<Driver, T, Bridge>

The concrete handler type for this OS and execution mode.

impl<Driver, T, Bridge> InjectorExecutionAdapter<UserMode, T, Bridge> for WindowsOs<Driver>

where Driver: VmiDriver<Architecture = Amd64> + VmiRead + VmiWrite + VmiSetProtection + VmiEventControl + VmiViewControl + VmiVmControl, Bridge: BridgeDispatch<WindowsOs<Driver>, u64>,

type Handler = UserInjectorHandler<Driver, T, Bridge>

The concrete handler type for this OS and execution mode.

impl<Driver> OsAdapter for WindowsOs<Driver>

where Driver: VmiDriver<Architecture = Amd64> + VmiRead + VmiWrite,

fn prepare_function_call( &self, vmi: &VmiCore<<WindowsOs<Driver> as VmiOs>::Driver>, registers: &mut Registers, builder: CallBuilder, ) -> Result<(), VmiError>

Prepares registers and stack for a function call according to OS conventions.

impl<Driver> OsAdapter for WindowsOs<Driver>

where Driver: VmiRead, <Driver as VmiDriver>::Architecture: ArchAdapter<Driver> + ArchAdapter<Driver>,

type DebugSignature = CodeView

OS-specific identifier that locates its debug symbols.

fn resolve_kernel_module( vmi: &VmiState<'_, WindowsOs<Driver>>, isr: &IsrCache, name: &str, ) -> Result<Option<Resolved<WindowsOs<Driver>>>, VmiError>

See resolve_kernel_module.

fn resolve_user_module( vmi: &VmiState<'_, WindowsOs<Driver>>, isr: &IsrCache, name: &str, process: impl ProcessPredicate<WindowsOs<Driver>>, ) -> Result<Option<Resolved<WindowsOs<Driver>>>, VmiError>

See resolve_user_module.

impl<Driver, Handler> VmiHandler<WindowsOs<Driver>> for Reactor<WindowsOs<Driver>, Handler>

where Driver: VmiFullDriver<Architecture = Amd64>, Handler: ReactorHandler<WindowsOs<Driver>>, <<Handler as ReactorHandler<WindowsOs<Driver>>>::Event as ReactorEvent>::Module: ReactorModule<WindowsOs<Driver>>,

type Output = Option<<Handler as ReactorHandler<WindowsOs<Driver>>>::Output>

The output type of the handler.

fn handle_event( &mut self, vmi: VmiContext<'_, WindowsOs<Driver>>, ) -> VmiEventResponse<<Driver as VmiDriver>::Architecture>

Called for each VMI event.

fn cleanup(&mut self, vmi: &VmiSession<'_, WindowsOs<Driver>>)

Called once before the session tears down monitoring.

fn poll( &self, ) -> Option<<Reactor<WindowsOs<Driver>, Handler> as VmiHandler<WindowsOs<Driver>>>::Output>

Checks if the handler has completed.

fn handle_timeout(&mut self, _session: &VmiSession<'_, Os>)

Called when the event loop times out waiting for the next event.

fn handle_interrupted(&mut self, _session: &VmiSession<'_, Os>)

Called when the event loop is interrupted by a signal.

impl<Driver> VmiOs for WindowsOs<Driver>

where Driver: VmiRead, <Driver as VmiDriver>::Architecture: ArchAdapter<Driver>,

fn kpti_enabled(vmi: VmiState<'_, WindowsOs<Driver>>) -> Result<bool, VmiError>

Checks if Kernel Virtual Address Shadow (KVA Shadow) is enabled.

KVA Shadow is a security feature introduced in Windows 10 that mitigates Meltdown and Spectre vulnerabilities by isolating kernel memory from user-mode processes.

Notes

This value is cached after the first read.

Implementation Details

Corresponds to KiKvaShadow symbol.

fn modules<'a>( vmi: VmiState<'a, WindowsOs<Driver>>, ) -> Result<impl Iterator<Item = Result<<WindowsOs<Driver> as VmiOs>::Module<'a>, VmiError>> + use<'a, Driver>, VmiError>

Returns an iterator over all loaded Windows Driver modules.

This method returns an iterator over all loaded Windows Driver modules. It reads the PsLoadedModuleList symbol from the kernel image and iterates over the linked list of KLDR_DATA_TABLE_ENTRY structures representing each loaded module.

fn processes<'a>( vmi: VmiState<'a, WindowsOs<Driver>>, ) -> Result<impl Iterator<Item = Result<<WindowsOs<Driver> as VmiOs>::Process<'a>, VmiError>> + use<'a, Driver>, VmiError>

Returns an iterator over all Windows processes.

This method returns an iterator over all Windows processes. It reads the PsActiveProcessHead symbol from the kernel image and iterates over the linked list of EPROCESS structures representing each process.

fn current_process( vmi: VmiState<'_, WindowsOs<Driver>>, ) -> Result<<WindowsOs<Driver> as VmiOs>::Process<'_>, VmiError>

Returns the current process.

fn system_process( vmi: VmiState<'_, WindowsOs<Driver>>, ) -> Result<<WindowsOs<Driver> as VmiOs>::Process<'_>, VmiError>

Returns the system process.

The system process is the first process created by the Windows kernel during system initialization. It is the parent process of all other processes in the system.

fn current_thread( vmi: VmiState<'_, WindowsOs<Driver>>, ) -> Result<<WindowsOs<Driver> as VmiOs>::Thread<'_>, VmiError>

Returns the current thread.

type Architecture = <Driver as VmiDriver>::Architecture

The architecture.

type Driver = Driver

The driver.

type Process<'a> = WindowsProcess<'a, Driver>

The process type.

type Thread<'a> = WindowsThread<'a, Driver>

The thread type.

type Image<'a> = WindowsImage<'a, Driver>

The image type.

type Module<'a> = WindowsModule<'a, Driver>

The kernel module type.

type UserModule<'a> = WindowsUserModule<'a, Driver>

The user-mode module type.

type Region<'a> = WindowsRegion<'a, Driver>

The memory region type.

type Mapped<'a> = WindowsControlArea<'a, Driver>

The memory mapped region type.

fn kernel_image_base( vmi: VmiState<'_, WindowsOs<Driver>>, ) -> Result<Va, VmiError>

Retrieves the base address of the kernel image.

fn kernel_information_string( vmi: VmiState<'_, WindowsOs<Driver>>, ) -> Result<String, VmiError>

Retrieves an implementation-specific string containing kernel information.

fn process( vmi: VmiState<'_, WindowsOs<Driver>>, process: ProcessObject, ) -> Result<<WindowsOs<Driver> as VmiOs>::Process<'_>, VmiError>

Returns the process corresponding to the given process object.

fn thread( vmi: VmiState<'_, WindowsOs<Driver>>, thread: ThreadObject, ) -> Result<<WindowsOs<Driver> as VmiOs>::Thread<'_>, VmiError>

Returns the thread corresponding to the given thread object.

fn image( vmi: VmiState<'_, WindowsOs<Driver>>, image_base: Va, ) -> Result<<WindowsOs<Driver> as VmiOs>::Image<'_>, VmiError>

Returns the image corresponding to the given base address.

fn module( vmi: VmiState<'_, WindowsOs<Driver>>, module: Va, ) -> Result<<WindowsOs<Driver> as VmiOs>::Module<'_>, VmiError>

Returns the kernel module corresponding to the given base address.

fn user_module( vmi: VmiState<'_, WindowsOs<Driver>>, module: Va, root: Pa, ) -> Result<<WindowsOs<Driver> as VmiOs>::UserModule<'_>, VmiError>

Returns the user-mode module corresponding to the given base address.

fn region( vmi: VmiState<'_, WindowsOs<Driver>>, region: Va, ) -> Result<<WindowsOs<Driver> as VmiOs>::Region<'_>, VmiError>

Returns the memory region corresponding to the given address.

fn syscall_argument( vmi: VmiState<'_, WindowsOs<Driver>>, index: u64, ) -> Result<u64, VmiError>

Retrieves a specific syscall argument according to the system call ABI.

fn function_argument( vmi: VmiState<'_, WindowsOs<Driver>>, index: u64, ) -> Result<u64, VmiError>

Retrieves a specific function argument according to the calling convention of the operating system.

fn function_return_value( vmi: VmiState<'_, WindowsOs<Driver>>, ) -> Result<u64, VmiError>

Retrieves the return value of a function.

fn last_error( vmi: VmiState<'_, WindowsOs<Driver>>, ) -> Result<Option<u32>, VmiError>

Retrieves the last error value.