Struct WindowsHandleTable 

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

Available on crate feature os-windows only.

A Windows handle table.

A handle table in Windows tracks handles to kernel objects for a specific process, allowing access control and management.

Implementation Details

Corresponds to _HANDLE_TABLE.

Implementations

impl<'a, Driver> WindowsHandleTable<'a, Driver>

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

pub fn new( vmi: VmiState<'a, WindowsOs<Driver>>, va: Va, ) -> WindowsHandleTable<'a, Driver>

Creates a new Windows module object.

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

Returns the table code of the handle table.

Notes

This value is cached after the first read.

Implementation Details

Corresponds to _HANDLE_TABLE.TableCode.

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

Returns the next handle needing pool.

This value tracks the next handle slot that requires additional pool allocation.

Notes

This value is cached after the first read.

Implementation Details

Corresponds to _HANDLE_TABLE.NextHandleNeedingPool.

pub fn iter( &self, ) -> Result<impl Iterator<Item = Result<(u64, WindowsHandleTableEntry<'a, Driver>), VmiError>> + use<'a, Driver>, VmiError>

Iterates over all handle table entries.

Returns an iterator over all handle table entries that have a valid object pointer. The iterator yields a tuple containing the handle value and the handle table entry.

Implementation Details

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

Examples found in repository

examples/windows-dump.rs (line 199)

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( &self, handle: u64, ) -> Result<Option<WindowsHandleTableEntry<'a, Driver>>, VmiError>

Performs a lookup in the handle table to find the address of a handle table entry.

Implements the multi-level handle table lookup algorithm used by Windows. Returns the virtual address of the handle table entry.

Implementation Details

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

Trait Implementations

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

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

fn va(&self) -> Va

Returns the virtual address.