Plugins

Plugin

Base class for all pwninit plugins.

Plugins must inherit from this class and implement the provide and/or setup methods. Plugins can also define provide_args and setup_args to specify CLI arguments for each role.

Attributes:

Name	Type	Description
name	str	The name of the plugin.
description	str	A brief description of the plugin's purpose.
provide_args	list	List of argument dictionaries for the provide role.
setup_args	list	List of argument dictionaries for the setup role.

Source code in src/pwninit/plugins/__init__.py

class Plugin:
    """
    Base class for all pwninit plugins.

    Plugins must inherit from this class and implement the `provide` and/or `setup` methods.
    Plugins can also define `provide_args` and `setup_args` to specify CLI arguments for each role.

    Attributes:
        name (str): The name of the plugin.
        description (str): A brief description of the plugin's purpose.
        provide_args (list): List of argument dictionaries for the `provide` role.
        setup_args (list): List of argument dictionaries for the `setup` role.
    """

    name = None
    description = ""
    provide_args = []
    setup_args = []

    def provide(self, args, path):
        """
        Provide functionality for the plugin (e.g., generate payloads, files, or configurations).

        Args:
            args: Parsed arguments for the `provide` role.
            path: Path to the target binary or directory.

        Raises:
            NotImplementedError: If not overridden by the subclass.
        """
        raise NotImplementedError

    def setup(self, args, bins):
        """
        Set up the environment or perform pre-exploitation tasks (e.g., start a service, patch a binary).

        Args:
            args: Parsed arguments for the `setup` role.
            bins: List of binaries to set up.

        Raises:
            NotImplementedError: If not overridden by the subclass.
        """
        raise NotImplementedError

    @property
    def has_provide(self):
        """
        Check if the plugin implements the `provide` method.

        Returns:
            bool: True if the plugin overrides `provide`, False otherwise.
        """
        return type(self).provide is not Plugin.provide

    @property
    def has_setup(self):
        """
        Check if the plugin implements the `setup` method.

        Returns:
            bool: True if the plugin overrides `setup`, False otherwise.
        """
        return type(self).setup is not Plugin.setup

has_provide property

Check if the plugin implements the provide method.

Returns:

Name	Type	Description
bool		True if the plugin overrides provide, False otherwise.

has_setup property

Check if the plugin implements the setup method.

Returns:

Name	Type	Description
bool		True if the plugin overrides setup, False otherwise.

provide(args, path)

Provide functionality for the plugin (e.g., generate payloads, files, or configurations).

Parameters:

Name	Type	Description	Default
args		Parsed arguments for the provide role.	required
path		Path to the target binary or directory.	required

Raises:

Type	Description
NotImplementedError	If not overridden by the subclass.

Source code in src/pwninit/plugins/__init__.py

def provide(self, args, path):
    """
    Provide functionality for the plugin (e.g., generate payloads, files, or configurations).

    Args:
        args: Parsed arguments for the `provide` role.
        path: Path to the target binary or directory.

    Raises:
        NotImplementedError: If not overridden by the subclass.
    """
    raise NotImplementedError

setup(args, bins)

Set up the environment or perform pre-exploitation tasks (e.g., start a service, patch a binary).

Parameters:

Name	Type	Description	Default
args		Parsed arguments for the setup role.	required
bins		List of binaries to set up.	required

Raises:

Type	Description
NotImplementedError	If not overridden by the subclass.

Source code in src/pwninit/plugins/__init__.py

def setup(self, args, bins):
    """
    Set up the environment or perform pre-exploitation tasks (e.g., start a service, patch a binary).

    Args:
        args: Parsed arguments for the `setup` role.
        bins: List of binaries to set up.

    Raises:
        NotImplementedError: If not overridden by the subclass.
    """
    raise NotImplementedError

arg(name, **kwargs)

Helper function to define a plugin argument.

Parameters:

Name	Type	Description	Default
name	str	The name of the argument.	required
**kwargs		Additional keyword arguments for argparse.ArgumentParser.add_argument.	{}

Returns:

Name	Type	Description
dict		A dictionary representing the argument configuration.

Source code in src/pwninit/plugins/__init__.py

def arg(name, **kwargs):
    """
    Helper function to define a plugin argument.

    Args:
        name (str): The name of the argument.
        **kwargs: Additional keyword arguments for `argparse.ArgumentParser.add_argument`.

    Returns:
        dict: A dictionary representing the argument configuration.
    """
    return {"name": name, **kwargs}

print_plugin_list()

Print a list of all available plugins and their usage information.

Source code in src/pwninit/plugins/__init__.py

def print_plugin_list():
    """
    Print a list of all available plugins and their usage information.
    """
    plugins = _list_plugins()
    if not plugins:
        log.info("No plugins found")
        return

    items = list(plugins.items())
    for i, (name, (plugin, roles, source)) in enumerate(items):
        print(f"{name}: {plugin.description}")

        if "provider" in roles:
            _build_parser(plugin, "provide").print_usage()
            for a in plugin.provide_args:
                print("      %s" % _format_arg(a))
            print()

        if "utility" in roles:
            _build_parser(plugin, "setup").print_usage()
            for a in plugin.setup_args:
                print("      %s" % _format_arg(a))
            print()

        if i < len(items) - 1:
            print(" " * 20 + "─" * 20)

run_plugins(args, role, settings)

Run a plugin with the specified role and arguments.

Parameters:

Name	Type	Description	Default
args	list	CLI arguments, where the first element is the plugin name.	required
role	str	The role (provide or setup).	required
settings		Additional settings or context for the plugin.	required

Returns:

Name	Type	Description
Any		The result of the plugin's provide or setup method, or None if the plugin fails.

Source code in src/pwninit/plugins/__init__.py

def run_plugins(args, role, settings):
    """
    Run a plugin with the specified role and arguments.

    Args:
        args (list): CLI arguments, where the first element is the plugin name.
        role (str): The role (`provide` or `setup`).
        settings: Additional settings or context for the plugin.

    Returns:
        Any: The result of the plugin's `provide` or `setup` method, or None if the plugin fails.
    """
    plugin = _resolve(args[0])
    if plugin is None:
        log.error("Plugin '%s' not found" % args[0])
        return None

    parsed = _parse_plugin_args(plugin, args[1:], role)
    if parsed is None:
        return None

    if role == "provide" and plugin.has_provide:
        return plugin.provide(parsed, settings)
    elif role == "setup" and plugin.has_setup:
        return plugin.setup(parsed, settings)
    else:
        log.error("Plugin '%s' has no %s()" % (args[0], role))
        return None