Struct PageTableMonitor 

pub struct PageTableMonitor<Driver, Tag = &'static str>
where
    Driver: VmiRead + VmiSetProtection,
    <Driver as VmiDriver>::Architecture: ArchAdapter<Driver, Tag>,
    Tag: TagType,
{ /* private fields */ }

Available on crate features ptm and utils only.

Architecture-independent page table monitor.

Thin wrapper that delegates to an architecture-specific implementation selected via ArchAdapter.

Implementations

impl<Driver, Tag> PageTableMonitor<Driver, Tag>

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

pub fn new() -> PageTableMonitor<Driver, Tag>

Creates a new page table monitor.

Examples found in repository

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

    pub fn new(
        session: &VmiSession<WindowsOs<Driver>>,
        profile: &Profile,
        terminate_flag: Arc<AtomicBool>,
    ) -> Result<Self, VmiError> {
        // Capture the current state of the vCPU and get the base address of
        // the kernel.
        //
        // This base address is essential to correctly offset monitored
        // functions.
        //
        // NOTE: `kernel_image_base` tries to find the kernel in the memory
        //       with the help of the CPU registers. On AMD64 architecture,
        //       the kernel image base 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 image base.
        let registers = session.registers(VcpuId(0))?;
        let vmi = session.with_registers(&registers);

        let kernel_image_base = vmi.os().kernel_image_base()?;
        tracing::info!(%kernel_image_base);

        // Get the system process.
        //
        // The system process is the first process created by the kernel.
        // In Windows, it is referenced by the kernel symbol `PsInitialSystemProcess`.
        // To monitor page table entries, we need to locate the translation root
        // of this process.
        let system_process = vmi.os().system_process()?;
        tracing::info!(system_process = %system_process.object()?);

        // Get the translation root of the system process.
        // This is effectively "the CR3 of the kernel".
        //
        // The translation root is the root of the page table hierarchy (also
        // known as the Directory Table Base or PML4).
        let root = system_process.translation_root()?;
        tracing::info!(%root);

        // Load the symbols from the profile.
        let symbols = Symbols::new(profile)?;

        // Enable monitoring of the INT3 and singlestep events.
        //
        // INT3 is used to monitor the execution of specific functions.
        // Singlestep is used to monitor the modifications of page table
        // entries.
        vmi.monitor_enable(EventMonitor::Interrupt(ExceptionVector::Breakpoint))?;
        vmi.monitor_enable(EventMonitor::Singlestep)?;

        // Create a new view for the monitor.
        // This view is used for monitoring function calls and memory accesses.
        let view = vmi.create_view(MemoryAccess::RWX)?;
        vmi.switch_to_view(view)?;

        // Create a new breakpoint controller.
        //
        // The breakpoint controller is used to insert breakpoints for specific
        // functions.
        //
        // From the guest's perspective, these breakpoints are "hidden", since
        // the breakpoint controller will unset the read/write access to the
        // physical memory page where the breakpoint is inserted, while keeping
        // the execute access.
        //
        // This way, the guest will be able to execute the code, but attempts to
        // read or write the memory will trigger the `memory_access` callback.
        //
        // When a vCPU tries to execute the breakpoint instruction:
        // - an `interrupt` callback will be triggered
        // - the breakpoint will be handled (e.g., log the function call)
        // - a fast-singlestep[1] will be performed over the INT3 instruction
        //
        // When a vCPU tries to read from this page (e.g., a PatchGuard check):
        // - `memory_access` callback will be triggered (with the `MemoryAccess::R`
        //   access type)
        // - fast-singlestep[1] will be performed over the instruction that tried to
        //   read the memory
        //
        // This way, the instruction will read the original memory content.
        //
        // [1] Fast-singlestep is a VMI feature that allows to switch the vCPU
        //     to a different view, execute a single instruction, and then
        //     switch back to the original view. In this case, the view is
        //     switched to the `default_view` (which is unmodified).
        let mut bpm = BreakpointManager::new();

        // Create a new page table monitor.
        //
        // The page table monitor is used to monitor the page table entries of
        // the hooked functions.
        //
        // More specifically, it is used to monitor the pages that the breakpoint
        // was inserted into. This is necessary to handle the case when the
        // page containing the breakpoint is paged out (and then paged in
        // again).
        //
        // `PageTableMonitor` works by unsetting the write access to the page
        // tables of the hooked functions. When the page is paged out, the
        // `PRESENT` bit in the page table entry is unset and, conversely, when
        // the page is paged in, the `PRESENT` bit is set again.
        //
        // When that happens:
        // - the `memory_access` callback will be triggered (with the `MemoryAccess::R`
        //   access type)
        // - the callback will mark the page as dirty in the page table monitor
        // - a singlestep will be performed over the instruction that tried to modify
        //   the memory containing the page table entry
        // - the `singlestep` handler will process the dirty page table entries and
        //   inform the breakpoint controller to handle the changes
        let mut ptm = PageTableMonitor::new();

        // Pause the VM to avoid race conditions between inserting breakpoints
        // and monitoring page table entries. The VM resumes when the pause
        // guard is dropped.
        let _pause_guard = vmi.pause_guard()?;

        // Insert breakpoint for the `NtCreateFile` function.
        let va_NtCreateFile = kernel_image_base + symbols.NtCreateFile;
        let cx_NtCreateFile = (va_NtCreateFile, root);
        let bp_NtCreateFile = Breakpoint::new(cx_NtCreateFile, view)
            .global()
            .with_tag("NtCreateFile");
        bpm.insert(&vmi, bp_NtCreateFile)?;
        ptm.monitor(&vmi, cx_NtCreateFile, view, "NtCreateFile")?;
        tracing::info!(%va_NtCreateFile);

        // Insert breakpoint for the `NtWriteFile` function.
        let va_NtWriteFile = kernel_image_base + symbols.NtWriteFile;
        let cx_NtWriteFile = (va_NtWriteFile, root);
        let bp_NtWriteFile = Breakpoint::new(cx_NtWriteFile, view)
            .global()
            .with_tag("NtWriteFile");
        bpm.insert(&vmi, bp_NtWriteFile)?;
        ptm.monitor(&vmi, cx_NtWriteFile, view, "NtWriteFile")?;
        tracing::info!(%va_NtWriteFile);

        // Insert breakpoint for the `PspInsertProcess` function.
        let va_PspInsertProcess = kernel_image_base + symbols.PspInsertProcess;
        let cx_PspInsertProcess = (va_PspInsertProcess, root);
        let bp_PspInsertProcess = Breakpoint::new(cx_PspInsertProcess, view)
            .global()
            .with_tag("PspInsertProcess");
        bpm.insert(&vmi, bp_PspInsertProcess)?;
        ptm.monitor(&vmi, cx_PspInsertProcess, view, "PspInsertProcess")?;

        // Insert breakpoint for the `MmCleanProcessAddressSpace` function.
        let va_MmCleanProcessAddressSpace = kernel_image_base + symbols.MmCleanProcessAddressSpace;
        let cx_MmCleanProcessAddressSpace = (va_MmCleanProcessAddressSpace, root);
        let bp_MmCleanProcessAddressSpace = Breakpoint::new(cx_MmCleanProcessAddressSpace, view)
            .global()
            .with_tag("MmCleanProcessAddressSpace");
        bpm.insert(&vmi, bp_MmCleanProcessAddressSpace)?;
        ptm.monitor(
            &vmi,
            cx_MmCleanProcessAddressSpace,
            view,
            "MmCleanProcessAddressSpace",
        )?;

        Ok(Self {
            terminate_flag,
            view,
            bpm,
            ptm,
        })
    }

pub fn monitored_tables(&self) -> usize

Returns the number of write-protected page table pages.

pub fn monitored_entries(&self) -> usize

Returns the number of monitored entries.

pub fn paged_in_entries(&self) -> usize

Returns the number of monitored addresses currently backed by physical memory.

pub fn dump(&self)

Logs the monitor state for debugging.

pub fn monitor( &mut self, vmi: &VmiCore<Driver>, ctx: impl Into<AddressContext>, view: View, tag: Tag, ) -> Result<(), VmiError>

Begins monitoring a virtual address for page table changes.

Walks the page table hierarchy and write-protects the relevant pages.

Examples found in repository

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

    pub fn new(
        session: &VmiSession<WindowsOs<Driver>>,
        profile: &Profile,
        terminate_flag: Arc<AtomicBool>,
    ) -> Result<Self, VmiError> {
        // Capture the current state of the vCPU and get the base address of
        // the kernel.
        //
        // This base address is essential to correctly offset monitored
        // functions.
        //
        // NOTE: `kernel_image_base` tries to find the kernel in the memory
        //       with the help of the CPU registers. On AMD64 architecture,
        //       the kernel image base 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 image base.
        let registers = session.registers(VcpuId(0))?;
        let vmi = session.with_registers(&registers);

        let kernel_image_base = vmi.os().kernel_image_base()?;
        tracing::info!(%kernel_image_base);

        // Get the system process.
        //
        // The system process is the first process created by the kernel.
        // In Windows, it is referenced by the kernel symbol `PsInitialSystemProcess`.
        // To monitor page table entries, we need to locate the translation root
        // of this process.
        let system_process = vmi.os().system_process()?;
        tracing::info!(system_process = %system_process.object()?);

        // Get the translation root of the system process.
        // This is effectively "the CR3 of the kernel".
        //
        // The translation root is the root of the page table hierarchy (also
        // known as the Directory Table Base or PML4).
        let root = system_process.translation_root()?;
        tracing::info!(%root);

        // Load the symbols from the profile.
        let symbols = Symbols::new(profile)?;

        // Enable monitoring of the INT3 and singlestep events.
        //
        // INT3 is used to monitor the execution of specific functions.
        // Singlestep is used to monitor the modifications of page table
        // entries.
        vmi.monitor_enable(EventMonitor::Interrupt(ExceptionVector::Breakpoint))?;
        vmi.monitor_enable(EventMonitor::Singlestep)?;

        // Create a new view for the monitor.
        // This view is used for monitoring function calls and memory accesses.
        let view = vmi.create_view(MemoryAccess::RWX)?;
        vmi.switch_to_view(view)?;

        // Create a new breakpoint controller.
        //
        // The breakpoint controller is used to insert breakpoints for specific
        // functions.
        //
        // From the guest's perspective, these breakpoints are "hidden", since
        // the breakpoint controller will unset the read/write access to the
        // physical memory page where the breakpoint is inserted, while keeping
        // the execute access.
        //
        // This way, the guest will be able to execute the code, but attempts to
        // read or write the memory will trigger the `memory_access` callback.
        //
        // When a vCPU tries to execute the breakpoint instruction:
        // - an `interrupt` callback will be triggered
        // - the breakpoint will be handled (e.g., log the function call)
        // - a fast-singlestep[1] will be performed over the INT3 instruction
        //
        // When a vCPU tries to read from this page (e.g., a PatchGuard check):
        // - `memory_access` callback will be triggered (with the `MemoryAccess::R`
        //   access type)
        // - fast-singlestep[1] will be performed over the instruction that tried to
        //   read the memory
        //
        // This way, the instruction will read the original memory content.
        //
        // [1] Fast-singlestep is a VMI feature that allows to switch the vCPU
        //     to a different view, execute a single instruction, and then
        //     switch back to the original view. In this case, the view is
        //     switched to the `default_view` (which is unmodified).
        let mut bpm = BreakpointManager::new();

        // Create a new page table monitor.
        //
        // The page table monitor is used to monitor the page table entries of
        // the hooked functions.
        //
        // More specifically, it is used to monitor the pages that the breakpoint
        // was inserted into. This is necessary to handle the case when the
        // page containing the breakpoint is paged out (and then paged in
        // again).
        //
        // `PageTableMonitor` works by unsetting the write access to the page
        // tables of the hooked functions. When the page is paged out, the
        // `PRESENT` bit in the page table entry is unset and, conversely, when
        // the page is paged in, the `PRESENT` bit is set again.
        //
        // When that happens:
        // - the `memory_access` callback will be triggered (with the `MemoryAccess::R`
        //   access type)
        // - the callback will mark the page as dirty in the page table monitor
        // - a singlestep will be performed over the instruction that tried to modify
        //   the memory containing the page table entry
        // - the `singlestep` handler will process the dirty page table entries and
        //   inform the breakpoint controller to handle the changes
        let mut ptm = PageTableMonitor::new();

        // Pause the VM to avoid race conditions between inserting breakpoints
        // and monitoring page table entries. The VM resumes when the pause
        // guard is dropped.
        let _pause_guard = vmi.pause_guard()?;

        // Insert breakpoint for the `NtCreateFile` function.
        let va_NtCreateFile = kernel_image_base + symbols.NtCreateFile;
        let cx_NtCreateFile = (va_NtCreateFile, root);
        let bp_NtCreateFile = Breakpoint::new(cx_NtCreateFile, view)
            .global()
            .with_tag("NtCreateFile");
        bpm.insert(&vmi, bp_NtCreateFile)?;
        ptm.monitor(&vmi, cx_NtCreateFile, view, "NtCreateFile")?;
        tracing::info!(%va_NtCreateFile);

        // Insert breakpoint for the `NtWriteFile` function.
        let va_NtWriteFile = kernel_image_base + symbols.NtWriteFile;
        let cx_NtWriteFile = (va_NtWriteFile, root);
        let bp_NtWriteFile = Breakpoint::new(cx_NtWriteFile, view)
            .global()
            .with_tag("NtWriteFile");
        bpm.insert(&vmi, bp_NtWriteFile)?;
        ptm.monitor(&vmi, cx_NtWriteFile, view, "NtWriteFile")?;
        tracing::info!(%va_NtWriteFile);

        // Insert breakpoint for the `PspInsertProcess` function.
        let va_PspInsertProcess = kernel_image_base + symbols.PspInsertProcess;
        let cx_PspInsertProcess = (va_PspInsertProcess, root);
        let bp_PspInsertProcess = Breakpoint::new(cx_PspInsertProcess, view)
            .global()
            .with_tag("PspInsertProcess");
        bpm.insert(&vmi, bp_PspInsertProcess)?;
        ptm.monitor(&vmi, cx_PspInsertProcess, view, "PspInsertProcess")?;

        // Insert breakpoint for the `MmCleanProcessAddressSpace` function.
        let va_MmCleanProcessAddressSpace = kernel_image_base + symbols.MmCleanProcessAddressSpace;
        let cx_MmCleanProcessAddressSpace = (va_MmCleanProcessAddressSpace, root);
        let bp_MmCleanProcessAddressSpace = Breakpoint::new(cx_MmCleanProcessAddressSpace, view)
            .global()
            .with_tag("MmCleanProcessAddressSpace");
        bpm.insert(&vmi, bp_MmCleanProcessAddressSpace)?;
        ptm.monitor(
            &vmi,
            cx_MmCleanProcessAddressSpace,
            view,
            "MmCleanProcessAddressSpace",
        )?;

        Ok(Self {
            terminate_flag,
            view,
            bpm,
            ptm,
        })
    }

pub fn unmonitor( &mut self, vmi: &VmiCore<Driver>, ctx: impl Into<AddressContext>, view: View, ) -> Result<(), VmiError>

Stops monitoring a virtual address.

Removes write protection from page table pages that no longer have any monitored entries.

pub fn unmonitor_all(&mut self, vmi: &VmiCore<Driver>)

Stops monitoring all virtual addresses and restores memory access.

pub fn unmonitor_view(&mut self, vmi: &VmiCore<Driver>, view: View)

Stops monitoring all virtual addresses associated with a view.

pub fn mark_dirty_entry( &mut self, entry_pa: Pa, view: View, vcpu_id: VcpuId, ) -> bool

Marks a page table entry as dirty after a write to a monitored page.

Returns true if the entry is being monitored (and was marked), false otherwise.

Examples found in repository

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

    fn memory_access(
        &mut self,
        vmi: &VmiContext<WindowsOs<Driver>>,
    ) -> Result<VmiEventResponse<Amd64>, VmiError> {
        let memory_access = vmi.event().reason().as_memory_access();

        tracing::trace!(
            pa = %memory_access.pa,
            va = %memory_access.va,
            access = %memory_access.access,
        );

        if memory_access.access.contains(MemoryAccess::W) {
            // It is assumed that a write memory access event is caused by a
            // page table modification.
            //
            // The page table entry is marked as dirty in the page table monitor
            // and a singlestep is performed to process the dirty entries.
            self.ptm
                .mark_dirty_entry(memory_access.pa, self.view, vmi.event().vcpu_id());

            Ok(VmiEventResponse::singlestep().with_view(vmi.default_view()))
        }
        else if memory_access.access.contains(MemoryAccess::R) {
            // When the guest tries to read from the memory, a fast-singlestep
            // is performed over the instruction that tried to read the memory.
            // This is done to allow the instruction to read the original memory
            // content.
            Ok(VmiEventResponse::fast_singlestep(vmi.default_view()))
        }
        else {
            panic!("Unhandled memory access: {memory_access:?}");
        }
    }

pub fn process_dirty_entries( &mut self, vmi: &VmiCore<Driver>, vcpu_id: VcpuId, ) -> Result<Vec<PageTableMonitorEvent>, VmiError>

Processes dirty entries for a vCPU, returning page-in/page-out events.

Should be called after singlestepping past the write that triggered the dirty marking, so the new PTE value is committed to memory.

Examples found in repository

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

    fn singlestep(
        &mut self,
        vmi: &VmiContext<WindowsOs<Driver>>,
    ) -> Result<VmiEventResponse<Amd64>, VmiError> {
        // Get the page table modifications by processing the dirty page table
        // entries.
        let ptm_events = self.ptm.process_dirty_entries(vmi, vmi.event().vcpu_id())?;

        // Let the breakpoint controller handle the page table modifications.
        self.bpm.handle_ptm_events(vmi, ptm_events)?;

        // Disable singlestep and switch back to our view.
        Ok(VmiEventResponse::default().with_view(self.view))
    }