Struct aobscan::PatternBuilder

source · [−]

pub struct PatternBuilder { /* private fields */ }

Expand description

Builder for the Pattern struct.
The builder is used to create a Pattern struct with the desired settings.

When building a pattern, (of any kind) the following rules apply:

The signature must be a valid hexadecimal string. (case-insensitive)
It might contain wildcards at the beginning and/or end of the string. (which are ignored during the scan)
- In the case of one or more wildcard bytes at the beginning of the string, the resulting address will be offset by the number of wildcards. (resulting in the address of the first non-wildcard byte minus the wildcard bytes at the beginning)
- End wildcards are ignored during the scan, so the match will be found even if the full pattern would not fit in the remaining bytes.

Examples

Multi-threaded scan for an IDA-style pattern

let data = std::fs::read("some.bin").unwrap();
let found = aobscan::PatternBuilder::from_ida_style("48 8B 05 ? ? ? ? 48 8B 88 ? ? ? ?")
    .unwrap()
    .with_all_threads()
    .build()
    .scan(&data, move |offset| {
        println!("Match at offset {:#02x}", offset);
        true // Return true to continue scanning for other matches
    });

Single-threaded scan for a code-style pattern

let data = std::fs::read("some.bin").unwrap();
let found = aobscan::PatternBuilder::from_code_style(
    b"\x48\x8B\x05\x00\x00\x00\x00\x48\x8B\x88\x00\x00\x00\x00",
    "...????...????"
).unwrap()
    .with_threads(1)
    .unwrap()
    .build()
    .scan(&data, move |offset| {
        println!("Match at offset {:#02x}", offset);
        true // Return true to continue scanning for other matches
    });

Implementations

source

impl PatternBuilder

source

pub fn from_code_style(
signature: &[u8],
mask: &str
) -> Result<Self, BuilderError>

Creates a pattern builder from a code-style signature.

A code-style signature is characterized by a byte array and a mask string.
The mask string is a list of characters, where each character represents whether the corresponding byte in the byte array is a wildcard or not.
You must use a ? for each wildcard byte, but you can choose any other character for non-wildcard bytes.

The length of the mask string must be equal to the length of the byte array, and the byte array can contain any hexadecimal value in the place of a wildcard.

This pattern representation is usually the most safe and reliable, but it is also the most verbose and tedious to write.

Arguments

signature - The byte array containing the bytes to search for.
mask - The mask string.

Returns

The current instance of the pattern, or None if the parameters are invalid.

Good Practices

In the mask string, use a [?] for each wildcard byte, and [.] for each non-wildcard byte.
In the byte array, use \x00 for each wildcard byte, and the actual byte value for each non-wildcard byte.

Errors

BuilderError::SizeMismatch - The size of the signature and mask do not match.

Format

signature:  `b"\x48\x8B\x05\x00\x00\x00\x00"`
mask:       `"...????"`

source

pub fn from_ida_style(pattern: &str) -> Result<Self, BuilderError>

Creates a pattern builder from an IDA-style signature.

An IDA-style signature is characterized by a single string of hexadecimal values separated by spaces.
In this string, you can use ? or ?? to represent a wildcard byte.

It is generally preferred as it is shorter and easier to read, but it may introduce some overhead as it is ultimately converted to a code-style like AOB.

Arguments

pattern - The IDA-style pattern string.

Returns

The current instance of the builder, or None if the parameters are invalid.

Errors

BuilderError::InvalidSignature - The pattern string is empty.
BuilderError::ParseError - The pattern string contains invalid hexadecimal values.

Format

pattern:    "48 8B 05 ? ? ? ?" // or "48 8B 05 ?? ?? ?? ??"

source

pub fn from_hex_string(pattern: &str) -> Result<Self, BuilderError>

Creates a pattern builder from a string of non-spaced, case-insensitive hex bytes.

The string must contain only hexadecimal characters (or ’??’s for wildcard bytes), and its length must be a multiple of 2.
Single-char wildcards are not supported!

Arguments

pattern - The pattern string.

Returns

The current instance of the builder, or None if the parameter is invalid.

Errors

BuilderError::InvalidSignature - The pattern is empty, its length is odd, contains invalid characters or single-char wildcards.
BuilderError::ParseError - The pattern contains invalid hexadecimal characters.

Format

pattern:    "488b05????????488b88??" // a pair of '??'s represents a wildcard byte

source

pub fn with_threads(self, threads: usize) -> Result<Self, BuilderError>

Sets the number of threads to use for scanning.
The number of threads is considered invalid if it is set to 0 or greater than the number of logical CPU cores.