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()