Struct VmiOsSessionProber

pub struct VmiOsSessionProber<'a, Driver, Os>(/* private fields */)
where
    Driver: VmiDriver,
    Os: VmiOs<Driver>;

Wrapper providing access to OS-specific operations with page fault handling.

Implementations

impl<Driver, Os> VmiOsSessionProber<'_, Driver, Os>

where Driver: VmiDriver, Os: VmiOs<Driver>,

pub fn kernel_image_base( &self, registers: &<Driver::Architecture as Architecture>::Registers, ) -> Result<Option<Va>, VmiError>

Retrieves the base address of the kernel image.

The kernel image base address is usually found using some special CPU register - for example, a register that contains the address of the system call handler. Such register is set by the operating system during boot and is left unchanged (unless some rootkits are involved).

Therefore, this function can accept the CPU registers from any point of the VM execution (except for the early boot stage).

For catching the exact moment when the kernel image base address is set, you can monitor the MSR_LSTAR register (on AMD64) for writes.

Architecture-specific

• AMD64: The kernel image base address is usually found using the MSR_LSTAR register.

Notes

A malicious code (such as a rootkit) could modify values of the registers, so the returned value might not be accurate.

pub fn kernel_information_string( &self, registers: &<Driver::Architecture as Architecture>::Registers, ) -> Result<Option<String>, VmiError>

Retrieves an implementation-specific string containing kernel information.

Platform-specific

• Windows: Retrieves the NtBuildLab string from the kernel image.
• Linux: Retrieves the linux_banner string from the kernel image.

pub fn kpti_enabled( &self, registers: &<Driver::Architecture as Architecture>::Registers, ) -> Result<Option<bool>, VmiError>

Checks if Kernel Page Table Isolation (KPTI) is enabled.

pub fn system_process( &self, registers: &<Driver::Architecture as Architecture>::Registers, ) -> Result<Option<ProcessObject>, VmiError>

Retrieves the system process object.

The system process is the first process created by the kernel.

Platform-specific

• Windows: Retrieves the PsInitialSystemProcess global variable.
• Linux: Retrieves the init_task global variable.

pub fn thread_id( &self, registers: &<Driver::Architecture as Architecture>::Registers, thread: ThreadObject, ) -> Result<Option<ThreadId>, VmiError>

Retrieves the thread ID for a given thread object.

pub fn process_id( &self, registers: &<Driver::Architecture as Architecture>::Registers, process: ProcessObject, ) -> Result<Option<ProcessId>, VmiError>

Retrieves the process ID for a given process object.

pub fn current_thread( &self, registers: &<Driver::Architecture as Architecture>::Registers, ) -> Result<Option<ThreadObject>, VmiError>

Retrieves the current thread object.

pub fn current_thread_id( &self, registers: &<Driver::Architecture as Architecture>::Registers, ) -> Result<Option<ThreadId>, VmiError>

Retrieves the current thread ID.

pub fn current_process( &self, registers: &<Driver::Architecture as Architecture>::Registers, ) -> Result<Option<ProcessObject>, VmiError>

Retrieves the current process object.

pub fn current_process_id( &self, registers: &<Driver::Architecture as Architecture>::Registers, ) -> Result<Option<ProcessId>, VmiError>

Retrieves the current process ID.

pub fn processes( &self, registers: &<Driver::Architecture as Architecture>::Registers, ) -> Result<Option<Vec<OsProcess>>, VmiError>

Retrieves a list of all processes in the system.

pub fn process_parent_process_id( &self, registers: &<Driver::Architecture as Architecture>::Registers, process: ProcessObject, ) -> Result<Option<ProcessId>, VmiError>

Retrieves the parent process ID for a given process object.

pub fn process_architecture( &self, registers: &<Driver::Architecture as Architecture>::Registers, process: ProcessObject, ) -> Result<Option<OsArchitecture>, VmiError>

Retrieves the architecture of a given process.

pub fn process_translation_root( &self, registers: &<Driver::Architecture as Architecture>::Registers, process: ProcessObject, ) -> Result<Option<Pa>, VmiError>

Retrieves the translation root for a given process.

The translation root is the root of the page table hierarchy (also known as the Directory Table Base (DTB) or Page Global Directory (PGD)).

Architecture-specific

• AMD64: The translation root corresponds with the CR3 register and PML4 table.

Platform-specific

• Windows: Retrieves the DirectoryTableBase field from the KPROCESS structure.
• Linux: Retrieves the mm->pgd field from the task_struct.

pub fn process_user_translation_root( &self, registers: &<Driver::Architecture as Architecture>::Registers, process: ProcessObject, ) -> Result<Option<Pa>, VmiError>

Retrieves the base address of the user translation root for a given process.

If KPTI is disabled, this function will return the same value as VmiOs::process_translation_root.

pub fn process_filename( &self, registers: &<Driver::Architecture as Architecture>::Registers, process: ProcessObject, ) -> Result<Option<String>, VmiError>

Retrieves the filename of a given process.

pub fn process_image_base( &self, registers: &<Driver::Architecture as Architecture>::Registers, process: ProcessObject, ) -> Result<Option<Va>, VmiError>

Retrieves the base address of the process image.

pub fn process_regions( &self, registers: &<Driver::Architecture as Architecture>::Registers, process: ProcessObject, ) -> Result<Option<Vec<OsRegion>>, VmiError>

Retrieves a list of memory regions for a given process.

pub fn process_address_is_valid( &self, registers: &<Driver::Architecture as Architecture>::Registers, process: ProcessObject, address: Va, ) -> Result<Option<Option<bool>>, VmiError>

Checks if a given virtual address is valid in a given process.

pub fn find_process_region( &self, registers: &<Driver::Architecture as Architecture>::Registers, process: ProcessObject, address: Va, ) -> Result<Option<Option<OsRegion>>, VmiError>

Finds a specific memory region in a process given an address.

pub fn image_architecture( &self, registers: &<Driver::Architecture as Architecture>::Registers, image_base: Va, ) -> Result<Option<OsArchitecture>, VmiError>

Retrieves the architecture of an image at a given base address.

pub fn image_exported_symbols( &self, registers: &<Driver::Architecture as Architecture>::Registers, image_base: Va, ) -> Result<Option<Vec<OsImageExportedSymbol>>, VmiError>

Retrieves a list of exported symbols from an image at a given base address.

pub fn syscall_argument( &self, registers: &<Driver::Architecture as Architecture>::Registers, index: u64, ) -> Result<Option<u64>, VmiError>

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

This function assumes that it is called in the prologue of the system call handler, i.e., the instruction pointer is pointing to the first instruction of the function.

pub fn function_argument( &self, registers: &<Driver::Architecture as Architecture>::Registers, index: u64, ) -> Result<Option<u64>, VmiError>

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

This function assumes that it is called in the function prologue, i.e., the instruction pointer is pointing to the first instruction of the function.

Platform-specific

• Windows: Assumes that the function is using the stdcall calling convention.

pub fn function_return_value( &self, registers: &<Driver::Architecture as Architecture>::Registers, ) -> Result<Option<u64>, VmiError>

Retrieves the return value of a function.

This function assumes that it is called immediately after the function returns.

pub fn last_error( &self, registers: &<Driver::Architecture as Architecture>::Registers, ) -> Result<Option<Option<u32>>, VmiError>

Retrieves the last error value.

Platform-specific

• Windows: Retrieves the value of the NtCurrentTeb()->LastErrorValue field.
  • See also: WindowsOs::last_status()

impl<Driver, Os> VmiOsSessionProber<'_, Driver, Os>

where Driver: VmiDriver, Os: VmiOs<Driver>,

pub fn core(&self) -> &VmiSessionProber<'_, Driver, Os>

Returns the VMI session prober.

pub fn underlying_os(&self) -> &Os

Returns the underlying OS-specific implementation.