Extensibility Overview

Introduction to Havoc Framework’s extensibility system

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 Configuration

Service {
    Endpoint = "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

1. Enable Service API

   Add a Service directive to your Teamserver profile:

   profiles/havoc.yaotl

   Service {
       Endpoint = "service-endpoint"
       Password = "service-password"
   }
   
2. 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 .
   
3. 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