pyplugins.wrappers.osi_wrap module

osi_wrap.py - Wrappers for process memory mappings (Operating System Introspection)

This module provides Pythonic wrappers for handling process memory mappings, typically as returned by a plugin or API that exposes Linux process memory map information. The wrappers are designed to make it easy to inspect, filter, and display memory mappings, such as those found in /proc/<pid>/maps.

Overview

This module defines two main classes: - MappingWrapper: Wraps a single memory mapping, providing properties for permissions, addresses, and device info. - MappingsWrapper: Wraps a list of MappingWrapper objects, providing search and display utilities.

These wrappers are useful for analyzing process memory layouts, debugging, or building tools that need to inspect memory regions of Linux processes. They abstract away the raw dictionary or struct data and provide convenient Pythonic accessors and search methods.

Typical Usage

Suppose you have a plugin or API that returns a list of memory mapping dictionaries for a process (e.g., from /proc/<pid>/maps or a similar source):

from wrappers.osi_wrap import MappingWrapper, MappingsWrapper

# Example: plugin.get_mappings() returns a list of dicts, one per mapping
raw_mappings = plugin.get_mappings()  # Each dict should have keys: flags, base, size, dev, pgoff, inode, name
mappings = [MappingWrapper(m) for m in raw_mappings]
all_mappings = MappingsWrapper(mappings)

You can then perform various queries and inspections:

# Find a mapping by address:
mapping = all_mappings.get_mapping_by_addr(0x7f1234567000)
if mapping:
    print(f"Permissions: {mapping.perms}, Name: {mapping.name}")

# List all mappings for a library:
libc_maps = all_mappings.get_mappings_by_name('libc')
for m in libc_maps:
    print(m)

# Print all mappings in a format similar to /proc/<pid>/maps:
print(all_mappings)

The MappingWrapper exposes properties such as .perms, .start, .end, .dev_major, .dev_minor, and .name, making it easy to work with mapping attributes.

Classes

• MappingWrapper: Wraps a single memory mapping, providing properties for permissions, addresses, and device info.

• MappingsWrapper: Wraps a list of MappingWrapper objects, providing search and display utilities.

class pyplugins.wrappers.osi_wrap.MappingWrapper(obj)

Bases: Wrapper

Wraps a single process memory mapping, providing convenient properties for permissions, addresses, and device information.

Attributes:

flags (int): Bitmask of mapping permissions and flags. base (int): Start address of the mapping. size (int): Size of the mapping in bytes. dev (int): Device number (major:minor) of the mapping. pgoff (int): Offset into the mapped file. inode (int): Inode number of the mapped file. name (str): Name or path of the mapped file.

Parameters:

obj (Any)

property dev_major: int

Return the major number of the mapping. In Linux, the major number is in the high 12 bits of dev.

property dev_minor: int

Return the minor number of the mapping. In Linux, the minor number is in the low 20 bits of dev.

property end: int

Return the end address of the mapping.

property exec: bool

Check if the mapping is executable.

property executable: bool

Check if the mapping is executable.

get_addr_offset(addr)

Return the offset of the address within the mapping.

Parameters:

addr (int)

Return type:

int | None

property perms: str

Return the permissions of the mapping.

property read: bool

Check if the mapping is readable.

property share: bool

Check if the mapping is shareable.

property start: int

Return the start address of the mapping.

property write: bool

Check if the mapping is writable.

class pyplugins.wrappers.osi_wrap.MappingsWrapper(data, wrapper_cls=<class 'wrappers.generic.Wrapper'>)

Bases: ArrayWrapper

Wraps a list of MappingWrapper objects, providing utilities to search and display memory mappings.

Methods:

get_mapping_by_addr(addr): Return the mapping containing the given address. get_mappings_by_name(name): Return all mappings whose name contains the given string.

Parameters:

• data (Sequence[Any])

• wrapper_cls (Type[T])

get_first_mapping_by_name(name)

Find the first (lowest in memory) mapping whose name contains the given string.

Parameters:

name (str)

Return type:

MappingWrapper | None

get_mapping_by_addr(addr)

Find the mapping for a given address.

Parameters:

addr (int)

Return type:

MappingWrapper | None

get_mappings_by_name(name)

Find all mappings whose name contains the given string.

Parameters:

name (str)

Return type:

List[MappingWrapper]