3.6. Server Signals

3.6.1. Overview

Server signals are used by the server to dispatch events to subscribed handlers. This allows plugins to subscribe specific functions to be executed when a particular event occurs. These signals are defined in the signals module.

3.6.2. Signal Sender

The first parameter of each signal is the signal sender. It can be used by subscribers to only receive signal when emitted by a particular sender, effectively providing a filter. See the blinker documentation for more information.

3.6.3. Campaign Signals

campaign_alert[source]

Emitted for each user who is subscribed to alerts for a particular campaign. Users subscribe to campaign alerts through the GUI by enabling the “Subscribe To Event Alerts” setting. Alerts are for either the “credentials” or “visits” table.

Note

This signal is not emitted for every entry into the respective tables but rather at progressively longer intervals to prevent the user from receiving an excessive amount of messages within a short period of time.

Parameters:
  • table (str) – The table name that the alert is for.
  • alert_subscription (king_phisher.server.database.models.AlertSubscription) – The alert subscription.
  • count (int) – The number associated with the alert event per the specified sender.
campaign_alert_expired[source]

Emitted for each user who is subscribed to alerts for a particular campaign after it has expired.

Parameters:
  • campaign (king_phisher.server.database.models.Campaign) – The campaign which is expiring.
  • alert_subscription (king_phisher.server.database.models.AlertSubscription) – The alert subscription.
campaign_expired[source]

Emitted after a campaign has expired as determined by the expiration field. The server periodically checks for newly expired campaigns at an arbitrary interval. If a campaign is updated to expire at a time less than the next check minus the interval, then this signal will not be emitted for the campaign.

Parameters:campaign (king_phisher.server.database.models.Campaign) – The campaign which is expiring.

3.6.4. Database Signals

db_initialized[source]

Emitted after a connection has been made and the database has been fully initialized. At this point, it is safe to operate on the database.

Parameters:connection_url (sqlalchemy.engine.url.URL) – The connection string for the database that has been initialized.
db_session_deleted[source]

Emitted after one or more rows have been deleted on a SQLAlchemy session. At this point, references are valid but objects can not be modified. See sqlalchemy.orm.events.SessionEvents.after_flush() for more details.

Parameters:
  • table (str) – The name of the table for which the target objects belong.
  • targets (tuple) – The objects that have been deleted with the session.
  • session (sqlalchemy.orm.session.Session) – The SQLAlchemy session with which the targets are associated.
db_session_inserted[source]

Emitted after one or more rows have been inserted in a SQLAlchemy session. At this point, references are valid but objects can not be modified. See sqlalchemy.orm.events.SessionEvents.after_flush() for more details.

Parameters:
  • table (str) – The name of the table for which the target objects belong.
  • targets (tuple) – The objects that have been inserted with the session.
  • session (sqlalchemy.orm.session.Session) – The SQLAlchemy session with which the targets are associated.
db_session_updated[source]

Emitted after one or more rows have been updated in a SQLAlchemy session. At this point, references are valid but objects can not be modified. See sqlalchemy.orm.events.SessionEvents.after_flush() for more details.

Parameters:
  • table (str) – The name of the table for which the target objects belong.
  • targets (tuple) – The objects that have been updated with the session.
  • session (sqlalchemy.orm.session.Session) – The SQLAlchemy session with which the targets are associated.
db_table_delete[source]

Emitted before a row inheriting from Base is deleted from the database table. To only subscribe to delete events for a specific table, specify the table’s name as the sender parameter when calling blinker.base.Signal.connect(). See sqlalchemy.orm.events.MapperEvents.before_delete() for more details.

Parameters:
  • table (str) – The name of the table for which the target object belongs.
  • mapper (sqlalchemy.orm.mapper.Mapper) – The Mapper object which is the target of the event.
  • connection (sqlalchemy.engine.Connection) – The SQLAlchemy connection object which is being used to emit the SQL statements for the instance.
  • target – The target object instance.
db_table_insert[source]

Emitted before a row inheriting from Base is inserted into the database table. To only subscribe to insert events for a specific table, specify the table’s name as the sender parameter when calling blinker.base.Signal.connect(). See sqlalchemy.orm.events.MapperEvents.before_insert() for more details.

Parameters:
  • table (str) – The name of the table for which the target object belongs.
  • mapper (sqlalchemy.orm.mapper.Mapper) – The Mapper object which is the target of the event.
  • connection (sqlalchemy.engine.Connection) – The SQLAlchemy connection object which is being used to emit the SQL statements for the instance.
  • target – The target object instance.
db_table_update[source]

Emitted before a row inheriting from Base is updated in the database table. To only subscribe to update events for a specific table, specify the table’s name as the sender parameter when calling blinker.base.Signal.connect(). See sqlalchemy.orm.events.MapperEvents.before_update() for more details.

Parameters:
  • table (str) – The name of the table for which the target object belongs.
  • mapper (sqlalchemy.orm.mapper.Mapper) – The Mapper object which is the target of the event.
  • connection (sqlalchemy.engine.Connection) – The SQLAlchemy connection object which is being used to emit the SQL statements for the instance.
  • target – The target object instance.

3.6.5. Request Handler Signals

Signals which are emitted for events specific to individual HTTP requests. These signals use the respective instance of KingPhisherRequestHandler as the sender.

credentials_received[source]

Sent when a new pair of credentials have been submitted.

Parameters:
  • request_handler – The handler for the received request.
  • username (str) – The username of the credentials that were submitted.
  • password (str) – The password of the credentials that were submitted.
email_opened[source]

Sent when a request for the embedded image is received.

Parameters:request_handler – The handler for the received request.
request_handle[source]

Sent after a new HTTP request has been received and is about to be handled. This signal is suitable for implementing custom request handlers or aborting requests. This signal is emitted after request_received to allow subscribers the opportunity to handle requests themselves.

Note

If a request has been handled by the signal, the signal handler must raise the KingPhisherAbortRequestError exception to prevent further processing.

Parameters:request_handler – The handler for the received request.
request_received[source]

Sent when a new HTTP request has been received and is about to be handled. This signal is not suitable for implementing custom request handlers or aborting requests. This signal is emitted before request_handle allowing subscribers to be notified before a request may be blocked.

Parameters:request_handler – The handler for the received request.
response_sent[source]

Sent after a response to an HTTP request has been sent to the client. At this point headers may be added to the response body.

Parameters:
  • request_handler – The handler for the received request.
  • code (int) – The HTTP status code that was sent in the response.
  • message (str) – The HTTP message that was sent in the response.
rpc_method_call[source]

Sent when a new RPC request has been received and it’s corresponding method is about to be called.

Parameters:
  • method (str) – The RPC method which is about to be executed.
  • request_handler – The handler for the received request.
  • args (tuple) – The arguments that are to be passed to the method.
  • kwargs (dict) – The key word arguments that are to be passed to the method.
rpc_method_called[source]

Sent after an RPC request has been received and it’s corresponding method has been called.

Parameters:
  • method (str) – The RPC method which has been executed.
  • request_handler – The handler for the received request.
  • args (tuple) – The arguments that were passed to the method.
  • kwargs (dict) – The key word arguments that were passed to the method.
  • retval – The value returned from the RPC method invocation.
rpc_user_logged_in[source]

Sent when a new RPC user has successfully logged in and created a new authenticated session.

Parameters:
  • request_handler – The handler for the received request.
  • session (str) – The session ID of the newly logged in user.
  • name (str) – The username of the newly logged in user.
rpc_user_logged_out[source]

Sent when an authenticated RPC user has successfully logged out and terminated their authenticated session.

Parameters:
  • request_handler – The handler for the received request.
  • session (str) – The session ID of the user who has logged out.
  • name (str) – The username of the user who has logged out.
visit_received[source]

Sent when a new visit is received on a landing page. This is only emitted when a new visit entry is added to the database.

Parameters:request_handler – The handler for the received request.

3.6.6. Server Signals

Signals which are emitted for a KingPhisherServer instance.

server_initialized[source]

Sent when a new instance of KingPhisherServer is initialized.

Parameters:server – The newly initialized server instance.