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_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.- SIGNAL_RUN_FIRST
Signals with the
SIGNAL_RUN_FIRST
flag execute the default handler before handlers which are connected with either theconnect()
orconnect_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 theconnect()
method but before handlers which are connected with theconnect_after()
method. This provides connected handlers with an opportunity to block the default function by halting emissionof the signal by using theemit_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.