3.5. RPC API¶

3.5.1. Overview¶

The RPC API is used by the King Phisher client to communicate with the server. It uses the RPC capabilities provided by the AdvancedHTTPServer module for the underlying communications. The RPC API provides a way for the client to retrieve and set information regarding campaigns as well as the server’s configuration. RPC requests must be authenticated and are only permitted from the loopback interface. The client is responsible for using SSH to set up a port forward for requests. See the Login Process documentation for more information.

3.5.2. RPC API Versioning¶

It’s important for the client and server components to have a compatible RPC version. The version each understands is described in the rpc_api_version object. This object contains both a major and minor version identifier. The major version is incremented when backwards-incompatible changes are made such as an argument or method is removed. The minor version is incremented when backwards-compatible changes are made such as when a new method is added or when a keyword argument is added whose default value maintains the original behavior.

In this way, it is possible for the server to support a newer RPC version than the client. This would be the case when the server is newer and provides more functionality than the older client requires. It is not possible for the client to support a newer RPC version than the server. This would imply that the client requires functionality that the server is unable to provide.

Since version v1.10.0, the GraphQL API loosens the interdependency between the RPC API version and the database’s schema version. Since GraphQL allows the client to specify only the fields it requires, new fields can be added to the database without incrementing the major RPC API version. It is still important to increment the minor RPC API version so the client knows that those fields are available to be requested through the graphql endpoint. If database fields are removed, columns are renamed, columns types are changed, or columns have additional restrictions placed on them (such as being nullable), the major RPC API version must be incremented.

3.5.2.1. The Table Fetch API¶

The RPC functions responsible for fetching table data through the db/table/* API endpoints (db/table/get and db/table/view) use a hard coded data set located in data/server/king_phisher/table-api.json to maintain backwards compatibility. This is required since the RPC client can not specify the columns and order of the columns that it is requesting as it can do with the graphql API endpoint. This data set effectively allows the table fetch RPC API endpoints to be artificially pinned to a specific database schema version. The other table API endpoints do not need to be pinned in such a fashion due to them taking the columns to work with as parameters. This means that an older but still compatible client (same major version but a lesser minor version as the server) would not be specifying columns which do not exist since renaming and removing columns require incrementing the major RPC API version.

3.5.3. General API¶

graphql(query, query_vars=None )¶

Handler:	`rpc_graphql()`

login( )¶

Handler:	`rpc_login()`

logout( )¶

Handler:	`rpc_logout()`

ping( )¶

Handler:	`rpc_ping()`

plugins/list( )¶

Handler:	`rpc_plugins_list()`

shutdown( )¶

Handler:	`rpc_shutdown()`

version( )¶

Handler:	`rpc_version()`

3.5.4. Campaign API¶

campaign/alerts/is_subscribed(campaign_id )¶

Handler:	`rpc_campaign_alerts_is_subscribed()`

campaign/alerts/subscribe(campaign_id )¶

Handler:	`rpc_campaign_alerts_subscribe()`

campaign/alerts/unsubscribe(campaign_id )¶

Handler:	`rpc_campaign_alerts_unsubscribe()`

campaign/landing_page/new(campaign_id, hostname, page )¶

Handler:	`rpc_campaign_landing_page_new()`

campaign/message/new(campaign_id, email_id, email_target, company_name, first_name, last_name )¶

Handler:	`rpc_campaign_message_new()`

campaign/new(name, description=None )¶

Handler:	`rpc_campaign_new()`

campaign/stats(campaign_id )¶

Handler:	`rpc_campaign_stats()`

3.5.5. Configuration API¶

config/get(option_name )¶

Handler:	`rpc_config_get()`

config/set(options )¶

Handler:	`rpc_config_set()`

3.5.6. Event API¶

events/is_subscribed(event_id, event_type )¶

Handler:	`rpc_events_is_subscribed()`

events/subscribe(event_id, event_types, attributes )¶

Handler:	`rpc_events_subscribe()`

events/unsubscribe(event_id, event_types, attributes )¶

Handler:	`rpc_events_unsubscribe()`

3.5.7. GeoIP API¶

geoip/lookup(ip, lang=None )¶

Handler:	`rpc_geoip_lookup()`

geoip/lookup/multi(ips, lang=None )¶

Handler:	`rpc_geoip_lookup_multi()`

3.5.8. Hostnames API¶

hostnames/add(hostname )¶

Handler:	`rpc_hostnames_add()`

New in version 1.13.0.

hostnames/get( )¶

Handler:	`rpc_hostnames_get()`

New in version 1.13.0.

3.5.9. SSL API¶

/ssl/letsencrypt/certbot_version( )¶

Handler:	`rpc_ssl_letsencrypt_certbot_version()`

/ssl/letsencrypt/issue(hostname, load=True )¶

Handler:	`rpc_ssl_letsencrypt_issue()`

/ssl/sni_hostnames/get( )¶

Handler:	`rpc_ssl_sni_hostnames_get()`

/ssl/sni_hostnames/load(hostname )¶

Handler:	`rpc_ssl_sni_hostnames_load()`

/ssl/sni_hostnames/unload(hostname )¶

Handler:	`rpc_ssl_sni_hostnames_unload()`

/ssl/status( )¶

Handler:	`rpc_ssl_status()`

3.5.10. Table API¶

db/table/count(table_name, query_filter=None )¶

Handler:	`rpc_database_count_rows()`

db/table/delete(table_name, row_id )¶

Handler:	`rpc_database_delete_row_by_id()`

db/table/delete/multi(table_name, row_ids )¶

Handler:	`rpc_database_delete_rows_by_id()`

db/table/get(table_name, row_id )¶

Handler:	`rpc_database_get_row_by_id()`

db/table/insert(table_name, keys, values )¶

Handler:	`rpc_database_insert_row()`

db/table/set(table_name, row_id, keys, values )¶

Handler:	`rpc_database_set_row_value()`

db/table/view(table_name, page=0, query_filter=None )¶

Handler:	`rpc_database_view_rows()`