pyplugins.apis.send_hypercall module

SendHypercall Plugin (send_hypercall.py) for Penguin

This module provides the SendHypercall plugin for the Penguin framework, enabling the registration and handling of custom hypercalls from the guest OS. It allows plugins to subscribe to specific hypercall events, receive arguments from the guest, process them, and return results back to the guest memory. The plugin is designed for extensibility and safe event-driven communication between guest and host.

Features

• Register and handle custom hypercall events from the guest.

• Safely read arguments and write results to guest memory.

• Supports both string and bytes output.

• Handles architecture-specific pointer sizes and endianness.

• Provides error handling and logging for robust operation.

Example Usage

from penguin import plugins

def my_hypercall_handler(arg1, arg2):
    # Process arguments and return (retval, output)
    return 0, f"Received: {arg1}, {arg2}"

# Direct registration
plugins.send_hypercall.subscribe("mycmd", my_hypercall_handler)

# Decorator usage
@plugins.send_hypercall.subscribe("mycmd2")
def my_hypercall_handler2(arg1):
    # Process arguments and return (retval, output)
    return 0, f"Handled by decorator: {arg1}"

# You can also use a bound method as a decorator:
class MyPlugin:
    @plugins.send_hypercall.subscribe("mycmd3")
    def my_method(self, arg):
        return 0, f"Handled in class: {arg}"

class pyplugins.apis.send_hypercall.SendHypercall

Bases: Plugin

SendHypercall Plugin

Handles registration and processing of custom hypercall events from the guest OS.

Attributes

outdirstr

Output directory for plugin data.

registered_eventsDict[str, Callable[…, Tuple[int, Union[str, bytes]]]]

Registered event handlers.

on_send_hypercall(cpu, buf_addr, buf_num_ptrs)

Handle an incoming hypercall from the guest.

Reads arguments from guest memory, dispatches to the registered handler, and writes the result back.

Parameters

cpuAny

CPU context from PANDA.

buf_addrint

Address of the pointer array in guest memory.

buf_num_ptrsint

Number of pointers in the array.

Returns

None

Parameters:

• cpu (Any)

• buf_addr (int)

• buf_num_ptrs (int)

Return type:

None

subscribe(event, callback=None)

Register a callback for a specific hypercall event.

Can be used as a decorator or called directly.

Parameters

eventstr

Event name to subscribe to.

callbackCallable[…, Tuple[int, Union[str, bytes]]], optional

Callback function that processes the event.

Raises

ValueError

If already subscribed to the event.

Returns

decorator or None

If used as a decorator, returns the decorator function. If called directly, returns None.

Parameters:

• event (str)

• callback (Callable[[...], Tuple[int, str | bytes]] | None)