Struct WindowsProcess 

pub struct WindowsProcess<'a, Driver>
where
    Driver: VmiRead,
    <Driver as VmiDriver>::Architecture: ArchAdapter<Driver>,
{ /* private fields */ }

Available on crate feature os-windows only.

A Windows process.

A process in Windows is represented by the _EPROCESS structure, which contains metadata about its execution state, memory layout, and handles.

Implementation Details

Corresponds to _EPROCESS.

Implementations

impl<'a, Driver> WindowsProcess<'a, Driver>

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

pub fn new( vmi: VmiState<'a, WindowsOs<Driver>>, process: ProcessObject, ) -> WindowsProcess<'a, Driver>

Creates a new Windows process.

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

Returns the creation time of the process.

Implementation Details

Corresponds to _EPROCESS.CreateTime.

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

Returns the exit time of the process.

Implementation Details

Corresponds to _EPROCESS.ExitTime.

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

Checks if the process is a WoW64 process.

Implementation Details

Corresponds to _EPROCESS.WoW64Process != NULL.

pub fn peb(&self) -> Result<Option<WindowsPeb<'a, Driver>>, VmiError>

Returns the process environment block (PEB).

Implementation Details

The function first reads the _EPROCESS.WoW64Process field to determine if the process is a 32-bit process. If the field is NULL, the process is 64-bit. Otherwise, the function reads the _EWOW64PROCESS.Peb field to get the 32-bit PEB.

Examples found in repository

examples/windows-dump.rs (line 321)

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

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

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

pub fn native_peb(&self) -> Result<Option<WindowsPeb<'a, Driver>>, VmiError>

Returns the native process environment block (PEB).

Implementation Details

Corresponds to _EPROCESS.Peb.

pub fn session(&self) -> Result<Option<WindowsSession<'a, Driver>>, VmiError>

Returns the session of the process.

Examples found in repository

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

fn match_lsass<Driver>(process: &WindowsProcess<Driver>) -> Result<bool, VmiError>
where
    Driver: VmiRead,
    Driver::Architecture: ArchAdapter<Driver>,
{
    // Match "lsass.exe" in SessionId 0.
    Ok(
        matches!(process.session()?, Some(session) if session.id()? == 0)
            && process.name()?.eq_ignore_ascii_case("lsass.exe"),
    )
}

examples/windows-dump.rs (line 369)

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

pub fn token(&self) -> Result<WindowsToken<'a, Driver>, VmiError>

Returns the primary access token of the process.

Implementation Details

Corresponds to _EPROCESS.Token (with reference count masked out).

pub fn handle_table( &self, ) -> Result<Option<WindowsHandleTable<'a, Driver>>, VmiError>

Returns the handle table of the process.

Implementation Details

Corresponds to _EPROCESS.ObjectTable.

Examples found in repository

examples/windows-dump.rs (line 186)

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

pub fn lookup_object<T>(&self, handle: u64) -> Result<Option<T>, VmiError>

where T: FromWindowsObject<'a, Driver>,

Looks up the object associated with the given handle and attempts to convert it to the specified type.

Resolves a handle value through the process handle table and converts the resulting WindowsObject using the FromWindowsObject trait.

Returns Ok(None) if the handle table is unavailable, the handle is invalid, the entry has no associated object, or the object is not of the requested type.

Examples

// Look up the raw object.
let object = process.lookup_object::<WindowsObject<_>>(handle)?;

// Look up and convert to a specific type.
let process = current_process.lookup_object::<WindowsProcess<_>>(handle)?;
let file = current_process.lookup_object::<WindowsFileObject<_>>(handle)?;

Examples found in repository

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

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

examples/windows-reactor/ntoskrnl.rs (line 43)

pub fn NtWriteFile<Driver>(
    vmi: &VmiContext<WindowsOs<Driver>>,
) -> Result<Action<<WindowsOs<Driver> as VmiOs>::Architecture>, VmiError>
where
    Driver: VmiRead,
    Driver::Architecture: ArchAdapter<Driver>,
{
    //
    // NTSTATUS
    // NTAPI
    // 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)?;

    // Check if we have to look for the object in the kernel handle table
    // or the current process handle table.
    let owning_process = match vmi.os().is_kernel_handle(FileHandle)? {
        true => vmi.os().system_process()?,
        false => vmi.os().current_process()?,
    };

    let file_object = match owning_process.lookup_object::<WindowsFileObject<_>>(FileHandle)? {
        Some(file_object) => file_object,
        None => {
            tracing::error!(handle = %Hex(FileHandle), "cannot find file object");
            return Ok(Action::default());
        }
    };

    let path = file_object.full_path()?;
    tracing::info!(handle = %Hex(FileHandle), path);

    Ok(Action::default())
}

pub fn vad_root(&self) -> Result<Option<WindowsRegion<'a, Driver>>, VmiError>

Returns the root of the virtual address descriptor (VAD) tree.

Implementation Details

Corresponds to _EPROCESS.VadRoot->BalancedRoot for Windows 7 and _EPROCESS.VadRoot->Root for Windows 8.1 and later.

pub fn vad_hint(&self) -> Result<Option<WindowsRegion<'a, Driver>>, VmiError>

Returns the VAD hint node.

The VAD hint is an optimization used by Windows to speed up VAD lookups. This method returns the address of the hint node in the VAD tree.

Implementation Details

Corresponds to _EPROCESS.VadRoot->NodeHint for Windows 7 and _EPROCESS.VadRoot->Hint for Windows 8.1 and later.

Trait Implementations

impl<'a, Driver> From<WindowsProcess<'a, Driver>> for WindowsObject<'a, Driver>

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

fn from(value: WindowsProcess<'a, Driver>) -> WindowsObject<'a, Driver>

Converts to this type from the input type.

impl<'a, Driver> FromWindowsObject<'a, Driver> for WindowsProcess<'a, Driver>

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

fn from_object( object: WindowsObject<'a, Driver>, ) -> Result<Option<WindowsProcess<'a, Driver>>, VmiError>

Attempts to convert a WindowsObject into a specific object type.

impl<'a, Driver> VmiOsProcess<'a, Driver> for WindowsProcess<'a, Driver>

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

fn id(&self) -> Result<ProcessId, VmiError>

Returns the process ID.

Implementation Details

Corresponds to _EPROCESS.UniqueProcessId.

fn object(&self) -> Result<ProcessObject, VmiError>

Returns the process object.

fn name(&self) -> Result<String, VmiError>

Returns the name of the process.

Implementation Details

Corresponds to _EPROCESS.ImageFileName.

fn parent_id(&self) -> Result<ProcessId, VmiError>

Returns the parent process ID.

Implementation Details

Corresponds to _EPROCESS.InheritedFromUniqueProcessId.

fn architecture(&self) -> Result<VmiOsImageArchitecture, VmiError>

Returns the architecture of the process.

Implementation Details

The function reads the _EPROCESS.WoW64Process field to determine if the process is a 32-bit process. If the field is NULL, the process is 64-bit. Otherwise, the process is 32-bit.

fn translation_root(&self) -> Result<Pa, VmiError>

Returns the process’s page table translation root.

Implementation Details

Corresponds to _KPROCESS.DirectoryTableBase.

fn user_translation_root(&self) -> Result<Pa, VmiError>

Returns the user-mode page table translation root.

If KPTI is disabled, this function will return the same value as translation_root.

Implementation Details

Corresponds to _KPROCESS.UserDirectoryTableBase.

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

Returns the base address of the process image.

Implementation Details

Corresponds to _EPROCESS.SectionBaseAddress.

fn regions( &self, ) -> Result<impl Iterator<Item = Result<WindowsRegion<'a, Driver>, VmiError>> + use<'a, Driver>, VmiError>

Returns an iterator over the process’s memory regions (VADs).

Implementation Details

The function iterates over the VAD tree of the process.

fn lookup_region( &self, address: Va, ) -> Result<Option<WindowsRegion<'a, Driver>>, VmiError>

Returns the memory region (VAD) containing the given address.

Searches the VAD tree to find the VAD node that covers the given virtual address within the process’s address space. Returns None if no VAD covers the address.

Implementation Details

The functionality is similar to the Windows kernel’s internal MiLocateAddress() function.

fn threads( &self, ) -> Result<impl Iterator<Item = Result<<<WindowsProcess<'a, Driver> as VmiOsProcess<'a, Driver>>::Os as VmiOs>::Thread<'a>, VmiError>> + use<'a, Driver>, VmiError>

Returns an iterator over the threads in the process.

Notes

Both _EPROCESS and _KPROCESS structures contain the same list of threads.

Implementation Details

Corresponds to _EPROCESS.ThreadListHead.

fn is_valid_address(&self, address: Va) -> Result<Option<bool>, VmiError>

Checks whether the given virtual address is valid in the process.

This method checks if page-faulting on the address would result in a successful access.

type Os = WindowsOs<Driver>

The VMI OS type.

impl<Driver> VmiVa for WindowsProcess<'_, Driver>

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

fn va(&self) -> Va

Returns the virtual address.