winappdbg.search

Process memory search.

class winappdbg.search.AsciiStringsPattern(minLength=4)

Pattern matching for extracting ASCII strings from binary data.

This pattern extracts printable ASCII strings similar to the Unix strings command. Only characters in the range 0x20-0x7E (space to tilde) are considered printable.

next_match()

Find the next ASCII string in the data buffer.

Return type:

int

Returns:

Position in the buffer where the string was found, or -1 if not found.

class winappdbg.search.HexPattern(pattern)

Hexadecimal pattern matching with wildcards.

Hex patterns must be in this form:

"68 65 6c 6c 6f 20 77 6f 72 6c 64"  # "hello world"

Spaces are optional. Capitalization of hex digits doesn’t matter. This is exactly equivalent to the previous example:

"68656C6C6F20776F726C64"            # "hello world"

Wildcards are allowed, in the form of a ? sign in any hex digit:

"5? 5? c3"          # pop register / pop register / ret
"b8 ?? ?? ?? ??"    # mov eax, immediate value
next_match()

This method MUST be reimplemented by subclasses. The data buffer can be found in self.data.

Return type:

int

Returns:

Position in the buffer where the pattern was found.

class winappdbg.search.IStringPattern(pattern)

Pattern matching for static strings (case insensitive).

next_match()

This method MUST be reimplemented by subclasses. The data buffer can be found in self.data.

Return type:

int

Returns:

Position in the buffer where the pattern was found.

exception winappdbg.search.MemoryAccessWarning

This warning is issued when a memory access error has occurred, but it can be safely ignored in most cases.

class winappdbg.search.Pattern(pattern)

Base class to code your own search mechanism.

Normally you only need to reimplement the following methods:

  • __len__()

  • next_match().

next_match()

This method MUST be reimplemented by subclasses. The data buffer can be found in self.data.

Return type:

int

Returns:

Position in the buffer where the pattern was found.

reset()

Used internally to reset the internal state of the search engine. Subclasses don’t normally need to reimplement this method.

search(address, data, overlapping)

Searches for the pattern in the given data buffer. Subclasses don’t normally need to reimplement this method.

Parameters:

  • address (int) – Memory address where the data was read from. Used to calculate the results tuple.

  • data (bytes) – Data buffer to search in.

  • overlapping (bool) – True for overlapped searches, False otherwise.

shift(delta)

Used internally to adjust offsets when doing buffered searches. Subclasses don’t normally need to reimplement this method.

Parameters:

delta (int) – Delta offset.

class winappdbg.search.Search(*argv, **argd)

Static class to group the search functionality.

Do not instance this class! Use its static methods instead.

classmethod search_process(process, patterns, minAddr=None, maxAddr=None, bufferPages=None, overlapping=True)

Search for the given string or pattern within the process memory.

Parameters:

  • process (Process) – Process to search.

  • patterns (list of Pattern) –

    List of strings or wildcard patterns to search for. It must be an instance of a subclass of Pattern.

    The following Pattern subclasses are provided by WinAppDbg: - StringPattern (case sensitive string search) - IStringPattern (case insensitive string search) - HexPattern (hexadecimal pattern with wildcards)

    You can also write your own subclass of Pattern for customized searches.

  • minAddr (int) – (Optional) Start the search at this memory address.

  • maxAddr (int) – (Optional) Stop the search at this memory address.

  • bufferPages (int) –

    (Optional) Number of memory pages to buffer when performing the search. Valid values are:

    • 0 or None: Automatically determine the required buffer size. This is the default.

    • > 0: Set the buffer size in memory pages.

    • < 0: Disable buffering entirely. This may give you a little speed gain at the cost of an increased memory usage. If the target process has very large contiguous memory regions it may actually be slower or even fail.

  • overlapping (bool) –

    True to allow overlapping results, False otherwise.

    Overlapping results yield the maximum possible number of results.

    For example, if searching for “AAAA” within “AAAAAAAA” at address 0x10000, when overlapping is turned off the following matches are yielded:

    (0x10000, 4, "AAAA")
(0x10004, 4, "AAAA")

    If overlapping is turned on, the following matches are yielded:

    (0x10000, 4, "AAAA")
(0x10001, 4, "AAAA")
(0x10002, 4, "AAAA")
(0x10003, 4, "AAAA")
(0x10004, 4, "AAAA")

    As you can see, the middle results are overlapping the last two.

Return type:

iterator of tuple( int, int, bytes )

Returns:

An iterator of tuples. Each tuple contains the following: - The memory address where the pattern was found. - The size of the data that matches the pattern. - The data that matches the pattern.

Raises:

WindowsError – An error occurred when querying or reading the process memory.

class winappdbg.search.StringPattern(pattern)

Pattern matching for static strings (case sensitive).

next_match()

This method MUST be reimplemented by subclasses. The data buffer can be found in self.data.

Return type:

int

Returns:

Position in the buffer where the pattern was found.

class winappdbg.search.UnicodeStringsPattern(minLength=4)

Pattern matching for extracting Unicode (UTF-16LE) strings from binary data.

This pattern extracts printable Unicode strings encoded as UTF-16LE (little-endian), which is the standard Unicode encoding on Windows.

next_match()

Find the next Unicode string in the data buffer.

Return type:

int

Returns:

Position in the buffer where the string was found, or -1 if not found.