1.1.7. client_rpc

This module facilitates communication with the server application over the RPC interface.

1.1.7.1. Data

UNRESOLVED = UNRESOLVED

A sentinel value used for values in rows to indicate that the data has not been loaded from the server.

1.1.7.2. Functions

vte_child_routine(config)

This is the method which is executed within the child process spawned by VTE. It expects additional values to be set in the config object so it can initialize a new KingPhisherRPCClient instance. It will then drop into an interpreter where the user may directly interact with the rpc object.

Parameters:config (str) – A JSON encoded client configuration.

1.1.7.3. Classes

class KingPhisherRPCClient(*args, **kwargs)

Bases: advancedhttpserver.RPCClientCached

The main RPC object for communicating with the King Phisher Server over RPC.

New in version 1.14.0: Asynchronous Methods

This RPC object provides a few methods for asynchronously making RPC calls to the server. This makes it easier to issue and RPC call and then process the results without having to either wait (and by extension lock the GUI thread) or start and manage a separate thread. These methods use the name async_ prefix and have many of the same arguments.

In all cases, the callback parameters on_success and on_error are called with the signature callback(*(cb_args + (results,)), **cb_kwargs) where results is either the return value of the RPC method in the case of on_success or the exception instance in the case of on_error. The when_idle parameter can be used to specify that the callbacks must be executed within the main GUI thread and can thus access GObjects such as widgets.

async_call(method, args=None, kwargs=None, on_success=None, on_error=None, when_idle=False, cb_args=None, cb_kwargs=None)

Perform an asynchronous RPC call to the server. This will queue a work item for a thread to issue the RPC call and then specifies the behavior for completion. See Asynchronous Methods for more information.

New in version 1.14.0.

Parameters:

• method (str) – The RPC method name to call.
• args (tuple) – The arguments to the RPC method.
• kwargs (tuple) – The keyword arguments to the RPC method.
• on_success – A callback function to be called after the RPC method returns successfully.
• on_error – A callback function to be called if the RPC method raises an exception.
• when_idle – Whether or not the on_success and on_error callback functions should be called from the main GUI thread while it is idle.
• cb_args – The arguments to the on_success and on_error callback functions.
• cb_kwargs – The keyword arguments to the on_success and on_error callback functions.

async_graphql(query, query_vars=None, on_success=None, on_error=None, when_idle=False, cb_args=None, cb_kwargs=None)

Perform an asynchronous RPC GraphQL query to the server. This will queue a work item for a thread to issue the RPC call and then specifies the behavior for completion. See Asynchronous Methods for more information.

New in version 1.14.0.

Parameters:

• query (str) – The GraphQL query string to execute asynchronously.
• query_vars (dict) – Any variable definitions required by the GraphQL query.
• on_success – A callback function to be called after the RPC method returns successfully.
• on_error – A callback function to be called if the RPC method raises an exception.
• when_idle – Whether or not the on_success and on_error callback functions should be called from the main GUI thread while it is idle.
• cb_args – The arguments to the on_success and on_error callback functions.
• cb_kwargs – The keyword arguments to the on_success and on_error callback functions.

async_graphql_file(file_or_path, *args, **kwargs)

Perform an asynchronous RPC GraphQL query from a file on the server. This will queue a work item for a thread to issue the RPC call and then specifies the behavior for completion. See Asynchronous Methods for more information.

New in version 1.14.0.

Parameters:file_or_path – The file object or path to the file from which to read.

geoip_lookup(ip)

Look up the geographic location information for the specified IP address in the server’s geoip database.

Parameters:ip (ipaddress.IPv4Address, str) – The IP address to lookup. Returns:The geographic location information for the specified IP address. Return type:GeoLocation

geoip_lookup_multi(ips)

Look up the geographic location information for the specified IP addresses in the server’s geoip database. Because results are cached for optimal performance, IP addresses to be queried should be grouped and sorted in a way that is unlikely to change, i.e. by a timestamp.

Parameters:ips (list, set, tuple) – The IP addresses to lookup. Returns:The geographic location information for the specified IP address. Return type:dict

get_tag_model(tag_table, model=None)

Load tag information from a remote table into a Gtk.ListStore instance. Tables compatible with the tag interface must have id, name and description fields. If no model is provided a new one will be created, else the current model will be cleared.

Parameters:

• tag_table (str) – The name of the table to load tag information from.
• model (Gtk.ListStore) – The model to place the information into.

Returns:

The model with the loaded data from the server.

Return type:

Gtk.ListStore

graphql(query, query_vars=None)

Execute a GraphQL query on the server and return the results. This will raise KingPhisherGraphQLQueryError if the query fails.

Parameters:

• query (str) – The GraphQL query string to execute.
• query_vars – Any variable definitions required by the GraphQL query.

Returns:

The query results.

Return type:

dict

graphql_file(file_or_path, query_vars=None)

This method wraps graphql() to provide a convenient way to execute GraphQL queries from files.

Parameters:

• file_or_path – The file object or path to the file from which to read.
• query_vars – The variables for query.

Returns:

The query results.

Return type:

dict

graphql_find_file(query_file, **query_vars)

This method is similar to graphql_file(). The first argument (query_file) is the name of a query file that will be located using find.data_file(). Additional keyword arguments are passed as the variables to the query.

Parameters:

• query_file (str) – The name of the query file to locate.
• query_vars – These keyword arguments are passed as the variables to the query.

Returns:

The query results.

Return type:

dict

login(username, password, otp=None)

Authenticate to the remote server. This is required before calling RPC methods which require an authenticated session.

Parameters:

• username (str) – The username to authenticate with.
• password (str) – The password to authenticate with.
• otp (str) – An optional one time password as a 6 digit string to provide if the account requires it.

Returns:

The login result and an accompanying reason.

Return type:

tuple

ping()

Call the ping RPC method on the remote server to ensure that it is responsive. On success this method will always return True, otherwise an exception will be thrown.

Returns:True Return type:bool

reconnect()

Reconnect to the remote server.

remote_row_resolve(row)

Take a RemoteRow instance and load all fields which are UNRESOLVED. If all fields are present, no modifications are made.

Parameters:row – The row who’s data is to be resolved. Return type:RemoteRow Returns:The row with all of it’s fields fully resolved. Return type:RemoteRow

remote_table(table, query_filter=None)

Iterate over a remote database table hosted on the server. Rows are yielded as named tuples whose fields are the columns of the specified table.

Parameters:table (str) – The table name to retrieve. Returns:A generator which yields rows of named tuples. Return type:tuple

remote_table_row(table, row_id, cache=False, refresh=False)

Get a row from the specified table by it’s id, optionally caching it.

Parameters:

• table (str) – The table in which the row exists.
• row_id – The value of the row’s id column.
• cache (bool) – Whether to use the cache for this row.
• refresh (bool) – If cache is True, get the current row value and store it.

Returns:

The remote row as a named tuple of the specified table.

Return type:

tuple

remote_table_row_set(table, row_id, attributes)

shutdown()

class RemoteRow(rpc, *args, **kwargs)

Bases: king_phisher.client.client_rpc._RemoteRow

A generic class representing a row of data from the remote King Phisher server.

commit()

Send this object to the server to update the remote instance.