pyplugins.apis.execs module

Execs

This plugin provides a generic interface for monitoring process execution events in the guest. It subscribes to syscall events for both execve and execveat, extracts execution details (process name, arguments, environment), and publishes this information to listeners via the plugin event system. Other plugins can subscribe to these events for custom analysis, logging, or automation.

Arguments

• outdir (str): Output directory for any optional logging or artifacts.

Plugin Interface

Publishes exec_event with a dictionary containing execution details:

{
    'procname': str or None,      # Name of the executed program (target of exec), resolved via OSI if AT_EMPTY_PATH
    'proc': Wrapper,              # Process info wrapper for the process being exec'd
    'argv': list[str],            # Argument vector for the new program
    'envp': dict[str, str],       # Environment for the new program
    'raw_args': tuple,            # Raw syscall arguments to the handler
    'parent': Wrapper or None,    # Process info wrapper for the parent process
    'retval': int,                # Return value of the syscall (negative on failure)
}

Both execve and execveat syscalls are tracked and normalized into this unified event format.

Overall Purpose

The Execs plugin provides a flexible, extensible interface for tracking process execution events in the guest, enabling downstream plugins to implement their own analysis or response logic.

class pyplugins.apis.execs.Execs

Bases: Plugin

Execs Plugin

Monitors execve and execveat syscalls and publishes normalized execution events.

Publishes ‘exec_event’ with a dictionary containing:

procname (str or None): Name of the executed program (target of exec), resolved via OSI if AT_EMPTY_PATH proc (Wrapper): Process info wrapper for the process being exec’d argv (List[str]): Argument vector for the new program envp (Dict[str, str]): Environment for the new program raw_args (tuple): Raw syscall arguments to the handler parent (Wrapper or None): Process info wrapper for the parent process retval (int): Return value of the syscall (negative on failure)

on_execve(regs, proto, syscall, fname_ptr, argv_ptr, envp_ptr)

Callback for execve syscall. Delegates to shared handler.

Returns

None

Parameters:

• regs (PtRegsWrapper)

• proto (Any)

• syscall (int)

• fname_ptr (int)

• argv_ptr (int)

• envp_ptr (int)

Return type:

Generator[Any, None, None]

on_execveat(regs, proto, syscall, dirfd, fname_ptr, argv_ptr, envp_ptr, flags)

Callback for execveat syscall. Delegates to shared handler.

Returns

None

Parameters:

• regs (PtRegsWrapper)

• proto (Any)

• syscall (int)

• dirfd (int)

• fname_ptr (int)

• argv_ptr (int)

• envp_ptr (int)

• flags (int)

Return type:

Generator[Any, None, None]