Extensibility Overview

Havoc Framework provides a comprehensive extensibility system that allows you to customize and extend its functionality through multiple mechanisms:

Extensibility Components

Custom Agents

Build third-party agents using the Python Service API

External C2

Integrate external command and control channels

Python API

Leverage the havoc-py API for automation and customization

Modules

Extend Demon agent capabilities with loadable modules

Architecture

Havoc’s extensibility is built on three core pillars:

Service API

The Service API provides a WebSocket-based communication channel between the Teamserver and external services. It enables:

Custom agent registration and management
External C2 listener integration
Bidirectional command/response flow
Authentication using SHA3-256 hashing

Service {
    Endpoint = "service-endpoint"
    Password = "service-password"
}

from havoc.service import HavocService

havoc_service = HavocService(
    endpoint="ws://0.0.0.0:40056/service-endpoint",
    password="service-password"
)

Python API (havoc-py)

The Python API provides classes and utilities for:

AgentType: Define custom agent implementations
Command: Create custom commands with parameters
Packer: Build binary command payloads
HavocService: Manage service connections

See the Python API documentation for detailed usage.

Module System

Modules extend the Demon agent’s capabilities without modifying the core codebase:

Load at runtime from the Havoc client
Execute in fork & run processes
Integrate with existing commands
Support both managed (.NET) and unmanaged code

Common Use Cases

Building a Custom Agent

Create agents in languages like Python, Go, or Rust that communicate with the Teamserver through the Service API. Perfect for:

Cross-platform agents (Linux, macOS)
Specialized communication channels
Custom payload formats
Integration with existing tools

Example: Talon - A Python-based custom agent

External C2 Integration

Route agent traffic through external channels:

Domain fronting
Custom protocols (DNS, ICMP)
Cloud services (AWS, Azure)
Third-party C2 frameworks

The Teamserver acts as a proxy, parsing agent packets while you control the transport layer.

Creating Modules

Extend Demon capabilities with modules:

Powerpick: Execute unmanaged PowerShell
InvokeAssembly: Run .NET assemblies with custom CLR versions
Custom COFF loaders
Persistence mechanisms

Automation & Scripting

Use the Python API for:

Automated tasking workflows
Custom UI integrations
Event-driven responses
Batch operations across agents

Getting Started

Enable Service API

Add a Service directive to your Teamserver profile:

profiles/havoc.yaotl

Service {
    Endpoint = "service-endpoint"
    Password = "service-password"
}

Install havoc-py

The Python API is available at github.com/HavocFramework/havoc-py

git clone https://github.com/HavocFramework/havoc-py
cd havoc-py
pip install .

Choose Your Extension Path

Custom Agent: Follow the Custom Agents guide
External C2: See External C2 documentation
Module: Check the Modules guide

Service API Protocol

The Service API uses JSON over WebSocket with the following message structure:

{
  "Head": {
    "Type": "Agent|Listener|Register|RegisterAgent"
  },
  "Body": {
    "Type": "<operation-type>",
    // ... operation-specific fields
  }
}

Message Types

Head Type	Body Types	Purpose
`Register`	-	Initial authentication
`RegisterAgent`	-	Register a new agent type
`Agent`	`AgentRegister`, `AgentTask`, `AgentResponse`, `AgentOutput`, `AgentBuild`	Agent operations
`Listener`	`ListenerAdd`, `ListenerStart`, `ListenerExC2`, `ListenerTransmit`	Listener management

The Service API authenticates using SHA3-256 hashed passwords. All subsequent messages must be sent over the authenticated WebSocket connection.

Examples Repository

Talon Agent

Reference implementation of a custom agent in Python

Official Modules

Collection of official Havoc modules including Powerpick and InvokeAssembly

Architecture Diagram

┌─────────────────┐
│  Havoc Client   │
└────────┬────────┘
         │
         │ WebSocket
         │
┌────────▼────────┐      ┌──────────────────┐
│   Teamserver    │◄─────┤  Python Scripts  │
│                 │      │  (havoc-py API)  │
│  ┌───────────┐  │      └──────────────────┘
│  │ Service   │  │
│  │ API       │◄─┼──────┐
│  └───────────┘  │      │
│                 │      │ WebSocket (Service)
│  ┌───────────┐  │      │
│  │ HTTP/S    │  │      ▼
│  │ Listener  │  │  ┌─────────────────┐
│  └───────────┘  │  │ Custom Agents   │
│                 │  │ (Talon, etc.)   │
│  ┌───────────┐  │  └─────────────────┘
│  │ External  │  │
│  │ C2        │◄─┼──────┐
│  └───────────┘  │      │
└────────┬────────┘      │
         │               │
         │ HTTP/S        │ Custom Protocol
         │               │
    ┌────▼────┐     ┌────▼────────┐
    │  Demon  │     │   External  │
    │  Agent  │     │   Transport │
    └─────────┘     └─────────────┘

Next Steps

Build a Custom Agent

Learn how to create agents in any language

Explore the Python API

Dive into havoc-py classes and methods

Create a Module

Extend Demon with custom functionality

Setup External C2

Integrate custom transport channels

Get Started

Core Concepts

Demon Agent

Listeners

Extensibility

Advanced

Extensibility Components

Custom Agents

External C2

Python API

Modules

Architecture

Service API

Python API (havoc-py)

Module System

Common Use Cases

Getting Started

Service API Protocol

Message Types

Examples Repository

Talon Agent

Official Modules

Architecture Diagram

Next Steps

Build a Custom Agent

Explore the Python API

Create a Module

Setup External C2

​Extensibility Components

Custom Agents

External C2

Python API

Modules

​Architecture

​Service API

​Python API (havoc-py)

​Module System

​Common Use Cases

​Getting Started

​Service API Protocol

​Message Types

​Examples Repository

Talon Agent

Official Modules

​Architecture Diagram

​Next Steps

Build a Custom Agent

Explore the Python API

Create a Module

Setup External C2

Extensibility Components

Architecture

Service API

Python API (havoc-py)

Module System

Common Use Cases

Getting Started

Service API Protocol

Message Types

Examples Repository

Architecture Diagram

Next Steps