2.3. GObject Signals¶

These signals can be used by the client API and plugins to subscribe to specific events. To explicitly connect after the default handler for a signal, use the connect_after method instead of connect. Some signals require a value to be returned by their handlers as noted.

2.3.1. Signal Flags¶

The “Signal flags” attribute of each of the signals describes certain attributes of their respective signals. See the GObject Signals documentation for more information including a detailed description of the signal emission process.

SIGNAL_RUN_FIRST:
SIGNAL_ACTION:	Signals with the `SIGNAL_ACTION` flag are safe to be emitted from arbitrary components within the application. These signals have default handlers which perform their action and are not stateful.
	Signals with the `SIGNAL_RUN_FIRST` flag execute the default handler before handlers which are connected with either the `connect()` or `connect_after()` methods. These signals therefor do not provide connected handlers with an opportunity to block the emission of the signal from the default handler.
SIGNAL_RUN_LAST:
	Signals with the `SIGNAL_RUN_LAST` flag execute the default function after handlers which are connected with the `connect()` method but before handlers which are connected with the `connect_after()` method. This provides connected handlers with an opportunity to block the default function by halting emissionof the signal by using the `emit_stop_by_name()` method.

Note

Plugins which connect to signals should use the signal_connect() method which by defaults uses connect() to connect the signal. Alternatively connect_after() can be used by setting the after keyword argument to True.

2.3.2. Application Signals¶

The following are the signals for the KingPhisherClientApplication object.

campaign-changed(campaign_id)¶

This signal is emitted when campaign attributes are changed. Subscribers to this signal can use it to update and refresh information for the modified campaign.

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	campaign_id (str) – The ID of the campaign whose information was changed.

campaign-created(campaign_id)¶

This signal is emitted after the user creates a new campaign id. Subscribers to this signal can use it to conduct an action after a new campaign id is created.

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	campaign_id (str) – The ID of the new campaign.

campaign-delete(campaign_id)¶

This signal is emitted when the user deletes a campaign. Subscribers to this signal can use it to conduct an action after the campaign is deleted.

Signal flags:	`SIGNAL_ACTION \| SIGNAL_RUN_LAST`
Parameters:	campaign_id (str) – The ID of the campaign.

campaign-set(old_campaign_id, new_campaign_id)¶

This signal is emitted when the user sets the current campaign. Subscribers to this signal can use it to update and refresh information for the current campaign. The config “campaign_id” and “campaign_name” keys have already been updated with the new values when this signal is emitted.

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	old_campaign_id (str) – The ID of the old campaign or None if the client is selecting one for the first time. new_campaign_id (str) – The ID of the new campaign.

config-load(load_defaults)¶

This signal is emitted when the client configuration is loaded from disk. This loads all of the clients settings used within the GUI.

Signal flags:	`SIGNAL_ACTION \| SIGNAL_RUN_LAST`
Parameters:	load_defaults (bool) – Load missing options from the template configuration file.

config-save()¶

This signal is emitted when the client configuration is written to disk. This saves all of the settings used within the GUI so they can be restored at a later point in time.

Signal flags:	`SIGNAL_ACTION \| SIGNAL_RUN_LAST`

credential-delete(row_ids)¶

This signal is emitted when the user deletes a credential entry. Subscribers to this signal can use it to conduct an action an entry is deleted.

Signal flags:	`SIGNAL_ACTION \| SIGNAL_RUN_LAST`
Parameters:	row_ids ([int, ..]) – The row IDs that are to be deleted.

exit()¶

This signal is emitted when the client is exiting. Subscribers can use it as a chance to clean up and save any remaining data. It is emitted before the client is disconnected from the server. At this point the exit operation can not be cancelled.

Signal flags:	`SIGNAL_ACTION \| SIGNAL_RUN_LAST`

exit-confirm()¶

This signal is emitted when the client has requested that the application exit. Subscribers to this signal can use it as a chance to display a warning dialog and cancel the operation.

Signal flags:	`SIGNAL_ACTION \| SIGNAL_RUN_LAST`

message-delete(row_ids)¶

This signal is emitted when the user deletes a message entry. Subscribers to this signal can use it to conduct an action an entry is deleted.

Signal flags:	`SIGNAL_ACTION \| SIGNAL_RUN_LAST`
Parameters:	row_ids ([str, ..]) – The row IDs that are to be deleted.

message-sent(target_uid, target_email)¶

This signal is emitted when the user sends a message. Subscribers to this signal can use it to conduct an action after the message is sent, and the information saved to the database.

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	target_uid (str) – Message uid that was sent. target_email (str) – Email address associated with the sent message.

reload-css-style()¶

This signal is emitted to reload the style resources of the King Phisher client.

Signal flags:	`SIGNAL_ACTION \| SIGNAL_RUN_LAST`

rpc-cache-clear()¶

This signal is emitted to clear the RPC objects cached information. Subsequent invocations of RPC cache enabled methods will return fresh information from the server.

Signal flags:	`SIGNAL_ACTION \| SIGNAL_RUN_LAST`

server-connected()¶

This signal is emitted when the client has connected to the King Phisher server. The default handler sets the initial campaign optionally prompting the user to select one if one has not already been selected.

Signal flags:	`SIGNAL_RUN_FIRST`

server-disconnected()¶

This signal is emitted when the client has disconnected from the King Phisher server.

Signal flags:	`SIGNAL_RUN_FIRST`

sftp-client-start()¶

This signal is emitted when the client starts sftp client from within King Phisher. Subscribers can conduct an action prior to the default option being ran from the client configuration.

Signal flags:	`SIGNAL_ACTION \| SIGNAL_RUN_LAST`

visit-delete(row_ids)¶

This signal is emitted when the user deletes a visit entry. Subscribers to this signal can use it to conduct an action an entry is deleted.

Signal flags:	`SIGNAL_ACTION \| SIGNAL_RUN_LAST`
Parameters:	row_ids ([str, ..]) – The row IDs that are to be deleted.

unhandled-exception(exc_info, error_uid)¶

This signal is emitted when the application encounters an unhandled Python exception.

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	exc_info (tuple) – A tuple of three objects corresponding to the return value of the `sys.exc_info()` function representing the exception that was raised. error_uid (`uuid.UUID`) – The unique identifier that has been assigned to this exception for tracking.

2.3.3. Mail Tab Signals¶

The following are the signals for the MailSenderTab object.

message-create(target, message)¶

This signal is emitted when the message and target have been loaded and constructed. Subscribers to this signal may use it as an opportunity to modify the message object prior to it being sent.

New in version 1.10.0b3.

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	target (`MessageTarget`) – The target for the message. message (`TopMIMEMultipart`) – The message about to be sent to the target.

message-data-export(target_file)¶

This signal is emitted when the client is going to export the message configuration to a King Phisher Message (KPM) archive file.

Signal flags:	`SIGNAL_ACTION \| SIGNAL_RUN_LAST`
Parameters:	target_file (str) – The path to write the archive file to.
Returns:	Whether or not the message archive was successfully imported.
Return type:	bool

message-data-import(target_file, dest_dir)¶

This signal is emitted when the client is going to import the message configuration from a King Phisher Message (KPM) archive file.

Signal flags:	`SIGNAL_ACTION \| SIGNAL_RUN_LAST`
Parameters:	target_file (str) – The source archive file to import. dest_dir (str) – The destination directory to unpack the archive into.
Returns:	Whether or not the message archive was successfully imported.
Return type:	bool

message-send(target, message)¶

This signal is emitted after the message has been fully constructed (after message-create) and can be used as an opportunity to inspect the message object and prevent it from being sent.

New in version 1.10.0b3.

Signal flags:	`SIGNAL_RUN_LAST`
Parameters:	target (`MessageTarget`) – The target for the message. message (`TopMIMEMultipart`) – The message about to be sent to the target.
Returns:	Whether or not to proceed with sending the message.
Return type:	bool

send-finished()¶

This signal is emitted after all messages have been sent.

Signal flags:	`SIGNAL_RUN_FIRST`

send-precheck()¶

This signal is emitted when the user is about to start sending phishing messages. It is used to ensure that all settings are sufficient before proceeding. A handler can return False to indicate that a pre-check condition has failed and the operation should be aborted.

Signal flags:	`SIGNAL_RUN_LAST`
Returns:	Whether or not the handler’s pre-check condition has passed.
Return type:	bool

target-create(target)¶

This signal is emitted when the target has been loaded and constructed. Subscribers to this signal may use it as an opportunity to modify the target object prior to it being sent.

New in version 1.10.0b3.

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	target (`MessageTarget`) – The target for the message.

target-send(target)¶

This signal is emitted after the target has been fully constructed (after target-create) and can be used as an opportunity to inspect the target object and prevent it from being sent to.

New in version 1.10.0b3.

Signal flags:	`SIGNAL_RUN_LAST`
Parameters:	target (`MessageTarget`) – The target for the message.
Returns:	Whether or not to proceed with sending to the target.
Return type:	bool

2.3.4. Server Event Signals¶

The following are the signals for the ServerEventSubscriber object. These events are published by the server forwarded to the client based on the active subscriptions. When an event is forwarded to a client the corresponding GObject signal is emitted for consumption by the client. See the section on Published Events for more details.

db-alert-subscriptions(event_type, objects)¶

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	event_type (str) – The type of event, one of either deleted, inserted or updated. objects (list) – The objects from the server. The available attributes depend on the subscription.

db-campaigns(event_type, objects)¶

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	event_type (str) – The type of event, one of either deleted, inserted or updated. objects (list) – The objects from the server. The available attributes depend on the subscription.

db-campaign-types(event_type, objects)¶

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	event_type (str) – The type of event, one of either deleted, inserted or updated. objects (list) – The objects from the server. The available attributes depend on the subscription.

db-companies(event_type, objects)¶

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	event_type (str) – The type of event, one of either deleted, inserted or updated. objects (list) – The objects from the server. The available attributes depend on the subscription.

db-company-departments(event_type, objects)¶

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	event_type (str) – The type of event, one of either deleted, inserted or updated. objects (list) – The objects from the server. The available attributes depend on the subscription.

db-credentials(event_type, objects)¶

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	event_type (str) – The type of event, one of either deleted, inserted or updated. objects (list) – The objects from the server. The available attributes depend on the subscription.

db-deaddrop-connections(event_type, objects)¶

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	event_type (str) – The type of event, one of either deleted, inserted or updated. objects (list) – The objects from the server. The available attributes depend on the subscription.

db-deaddrop-deployments(event_type, objects)¶

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	event_type (str) – The type of event, one of either deleted, inserted or updated. objects (list) – The objects from the server. The available attributes depend on the subscription.

db-industries(event_type, objects)¶

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	event_type (str) – The type of event, one of either deleted, inserted or updated. objects (list) – The objects from the server. The available attributes depend on the subscription.

db-landing-pages(event_type, objects)¶

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	event_type (str) – The type of event, one of either deleted, inserted or updated. objects (list) – The objects from the server. The available attributes depend on the subscription.

db-messages(event_type, objects)¶

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	event_type (str) – The type of event, one of either deleted, inserted or updated. objects (list) – The objects from the server. The available attributes depend on the subscription.

db-users(event_type, objects)¶

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	event_type (str) – The type of event, one of either deleted, inserted or updated. objects (list) – The objects from the server. The available attributes depend on the subscription.

db-visits(event_type, objects)¶

Signal flags:	`SIGNAL_RUN_FIRST`
Parameters:	event_type (str) – The type of event, one of either deleted, inserted or updated. objects (list) – The objects from the server. The available attributes depend on the subscription.