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.