pyplugins.apis.osi module¶

OSI Plugin (osi.py) for Penguin¶

This module provides the OSI plugin for the Penguin framework, enabling coroutine-based access to guest OS state via the hypervisor portal. It allows querying of process information, file descriptors, memory mappings, process handles, arguments, and environment variables. The plugin is designed for advanced analysis, automation, and plugin interoperability.

Features¶

Retrieve process arguments, environment variables, and process names.
List open file descriptors and resolve their names.
Query memory mappings and locate mappings by address.
Fetch process handles and detailed process information.
All methods are coroutine-based and return wrapper objects or lists for further inspection.

Example Usage¶

from penguin import plugins

# Get process name
procname = yield from plugins.OSI.get_proc_name(pid)

# Get process arguments
args = yield from plugins.OSI.get_args(pid)

# Get environment variables
env = yield from plugins.OSI.get_env(pid)

# Get open file descriptors
fds = yield from plugins.OSI.get_fds(pid)

# Get memory mappings
mappings = yield from plugins.OSI.get_mappings(pid)

Purpose¶

The OSI plugin enables flexible, efficient, and scriptable access to guest OS state, supporting advanced analysis, automation, and plugin interoperability in the Penguin environment.

class pyplugins.apis.osi.OSI[source]¶

Bases: Plugin

OSI Plugin¶

Provides coroutine-based methods for querying OS-level information (processes, FDs, mappings) from the guest via the hypervisor portal.

Attributes¶

loggerobject: Logger for debug and error messages.

get_args(pid=None)[source]¶

Get the argument list for a process.

Parameters¶

pidint, optional: Process ID, or None for current process.

Returns¶

List[str]: List of argument strings (empty if not found).

Parameters:: pid (int | None)
Return type:: Generator[Any, None, List[str]]

get_env(pid=None)[source]¶

Get the environment variables for a process.

Parameters¶

pidint, optional: Process ID, or None for current process.

Returns¶

Dict[str, str]: Dictionary of environment variables (empty if not found).

Parameters:: pid (int | None)
Return type:: Generator[Any, None, Dict[str, str]]

get_fd_name(fd, pid=None)[source]¶

Get the filename for a specific file descriptor.

Uses the efficient get_fds function to retrieve information for a specific file descriptor.

Parameters¶

fdint: File descriptor number.
pidint, optional: Process ID, or None for current process.

Returns¶

str or None: The file descriptor name, or None if not found.

Parameters:

fd (int)
pid (int | None)

Return type:

Generator[Any, None, str | None]

get_fds(pid=None, start_fd=0, count=None)[source]¶

Retrieve file descriptors for a process.

Parameters¶

pidint, optional: Process ID, or None for current process.
start_fdint, optional: FD number to start listing from (default: 0).
countint, optional: Maximum number of file descriptors to return (None for all).

Returns¶

List[Wrapper]: List of file descriptor objects with fd and name properties (empty if not found).

Parameters:

pid (int | None)
start_fd (int)
count (int | None)

Return type:

Generator[Any, None, List[Wrapper]]

get_mapping_by_addr(addr)[source]¶

Get the memory mapping containing a specific address.

Parameters¶

addrint: Address to look up.

Returns¶

MappingWrapper or None: Mapping containing the address, or None if not found.

Parameters:: addr (int)
Return type:: Generator[Any, None, MappingWrapper | None]

get_mappings(pid=None)[source]¶

Get memory mappings for a process.

Parameters¶

pidint, optional: Process ID, or None for current process.

Returns¶

MappingsWrapper: Wrapper containing all memory mappings (empty if not found).

Parameters:: pid (int | None)
Return type:: Generator[Any, None, MappingsWrapper]

get_proc(pid=None)[source]¶

Get detailed process information for a process.

Parameters¶

pidint, optional: Process ID, or None for current process.

Returns¶

Wrapper or None: Process information wrapper object, or None if not found.

Parameters:: pid (int | None)
Return type:: Generator[Any, None, Wrapper | None]

get_proc_exe(pid=None)[source]¶

Get the full executable path for a process.

Parameters¶

pidint, optional: Process ID, or None for current process.

Returns¶

Wrapper or None: Process information wrapper object, or None if not found.

Parameters:: pid (int | None)
Return type:: Generator[Any, None, str | None]

get_proc_handles()[source]¶

Retrieve a list of process handles from the kernel.

Returns¶

List[Wrapper]: List of process handle objects with properties: pid, taskd, start_time (empty if not found).

Return type:: Generator[Any, None, List[Wrapper]]

get_proc_name(pid=None)[source]¶

Get the process name (first argument) for a process.

Parameters¶

pidint, optional: Process ID, or None for current process.

Returns¶

str: Process name or ‘[???]’ if not found.

Parameters:: pid (int | None)
Return type:: Generator[Any, None, str]