Client

The Havoc client is a cross-platform graphical user interface built with C++ and Qt. It provides operators with a modern, intuitive interface for managing agents, executing commands, and collaborating with team members.

Overview

The client connects to the teamserver via WebSocket and supports multiple operators working simultaneously on the same engagement.

Cross-Platform

Runs on Linux, macOS, and Windows

Modern UI

Dark theme based on Dracula color scheme

Multiplayer

Multiple operators share session state

Extensible

Python API for custom scripts and automation

Key Features

User Interface

The client provides a comprehensive interface with several key components: Main Window (Havoc.hpp):

class HavocSpace::Havoc {
    UserInterface::HavocUi HavocAppUI;
    DBManager* dbManager;
    QMainWindow* HavocMainWindow;
    bool ClientInitConnect = true;
    
    void Init(int argc, char** argv);
    void Start();
};

Core UI Elements:

Session Table: View all active and historical agents
Session Console: Interact with individual agents
Listener Manager: Create and manage listeners
Payload Generator: Build custom Demon payloads
Team Chat: Communicate with other operators
Loot Browser: View downloaded files and credentials
Event Log: Monitor all framework events
Script Manager: Load and manage Python scripts

The client uses Monaco font (embedded in Qt resources) for proper monospace formatting. On Kali Linux, you may need to manually configure fonts if the embedded resource fails to load.

Connecting to Teamserver

The client connects via WebSocket Secure (WSS):

Launch the client:

./Havoc

Connection Dialog:

Host: Teamserver IP or hostname
Port: Teamserver port (default: 40056)
Username: Operator name from YAOTL profile
Password: Operator password from YAOTL profile

Authentication Flow:

Client                           Teamserver
  |                                  |
  |---> Connect to wss://host:port--|  
  |                                  |
  |<----- TLS Handshake ------------|
  |                                  |
  |---> Auth Package --------------->|
  |     (username + SHA3-256(pw))    |
  |                                  |
  |<----- Auth Success + State ------|
  |     (agents, listeners, events)  |

The password is hashed with SHA3-256 before transmission. The teamserver validates this hash against the YAOTL profile.

Session Management

The client maintains synchronized state with the teamserver: TeamserverTabSession (TeamserverTabSession.h):

Manages connection to a single teamserver
Handles WebSocket message parsing
Dispatches events to appropriate UI widgets
Maintains local cache of session state

Session Views:

Table View: Overview of all agents with filtering
Graph View: Visual representation of pivot chains
Console View: Interactive terminal for agent commands

Agent Interaction

DemonInteracted widget (DemonInteracted.h):

Dedicated console for each agent session
Command history and auto-completion
Output formatting (ANSI colors, tables)
Task management (view pending/completed tasks)

Command Dispatch (DemonCmdDispatch.h):

class DemonCmdDispatch {
    // Parses operator input and builds command packages
    void DispatchCommand(QString command, QStringList args);
    
    // Sends package to teamserver via WebSocket
    void SendPackage(Package pkg);
};

Type help in any agent console to see available commands. Use Tab for auto-completion.

Payload Generation

The client provides a GUI for building Demon payloads: Configuration Options:

Listener: Select target listener
Architecture: x64 or x86
Format: EXE, DLL, or shellcode
Sleep/Jitter: Override profile defaults
Indirect Syscalls: Enable/disable
Stack Duplication: Enable/disable
Sleep Obfuscation: Ekko, Zilean, or FOLIAGE
Injection Config: Process spawn targets

Binary Options:

Custom compile time
MZ header modification
Image size spoofing
String replacement

The client sends the configuration to the teamserver, which compiles and returns the payload.

Listener Management

Create and manage listeners through the GUI: HTTP/HTTPS Listener:

Name: Unique identifier
Hosts: Callback domains/IPs
Host Bind: Interface to bind (0.0.0.0 for all)
Port Bind: Listener port on server
Port Conn: Port agents connect to
User Agent: Custom UA string
Headers: Additional HTTP headers
URIs: Callback paths
Secure: Enable HTTPS
Cert/Key: Custom TLS certificate (optional)

SMB Listener:

Name: Unique identifier
Pipe Name: Named pipe for SMB callbacks

External C2:

Name: Unique identifier
Endpoint: Custom endpoint path

Loot Management

LootWidget (LootWidget.h):

View downloaded files
Extract credentials and secrets
Export data in various formats
Filter by agent, date, or type

Loot Categories:

Downloads
Screenshots
Credentials
Hashes
Tickets (Kerberos)
Process dumps

Team Collaboration

Chat System:

Real-time messaging between operators
Join/leave notifications
Persistent chat history

Event Synchronization:

All operators see agent callbacks
Commands issued by one operator visible to all
Shared session state (agents, listeners, loot)

User Management:

See who’s connected
Track command attribution
Coordinate tasks between operators

Each operator action is logged with username and timestamp for accountability and collaboration.

Python API Integration

The client embeds Python 3.10 for extensibility: PythonApi (PythonApi/PythonApi.h):

class PythonApi {
    // Initialize Python interpreter
    void InitPythonInterpreter();
    
    // Load and execute scripts
    void ExecuteScript(QString path);
    
    // Event handlers
    void RegisterEventHandler(QString event, PyObject* callback);
};

Event System (PythonApi/Event.h):

onNewDemon: New agent registered
onDemonOutput: Agent sent output
onDemonMark: Agent marked (dead/active)
onNewListener: Listener created
onListenerError: Listener error

HavocUi API (PythonApi/HavocUi.h):

Create custom dialogs
Add menu items
Display notifications
Modify UI elements

PyDemonClass (PythonApi/PyDemonClass.h):

Access agent properties
Issue commands programmatically
Query agent state

Script Manager

ScriptManager widget (ScriptManager.h):

Load scripts from disk
View loaded scripts
Enable/disable scripts
Reload scripts without restarting

Example Script Locations:

User scripts: ~/.havoc/scripts/
System scripts: /usr/share/havoc/scripts/

Use the Python API to automate repetitive tasks, create custom commands, or integrate with external tools.

Configuration

The client stores configuration in TOML format: config.toml (from client/config.toml):

[Havoc]
version = "0.7"

[Teamserver]
default_profile = "havoc.yaotl"

[UI]
theme = "dracula"
font = "Monaco"
font_size = 10

Saved Sessions:

Recent teamserver connections
Saved credentials (optional)
Window layout preferences
Script configurations

Database Management

The client uses a local database for caching: DBManager (DBManager/DBManager.hpp):

Caches teamserver data locally
Stores session history
Maintains script state
Saves UI preferences

Benefits:

Faster UI updates
Offline session review
Persistent preferences
Reduced teamserver queries

Building the Client

Prerequisites

Debian/Ubuntu:

sudo apt install -y qtbase5-dev qtchooser qt5-qmake qtbase5-dev-tools \
    libqt5websockets5 libqt5websockets5-dev qtdeclarative5-dev \
    python3.10-dev libspdlog-dev libboost-all-dev cmake build-essential

Arch Linux:

sudo pacman -S qt5-base qt5-websockets python3 spdlog boost cmake gcc

Compilation

cd client
make

This generates:

Havoc executable
Embedded Qt resources
Python module bindings

The client requires Python 3.10 specifically. Ensure python3.10-dev is installed.

Starting the Client

Standalone

./client/Havoc

Via Teamserver Binary

./teamserver client

Command Line Options

Option	Description
`--profile <path>`	Auto-connect using profile
`--no-connect`	Launch without connection dialog

Troubleshooting

Font Issues (Kali Linux)

If Monaco font doesn’t load:

Install a monospace font:

sudo apt install fonts-firacode

Modify config.toml:

[UI]
font = "Fira Code"

Connection Errors

Certificate verification failed: Teamserver using self-signed cert (expected)
Connection refused: Check teamserver is running and port is correct
Authentication failed: Verify username/password match YAOTL profile

Performance Issues

Disable verbose output on high-traffic operations
Clear old sessions from database
Reduce agent callback frequency (sleep/jitter)
Close unused agent consoles

For large engagements, use the graph view to visualize pivot chains and identify bottlenecks.

Best Practices

Session Management

Name sessions descriptively
Close consoles when not in use
Archive completed engagements
Back up important loot

Collaboration

Use chat for coordination
Review command history
Mark agents appropriately
Document findings in loot notes

Automation

Use Python scripts for repetitive tasks
Create custom commands
Automate loot extraction
Integrate with ticketing systems

Security

Don’t save passwords in config
Use encrypted connections only
Clear cache after engagements
Protect client machine

Get Started

Core Concepts

Demon Agent

Listeners

Extensibility

Advanced

Documentation Index

​Client

​Overview

Cross-Platform

Modern UI

Multiplayer

Extensible

​Key Features

​User Interface

​Connecting to Teamserver

​Session Management

​Agent Interaction

​Payload Generation

​Listener Management

​Loot Management

​Team Collaboration

​Python API Integration

​Script Manager

​Configuration

​Database Management

​Building the Client

​Prerequisites

​Compilation

​Starting the Client

​Standalone

​Via Teamserver Binary

​Command Line Options

​Troubleshooting

​Font Issues (Kali Linux)

​Connection Errors

​Performance Issues

​Best Practices

Session Management

Collaboration

Automation

Security

Build docs developers (and LLMs) love

Client

Overview

Key Features

User Interface

Connecting to Teamserver

Session Management

Agent Interaction

Payload Generation

Listener Management

Loot Management

Team Collaboration

Python API Integration

Script Manager

Configuration

Database Management

Building the Client

Prerequisites

Compilation

Starting the Client

Standalone

Via Teamserver Binary

Command Line Options

Troubleshooting

Font Issues (Kali Linux)

Connection Errors

Performance Issues

Best Practices