Struct VmmSearch 

pub struct VmmSearch<'a> { /* private fields */ }

Search API.

Search for binary keywords in physical or virtual memory.

Each keyword/term may be up to 32 bytes long. Up to 16 search terms may be used in the same search.

The search may optionally take place with a skipmask - i.e. a bitmask in which ‘1’ would equal a wildcard bit.

The VmmSearch must be used as mut. Also see VmmSearchResult.

The synchronous search workflow:

1. Acquire search object from vmm.search() or vmmprocess.search().
2. Add 1-16 different search terms using vmmsearch.add_search() and/or vmmsearch.add_search_ex().
3. Start the search and retrieve result (blocking) by calling vmmsearch.result().

The asynchronous search workflow:

1. Acquire search object from vmm.search() or vmmprocess.search().
2. Add 1-16 different search terms using vmmsearch.add_search() and/or vmmsearch.add_search_ex().
3. Start the search in the background using vmmsearch.start().
4. Optionally abort the search with vmmsearch.abort().
5. Optionally poll status or result (if completed) using vmmsearch.poll().
6. Optionally retrieve result (blocking) by calling vmmsearch.result().
7. Search goes out of scope and is cleaned up. Any on-going searches may take a short while to terminate gracefully.

Created By

• vmm.search()
• vmmprocess.search()

Examples

// Fetch search struct for entire process virtual address space.
// Max 256 search hits and avoid using the cache in this example.
let mut vmmsearch = vmmprocess.search(0, 0, 256, FLAG_NOCACHE);
// Search for 'MZ' - i.e. start at PE file at even 0x1000 alignment.
let search_term = ['M' as u8, 'Z' as u8];
let _search_term_id = vmmsearch.add_search_ex(&search_term, None, 0x1000);
// Start search in async mode.
vmmsearch.start();
// Search is now running - it's possible to do other actions here.
// It's possible to poll() to see current progress (or if finished).
// It's possible to abort() to stop search.
// It's possible to fetch result() which will block until search is finished.
let search_result = vmmsearch.result();

Implementations

impl VmmSearch<'_>

pub fn add_search(&mut self, search_bytes: &[u8]) -> ResultEx<u32>

Add a search term.

The search will later be performed using the whole search term and without alignment requirements (align = 1 byte).

On success the search_term_id will be returned. This is the 2nd field (searchresulttuple.1) in the search result tuple. This may be useful if multiple searches are undertaken in one single search run.

Arguments

• search_bytes - Byte data to search for. Max 32 bytes.

Examples

// add a search term for pointer references to address 0x7ffcec973308.
let search_term = [0x08, 0x33, 0x97, 0xec, 0xfc, 0x7f, 0x00, 0x00];
let search_term_id = vmmsearch.add_search(&search_term)?;

pub fn add_search_ex( &mut self, search_bytes: &[u8], search_skipmask: Option<&[u8]>, byte_align: u32, ) -> ResultEx<u32>

Add a search term.

The search will later be performed using the search term with the given alignment (typically 1, 2, 4, 8, 16, .. 0x1000) and an optional skip bitmask in which bit ‘1’ represents a search wildcard value.

On success the search_term_id will be returned. This is the 2nd field (searchresulttuple.1) in the search result tuple. This may be useful if multiple searches are undertaken in one single search run.

Arguments

• search_bytes - Byte data to search for. Max 32 bytes.
• search_skipmask - Optional skipmask (see above). Max search_bytes.len().
• byte_align - Byte alignment (see above).

Examples

// Add a search term for pointer references to address 0x7ffcec973308.
// Pointers are 64-bit/8-byte aligned hence the 8-byte alignment.
let search_term = [0x08, 0x33, 0x97, 0xec, 0xfc, 0x7f, 0x00, 0x00];
let search_term_id = vmmsearch.add_search_ex(&search_term, None, 8)?;

pub fn start(&mut self)

Start a search in asynchronous background thread.

This is useful since the search may take some time and other work may be done while waiting for the result.

The search will start immediately and the progress (and result, if finished) may be polled by calling poll().

The result may be retrieved by a call to poll() or by a blocking call to result() which will return when the search is completed.

Examples

vmmsearch.start();

pub fn abort(&mut self)

Abort an on-going search.

Examples

vmmsearch.abort();

pub fn poll(&mut self) -> VmmSearchResult

Poll an on-going search for the status/result.

Also see VmmSearch and VmmSearchResult.

Examples

let search_status_and_result = vmmsearch.poll();

pub fn result(&mut self) -> VmmSearchResult

Retrieve the search result.

If the search haven’t yet been started it will be started. The function is blocking and will wait for the search to complete before the search results are returned.

Also see VmmSearch and VmmSearchResult.

Examples

let search_status_and_result = vmmsearch.result();

Trait Implementations

impl<'a> Debug for VmmSearch<'a>

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

Formats the value using the given formatter.

impl Display for VmmSearch<'_>

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

Formats the value using the given formatter.

impl Drop for VmmSearch<'_>

fn drop(&mut self)

Executes the destructor for this type.