Struct VmiEventResponse 

pub struct VmiEventResponse<Arch>
where
    Arch: Architecture,
{
    pub action: VmiEventAction,
    pub view: Option<View>,
    pub registers: Option<<<Arch as Architecture>::Registers as Registers>::GpRegisters>,
}

A response to a VMI event.

Fields

action: VmiEventAction

The primary action to take when resuming.

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,

pub fn deny() -> VmiEventResponse<Arch>

Available on crate features injector and utils only.

Creates a response to deny the event.

pub fn reinject_interrupt() -> VmiEventResponse<Arch>

Available on crate features injector and utils only.

Creates a response to reinject an interrupt.

Examples found in repository

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

    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()))
    }

pub fn singlestep() -> VmiEventResponse<Arch>

Available on crate features injector and utils only.

Creates a response to single-step one instruction.

Examples found in repository

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

    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 fast_singlestep(view: View) -> VmiEventResponse<Arch>

Available on crate features injector and utils only.

Creates a response to fast single-step one instruction in the specified view. Unlike regular singlestep, fast singlestep never generates a VMI event.

Examples found in repository

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

    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()))
    }

pub fn emulate() -> VmiEventResponse<Arch>

Available on crate features injector and utils only.

Creates a response to emulate the instruction.

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

Available on crate features injector and utils only.

Sets a specific view for the response.

Examples found in repository

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

    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))
    }

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

Available on crate features injector and utils only.

Sets specific CPU registers for the response.

Examples found in repository

examples/windows-reactor/netio.rs (line 564)

pub fn KfdIsLayerEmpty<Driver>(
    vmi: &VmiContext<WindowsOs<Driver>>,
) -> Result<Action<<WindowsOs<Driver> as VmiOs>::Architecture>, VmiError>
where
    Driver: VmiRead,
    Driver::Architecture: ArchAdapter<Driver>,
{
    //
    // BOOLEAN
    // NTAPI
    // KfdIsLayerEmpty (
    //     _In_ UINT16 layerId
    //     );
    //

    let layerId = FwpsLayer(vmi.os().function_argument(0)? as u16);

    if !matches!(
        layerId,
        FwpsLayer::ALE_AUTH_CONNECT_V4
            | FwpsLayer::ALE_AUTH_CONNECT_V6
            | FwpsLayer::ALE_FLOW_ESTABLISHED_V4
            | FwpsLayer::ALE_FLOW_ESTABLISHED_V6
    ) {
        tracing::trace!(?layerId, "passing through");
        return Ok(Action::default());
    }

    tracing::trace!(?layerId, "overriding");

    let return_address = vmi.return_address()?;
    let stack_pointer = vmi.registers().stack_pointer();
    let address_width = vmi.registers().address_width() as u64;

    let mut registers = vmi.registers().gp_registers();
    registers.set_result(0); // Return FALSE
    registers.set_instruction_pointer(return_address.into());
    registers.set_stack_pointer(stack_pointer + address_width);

    Ok(Action::Response(
        VmiEventResponse::default().with_registers(registers),
    ))
}

Trait Implementations

impl<Arch> Debug for VmiEventResponse<Arch>

where Arch: Debug + Architecture, <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,

fn default() -> VmiEventResponse<Arch>

Returns the “default value” for a type.