5.1. Architecture Overview

The following diagram outlines the generic architecture of how the major components both contained in and used by King Phisher interact.

// diagram overview of the king phisher architecture
digraph {
    graph [pad="0.5", nodesep="1", ranksep="1"];
    label="King Phisher Connection Diagram";

    {rank=same; KingPhisherClient; SMTPServer}
    {rank=same; Database; PhishingTargets}

    KingPhisherClient  [label="King Phisher Client"]
    KingPhisherServer  [label="King Phisher Server"]
    PhishingTargets    [label="Phishing Targets"]
    RPC                [color=white; shape=box; style=filled; label="Remote Procedure Call"]
    SMTPServer         [label="SMTP Server"]
    WebSocket          [color=white; shape=box; style=filled]

    subgraph cluster_SSHTunnel {
        color = lightgray;
        label = "SSH Tunnel";
        style = filled;
        RPC WebSocket;

    KingPhisherClient       -> SMTPServer
    KingPhisherClient       -> WebSocket         [arrowhead=none]
    WebSocket               -> KingPhisherServer
    KingPhisherClient       -> RPC               [arrowhead=none]
    KingPhisherServer       -> Database
    PhishingTargets         -> KingPhisherServer
    RPC                     -> KingPhisherServer

In the diagram above, all major components (shown in oval shapes) can technically coexist on the same host system. In this case the term “host” refers to a single OS installation whether that be a Virtual Machine or not. It is however recommended to at a minimum install the King Phisher client and server components on separate hosts for production deployments.

The King Phisher project consists of the client and server components. The major responsibilities of each are noted as follows:

5.1.1. Client Responsibilities

  • Creating Campaigns – The client facilitates creating new campaigns through its user interface. Once the campaign user is done adjusting the settings for the new campaign, the client uses RPC to transfer the information to the King Phisher server.
  • Sending Email – The client is responsible for editing, rendering and ultimately sending phishing messages through an external SMTP server. Once a message is sent, the client notifies the King Phisher server via an RPC call with the applicable details such as who the message was sent to.
  • Processing Campaign Data – Once data has been collected on the King Phisher server for a particular campaign, the client retrieves it using GraphQL queries over RPC. Once the data has been transferred it is displayed through the user interface.

5.1.2. Server Responsibilities

  • Handling HTTP(S) Requests – The server handles all HTTP and HTTPS requests either from phishing targets or the King Phisher client (which uses a form of RPC over HTTP).
  • Tracking Campaigns – The server tracks the status of campaigns through the configured database backend. This allows the King Phisher client to disconnect and shutdown once it is done making changes.
  • Dispatching Campaign Notifications – While tracking campaign data, the server publishes event notifications to various pieces of subscriber code. Plugins utilizes this model to subscribe to events and execute arbitrary routines (such as sending alerts to end users) when they are received. The King Phisher client can also subscribe to a subset of events which are forwarded over websockets.

5.1.3. Login Process

The following steps outline the procedure taken by the client to open a a connection to, and authenticate with the server for communication.

  1. The client communicates to the server through an SSH tunnel which it establishes first. This requires the client to authenticate to the host on which the server is running.
  2. The client issues an RPC request through the established SSH tunnel to the version endpoint to determine compatibility.
  3. The client issues an additional RPC request through the established SSH tunnel, this time to the login endpoint to authenticate and create a new session.
  4. The client opens a websocket connection through the SSH tunnel to subscribe to and receive events published by the server in real time.

At this point the client is fully connected to the server.

5.1.4. Signal Architecture

Both the client and server utilize and provide functionality for signal-driven callbacks. The two use different backends, but in both cases, there is a core interface through which King Phisher signals are published to registered callback functions as events. The signal subsystem is particularly useful for plugins to modify system behavior. Client Signals

Due to the nature of the client application using GTK, the GObject Signal functionality is used to provide the core of client events. These events are defined in the GObject Signals documentation. These signals are published by particular object instances, with the most notable being the KingPhisherClientApplication. Server Signals

The server utilizes the blinker module to support application events. This interface is defined and documented in Server Signals documentation. Server signals are centrally located within the signals module from which that can be both connected to and emitted. Signal Forwarders

Due to the both the client and server having a centralized signal mechanism, there are notable components which both forward signals to and from other components to make the interface consistent.

Name Direction Description
SQLAlchemy From: SQLAlchemy Forwards events from SQLAlchemy into the server’s core signal dispatcher. This allows server components to connect to SQLAlchemy signals for database events through the central interface.
To: Server Core
WebSocket Server From: Server Core Forwards events from the server’s core signal dispatcher to connected and subscribed client web sockets. This effectively enables subscribers to receive a subset of server signals.
To: WebSocket Clients
WebSocket Client From: WebSocket Client Forwards events received from the web sockets to the client’s core signal dispatcher. This effectively enables client components to receive a subset of server signals.
To: Client Core
// diagram overview of a signal emission example
digraph {
    graph [pad="0.5", nodesep="1", ranksep="1"];
    label="King Phisher Signal Emission Diagram";


    subgraph cluster_Client {
        color = lightgray;
        label = "Client";
        style = filled;
        WebSocketClient ClientCore;

    subgraph cluster_Server {
        color = lightgray;
        label = "Server";
        style = filled;
        SQLAlchemy ServerCore WebSocketServer

    SQLAlchemy       -> ServerCore
    ServerCore       -> WebSocketServer
    WebSocketServer  -> WebSocketClient [constraint=false; label="Transmission over the network"]
    WebSocketClient  -> ClientCore