Struct InjectorHandler 

pub struct InjectorHandler<Os, Mode, T, Bridge = ()>
where
    Os: InjectorExecutionAdapter<Mode, T, Bridge>,
    Mode: ExecutionMode,
    Bridge: BridgeDispatch<Os, u64>,
{ /* private fields */ }

Available on crate features utils and injector only.

Generic injector handler that delegates to an OS- and mode-specific implementation.

Prefer the KernelInjectorHandler and UserInjectorHandler type aliases for the common case without a bridge. When a custom BridgeDispatch is needed, use this type directly with an explicit Bridge parameter.

Implementations

impl<Os, Mode, T, Bridge> InjectorHandler<Os, Mode, T, Bridge>

where Os: InjectorExecutionAdapter<Mode, T, Bridge>, Mode: ExecutionMode, Bridge: BridgeDispatch<Os, u64>,

pub fn new( vmi: &VmiSession<'_, Os>, recipe: Recipe<Os, T>, ) -> Result<InjectorHandler<Os, Mode, T, Bridge>, VmiError>

where Bridge: Default,

Creates a new injector handler with a default (no-op) bridge.

Examples found in repository

examples/windows-recipe-messagebox.rs (lines 95-101)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (session, _profile) = common::create_vmi_session()?;

    let explorer_pid = {
        // This block is used to drop the pause guard after the PID is found.
        // If the `session.handle()` would be called with the VM paused, no
        // events would be triggered.
        let _pause_guard = session.pause_guard()?;

        let registers = session.registers(VcpuId(0))?;
        let vmi = session.with_registers(&registers);

        let explorer = match common::find_process(&vmi, "explorer.exe")? {
            Some(explorer) => explorer,
            None => {
                tracing::error!("explorer.exe not found");
                return Ok(());
            }
        };

        tracing::info!(
            pid = %explorer.id()?,
            object = %explorer.object()?,
            "found explorer.exe"
        );

        explorer.id()?
    };

    session.handle(|session| {
        UserInjectorHandler::new(
            session,
            recipe_factory(MessageBox::new(
                "Hello, World!",
                "This is a message box from the VMI!",
            )),
        )?
        .with_pid(explorer_pid)
    })?;

    Ok(())
}

examples/windows-recipe-writefile.rs (lines 233-239)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (session, _profile) = common::create_vmi_session()?;

    let explorer_pid = {
        // This block is used to drop the pause guard after the PID is found.
        // If the `session.handle()` would be called with the VM paused, no
        // events would be triggered.
        let _pause_guard = session.pause_guard()?;

        let registers = session.registers(VcpuId(0))?;
        let vmi = session.with_registers(&registers);

        let explorer = match common::find_process(&vmi, "explorer.exe")? {
            Some(explorer) => explorer,
            None => {
                tracing::error!("explorer.exe not found");
                return Ok(());
            }
        };

        tracing::info!(
            pid = %explorer.id()?,
            object = %explorer.object()?,
            "found explorer.exe"
        );

        explorer.id()?
    };

    session.handle(|session| {
        UserInjectorHandler::new(
            session,
            recipe_factory(GuestFile::new(
                "C:\\Users\\John\\Desktop\\test.txt",
                "Hello, World!".as_bytes(),
            )),
        )?
        .with_pid(explorer_pid)
    })?;

    Ok(())
}

examples/windows-recipe-writefile-advanced.rs (lines 336-342)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (session, _profile) = common::create_vmi_session()?;

    let explorer_pid = {
        // This block is used to drop the pause guard after the PID is found.
        // If the `session.handle()` would be called with the VM paused, no
        // events would be triggered.
        let _pause_guard = session.pause_guard()?;

        let registers = session.registers(VcpuId(0))?;
        let vmi = session.with_registers(&registers);

        let explorer = match common::find_process(&vmi, "explorer.exe")? {
            Some(explorer) => explorer,
            None => {
                tracing::error!("explorer.exe not found");
                return Ok(());
            }
        };

        tracing::info!(
            pid = %explorer.id()?,
            object = %explorer.object()?,
            "found explorer.exe"
        );

        explorer.id()?
    };

    let mut content = Vec::new();
    for c in 'A'..='Z' {
        content.extend((0..2049).map(|_| c as u8).collect::<Vec<_>>());
    }

    session.handle(|session| {
        UserInjectorHandler::new(
            session,
            recipe_factory(GuestFile::new(
                "C:\\Users\\John\\Desktop\\test.txt",
                content,
            )),
        )?
        .with_pid(explorer_pid)
    })?;

    Ok(())
}

pub fn with_bridge( vmi: &VmiSession<'_, Os>, bridge: Bridge, recipe: Recipe<Os, T>, ) -> Result<InjectorHandler<Os, Mode, T, Bridge>, VmiError>

Creates a new injector handler with a custom bridge for guest-host communication.

pub fn with_pid( self, pid: ProcessId, ) -> Result<InjectorHandler<Os, Mode, T, Bridge>, VmiError>

Restricts injection to a specific process.

Examples found in repository

examples/windows-recipe-messagebox.rs (line 102)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (session, _profile) = common::create_vmi_session()?;

    let explorer_pid = {
        // This block is used to drop the pause guard after the PID is found.
        // If the `session.handle()` would be called with the VM paused, no
        // events would be triggered.
        let _pause_guard = session.pause_guard()?;

        let registers = session.registers(VcpuId(0))?;
        let vmi = session.with_registers(&registers);

        let explorer = match common::find_process(&vmi, "explorer.exe")? {
            Some(explorer) => explorer,
            None => {
                tracing::error!("explorer.exe not found");
                return Ok(());
            }
        };

        tracing::info!(
            pid = %explorer.id()?,
            object = %explorer.object()?,
            "found explorer.exe"
        );

        explorer.id()?
    };

    session.handle(|session| {
        UserInjectorHandler::new(
            session,
            recipe_factory(MessageBox::new(
                "Hello, World!",
                "This is a message box from the VMI!",
            )),
        )?
        .with_pid(explorer_pid)
    })?;

    Ok(())
}

examples/windows-recipe-writefile.rs (line 240)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (session, _profile) = common::create_vmi_session()?;

    let explorer_pid = {
        // This block is used to drop the pause guard after the PID is found.
        // If the `session.handle()` would be called with the VM paused, no
        // events would be triggered.
        let _pause_guard = session.pause_guard()?;

        let registers = session.registers(VcpuId(0))?;
        let vmi = session.with_registers(&registers);

        let explorer = match common::find_process(&vmi, "explorer.exe")? {
            Some(explorer) => explorer,
            None => {
                tracing::error!("explorer.exe not found");
                return Ok(());
            }
        };

        tracing::info!(
            pid = %explorer.id()?,
            object = %explorer.object()?,
            "found explorer.exe"
        );

        explorer.id()?
    };

    session.handle(|session| {
        UserInjectorHandler::new(
            session,
            recipe_factory(GuestFile::new(
                "C:\\Users\\John\\Desktop\\test.txt",
                "Hello, World!".as_bytes(),
            )),
        )?
        .with_pid(explorer_pid)
    })?;

    Ok(())
}

examples/windows-recipe-writefile-advanced.rs (line 343)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let (session, _profile) = common::create_vmi_session()?;

    let explorer_pid = {
        // This block is used to drop the pause guard after the PID is found.
        // If the `session.handle()` would be called with the VM paused, no
        // events would be triggered.
        let _pause_guard = session.pause_guard()?;

        let registers = session.registers(VcpuId(0))?;
        let vmi = session.with_registers(&registers);

        let explorer = match common::find_process(&vmi, "explorer.exe")? {
            Some(explorer) => explorer,
            None => {
                tracing::error!("explorer.exe not found");
                return Ok(());
            }
        };

        tracing::info!(
            pid = %explorer.id()?,
            object = %explorer.object()?,
            "found explorer.exe"
        );

        explorer.id()?
    };

    let mut content = Vec::new();
    for c in 'A'..='Z' {
        content.extend((0..2049).map(|_| c as u8).collect::<Vec<_>>());
    }

    session.handle(|session| {
        UserInjectorHandler::new(
            session,
            recipe_factory(GuestFile::new(
                "C:\\Users\\John\\Desktop\\test.txt",
                content,
            )),
        )?
        .with_pid(explorer_pid)
    })?;

    Ok(())
}

Trait Implementations

impl<Os, Mode, T, Bridge> VmiHandler<Os> for InjectorHandler<Os, Mode, T, Bridge>

where Os: InjectorExecutionAdapter<Mode, T, Bridge>, Mode: ExecutionMode, Bridge: BridgeDispatch<Os, u64>,

type Output = <<Os as InjectorExecutionAdapter<Mode, T, Bridge>>::Handler as VmiHandler<Os>>::Output

The output type of the handler.

fn handle_event( &mut self, vmi: VmiContext<'_, Os>, ) -> VmiEventResponse<<Os as VmiOs>::Architecture>

Called for each VMI event.

fn poll( &self, ) -> Option<<InjectorHandler<Os, Mode, T, Bridge> as VmiHandler<Os>>::Output>

Checks if the handler has completed.

fn handle_timeout(&mut self, _session: &VmiSession<'_, Os>)

Called when the event loop times out waiting for the next event.

fn handle_interrupted(&mut self, _session: &VmiSession<'_, Os>)

Called when the event loop is interrupted by a signal.

fn cleanup(&mut self, _session: &VmiSession<'_, Os>)

Called once before the session tears down monitoring.