Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/HavocFramework/Havoc/llms.txt

Use this file to discover all available pages before exploring further.

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"
}

​
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

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
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.
Extend Demon capabilities with modules:
  • Powerpick: Execute unmanaged PowerShell
  • InvokeAssembly: Run .NET assemblies with custom CLR versions
  • Custom COFF loaders
  • Persistence mechanisms
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

​
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 TypeBody TypesPurpose
Register-Initial authentication
RegisterAgent-Register a new agent type
AgentAgentRegister, AgentTask, AgentResponse, AgentOutput, AgentBuildAgent operations
ListenerListenerAdd, ListenerStart, ListenerExC2, ListenerTransmitListener 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

Build docs developers (and LLMs) love

Get started for freeTalk to us