Skip to content

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 
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
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: argparse.Namespace, path: str) -> str:
        """
        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: argparse.Namespace, bins: dict) -> dict:
        """
        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) -> bool:
        """
        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) -> bool:
        """
        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 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 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 Namespace

Parsed arguments for the provide role.

 required
path str

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 
33
34
35
36
37
38
39
40
41
42
43
44
def provide(self, args: argparse.Namespace, path: str) -> str:
    """
    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 Namespace

Parsed arguments for the setup role.

 required
bins dict

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 
46
47
48
49
50
51
52
53
54
55
56
57
def setup(self, args: argparse.Namespace, bins: dict) -> dict:
    """
    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 Any

Additional keyword arguments for argparse.ArgumentParser.add_argument.

 {}

Returns:

Name Type Description
dict dict

A dictionary representing the argument configuration.
Source code in src/pwninit/plugins/__init__.py 
79
80
81
82
83
84
85
86
87
88
89
90
def arg(name: str, **kwargs: Any) -> dict:
    """
    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 
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
def print_plugin_list() -> None:
    """
    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 dict | str

Additional settings or context for the plugin.

 required

Returns:

Name Type Description
Any 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 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
def run_plugins(args: list, role: str, settings: dict|str) -> Any:
    """
    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