Struct VmiEventResponse

pub struct VmiEventResponse<Arch>
where
    Arch: Architecture + ?Sized,
{
    pub flags: VmiEventResponseFlags,
    pub view: Option<View>,
    pub registers: Option<<<Arch as Architecture>::Registers as Registers>::GpRegisters>,
}

A response to a VMI event.

Fields

flags: VmiEventResponseFlags

Flags associated with the response.

view: Option<View>

The view to set for the VCPU.

registers: Option<<<Arch as Architecture>::Registers as Registers>::GpRegisters>

The VCPU registers to set.

Implementations

impl<Arch> VmiEventResponse<Arch>

where Arch: Architecture + ?Sized,

pub fn reinject_interrupt() -> VmiEventResponse<Arch>

Available on crate feature utils only.

Creates a response to reinject an interrupt.

Examples found in repository

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

    fn interrupt(
        &mut self,
        vmi: &VmiContext<'_, Driver, 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::toggle_fast_singlestep().and_set_view(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::toggle_fast_singlestep().and_set_view(vmi.default_view()))
    }

pub fn toggle_singlestep() -> VmiEventResponse<Arch>

Available on crate feature utils only.

Creates a response to toggle single-step mode.

Examples found in repository

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

    fn memory_access(
        &mut self,
        vmi: &VmiContext<'_, Driver, 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::toggle_singlestep().and_set_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::toggle_fast_singlestep().and_set_view(vmi.default_view()))
        }
        else {
            panic!("Unhandled memory access: {memory_access:?}");
        }
    }

    #[tracing::instrument(skip_all, fields(pid, process))]
    fn interrupt(
        &mut self,
        vmi: &VmiContext<'_, Driver, 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::toggle_fast_singlestep().and_set_view(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::toggle_fast_singlestep().and_set_view(vmi.default_view()))
    }

    #[tracing::instrument(skip_all)]
    fn singlestep(
        &mut self,
        vmi: &VmiContext<'_, Driver, 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())?;

        for event in &ptm_events {
            // Log the page table modifications.
            match &event {
                PageTableMonitorEvent::PageIn(update) => tracing::debug!(?update, "page-in"),
                PageTableMonitorEvent::PageOut(update) => tracing::debug!(?update, "page-out"),
            }

            // Let the breakpoint controller handle the page table modifications.
            self.bpm.handle_ptm_event(vmi, event)?;
        }

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

pub fn toggle_fast_singlestep() -> VmiEventResponse<Arch>

Available on crate feature utils only.

Creates a response to toggle fast single-step mode.

Examples found in repository

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

    fn memory_access(
        &mut self,
        vmi: &VmiContext<'_, Driver, 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::toggle_singlestep().and_set_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::toggle_fast_singlestep().and_set_view(vmi.default_view()))
        }
        else {
            panic!("Unhandled memory access: {memory_access:?}");
        }
    }

    #[tracing::instrument(skip_all, fields(pid, process))]
    fn interrupt(
        &mut self,
        vmi: &VmiContext<'_, Driver, 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::toggle_fast_singlestep().and_set_view(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::toggle_fast_singlestep().and_set_view(vmi.default_view()))
    }

pub fn emulate() -> VmiEventResponse<Arch>

Available on crate feature utils only.

Creates a response to emulate the instruction.

pub fn set_view(view: View) -> VmiEventResponse<Arch>

Available on crate feature utils only.

Creates a response to set a specific view.

pub fn set_registers( registers: <<Arch as Architecture>::Registers as Registers>::GpRegisters, ) -> VmiEventResponse<Arch>

Available on crate feature utils only.

Creates a response to set specific CPU registers.

pub fn and_reinject_interrupt(self) -> VmiEventResponse<Arch>

Available on crate feature utils only.

Adds the reinject interrupt flag to the response.

pub fn and_toggle_singlestep(self) -> VmiEventResponse<Arch>

Available on crate feature utils only.

Adds the toggle single-step flag to the response.

pub fn and_toggle_fast_singlestep(self) -> VmiEventResponse<Arch>

Available on crate feature utils only.

Adds the toggle fast single-step flag to the response.

pub fn and_emulate(self) -> VmiEventResponse<Arch>

Available on crate feature utils only.

Adds the emulate flag to the response.

pub fn and_set_view(self, view: View) -> VmiEventResponse<Arch>

Available on crate feature utils only.

Sets a specific view for the response.

Examples found in repository

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

    fn memory_access(
        &mut self,
        vmi: &VmiContext<'_, Driver, 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::toggle_singlestep().and_set_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::toggle_fast_singlestep().and_set_view(vmi.default_view()))
        }
        else {
            panic!("Unhandled memory access: {memory_access:?}");
        }
    }

    #[tracing::instrument(skip_all, fields(pid, process))]
    fn interrupt(
        &mut self,
        vmi: &VmiContext<'_, Driver, 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::toggle_fast_singlestep().and_set_view(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::toggle_fast_singlestep().and_set_view(vmi.default_view()))
    }

    #[tracing::instrument(skip_all)]
    fn singlestep(
        &mut self,
        vmi: &VmiContext<'_, Driver, 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())?;

        for event in &ptm_events {
            // Log the page table modifications.
            match &event {
                PageTableMonitorEvent::PageIn(update) => tracing::debug!(?update, "page-in"),
                PageTableMonitorEvent::PageOut(update) => tracing::debug!(?update, "page-out"),
            }

            // Let the breakpoint controller handle the page table modifications.
            self.bpm.handle_ptm_event(vmi, event)?;
        }

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

pub fn and_set_registers( self, registers: <<Arch as Architecture>::Registers as Registers>::GpRegisters, ) -> VmiEventResponse<Arch>

Available on crate feature utils only.

Sets specific CPU registers for the response.

Trait Implementations

impl<Arch> Debug for VmiEventResponse<Arch>

where Arch: Debug + Architecture + ?Sized, <Arch as Architecture>::Registers: Debug,

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

Formats the value using the given formatter.

impl<Arch> Default for VmiEventResponse<Arch>

where Arch: Architecture + ?Sized,

fn default() -> VmiEventResponse<Arch>

Returns the “default value” for a type.