3.2.1. GraphQL Overview¶
The RPC API provides a function for executing GraphQL queries against the
server. The schema the server supports allows accessing the database models
through the db type as well as some additional information such as the
server plugins.
Note
For consistencies within the GraphQL API and with GraphQL best practices, it
is important to note that names are camelCase and not snake_case.
3.2.1.1. Interface Extensions¶
The GraphQL schema supported by King Phisher implements the Relay connection
interface allowing easier pagination using a cursor. As an extension to this
interface, the King Phisher schema also includes a total attribute to the
connection object. This attribute allows a query to access the number of
nodes available for a specific connection.
3.2.1.2. Schema¶
The following table represents the top-level objects available in the GraphQL schema and their various sub-object types as applicable. For more information, see the GraphQL Schema documentation.
| Object Name | Object Type | Description |
|---|---|---|
db |
Object | Database models. See Table Relationships for information on available sub-objects. |
geoloc |
GeoLocation |
Geolocation information. |
hostnames |
[String] | The hostnames that are configured for use with this server. |
plugin |
Plugin |
Specific information for a loaded plugin. |
plugins |
Connection | Information on all loaded plugins. |
siteTemplate |
SiteTemplate |
Information for an available site template. |
siteTemplates |
Connection | Information on all available site templates. |
ssl |
SSL |
Information regarding the SSL configuration and status. |
version |
String | The version of the King
Phisher server. |
| Connection: | A connection sub-object is a special object providing a defined interface used
to refer to an array of objects. The connection sub-object has a total
attribute which is an integer as well as an edges attribute. See
Connection Types for more information. |
|---|---|
| Object: | Objects can in turn have their own attributes which can be a combination of additional sub-objects or scalars. |
3.2.1.3. Additional Database Model Attributes¶
Database objects which have an IP address string attribute associated with
their model have an additional attribute containing the corresponding geo
location information. This geo location attribute uses the same naming prefix,
for example the geo location information for a ip attribute can be accessed
from the ipGeoloc attribute.
3.2.1.4. Additional Database Connection Arguments¶
Database connections can include additional arguments which allow manipulation of the queried data.
3.2.1.4.1. The filter Argument¶
The filter argument is a FilterInput GraphQL object and can be passed
to database connection to filter what data is returned by the query. This
argument is an object containing one or more of the following key words.
| Keyword | Type | Default | Description |
|---|---|---|---|
| and 1 | List | N/A | A list of additional filter objects, where all must evaluate to true. |
| or 1 | List | N/A | A list of additional filter objects, where one or more must evaluate to true. |
| field 1 | String | N/A | The name of a database field to filter by. |
| operator | FilterOperatorEnum | EQ |
The operator to use with value, one of EQ,
GE, GT, LE, LT, or NE. |
| value | AnyScalar | Null
2 |
The value of the field to use with the specified comparison operator. |
1 Exactly one of these keywords must be specified.
2 null can not be passed as a literal for input. To compare a value to
null, the value keyword must be omitted.
3.2.1.4.2. The sort Argument¶
The sort argument is a list of SortInput GraphQL objects (described
below) which can be passed to a database connection to sort the query data by
one or more fields.
| Keyword | Type | Default | Description |
|---|---|---|---|
| field* | String | N/A | The name of a database field to sort by. |
| direction | SortDirectionEnum | AESC |
The direction in which to sort the data, either
AESC or DESC. |
* This keyword must be specified.
3.2.1.5. Executing Raw Queries¶
Raw GraphQL queries can be executed using the tools/database_console.py
utility. This console provides a graphql_query function which takes a query
string parameter and optional query variables. This can be used for easily
testing queries. It should be noted however that using this utility directly on
the server does not restrict access to data as the RPC interface does.
The client’s RPC terminal (only available on Linux due to the dependency on VTE)
can also be used to easily execute raw GraphQL queries. The RPC method can be
called directly, or when IPython is available, either the %graphql or
%graphql_file commands can be used. The former of which takes a GraphQL
query as an argument, while the second takes the path to a file on disk to
execute. Both of these are useful for debugging and inspecting GraphQL queries
and their resulting data structures.