Struct VmiEvent 

pub struct VmiEvent<Arch>
where
    Arch: Architecture,
{ /* private fields */ }

An event that occurred during VMI.

Implementations

impl<Arch> VmiEvent<Arch>

where Arch: Architecture,

pub fn new( vcpu_id: VcpuId, flags: VmiEventFlags, view: Option<View>, registers: <Arch as Architecture>::Registers, reason: <Arch as Architecture>::EventReason, ) -> VmiEvent<Arch>

Available on crate features utils and injector only.

Creates a new VMI event.

pub fn vcpu_id(&self) -> VcpuId

Available on crate features utils and injector only.

Returns the ID of the virtual CPU where the event occurred.

Examples found in repository

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

    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:?}");
        }
    }

    #[tracing::instrument(skip_all, fields(pid, process))]
    fn interrupt(
        &mut self,
        vmi: &VmiContext<WindowsOs<Driver>>,
    ) -> Result<VmiEventResponse<Amd64>, VmiError> {
        let tag = match self.bpm.get_by_event(vmi.event(), ()) {
            Some(breakpoints) => {
                // Breakpoints can have multiple tags, but we have set only one
                // tag for each breakpoint.
                let first_breakpoint = breakpoints.into_iter().next().expect("breakpoint");
                first_breakpoint.tag()
            }
            None => {
                if BreakpointController::is_breakpoint(vmi, vmi.event())? {
                    // This breakpoint was not set by us. Reinject it.
                    tracing::warn!("Unknown breakpoint, reinjecting");
                    return Ok(VmiEventResponse::reinject_interrupt());
                }
                else {
                    // We have received a breakpoint event, but there is no
                    // breakpoint instruction at the current memory location.
                    // This can happen if the event was triggered by a breakpoint
                    // we just removed.
                    tracing::warn!("Ignoring old breakpoint event");
                    return Ok(VmiEventResponse::fast_singlestep(vmi.default_view()));
                }
            }
        };

        let process = vmi.os().current_process()?;
        let process_id = process.id()?;
        let process_name = process.name()?;
        tracing::Span::current()
            .record("pid", process_id.0)
            .record("process", process_name);

        match tag {
            "NtCreateFile" => self.NtCreateFile(vmi)?,
            "NtWriteFile" => self.NtWriteFile(vmi)?,
            "PspInsertProcess" => self.PspInsertProcess(vmi)?,
            "MmCleanProcessAddressSpace" => self.MmCleanProcessAddressSpace(vmi)?,
            _ => panic!("Unhandled tag: {tag}"),
        }

        Ok(VmiEventResponse::fast_singlestep(vmi.default_view()))
    }

    #[tracing::instrument(skip_all)]
    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))
    }

    #[tracing::instrument(skip_all)]
    fn NtCreateFile(&mut self, vmi: &VmiContext<WindowsOs<Driver>>) -> Result<(), VmiError> {
        //
        // NTSTATUS
        // NtCreateFile (
        //     _Out_ PHANDLE FileHandle,
        //     _In_ ACCESS_MASK DesiredAccess,
        //     _In_ POBJECT_ATTRIBUTES ObjectAttributes,
        //     _Out_ PIO_STATUS_BLOCK IoStatusBlock,
        //     _In_opt_ PLARGE_INTEGER AllocationSize,
        //     _In_ ULONG FileAttributes,
        //     _In_ ULONG ShareAccess,
        //     _In_ ULONG CreateDisposition,
        //     _In_ ULONG CreateOptions,
        //     _In_reads_bytes_opt_(EaLength) PVOID EaBuffer,
        //     _In_ ULONG EaLength
        //     );
        //

        let ObjectAttributes = Va(vmi.os().function_argument(2)?);

        let object_attributes = vmi.os().object_attributes(ObjectAttributes)?;
        let object_name = match object_attributes.object_name()? {
            Some(object_name) => object_name,
            None => {
                tracing::warn!(%ObjectAttributes, "No object name found");
                return Ok(());
            }
        };

        tracing::info!(%object_name);

        Ok(())
    }

    #[tracing::instrument(skip_all)]
    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(())
    }

    #[tracing::instrument(skip_all)]
    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(())
    }

    #[tracing::instrument(skip_all)]
    fn MmCleanProcessAddressSpace(
        &mut self,
        vmi: &VmiContext<WindowsOs<Driver>>,
    ) -> Result<(), VmiError> {
        //
        // VOID
        // MmCleanProcessAddressSpace (
        //     _In_ PEPROCESS Process
        //     );
        //

        let Process = vmi.os().function_argument(0)?;

        let process = vmi.os().process(ProcessObject(Va(Process)))?;
        let process_id = process.id()?;

        let name = process.name()?;
        let image_base = process.image_base()?;

        tracing::info!(%process_id, name, %image_base);

        Ok(())
    }

    fn dispatch(
        &mut self,
        vmi: &VmiContext<WindowsOs<Driver>>,
    ) -> Result<VmiEventResponse<Amd64>, VmiError> {
        let event = vmi.event();
        let result = match event.reason() {
            EventReason::MemoryAccess(_) => self.memory_access(vmi),
            EventReason::Interrupt(_) => self.interrupt(vmi),
            EventReason::Singlestep(_) => self.singlestep(vmi),
            _ => panic!("Unhandled event: {:?}", event.reason()),
        };

        // If VMI tries to read from a page that is not present, it will return
        // a page fault error. In this case, we inject a page fault interrupt
        // to the guest.
        //
        // Once the guest handles the page fault, it will retry to execute the
        // instruction that caused the page fault.
        if let Err(VmiError::Translation(pfs)) = result {
            tracing::warn!(?pfs, "Page fault, injecting");
            vmi.inject_interrupt(event.vcpu_id(), Interrupt::page_fault(pfs[0].va, 0))?;
            return Ok(VmiEventResponse::default());
        }

        result
    }

pub fn flags(&self) -> VmiEventFlags

Available on crate features utils and injector only.

Returns flags associated with the event.

pub fn view(&self) -> Option<View>

Available on crate features utils and injector only.

Returns the view associated with the event, if any.

pub fn registers(&self) -> &<Arch as Architecture>::Registers

Available on crate features utils and injector only.

Returns a reference to the CPU registers at the time of the event.

pub fn reason(&self) -> &<Arch as Architecture>::EventReason

Available on crate features utils and injector only.

Returns a reference to the reason for the event.

Examples found in repository

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

    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:?}");
        }
    }

    #[tracing::instrument(skip_all, fields(pid, process))]
    fn interrupt(
        &mut self,
        vmi: &VmiContext<WindowsOs<Driver>>,
    ) -> Result<VmiEventResponse<Amd64>, VmiError> {
        let tag = match self.bpm.get_by_event(vmi.event(), ()) {
            Some(breakpoints) => {
                // Breakpoints can have multiple tags, but we have set only one
                // tag for each breakpoint.
                let first_breakpoint = breakpoints.into_iter().next().expect("breakpoint");
                first_breakpoint.tag()
            }
            None => {
                if BreakpointController::is_breakpoint(vmi, vmi.event())? {
                    // This breakpoint was not set by us. Reinject it.
                    tracing::warn!("Unknown breakpoint, reinjecting");
                    return Ok(VmiEventResponse::reinject_interrupt());
                }
                else {
                    // We have received a breakpoint event, but there is no
                    // breakpoint instruction at the current memory location.
                    // This can happen if the event was triggered by a breakpoint
                    // we just removed.
                    tracing::warn!("Ignoring old breakpoint event");
                    return Ok(VmiEventResponse::fast_singlestep(vmi.default_view()));
                }
            }
        };

        let process = vmi.os().current_process()?;
        let process_id = process.id()?;
        let process_name = process.name()?;
        tracing::Span::current()
            .record("pid", process_id.0)
            .record("process", process_name);

        match tag {
            "NtCreateFile" => self.NtCreateFile(vmi)?,
            "NtWriteFile" => self.NtWriteFile(vmi)?,
            "PspInsertProcess" => self.PspInsertProcess(vmi)?,
            "MmCleanProcessAddressSpace" => self.MmCleanProcessAddressSpace(vmi)?,
            _ => panic!("Unhandled tag: {tag}"),
        }

        Ok(VmiEventResponse::fast_singlestep(vmi.default_view()))
    }

    #[tracing::instrument(skip_all)]
    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))
    }

    #[tracing::instrument(skip_all)]
    fn NtCreateFile(&mut self, vmi: &VmiContext<WindowsOs<Driver>>) -> Result<(), VmiError> {
        //
        // NTSTATUS
        // NtCreateFile (
        //     _Out_ PHANDLE FileHandle,
        //     _In_ ACCESS_MASK DesiredAccess,
        //     _In_ POBJECT_ATTRIBUTES ObjectAttributes,
        //     _Out_ PIO_STATUS_BLOCK IoStatusBlock,
        //     _In_opt_ PLARGE_INTEGER AllocationSize,
        //     _In_ ULONG FileAttributes,
        //     _In_ ULONG ShareAccess,
        //     _In_ ULONG CreateDisposition,
        //     _In_ ULONG CreateOptions,
        //     _In_reads_bytes_opt_(EaLength) PVOID EaBuffer,
        //     _In_ ULONG EaLength
        //     );
        //

        let ObjectAttributes = Va(vmi.os().function_argument(2)?);

        let object_attributes = vmi.os().object_attributes(ObjectAttributes)?;
        let object_name = match object_attributes.object_name()? {
            Some(object_name) => object_name,
            None => {
                tracing::warn!(%ObjectAttributes, "No object name found");
                return Ok(());
            }
        };

        tracing::info!(%object_name);

        Ok(())
    }

    #[tracing::instrument(skip_all)]
    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(())
    }

    #[tracing::instrument(skip_all)]
    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(())
    }

    #[tracing::instrument(skip_all)]
    fn MmCleanProcessAddressSpace(
        &mut self,
        vmi: &VmiContext<WindowsOs<Driver>>,
    ) -> Result<(), VmiError> {
        //
        // VOID
        // MmCleanProcessAddressSpace (
        //     _In_ PEPROCESS Process
        //     );
        //

        let Process = vmi.os().function_argument(0)?;

        let process = vmi.os().process(ProcessObject(Va(Process)))?;
        let process_id = process.id()?;

        let name = process.name()?;
        let image_base = process.image_base()?;

        tracing::info!(%process_id, name, %image_base);

        Ok(())
    }

    fn dispatch(
        &mut self,
        vmi: &VmiContext<WindowsOs<Driver>>,
    ) -> Result<VmiEventResponse<Amd64>, VmiError> {
        let event = vmi.event();
        let result = match event.reason() {
            EventReason::MemoryAccess(_) => self.memory_access(vmi),
            EventReason::Interrupt(_) => self.interrupt(vmi),
            EventReason::Singlestep(_) => self.singlestep(vmi),
            _ => panic!("Unhandled event: {:?}", event.reason()),
        };

        // If VMI tries to read from a page that is not present, it will return
        // a page fault error. In this case, we inject a page fault interrupt
        // to the guest.
        //
        // Once the guest handles the page fault, it will retry to execute the
        // instruction that caused the page fault.
        if let Err(VmiError::Translation(pfs)) = result {
            tracing::warn!(?pfs, "Page fault, injecting");
            vmi.inject_interrupt(event.vcpu_id(), Interrupt::page_fault(pfs[0].va, 0))?;
            return Ok(VmiEventResponse::default());
        }

        result
    }

Trait Implementations

impl<Arch> Clone for VmiEvent<Arch>

where Arch: Clone + Architecture, <Arch as Architecture>::Registers: Clone, <Arch as Architecture>::EventReason: Clone,

fn clone(&self) -> VmiEvent<Arch>

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<Arch> Debug for VmiEvent<Arch>

where Arch: Debug + Architecture, <Arch as Architecture>::Registers: Debug, <Arch as Architecture>::EventReason: Debug,

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl<Arch> Copy for VmiEvent<Arch>

where Arch: Copy + Architecture, <Arch as Architecture>::Registers: Copy, <Arch as Architecture>::EventReason: Copy,