1.2.12. server_rpc

This module provides the RPC server functionality that is used by the client to communicate with the server application.

1.2.12.1. Data

CONFIG_READABLE

Configuration options that can be accessed by the client.

CONFIG_WRITEABLE

Configuration options that can be changed by the client at run time.

RPC_AUTH_HEADER = 'X-RPC-Auth'

The header which contains the RPC authorization / session token.

VIEW_ROW_COUNT = 50

The default number of rows to return when one of the /view methods are called.

1.2.12.2. Functions

register_rpc(path, database_access=False, log_call=False)

Register an RPC function with the HTTP request handler. This allows the method to be remotely invoked using King Phisher’s standard RPC interface. If database_access is specified, a SQLAlchemy session will be passed as the second argument, after the standard RequestHandler instance.

Parameters:

• path (str) – The path for the RPC function.
• database_access (bool) – Whether or not the function requires database access.
• log_call (bool) – Whether or not to log the arguments which the function is called with.

rpc_campaign_alerts_is_subscribed(handler, session, campaign_id)

Check if the user is subscribed to alerts for the specified campaign.

Parameters:campaign_id (int) – The ID of the campaign. Returns:The alert subscription status. Return type:bool

rpc_campaign_alerts_subscribe(handler, session, campaign_id)

Subscribe to alerts for the specified campaign.

Parameters:campaign_id (int) – The ID of the campaign.

rpc_campaign_alerts_unsubscribe(handler, session, campaign_id)

Unsubscribe to alerts for the specified campaign.

Parameters:campaign_id (int) – The ID of the campaign.

rpc_campaign_landing_page_new(handler, session, campaign_id, hostname, page)

Add a landing page for the specified campaign. Landing pages refer to resources that when visited by a user should cause the visit counter to be incremented.

Parameters:

• campaign_id (int) – The ID of the campaign.
• hostname (str) – The hostname which will be used to serve the request.
• page (str) – The request resource.

rpc_campaign_message_new(handler, session, campaign_id, email_id, target_email, first_name, last_name, department_name=None)

Record a message that has been sent as part of a campaign. These details can be retrieved later for value substitution in template pages.

Parameters:

• campaign_id (int) – The ID of the campaign.
• email_id (str) – The message id of the sent email.
• target_email (str) – The email address that the message was sent to.
• first_name (str) – The first name of the message’s recipient.
• last_name (str) – The last name of the message’s recipient.
• department_name (str) – The name of the company department that the message’s recipient belongs to.

rpc_campaign_new(handler, session, name, description=None)

Create a new King Phisher campaign and initialize the database information.

Parameters:

• name (str) – The new campaign’s name.
• description (str) – The new campaign’s description.

Returns:

The ID of the new campaign.

Return type:

int

rpc_campaign_stats(handler, session, campaign_id)

Generate statistics regarding the specified campaign and return them in a dictionary. The dictionary will contain the keys credentials, credentials-unique, messages, messages-trained, visits, visits-unique. Values with unique in the key are counted unique by the message id for which they are associated.

Parameters:campaign_id – The unique ID of the campaign to generate statistics for. Returns:The statistics for the specified campaign. Return type:dict

rpc_config_get(handler, option_name)

Retrieve a value from the server’s configuration.

Parameters:option_name (str) – The name of the configuration option. Returns:The option’s value.

rpc_config_set(handler, options)

Set options in the server’s configuration. Any changes to the server’s configuration are not written to disk.

Parameters:options (dict) – A dictionary of option names and values

rpc_events_is_subscribed(handler, event_id, event_type)

Check if the client is currently subscribed to the specified server event.

Parameters:

• event_id (str) – The identifier of the event to subscribe to.
• event_type (str) – A sub-type for the corresponding event.

Returns:

Whether or not the client is subscribed to the event.

Return type:

bool

rpc_events_subscribe(handler, event_id, event_types=None, attributes=None)

Subscribe the client to the specified event published by the server. When the event is published the specified attributes of it and it’s corresponding id and type information will be sent to the client.

Parameters:

• event_id (str) – The identifier of the event to subscribe to.
• 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.

rpc_events_unsubscribe(handler, event_id, event_types=None, attributes=None)

Unsubscribe from an event published by the server that the client previously subscribed to.

Parameters:

• event_id (str) – The identifier of the event to subscribe to.
• 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.

rpc_database_count_rows(handler, session, table_name, query_filter=None)

Get a count of the rows in the specified table where the search criteria matches.

Parameters:

• table_name (str) – The name of the database table to query.
• query_filter (dict) – A dictionary mapping optional search criteria for matching the query.

Returns:

The number of matching rows.

Return type:

int

rpc_database_delete_row_by_id(handler, session, table_name, row_id)

Delete the row from the table with the specified value in the id column. If the row does not exist, no error is raised.

Parameters:

• table_name (str) – The name of the database table to delete a row from.
• row_id – The id value.

rpc_database_delete_rows_by_id(handler, session, table_name, row_ids)

Delete multiple rows from a table with the specified values in the id column. If a row id specified in row_ids does not exist, then it will be skipped and no error will be thrown.

Parameters:

• table_name (str) – The name of the database table to delete rows from.
• row_ids (list) – The row ids to delete.

Returns:

The row ids that were deleted.

Return type:

list

rpc_database_get_row_by_id(handler, session, table_name, row_id)

Retrieve a row from a given table with the specified value in the id column.

Parameters:

• table_name (str) – The name of the database table to retrieve a row from.
• row_id – The id value.

Returns:

The specified row data.

Return type:

dict

rpc_database_insert_row(handler, session, table_name, keys, values)

Insert a new row into the specified table.

Parameters:

• table_name (str) – The name of the database table to insert a new row into.
• keys (list) – The column names of values.
• values (list) – The values to be inserted in the row.

Returns:

The id of the new row that has been added.

rpc_database_set_row_value(handler, session, table_name, row_id, keys, values)

Set values for a row in the specified table with an id of row_id.

Parameters:

• table_name (str) – The name of the database table to set the values of the specified row.
• keys (tuple) – The column names of values.
• values (tuple) – The values to be updated in the row.

rpc_database_view_rows(handler, session, table_name, page=0, query_filter=None)

Retrieve the rows from the specified table where the search criteria matches.

Parameters:

• table_name (str) – The name of the database table to query.
• page (int) – The page number to retrieve results for.
• query_filter (dict) – A dictionary mapping optional search criteria for matching the query.

Returns:

A dictionary with columns and rows keys.

Return type:

dict

rpc_geoip_lookup(handler, ip, lang=None)

Look up an IP address in the servers GeoIP database. If the IP address can not be found in the database, None will be returned.

Parameters:

• ip (str) – The IP address to look up.
• lang (str) – The language to prefer for regional names.

Returns:

The geographic information for the specified IP address.

Return type:

dict

rpc_geoip_lookup_multi(handler, ips, lang=None)

Look up multiple IP addresses in the servers GeoIP database. Each IP address that can not be found in the database will have its result set to None.

Parameters:

• ips (list) – The list of IP addresses to look up.
• lang (str) – The language to prefer for regional names.

Returns:

A dictionary containing the results keyed by the specified IP addresses.

Return type:

dict

rpc_graphql(handler, session, query, query_vars=None)

Execute a GraphQL query and return the results. If the query fails to execute the errors returned are populated in the errors key of the results dictionary. If the query executes successfully the returned data is available in the data key of the results dictionary.

Parameters:

• query (str) – The GraphQL query to execute.
• query_vars (dict) – Any variables needed by the query.

Returns:

The results of the query as a dictionary.

Return type:

dict

rpc_hostnames_add(handler, hostname)

Add a hostname to the list of values that are configured for use with this server. At this time, these changes (like other config changes) are not persisted in the server so they will be lost when the server reboots.

New in version 1.13.0.

Parameters:hostname (str) – The hostname to add.

rpc_hostnames_get(handler)

Get the hostnames that are configured for use with this server. This is not related to the ssl/hostnames RPC methods which deal with hostnames as they relate to SSL for the purposes of certificate usage.

New in version 1.13.0.

Returns:The configured hostnames. Return type:list

rpc_login(handler, session, username, password, otp=None)

rpc_logout(handler, session)

rpc_ping(handler)

An RPC method that can be used by clients to assert the status and responsiveness of this server.

Returns:This method always returns True. Return type:bool

rpc_plugins_list(handler)

Return information regarding enabled plugins in the server.

Returns:A dictionary representing enabled plugins and their meta-data. Return type:dict

rpc_shutdown(handler)

This method can be used to shut down the server. This function will return, however no subsequent requests will be processed.

Warning

This action will stop the server process and there is no confirmation before it takes place.

rpc_ssl_letsencrypt_issue(handler, hostname, load=True)

Issue a certificate with Let’s Encrypt. This operation can fail for a wide variety of reasons, check the message key of the returned dictionary for a string description of what occurred. Successful operation requires that the certbot utility be installed, and the server’s Let’s Encrypt data path is configured.

New in version 1.14.0.

Parameters:

• hostname (str) – The hostname of the certificate to issue.
• load (bool) – Whether or not to load the certificate once it has been issued.

Returns:

A dictionary containing the results of the operation.

Return type:

dict

rpc_ssl_letsencrypt_certbot_version(handler)

Find the certbot binary and retrieve it’s version information. If the certbot binary could not be found, None is returned.

New in version 1.14.0.

Returns:The version of certbot. Return type:str

rpc_ssl_sni_hostnames_get(handler)

Get the hostnames that have available Server Name Indicator (SNI) configurations for use with SSL.

New in version 1.14.0.

Returns:A dictionary keyed by hostnames with values of dictionaries containing additional metadata. Return type:dict

rpc_ssl_sni_hostnames_load(handler, hostname)

Load the SNI configuration for the specified hostname, effectively enabling it. If SSL is not enabled, SNI is not available, or the necessary data files are not available, this function returns False.

New in version 1.14.0.

Parameters:hostname (str) – The hostname to configure SSL for. Returns:Returns True only if the SNI configuration for hostname was either able to be loaded or was already loaded. Return type:bool

rpc_ssl_sni_hostnames_unload(handler, hostname)

Unload the SNI configuration for the specified hostname, effectively disabling it. If SNI is not available, or the specified configuration was not already loaded, this function returns False.

New in version 1.14.0.

Parameters:hostname (str) – The hostname to configure SSL for. Returns:Returns True only if the SNI configuration for hostname was unloaded. Return type:bool

rpc_ssl_status(handler)

Get information regarding the status of SSL on the server. This method returns a dictionary with keys describing whether or not SSL is enabled on one or more interfaces, and whether or not the server possess the SNI support. For details regarding which addresses are using SSL, see the rpc_config_get() method.

New in version 1.14.0.

Returns:A dictionary with SSL status information. Return type:dict

rpc_version(handler)

Get the version information of the server. This returns a dictionary with keys of version, version_info and rpc_api_version. These values are provided for the client to determine compatibility.

Returns:A dictionary with version information. Return type:dict