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.

​
Overview

The AgentType class is the base class for implementing custom agents in Havoc. It defines the agent’s metadata, build configuration, command handlers, and communication protocol.

​
Class Definition

from havoc.agent import *

class MyCustomAgent(AgentType):
    Name = "CustomAgent"
    Author = "@YourHandle"
    Version = "0.1"
    Description = "Description of your custom agent"
    MagicValue = 0x12345678
    
    # Required methods
    def buildconfig(self) -> dict:
        pass
    
    def response(self, response: dict) -> None:
        pass

​
Required Attributes

​
Name
string
required
The display name of your agent shown in the Havoc client interface.
​
Author
string
required
Author identifier (typically a handle or username).
​
Version
string
required
Version string for your agent implementation.
​
Description
string
required
Brief description of the agent’s purpose and capabilities.
​
MagicValue
int
required
Unique identifier (hex value) used to distinguish your agent’s traffic from other agents.Example: 0x12345678

​
Required Methods

​
buildconfig()

Defines the build configuration options for your agent. These settings are displayed in the Havoc client when generating an agent payload. Returns: dict - Configuration key-value pairs 
def buildconfig(self) -> dict:
    return {
        "Sleep": "5",
        "Jitter": "20",
        "Host": "0.0.0.0",
        "Port": "8080"
    }
  • Sleep: Default sleep interval in seconds between check-ins
  • Jitter: Randomization percentage applied to sleep interval
  • Host: Callback host address
  • Port: Callback port number
  • UserAgent: HTTP User-Agent string (for HTTP/HTTPS agents)
  • KillDate: Date when agent should terminate itself

​
response()

Handles incoming responses from the agent. This method is called when the agent checks in with data. Parameters:
​
response
dict
required
Dictionary containing the agent’s response data, including:
  • AgentHeader: Metadata about the agent
  • Encrypted payload data
def response(self, response: dict) -> None:
    agent_header = response["AgentHeader"]
    
    # Decrypt the response
    agent_response = self.decrypt_response(agent_header, response)
    
    # Parse the response
    parser = Parser(agent_response)
    command_id = parser.parse_int()
    
    if command_id == COMMAND_SHELL:
        output = parser.parse_str()
        self.console_message(output, "")
    elif command_id == COMMAND_REGISTER:
        self.handle_registration(parser)

​
Communication Methods

​
console_message()

Sends output to the agent’s console in the Havoc client. 
self.console_message(message, message_type)
​
message
string
required
The message content to display
​
message_type
string
Message type classification (e.g., “good”, “error”, “info”, "")

​
decrypt_response()

Decrypts an encrypted agent response using your agent’s encryption scheme. 
decrypted_data = self.decrypt_response(agent_header, response)

​
Complete Example

from havoc.service import HavocService
from havoc.agent import *

COMMAND_REGISTER = 0x100
COMMAND_SHELL = 0x101
COMMAND_UPLOAD = 0x102

class CustomAgent(AgentType):
    Name = "Custom Agent"
    Author = "@operator"
    Version = "1.0"
    Description = "Custom agent with shell and file upload"
    MagicValue = 0xdeadbeef
    
    def __init__(self):
        super().__init__()
        self.register_commands()
    
    def buildconfig(self) -> dict:
        return {
            "Sleep": "5",
            "Jitter": "20",
            "Host": "192.168.1.100",
            "Port": "443"
        }
    
    def register_commands(self):
        # Register custom commands
        self.register_command(CommandShell())
        self.register_command(CommandUpload())
    
    def response(self, response: dict) -> None:
        agent_header = response["AgentHeader"]
        agent_response = self.decrypt_response(agent_header, response)
        
        parser = Parser(agent_response)
        command_id = parser.parse_int()
        
        if command_id == COMMAND_REGISTER:
            self.handle_registration(parser)
        elif command_id == COMMAND_SHELL:
            output = parser.parse_str()
            self.console_message(output, "")
        elif command_id == COMMAND_UPLOAD:
            status = parser.parse_int()
            if status == 0:
                self.console_message("[+] File uploaded successfully", "good")
            else:
                self.console_message("[-] Upload failed", "error")
    
    def handle_registration(self, parser: Parser):
        hostname = parser.parse_str()
        username = parser.parse_str()
        domain = parser.parse_str()
        internal_ip = parser.parse_str()
        process_name = parser.parse_str()
        process_pid = parser.parse_int()
        os_version = parser.parse_str()
        os_arch = parser.parse_str()
        
        # Set agent metadata
        self.set_info({
            "Hostname": hostname,
            "Username": username,
            "Domain": domain,
            "InternalIP": internal_ip,
            "Process": f"{process_name} ({process_pid})",
            "OS": f"{os_version} {os_arch}"
        })
        
        self.console_message(f"[+] Agent registered from {hostname}", "good")

# Initialize and register the agent
agent = CustomAgent()

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

havoc_service.register_agent(agent)

​
Helper Classes

​
Parser

Utility class for parsing binary data received from agents. 
from havoc.agent import Parser

parser = Parser(binary_data)

# Parse different data types
int_value = parser.parse_int()
string_value = parser.parse_str()
data_value = parser.parse_data()
Methods:
  • parse_int() - Parse a 4-byte integer
  • parse_str() - Parse a length-prefixed string
  • parse_data() - Parse length-prefixed binary data

HavocService

Connect your agent to the Teamserver

Commands

Define custom commands for your agent

Build docs developers (and LLMs) love

Get started for freeTalk to us