Package winappdbg :: Module system :: Class MemoryOperations
[hide private]
[frames] | no frames]

Class MemoryOperations

source code


Encapsulates the capabilities to manipulate the memory of a process.

Instance Methods [hide private]
str, unicode
read_string(self, lpBaseAddress, nChars, fUnicode=False)
Reads an ASCII or Unicode string from the address space of the process.
source code
dict( int → str )
get_mapped_filenames(self, memoryMap=None)
Retrieves the filenames for memory mapped files in the debugee.
source code
list( win32.MemoryBasicInformation )
take_memory_snapshot(self, minAddr=None, maxAddr=None)
Takes a snapshot of the memory contents of the process.
source code
 
restore_memory_snapshot(self, snapshot)
Attempts to restore the memory state as it was when the given snapshot was taken.
source code
 
__restore_mbi(self, hProcess, new_mbi, old_mbi)
Used internally by restore_memory_snapshot.
source code

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __init__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

    Memory mapping
int
malloc(self, dwSize, lpAddress=None)
Allocates memory into the address space of the process.
source code
int
mprotect(self, lpAddress, dwSize, flNewProtect)
Set memory protection in the address space of the process.
source code
win32.MemoryBasicInformation
mquery(self, lpAddress)
Query memory information from the address space of the process.
source code
bool
free(self, lpAddress, dwSize=0)
Frees memory from the address space of the process.
source code
bool
is_pointer(self, address)
Determines if an address is a valid code or data pointer.
source code
bool
is_address_valid(self, address)
Determines if an address is a valid user mode address.
source code
bool
is_address_free(self, address)
Determines if an address belongs to a free page.
source code
bool
is_address_reserved(self, address)
Determines if an address belongs to a reserved page.
source code
bool
is_address_commited(self, address)
Determines if an address belongs to a commited page.
source code
bool
is_address_guard(self, address)
Determines if an address belongs to a guard page.
source code
bool
is_address_readable(self, address)
Determines if an address belongs to a commited and readable page.
source code
bool
is_address_writeable(self, address)
Determines if an address belongs to a commited and writeable page.
source code
bool
is_address_copy_on_write(self, address)
Determines if an address belongs to a commited, copy-on-write page.
source code
bool
is_address_executable(self, address)
Determines if an address belongs to a commited and executable page.
source code
bool
is_address_executable_and_writeable(self, address)
Determines if an address belongs to a commited, writeable and executable page.
source code
list( win32.MemoryBasicInformation )
get_memory_map(self, minAddr=None, maxAddr=None)
Produces a memory map to the process address space.
source code
    Memory read
str
read(self, lpBaseAddress, nSize)
Reads from the memory of the process.
source code
int
read_uint(self, lpBaseAddress)
Reads a single unsigned integer from the memory of the process.
source code
int
read_pointer(self, lpBaseAddress)
Reads a single pointer value from the memory of the process.
source code
int
read_char(self, lpBaseAddress)
Reads a single character to the memory of the process.
source code
int
read_structure(self, lpBaseAddress, stype)
Reads a ctypes structure from the memory of the process.
source code
str
peek(self, lpBaseAddress, nSize)
Reads the memory of the process.
source code
int
peek_uint(self, lpBaseAddress)
Reads a single unsigned integer from the memory of the process.
source code
int
peek_pointer(self, lpBaseAddress)
Reads a single pointer value from the memory of the process.
source code
int
peek_char(self, lpBaseAddress)
Reads a single character from the memory of the process.
source code
str, unicode
peek_string(self, lpBaseAddress, fUnicode=False, dwMaxSize=4096)
Tries to read an ASCII or Unicode string from the address space of the process.
source code
    Memory write
 
write(self, lpBaseAddress, lpBuffer)
Writes to the memory of the process.
source code
 
write_uint(self, lpBaseAddress, unpackedDword)
Writes a single unsigned integer to the memory of the process.
source code
 
write_pointer(self, lpBaseAddress, unpackedValue)
Writes a single pointer value to the memory of the process.
source code
 
write_char(self, lpBaseAddress, char)
Writes a single character to the memory of the process.
source code
int
poke(self, lpBaseAddress, lpBuffer)
Writes to the memory of the process.
source code
int
poke_uint(self, lpBaseAddress, unpackedDword)
Writes a single unsigned integer to the memory of the process.
source code
int
poke_pointer(self, lpBaseAddress, unpackedValue)
Writes a single pointer value to the memory of the process.
source code
int
poke_char(self, lpBaseAddress, char)
Writes a single character to the memory of the process.
source code
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

read(self, lpBaseAddress, nSize)

source code 

Reads from the memory of the process.

Parameters:
  • lpBaseAddress (int) - Memory address to begin reading.
  • nSize (int) - Number of bytes to read.
Returns: str
Bytes read from the process memory.
Raises:
  • WindowsError - On error an exception is raised.

See Also: peek

write(self, lpBaseAddress, lpBuffer)

source code 

Writes to the memory of the process.

Parameters:
  • lpBaseAddress (int) - Memory address to begin writing.
  • lpBuffer (int) - Bytes to write.
Raises:
  • WindowsError - On error an exception is raised.

See Also: poke

read_uint(self, lpBaseAddress)

source code 

Reads a single unsigned integer from the memory of the process.

Parameters:
  • lpBaseAddress (int) - Memory address to begin reading.
Returns: int
Integer value read from the process memory.
Raises:
  • WindowsError - On error an exception is raised.

See Also: peek

write_uint(self, lpBaseAddress, unpackedDword)

source code 

Writes a single unsigned integer to the memory of the process.

Parameters:
  • lpBaseAddress (int) - Memory address to begin writing.
  • unpackedDword (int, long) - Value to write.
Raises:
  • WindowsError - On error an exception is raised.

See Also: poke_uint

read_pointer(self, lpBaseAddress)

source code 

Reads a single pointer value from the memory of the process.

Parameters:
  • lpBaseAddress (int) - Memory address to begin reading.
Returns: int
Pointer value read from the process memory.
Raises:
  • WindowsError - On error an exception is raised.

See Also: peek_pointer

write_pointer(self, lpBaseAddress, unpackedValue)

source code 

Writes a single pointer value to the memory of the process.

Parameters:
  • lpBaseAddress (int) - Memory address to begin writing.
  • unpackedValue (int, long) - Value to write.
Raises:
  • WindowsError - On error an exception is raised.

See Also: poke_pointer

read_char(self, lpBaseAddress)

source code 

Reads a single character to the memory of the process.

Parameters:
  • lpBaseAddress (int) - Memory address to begin writing.
Returns: int
Character value read from the process memory.
Raises:
  • WindowsError - On error an exception is raised.

See Also: write_char

write_char(self, lpBaseAddress, char)

source code 

Writes a single character to the memory of the process.

Parameters:
  • lpBaseAddress (int) - Memory address to begin writing.
  • char (int) - Character to write.
Raises:
  • WindowsError - On error an exception is raised.

See Also: write_char

read_structure(self, lpBaseAddress, stype)

source code 

Reads a ctypes structure from the memory of the process.

Parameters:
  • lpBaseAddress (int) - Memory address to begin reading.
  • stype (class ctypes.Structure or a subclass.) - Structure definition.
Returns: int
Structure instance filled in with data read from the process memory.
Raises:
  • WindowsError - On error an exception is raised.

See Also: read

read_string(self, lpBaseAddress, nChars, fUnicode=False)

source code 

Reads an ASCII or Unicode string from the address space of the process.

Parameters:
  • lpBaseAddress (int) - Memory address to begin reading.
  • nChars (int) - String length to read, in characters. Remember that Unicode strings have two byte characters.
  • fUnicode (bool) - True is the string is expected to be Unicode, False if it's expected to be ANSI.
Returns: str, unicode
String read from the process memory space.
Raises:
  • WindowsError - On error an exception is raised.

See Also: read

peek(self, lpBaseAddress, nSize)

source code 

Reads the memory of the process.

Parameters:
  • lpBaseAddress (int) - Memory address to begin reading.
  • nSize (int) - Number of bytes to read.
Returns: str
Bytes read from the process memory. Returns an empty string on error.

See Also: read

poke(self, lpBaseAddress, lpBuffer)

source code 

Writes to the memory of the process.

Parameters:
  • lpBaseAddress (int) - Memory address to begin writing.
  • lpBuffer (str) - Bytes to write.
Returns: int
Number of bytes written. May be less than the number of bytes to write.

See Also: write

peek_uint(self, lpBaseAddress)

source code 

Reads a single unsigned integer from the memory of the process.

Parameters:
  • lpBaseAddress (int) - Memory address to begin reading.
Returns: int
Integer value read from the process memory. Returns zero on error.

See Also: read_uint

poke_uint(self, lpBaseAddress, unpackedDword)

source code 

Writes a single unsigned integer to the memory of the process.

Parameters:
  • lpBaseAddress (int) - Memory address to begin writing.
  • unpackedDword (int, long) - Value to write.
Returns: int
Number of bytes written. May be less than the number of bytes to write.

See Also: write_uint

peek_pointer(self, lpBaseAddress)

source code 

Reads a single pointer value from the memory of the process.

Parameters:
  • lpBaseAddress (int) - Memory address to begin reading.
Returns: int
Pointer value read from the process memory. Returns zero on error.

See Also: read_pointer

poke_pointer(self, lpBaseAddress, unpackedValue)

source code 

Writes a single pointer value to the memory of the process.

Parameters:
  • lpBaseAddress (int) - Memory address to begin writing.
  • unpackedValue (int, long) - Value to write.
Returns: int
Number of bytes written. May be less than the number of bytes to write.

See Also: write_pointer

peek_char(self, lpBaseAddress)

source code 

Reads a single character from the memory of the process.

Parameters:
  • lpBaseAddress (int) - Memory address to begin reading.
Returns: int
Character read from the process memory. Returns zero on error.

See Also: read_char

poke_char(self, lpBaseAddress, char)

source code 

Writes a single character to the memory of the process.

Parameters:
  • lpBaseAddress (int) - Memory address to begin writing.
  • char (str) - Character to write.
Returns: int
Number of bytes written. May be less than the number of bytes to write.

See Also: write_char

peek_string(self, lpBaseAddress, fUnicode=False, dwMaxSize=4096)

source code 

Tries to read an ASCII or Unicode string from the address space of the process.

Parameters:
  • lpBaseAddress (int) - Memory address to begin reading.
  • fUnicode (bool) - True is the string is expected to be Unicode, False if it's expected to be ANSI.
  • dwMaxSize (int) - Maximum allowed string length to read, in bytes.
Returns: str, unicode
String read from the process memory space. It doesn't include the terminating null character. Returns an empty string on failure.

See Also: peek

malloc(self, dwSize, lpAddress=None)

source code 

Allocates memory into the address space of the process.

Parameters:
  • dwSize (int) - Number of bytes to allocate.
  • lpAddress (int) - (Optional) Desired address for the newly allocated memory. This is only a hint, the memory could still be allocated somewhere else.
Returns: int
Address of the newly allocated memory.
Raises:
  • WindowsError - On error an exception is raised.

See Also: free

mprotect(self, lpAddress, dwSize, flNewProtect)

source code 

Set memory protection in the address space of the process.

Parameters:
  • lpAddress (int) - Address of memory to protect.
  • dwSize (int) - Number of bytes to protect.
  • flNewProtect (int) - New protect flags.
Returns: int
Old protect flags.
Raises:
  • WindowsError - On error an exception is raised.

mquery(self, lpAddress)

source code 

Query memory information from the address space of the process. Returns a win32.MemoryBasicInformation object.

Parameters:
  • lpAddress (int) - Address of memory to query.
Returns: win32.MemoryBasicInformation
Memory region information.
Raises:
  • WindowsError - On error an exception is raised.

free(self, lpAddress, dwSize=0)

source code 

Frees memory from the address space of the process.

Parameters:
  • lpAddress (int) - Address of memory to free.
  • dwSize (int) - (Optional) Number of bytes to free.
Returns: bool
True on success, False on error.

See Also: malloc

is_pointer(self, address)

source code 

Determines if an address is a valid code or data pointer.

That is, the address must be valid and must point to code or data in the target process.

Parameters:
  • address (int) - Memory address to query.
Returns: bool
True if the address is a valid code or data pointer.
Raises:
  • WindowsError - An exception is raised on error.

is_address_valid(self, address)

source code 

Determines if an address is a valid user mode address.

Parameters:
  • address (int) - Memory address to query.
Returns: bool
True if the address is a valid user mode address.
Raises:
  • WindowsError - An exception is raised on error.

is_address_free(self, address)

source code 

Determines if an address belongs to a free page.

Parameters:
  • address (int) - Memory address to query.
Returns: bool
True if the address belongs to a free page.
Raises:
  • WindowsError - An exception is raised on error.

Note: Returns always False for kernel mode addresses.

is_address_reserved(self, address)

source code 

Determines if an address belongs to a reserved page.

Parameters:
  • address (int) - Memory address to query.
Returns: bool
True if the address belongs to a reserved page.
Raises:
  • WindowsError - An exception is raised on error.

Note: Returns always False for kernel mode addresses.

is_address_commited(self, address)

source code 

Determines if an address belongs to a commited page.

Parameters:
  • address (int) - Memory address to query.
Returns: bool
True if the address belongs to a commited page.
Raises:
  • WindowsError - An exception is raised on error.

Note: Returns always False for kernel mode addresses.

is_address_guard(self, address)

source code 

Determines if an address belongs to a guard page.

Parameters:
  • address (int) - Memory address to query.
Returns: bool
True if the address belongs to a guard page.
Raises:
  • WindowsError - An exception is raised on error.

Note: Returns always False for kernel mode addresses.

is_address_readable(self, address)

source code 

Determines if an address belongs to a commited and readable page. The page may or may not have additional permissions.

Parameters:
  • address (int) - Memory address to query.
Returns: bool
True if the address belongs to a commited and readable page.
Raises:
  • WindowsError - An exception is raised on error.

Note: Returns always False for kernel mode addresses.

is_address_writeable(self, address)

source code 

Determines if an address belongs to a commited and writeable page. The page may or may not have additional permissions.

Parameters:
  • address (int) - Memory address to query.
Returns: bool
True if the address belongs to a commited and writeable page.
Raises:
  • WindowsError - An exception is raised on error.

Note: Returns always False for kernel mode addresses.

is_address_copy_on_write(self, address)

source code 

Determines if an address belongs to a commited, copy-on-write page. The page may or may not have additional permissions.

Parameters:
  • address (int) - Memory address to query.
Returns: bool
True if the address belongs to a commited, copy-on-write page.
Raises:
  • WindowsError - An exception is raised on error.

Note: Returns always False for kernel mode addresses.

is_address_executable(self, address)

source code 

Determines if an address belongs to a commited and executable page. The page may or may not have additional permissions.

Parameters:
  • address (int) - Memory address to query.
Returns: bool
True if the address belongs to a commited and executable page.
Raises:
  • WindowsError - An exception is raised on error.

Note: Returns always False for kernel mode addresses.

is_address_executable_and_writeable(self, address)

source code 

Determines if an address belongs to a commited, writeable and executable page. The page may or may not have additional permissions.

Looking for writeable and executable pages is important when exploiting a software vulnerability.

Parameters:
  • address (int) - Memory address to query.
Returns: bool
True if the address belongs to a commited, writeable and executable page.
Raises:
  • WindowsError - An exception is raised on error.

Note: Returns always False for kernel mode addresses.

get_memory_map(self, minAddr=None, maxAddr=None)

source code 

Produces a memory map to the process address space. Optionally restrict the map to the given address range.

Parameters:
  • minAddr (int) - (Optional) Starting address in address range to query.
  • maxAddr (int) - (Optional) Ending address in address range to query.
Returns: list( win32.MemoryBasicInformation )
List of memory region information objects.

See Also: mquery

get_mapped_filenames(self, memoryMap=None)

source code 

Retrieves the filenames for memory mapped files in the debugee.

Parameters:
Returns: dict( int → str )
Dictionary mapping memory addresses to file names. Native filenames are converted to Win32 filenames when possible.

take_memory_snapshot(self, minAddr=None, maxAddr=None)

source code 

Takes a snapshot of the memory contents of the process.

Parameters:
  • minAddr (int) - (Optional) Starting address in address range to query.
  • maxAddr (int) - (Optional) Ending address in address range to query.
Returns: list( win32.MemoryBasicInformation )
List of memory region information objects. Two extra properties are added to these objects:
  • filename: Mapped filename, or None.
  • content: Memory contents, or None.

restore_memory_snapshot(self, snapshot)

source code 

Attempts to restore the memory state as it was when the given snapshot was taken.

Parameters:
Raises:
  • WindowsError - An error occured while restoring the snapshot.
  • RuntimeError - An error occured while restoring the snapshot.

Warning: Currently only the memory contents, state and protect bits are restored. Under some circumstances this method may fail (for example if memory was freed and then reused by a mapped file).