Struct VmiOsContextProber

pub struct VmiOsContextProber<'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> VmiOsContextProber<'_, Driver, Os>

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

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

Returns the VMI context prober.

pub fn underlying_os(&self) -> &Os

Returns the underlying OS-specific implementation.

pub fn function_argument_for_registers( &self, regs: &<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.

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

Retrieves the return value of a function.

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

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

pub fn kernel_image_base(&self) -> 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) -> 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) -> Result<Option<bool>, VmiError>

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

pub fn system_process(&self) -> 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, thread: ThreadObject, ) -> Result<Option<ThreadId>, VmiError>

Retrieves the thread ID for a given thread object.

pub fn process_id( &self, process: ProcessObject, ) -> Result<Option<ProcessId>, VmiError>

Retrieves the process ID for a given process object.

pub fn current_thread(&self) -> Result<Option<ThreadObject>, VmiError>

Retrieves the current thread object.

pub fn current_thread_id(&self) -> Result<Option<ThreadId>, VmiError>

Retrieves the current thread ID.

pub fn current_process(&self) -> Result<Option<ProcessObject>, VmiError>

Retrieves the current process object.

pub fn current_process_id(&self) -> Result<Option<ProcessId>, VmiError>

Retrieves the current process ID.

pub fn processes(&self) -> Result<Option<Vec<OsProcess>>, VmiError>

Retrieves a list of all processes in the system.

pub fn process_parent_process_id( &self, process: ProcessObject, ) -> Result<Option<ProcessId>, VmiError>

Retrieves the parent process ID for a given process object.

pub fn process_architecture( &self, process: ProcessObject, ) -> Result<Option<OsArchitecture>, VmiError>

Retrieves the architecture of a given process.

pub fn process_translation_root( &self, 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, 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, process: ProcessObject, ) -> Result<Option<String>, VmiError>

Retrieves the filename of a given process.

pub fn process_image_base( &self, process: ProcessObject, ) -> Result<Option<Va>, VmiError>

Retrieves the base address of the process image.

pub fn process_regions( &self, process: ProcessObject, ) -> Result<Option<Vec<OsRegion>>, VmiError>

Retrieves a list of memory regions for a given process.

pub fn process_address_is_valid( &self, 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, 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, image_base: Va, ) -> Result<Option<OsArchitecture>, VmiError>

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

pub fn image_exported_symbols( &self, 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, 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, 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) -> 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) -> 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()