1.1.12. plugins

1.1.12.1. Classes

class CatalogCacheManager(cache_file)[source]

Bases: object

Manager to handle cache information for catalogs. Cache entries are stored as dictionaries with metadata information and the catalog data under the “value” key.

__init__(cache_file)[source]

Initialize self. See help(type(self)) for accurate signature.

get_catalog_by_id(catalog_id)[source]

Return the catalog cache data for the specified catalog ID.

Parameters:catalog_id (str) – The ID of the catalog to look up in the cache.
Returns:The cache entry for the catalog or None if the catalog was not found.
Return type:dict
get_catalog_by_url(catalog_url)[source]

Return the catalog cache data for the specified catalog URL.

Parameters:catalog_url (str) – The URL of the catalog to look up in the cache.
Returns:The cache entry for the catalog or None if the catalog was not found.
Return type:dict
class ClientCatalogManager(user_data_path, manager_type='plugins/client', *args, **kwargs)[source]

Bases: king_phisher.catalog.CatalogManager

Base manager for handling Catalogs.

__init__(user_data_path, manager_type='plugins/client', *args, **kwargs)[source]

Initialize self. See help(type(self)) for accurate signature.

add_catalog(catalog, catalog_url, cache=False)[source]

Adds the specified catalog to the manager and stores the associated source URL for caching.

Parameters:
  • catalog (Catalog) – The catalog to add to the cache manager.
  • catalog_url (str) – The URL from which the catalog was loaded.
  • cache (bool) – Whether or not the catalog should be saved to the cache.
Returns:

The catalog.

Return type:

Catalog

catalog_ids()[source]

The key names of the catalogs in the manager.

Returns:The catalogs IDs in the manager instance.
Return type:tuple
compatibility(catalog_id, repo_id, plugin_name)[source]

Checks the compatibility of a plugin.

Parameters:
  • catalog_id (str) – The catalog id associated with the plugin.
  • repo_id (str) – The repository id associated with the plugin.
  • plugin_name (str) – The name of the plugin.
Returns:

Tuple of packages and if the requirements are met.

Return type:

tuple

get_cache()[source]

Returns the catalog cache.

Returns:The catalog cache.
Return type:CatalogCacheManager
get_collection(catalog_id, repo_id)[source]

Returns the manager type of the plugin collection of the requested catalog and repository.

Parameters:
  • catalog_id (str) – The name of the catalog the repo belongs to
  • repo_id (str) – The id of the repository requested.
Returns:

The the collection of manager type from the specified catalog and repository.

install_plugin(catalog_id, repo_id, plugin_id, install_path)[source]

Installs the specified plugin to the desired plugin path.

Parameters:
  • catalog_id (str) – The id of the catalog of the desired plugin to install.
  • repo_id (str) – The id of the repository of the desired plugin to install.
  • plugin_id (str) – The id of the plugin to install.
  • install_path (str) – The path to install the plugin too.
is_compatible(catalog_id, repo_id, plugin_name)[source]

Checks the compatibility of a plugin.

Parameters:
  • catalog_id – The catalog id associated with the plugin.
  • repo_id – The repository id associated with the plugin.
  • plugin_name – The name of the plugin.
Returns:

Whether or not it is compatible.

Return type:

bool

save_cache(catalog, catalog_url)[source]

Saves the catalog or catalogs in the manager to the cache.

Parameters:catalog – The Catalog to save.
class ClientOptionBoolean(name, *args, **kwargs)[source]

Bases: king_phisher.client.plugins.ClientOptionMixin, king_phisher.plugins.OptionBoolean

__init__(name, *args, **kwargs)[source]
Parameters:
  • name (str) – The name of this option.
  • description (str) – The description of this option.
  • default – The default value of this option.
  • display_name (str) – The name to display in the UI to the user for this option.
get_widget(_, value)[source]

Create a widget suitable for configuring this option. This is meant to allow subclasses to specify and create an appropriate widget type.

Parameters:
  • application (Gtk.Application) – The parent application for this object.
  • value – The initial value to set for this widget.
Returns:

The widget for the user to set the option with.

Return type:

Gtk.Widget

get_widget_value(widget)[source]

Get the value of a widget previously created with get_widget().

Parameters:widget (Gtk.Widget) – The widget from which to retrieve the value from for this option.
Returns:The value for this option as set in the widget.
set_widget_value(widget, value)[source]

Set the value of a widget.

Parameters:widget (Gtk.Widget) – The widget whose value is to set for this option.
class ClientOptionEnum(name, *args, **kwargs)[source]

Bases: king_phisher.client.plugins.ClientOptionMixin, king_phisher.plugins.OptionEnum

__init__(name, *args, **kwargs)[source]
Parameters:
  • name (str) – The name of this option.
  • description (str) – The description of this option.
  • choices (tuple) – The supported values for this option.
  • default – The default value of this option.
  • display_name (str) – The name to display in the UI to the user for this option
get_widget(_, value)[source]

Create a widget suitable for configuring this option. This is meant to allow subclasses to specify and create an appropriate widget type.

Parameters:
  • application (Gtk.Application) – The parent application for this object.
  • value – The initial value to set for this widget.
Returns:

The widget for the user to set the option with.

Return type:

Gtk.Widget

get_widget_value(widget)[source]

Get the value of a widget previously created with get_widget().

Parameters:widget (Gtk.Widget) – The widget from which to retrieve the value from for this option.
Returns:The value for this option as set in the widget.
set_widget_value(widget, value)[source]

Set the value of a widget.

Parameters:widget (Gtk.Widget) – The widget whose value is to set for this option.
class ClientOptionInteger(name, *args, **kwargs)[source]

Bases: king_phisher.client.plugins.ClientOptionMixin, king_phisher.plugins.OptionInteger

__init__(name, *args, **kwargs)[source]
Parameters:
  • name (str) – The name of this option.
  • description (str) – The description of this option.
  • default – The default value of this option.
  • display_name (str) – The name to display in the UI to the user for this option.
  • adjustment (Gtk.Adjustment) – The adjustment details of the options value.
get_widget(_, value)[source]

Create a widget suitable for configuring this option. This is meant to allow subclasses to specify and create an appropriate widget type.

Parameters:
  • application (Gtk.Application) – The parent application for this object.
  • value – The initial value to set for this widget.
Returns:

The widget for the user to set the option with.

Return type:

Gtk.Widget

get_widget_value(widget)[source]

Get the value of a widget previously created with get_widget().

Parameters:widget (Gtk.Widget) – The widget from which to retrieve the value from for this option.
Returns:The value for this option as set in the widget.
set_widget_value(_, value)[source]

Set the value of a widget.

Parameters:widget (Gtk.Widget) – The widget whose value is to set for this option.
class ClientOptionMixin(name, *args, **kwargs)[source]

Bases: object

A mixin for options used by plugins for the client application. It provides additional methods for creating GTK widgets for the user to set the option’s value as well as retrieve it.

__init__(name, *args, **kwargs)[source]
Parameters:
  • name (str) – The name of this option.
  • description (str) – The description of this option.
  • default – The default value of this option.
  • display_name (str) – The name to display in the UI to the user for this option.
get_widget(application, value)[source]

Create a widget suitable for configuring this option. This is meant to allow subclasses to specify and create an appropriate widget type.

Parameters:
  • application (Gtk.Application) – The parent application for this object.
  • value – The initial value to set for this widget.
Returns:

The widget for the user to set the option with.

Return type:

Gtk.Widget

get_widget_value(widget)[source]

Get the value of a widget previously created with get_widget().

Parameters:widget (Gtk.Widget) – The widget from which to retrieve the value from for this option.
Returns:The value for this option as set in the widget.
set_widget_value(widget, value)[source]

Set the value of a widget.

Parameters:widget (Gtk.Widget) – The widget whose value is to set for this option.
class ClientOptionPath(name, *args, **kwargs)[source]

Bases: king_phisher.client.plugins.ClientOptionString

__init__(name, *args, **kwargs)[source]
Parameters:
  • name (str) – The name of this option.
  • description (str) – The description of this option.
  • default – The default value of this option.
  • display_name (str) – The name to display in the UI to the user for this option.
  • path_type (str) – The type of the path to select, either ‘directory’, ‘file-open’ or ‘file-save’.
get_widget(application, value)[source]

Create a widget suitable for configuring this option. This is meant to allow subclasses to specify and create an appropriate widget type.

Parameters:
  • application (Gtk.Application) – The parent application for this object.
  • value – The initial value to set for this widget.
Returns:

The widget for the user to set the option with.

Return type:

Gtk.Widget

get_widget_value(widget)[source]

Get the value of a widget previously created with get_widget().

Parameters:widget (Gtk.Widget) – The widget from which to retrieve the value from for this option.
Returns:The value for this option as set in the widget.
set_widget_value(widget, value)[source]

Set the value of a widget.

Parameters:widget (Gtk.Widget) – The widget whose value is to set for this option.
class ClientOptionPort(*args, **kwargs)[source]

Bases: king_phisher.client.plugins.ClientOptionInteger

__init__(*args, **kwargs)[source]
Parameters:
  • name (str) – The name of this option.
  • description (str) – The description of this option.
  • default – The default value of this option.
  • display_name (str) – The name to display in the UI to the user for this option.
get_widget(_, value)[source]

Create a widget suitable for configuring this option. This is meant to allow subclasses to specify and create an appropriate widget type.

Parameters:
  • application (Gtk.Application) – The parent application for this object.
  • value – The initial value to set for this widget.
Returns:

The widget for the user to set the option with.

Return type:

Gtk.Widget

get_widget_value(widget)[source]

Get the value of a widget previously created with get_widget().

Parameters:widget (Gtk.Widget) – The widget from which to retrieve the value from for this option.
Returns:The value for this option as set in the widget.
set_widget_value(_, value)[source]

Set the value of a widget.

Parameters:widget (Gtk.Widget) – The widget whose value is to set for this option.
class ClientOptionString(name, *args, **kwargs)[source]

Bases: king_phisher.client.plugins.ClientOptionMixin, king_phisher.plugins.OptionString

__init__(name, *args, **kwargs)[source]

Changed in version 1.9.0b5: Added the multiline parameter.

Parameters:
  • name (str) – The name of this option.
  • description (str) – The description of this option.
  • default – The default value of this option.
  • display_name (str) – The name to display in the UI to the user for this option.
  • multiline (bool) – Whether or not this option allows multiple lines of input.
get_widget(_, value)[source]

Create a widget suitable for configuring this option. This is meant to allow subclasses to specify and create an appropriate widget type.

Parameters:
  • application (Gtk.Application) – The parent application for this object.
  • value – The initial value to set for this widget.
Returns:

The widget for the user to set the option with.

Return type:

Gtk.Widget

get_widget_value(widget)[source]

Get the value of a widget previously created with get_widget().

Parameters:widget (Gtk.Widget) – The widget from which to retrieve the value from for this option.
Returns:The value for this option as set in the widget.
set_widget_value(widget, value)[source]

Set the value of a widget.

Parameters:widget (Gtk.Widget) – The widget whose value is to set for this option.
class ClientPlugin(application)[source]

Bases: king_phisher.plugins.PluginBase

The base object to be inherited by plugins that are loaded into the King Phisher client. This provides a convenient interface for interacting with the runtime.

add_menu_item(menu_path, handler=None)[source]

Add a new item into the main menu bar of the application. Menu items created through this method are automatically removed when the plugin is disabled. If no handler is specified, the menu item will be a separator, otherwise handler will automatically be connected to the menu item’s activate signal.

Parameters:
  • menu_path (str) – The path to the menu item, delimited with > characters.
  • handler – The optional callback function to be connected to the new Gtk.MenuItem instance’s activate signal.
Returns:

The newly created and added menu item.

Return type:

Gtk.MenuItem

add_submenu(menu_path)[source]

Add a submenu into the main menu bar of the application. Submenus created through this method are automatically removed when the plugin is disabled.

Parameters:menu_path (str) – The path to the submenu, delimited with > characters.
Returns:The newly created and added menu item.
Return type:Gtk.MenuItem
application = None[source]

A reference to the KingPhisherClientApplication.

config[source]

A dictionary that can be used by this plugin for persistent storage of it’s configuration.

render_template_string(template_string, target=None, description='string', log_to_mailer=True)[source]

Render the specified template_string in the message environment. If an error occurs during the rendering process, a message will be logged and None will be returned. If log_to_mailer is set to True then a message will also be displayed in the message send tab of the client.

New in version 1.9.0b5.

Parameters:
  • template_string (str) – The string to render as a template.
  • target (MessageTarget) – An optional target to pass to the rendering environment.
  • description (str) – A keyword to use to identify the template string in error messages.
  • log_to_mailer (bool) – Whether or not to log to the message send tab as well.
Returns:

The rendered string or None if an error occurred.

Return type:

str

signal_connect(name, handler, gobject=None, after=False)[source]

Connect handler to a signal by name to an arbitrary GObject. Signals connected through this method are automatically cleaned up when the plugin is disabled. If no GObject is specified, the application instance is used.

Warning

If the signal needs to be disconnected manually by the plugin, this method should not be used. Instead the handler id should be kept as returned by the GObject’s native connect method.

Parameters:
  • name (str) – The name of the signal.
  • handler (function) – The function to be invoked with the signal is emitted.
  • gobject – The object to connect the signal to.
  • after (bool) – Whether to call the user specified handler after the default signal handler or before.
signal_connect_server_event(name, handler, event_types, attributes)[source]

Connect handler to the server signal with name. This method is similar to signal_connect() but also sets up the necessary event subscriptions to ensure that the handler will be called. These event subscriptions are automatically cleaned up when the plugin is disabled.

Warning

Server events are emitted based on the client applications event subscriptions. This means that while handler will be called for the event types specified, it may also be called for additional unspecified event types if other plugins have subscribed to them. This means that it is important to check the event type within the handler itself and react as necessary. To avoid this simply use the event_type_filter() decorator for the handler function.

Parameters:
  • name (str) – The name of the signal.
  • handler – The function to be invoked with the signal is emitted.
  • event_types (list) – A list of sub-types for the corresponding event.
  • attributes (list) – A list of attributes of the event object to be sent to the client.
class ClientPluginMailerAttachment(*args, **kwargs)[source]

Bases: king_phisher.client.plugins.ClientPlugin

The base object to be inherited by plugins that intend to modify attachment files such as for inserting the tracking URL into them. Plugins which inherit from this base class must override the process_attachment_file() method which will automatically be called for each target a user is sending messages to.

__init__(*args, **kwargs)[source]

Initialize self. See help(type(self)) for accurate signature.

process_attachment_file(input_path, output_path, target)[source]

This function is automatically called for each target that a user is sending messages to. This method is intended to process the specified attachment file. This method removes the need to manually cleanup the output_path because it is handled automatically as necessary.

Parameters:
  • input_path (str) – The path to the input file to process. This path is guaranteed to be an existing file that is readable.
  • output_path (str) – The path to optionally write the output file to. This path may or may not be the same as input_path. If the plugin needs to rename the file, to for example change the extension, then the new output_path must be returned.
  • target (MessageTarget) – The target information for the messages intended recipient.
Returns:

None or an updated value for output_path in the case that the plugin renames it.

class ClientPluginManager(path, application)[source]

Bases: king_phisher.plugins.PluginManagerBase

The manager for plugins loaded into the King Phisher client application.