pyplugins.apis.mem module¶

Memory Access Plugin (mem.py)¶

This module provides the Mem plugin for the Penguin framework, enabling safe and efficient reading and writing of guest memory via the hypervisor portal. It abstracts low-level memory operations, supporting chunked access, endianness handling, and architecture-specific pointer sizes. The plugin is designed to work with both PANDA and non-PANDA environments, and provides utilities for reading and writing bytes, integers, pointers, strings, arrays, and more.

Features¶

Read and write arbitrary bytes to guest memory.
Read and write integers, longs, words, and pointers with correct endianness.
Read and write null-terminated and UTF-8 strings.
Read arrays of integers and lists of pointers or strings.
Memory comparison and memset utilities.
Handles chunking for large memory operations.
Supports both PANDA and hypervisor portal backends.

Example Usage¶

from penguin import plugins

# Read 16 bytes from address 0x1000
data = yield from plugins.mem.read_bytes(0x1000, 16)

# Write a string to memory
yield from plugins.mem.write_str(0x2000, "hello world")

# Read a pointer-sized value
ptr = yield from plugins.mem.read_ptr(0x3000)

# Compare two memory regions
equal = yield from plugins.mem.memcmp(0x4000, 0x5000, 32)

class pyplugins.apis.mem.Mem[source]¶

Bases: Plugin

Mem Plugin¶

Provides guest memory access and manipulation via the hypervisor portal.

Attributes¶

endian_formatstr: Endianness format for struct packing/unpacking.
try_pandabool: Whether to attempt PANDA-based memory access.

copy_buf_guest(data)[source]¶

Copy a buffer into guest kernel memory and return the guest address.

Uses the HYPER_OP_COPY_BUF_GUEST portal command to allocate and copy a buffer into guest kernel memory. Handles chunking if the buffer is larger than the portal region.

Parameters¶

databytes: The data to copy into guest memory.

Returns¶

int: Guest address of the copied buffer, or 0 on failure.

Parameters:: data (bytes)
Return type:: Generator[Any, Any, int]

memcmp(addr1, addr2, size, pid=None)[source]¶

Compare two regions of guest memory for equality.

Compares two regions of guest memory for equality.

Parameters¶

addr1int: First address.
addr2int: Second address.
sizeint: Number of bytes to compare.
pidint, optional: Process ID for context.

Returns¶

bool: True if memory regions are equal, False otherwise.

Parameters:

addr1 (int)
addr2 (int)
size (int)
pid (int | None)

Return type:

Generator[Any, Any, bool]

memset(addr, value, size, pid=None)[source]¶

Set a region of guest memory to a specific byte value.

Sets a region of guest memory to a specific byte value.

Parameters¶

addrint: Address to start setting.
valueint: Byte value to set (0-255).
sizeint: Number of bytes to set.
pidint, optional: Process ID for context.

Returns¶

int: Number of bytes written.

Parameters:

addr (int)
value (int)
size (int)
pid (int | None)

Return type:

Generator[Any, Any, int]

read_byte(addr, pid=None)[source]¶

Read a single byte from guest memory.

Reads a single byte from guest memory.

Parameters¶

addrint: Address to read from.
pidint, optional: Process ID for context.

Returns¶

int or None: Byte value read (0-255), or None on failure.

Parameters:

addr (int)
pid (int | None)

Return type:

Generator[Any, Any, int | None]

read_bytes(addr, size, pid=None)[source]¶

Reads bytes from guest memory. Optimized with a Fast Path for single-chunk reads.

Parameters:

addr (int)
size (int)
pid (int | None)

Return type:

Generator[Any, Any, bytes]

read_bytes_panda(cpu, addr, size)[source]¶

Optimized PANDA read.

Parameters:

addr (int)
size (int)

Return type:

bytes

read_char_ptrlist(addr, length, pid=None)[source]¶

Read a list of null-terminated strings from a list of pointers.

Reads a list of null-terminated strings from a list of pointers in guest memory.

Parameters¶

addrint: Address to start reading pointer list from.
lengthint: Maximum number of pointers to read.
pidint, optional: Process ID for context.

Returns¶

list of str: List of strings read from memory.

Parameters:

addr (int)
length (int)
pid (int | None)

Return type:

Generator[Any, Any, List[str]]

read_int(addr, pid=None)[source]¶

Read a 4-byte integer from guest memory.

Reads a 4-byte integer from guest memory at a specified address.

Parameters¶

addrint: Address to read from.
pidint, optional: Process ID for context.

Returns¶

int or None: Integer value read, or None on failure.

Parameters:

addr (int)
pid (int | None)

Return type:

Generator[Any, Any, int | None]

read_int_array(addr, count, pid=None)[source]¶

Read an array of 4-byte integers from guest memory.

Reads an array of 4-byte integers from guest memory.

Parameters¶

addrint: Address to start reading from.
countint: Number of integers to read.
pidint, optional: Process ID for context.

Returns¶

list of int: List of integers read from memory.

Parameters:

addr (int)
count (int)
pid (int | None)

Return type:

Generator[Any, Any, List[int]]

read_long(addr, pid=None)[source]¶

Read an 8-byte long integer from guest memory.

Reads an 8-byte long integer from guest memory at a specified address.

Parameters¶

addrint: Address to read from.
pidint, optional: Process ID for context.

Returns¶

int or None: Long value read, or None on failure.

Parameters:

addr (int)
pid (int | None)

Return type:

Generator[Any, Any, int | None]

read_long_array(addr, count, pid=None)[source]¶

Read an array of 8-byte long integers from guest memory.

Reads an array of 8-byte long integers from guest memory.

Parameters¶

addrint: Address to start reading from.
countint: Number of longs to read.
pidint, optional: Process ID for context.

Returns¶

list of int: List of long integers read from memory.

Parameters:

addr (int)
count (int)
pid (int | None)

Return type:

Generator[Any, Any, List[int]]

read_ptr(addr, pid=None)[source]¶

Read a pointer-sized value from guest memory.

Reads a pointer-sized value from guest memory at a specified address.

Parameters¶

addrint: Address to read from.
pidint, optional: Process ID for context.

Returns¶

int or None: Pointer value read, or None on failure.

Parameters:

addr (int)
pid (int | None)

Return type:

Generator[Any, Any, int | None]

read_ptr_array(addr, pid=None)[source]¶

Read a NULL-terminated array of pointers to strings from guest memory using the portal’s optimized handler.

Uses the HYPER_OP_READ_PTR_ARRAY portal command for efficient reading.

Parameters¶

addrint: Address of the pointer array in guest memory.
pidint, optional: Process ID for context.

Returns¶

list of str: List of strings read from the array.

Parameters:

addr (int)
pid (int | None)

Return type:

Generator[Any, Any, List[str]]

read_ptrlist(addr, length, pid=None)[source]¶

Read a list of pointer values from guest memory.

Reads a list of pointer values from guest memory.

Parameters¶

addrint: Address to start reading from.
lengthint: Maximum number of pointers to read.
pidint, optional: Process ID for context.

Returns¶

list of int: List of pointer values.

Parameters:

addr (int)
length (int)
pid (int | None)

Return type:

Generator[Any, Any, List[int]]

read_str(addr, pid=None)[source]¶

Read a null-terminated string from guest memory.

Reads a null-terminated string from guest memory at a specified address. Optimized to read in page-aligned chunks to minimize overhead, with fallback to PortalCmd if memory is unmapped in the emulator.

Parameters¶

addrint: Address to read from.
pidint, optional: Process ID for context.

Returns¶

str: String read from memory.

Parameters:

addr (int)
pid (int | None)

Return type:

Generator[Any, Any, str]

read_str_panda(cpu, addr)[source]¶

Read a null-terminated string from guest memory using PANDA only.

Reads a null-terminated string from guest memory at a specified address, using PANDA’s virtual_memory_read in page-aligned chunks. Never falls back to the portal.

Parameters¶

cpu : Any (CPUState) addr : int

Address to read from.

Returns¶

str: String read from memory.

Parameters:: addr (int)
Return type:: str

read_uint64_array(addr, count, pid=None)[source]¶

Read an array of 8-byte unsigned integers from guest memory.

Reads an array of 8-byte unsigned integers from guest memory.

Parameters¶

addrint: Address to start reading from.
countint: Number of uint64s to read.
pidint, optional: Process ID for context.

Returns¶

list of int: List of uint64s read from memory.

Parameters:

addr (int)
count (int)
pid (int | None)

Return type:

Generator[Any, Any, List[int]]

read_utf8_str(addr, pid=None)[source]¶

Read a null-terminated UTF-8 string from guest memory.

Reads a null-terminated UTF-8 string from guest memory at a specified address.

Parameters¶

addrint: Address to read from.
pidint, optional: Process ID for context.

Returns¶

str: UTF-8 string read from memory.

Parameters:

addr (int)
pid (int | None)

Return type:

Generator[Any, Any, str]

read_word(addr, pid=None)[source]¶

Read a 2-byte word from guest memory.

Reads a 2-byte word from guest memory.

Parameters¶

addrint: Address to read from.
pidint, optional: Process ID for context.

Returns¶

int or None: Word value read, or None on failure.

Parameters:

addr (int)
pid (int | None)

Return type:

Generator[Any, Any, int | None]

write_byte(addr, value, pid=None)[source]¶

Write a single byte to guest memory.

Writes a single byte to guest memory.

Parameters¶

addrint: Address to write to.
valueint: Byte value to write (0-255).
pidint, optional: Process ID for context.

Returns¶

int: Number of bytes written (should be 1).

Parameters:

addr (int)
value (int)
pid (int | None)

Return type:

Generator[Any, Any, int]

write_bytes(addr, data, pid=None)[source]¶

Write bytes to guest memory.

Writes bytes to guest memory at a specified address, handling chunking for large data.

Parameters¶

addrint: Address to write to.
databytes: Data to write.
pidint, optional: Process ID for context.

Returns¶

int: Number of bytes written.

Parameters:

addr (int)
data (bytes)
pid (int | None)

Return type:

Generator[Any, Any, int]

write_bytes_panda(cpu, addr, data)[source]¶

Write a bytearray into memory at the specified physical/virtual address

Parameters:

addr (int)
data (bytes)

Return type:

None

write_int(addr, value, pid=None)[source]¶

Write a 4-byte integer to guest memory.

Writes a 4-byte integer to guest memory at a specified address.

Parameters¶

addrint: Address to write to.
valueint: Integer value to write.
pidint, optional: Process ID for context.

Returns¶

int: Number of bytes written.

Parameters:

addr (int)
value (int)
pid (int | None)

Return type:

Generator[Any, Any, int]

write_int_array(addr, values, pid=None)[source]¶

Write an array of 4-byte integers to guest memory.

Writes an array of 4-byte integers to guest memory.

Parameters¶

addrint: Address to start writing to.
valueslist of int: List of integers to write.
pidint, optional: Process ID for context.

Returns¶

int: Number of bytes written.

Parameters:

addr (int)
values (List[int])
pid (int | None)

Return type:

Generator[Any, Any, int]

write_long(addr, value, pid=None)[source]¶

Write an 8-byte long integer to guest memory.

Writes an 8-byte long integer to guest memory at a specified address.

Parameters¶

addrint: Address to write to.
valueint: Long value to write.
pidint, optional: Process ID for context.

Returns¶

int: Number of bytes written.

Parameters:

addr (int)
value (int)
pid (int | None)

Return type:

Generator[Any, Any, int]

write_ptr(addr, value, pid=None)[source]¶

Write a pointer-sized value to guest memory.

Writes a pointer-sized value to guest memory at a specified address.

Parameters¶

addrint: Address to write to.
valueint: Pointer value to write.
pidint, optional: Process ID for context.

Returns¶

None

Parameters:

addr (int)
value (int)
pid (int | None)

Return type:

Generator[Any, Any, None]

write_str(addr, string, null_terminate=True, pid=None)[source]¶

Write a string to guest memory.

Writes a string to guest memory at a specified address, optionally null-terminated.

Parameters¶

addrint: Address to write to.
stringstr or bytes: String to write.
null_terminatebool, optional: Whether to append a null terminator (default: True).
pidint, optional: Process ID for context.

Returns¶

int: Number of bytes written.

Parameters:

addr (int)
string (str | bytes)
null_terminate (bool)
pid (int | None)

Return type:

Generator[Any, Any, int]

write_word(addr, value, pid=None)[source]¶

Write a 2-byte word to guest memory.

Writes a 2-byte word to guest memory.

Parameters¶

addrint: Address to write to.
valueint: Word value to write.
pidint, optional: Process ID for context.

Returns¶

int: Number of bytes written (should be 2).

Parameters:

addr (int)
value (int)
pid (int | None)

Return type:

Generator[Any, Any, int]