Teamserver

The Havoc teamserver is the core backend component written in Go. It manages all agent sessions, handles client connections, spawns listeners, and generates payloads.

Overview

The teamserver acts as the central hub between operator clients and deployed agents:

Multi-user: Supports multiple operators connecting simultaneously
Persistent: Saves sessions to SQLite database
Configurable: Driven by YAOTL profile files
Cross-platform: Runs on Linux, macOS, and Docker

The teamserver requires Go 1.18+ and several build dependencies (MinGW, NASM) for payload compilation.

Core Responsibilities

1. Client Connection Management

The teamserver runs a WebSocket server for operator clients:

// From teamserver.go
t.Server.Engine.GET("/havoc/", func(context *gin.Context) {
    var upgrade websocket.Upgrader
    WebSocket, err := upgrade.Upgrade(context.Writer, context.Request, nil)
    
    t.Clients.Store(ClientID, &Client{
        Username:      "",
        GlobalIP:      WebSocket.RemoteAddr().String(),
        Connection:    WebSocket,
        Authenticated: false,
    })
    
    go t.handleRequest(ClientID)
})

Authentication Flow:

Client connects to wss://teamserver:40056/havoc/
Teamserver generates self-signed TLS certificate
Client sends credentials with SHA3-256 hashed password
Teamserver validates against YAOTL profile operators
On success, sends all session state to client

Each client connection runs in its own goroutine for concurrent handling.

2. Listener Management

The teamserver spawns and manages multiple listener types: HTTP/HTTPS Listeners

// Configured in YAOTL profile
for _, listener := range t.Profile.Config.Listener.ListenerHTTP {
    HandlerData := handlers.HTTPConfig{
        Name:         listener.Name,
        Hosts:        listener.Hosts,
        HostBind:     listener.HostBind,
        PortBind:     strconv.Itoa(listener.PortBind),
        UserAgent:    listener.UserAgent,
        Headers:      listener.Headers,
        Uris:         listener.Uris,
        Secure:       listener.Secure,
    }
    t.ListenerStart(handlers.LISTENER_HTTP, HandlerData)
}

SMB Named Pipe Listeners

for _, listener := range t.Profile.Config.Listener.ListenerSMB {
    HandlerData := handlers.SMBConfig{
        Name:     listener.Name,
        PipeName: listener.PipeName,
    }
    t.ListenerStart(handlers.LISTENER_PIVOT_SMB, HandlerData)
}

External C2 Listeners

for _, listener := range t.Profile.Config.Listener.ListenerExternal {
    HandlerData := handlers.ExternalConfig{
        Name:     listener.Name,
        Endpoint: listener.Endpoint,
    }
    t.ListenerStart(handlers.LISTENER_EXTERNAL, HandlerData)
}

Listeners are automatically restored from the database on teamserver restart.

3. Agent Session Handling

The teamserver processes agent callbacks:

// From handlers.go
func handleDemonAgent(Teamserver agent.TeamServer, Header agent.Header, ExternalIP string) {
    // Check magic value
    if Header.MagicValue == agent.DEMON_MAGIC_VALUE {
        
        // New agent registration
        if Command == agent.DEMON_INIT {
            Agent = agent.ParseDemonRegisterRequest(Header.AgentID, Header.Data, ExternalIP)
            Teamserver.AgentAdd(Agent)
            Teamserver.AgentSendNotify(Agent)
        }
        
        // Existing agent checking in
        if Teamserver.AgentExist(Header.AgentID) {
            Agent = Teamserver.AgentInstance(Header.AgentID)
            Agent.UpdateLastCallback(Teamserver)
            
            // Dispatch commands to agent
            Agent.TaskDispatch(RequestID, Command, Parser, Teamserver)
            
            // Send queued jobs or NOJOB
            if len(Agent.JobQueue) == 0 {
                Response = agent.BuildPayloadMessage(NoJob, AESKey, AESIv)
            } else {
                job := Agent.GetQueuedJobs()
                Response = agent.BuildPayloadMessage(job, AESKey, AESIv)
            }
        }
    }
}

Agent State Management:

Each agent has unique AgentID, AES key, and IV
Job queue stores pending commands
Last callback time tracked for health monitoring
Pivot relationships stored for linked agents

4. Payload Generation

The teamserver compiles Demon payloads on demand:

// From teamserver.go
func (t *Teamserver) FindSystemPackages() bool {
    // Locate MinGW compilers
    t.Settings.Compiler64 = t.Profile.Config.Server.Build.Compiler64
    t.Settings.Compiler32 = t.Profile.Config.Server.Build.Compiler86
    t.Settings.Nasm = t.Profile.Config.Server.Build.Nasm
    
    logger.Info(fmt.Sprintf(
        "Build: \n"+
        " - Compiler x64 : %v\n"+
        " - Compiler x86 : %v\n"+
        " - Nasm         : %v",
        t.Settings.Compiler64,
        t.Settings.Compiler32,
        t.Settings.Nasm,
    ))
}

Supported Formats:

EXE: Standalone executable
DLL: Dynamic library with exported functions
Shellcode: Position-independent code for injection

Compilers must be specified in the YAOTL profile’s Build block or auto-detected from PATH.

5. Event Broadcasting

The teamserver maintains event synchronization across all clients:

func (t *Teamserver) EventBroadcast(ExceptClient string, pk packager.Package) {
    t.Clients.Range(func(key, value any) bool {
        ClientID := key.(string)
        if ExceptClient != ClientID {
            t.SendEvent(ClientID, pk)
        }
        return true
    })
}

func (t *Teamserver) EventAppend(event packager.Package) {
    if event.Head.OneTime != "true" {
        t.EventsList = append(t.EventsList, event)
    }
}

Event Types:

New agent registration
Agent output and command results
Listener status changes
Chat messages
Loot and downloads

6. Database Persistence

All session data persists to SQLite:

// From teamserver.go
if t.DB.Existed() {
    logger.Info("Opens existing database: " + DBPath)
} else {
    logger.Info("Creates new database: " + DBPath)
}

// Restore listeners
for _, listener := range t.DB.ListenerAll() {
    // Restart HTTP/HTTPS/SMB/External listeners
}

// Restore agents
Agents := t.DB.AgentAll()
for _, Agent := range Agents {
    t.AgentAdd(Agent)
}

logger.Info(fmt.Sprintf("Restored %v agents from last session", len(Agents)))

Starting the Teamserver

Basic Usage

# With a custom profile
sudo ./teamserver server --profile profiles/havoc.yaotl -v

# With the default profile
sudo ./teamserver server --default -v

Root privileges are required to bind listeners on ports below 1024 (e.g., port 80/443).

Command Line Arguments

Argument	Description
`--profile <path>`	Path to YAOTL profile file
`--default`	Use default profile (data/havoc.yaotl)
`-v, --verbose`	Enable verbose output with timestamps
`--debug`	Enable debug logging
`--host <ip>`	Override teamserver bind address
`--port <port>`	Override teamserver port

Startup Sequence

// From server.go
func (t *Teamserver) Start() {
    // 1. Parse YAOTL profile
    Server.SetProfile(DirPath + "/data/havoc.yaotl")
    
    // 2. Verify build tools (MinGW, NASM)
    Server.FindSystemPackages()
    
    // 3. Generate TLS certificates
    Cert, Key, err = certs.HTTPSGenerateRSACertificate(Host)
    
    // 4. Start WebSocket server
    t.Server.Engine.RunTLS(Host+":"+Port, certPath, keyPath)
    
    // 5. Initialize Service API (if configured)
    if t.Profile.Config.Service != nil {
        t.Service.Start()
    }
    
    // 6. Start listeners from profile
    for _, listener := range t.Profile.Config.Listener.ListenerHTTP {
        t.ListenerStart(handlers.LISTENER_HTTP, HandlerData)
    }
    
    // 7. Restore listeners from database
    for _, listener := range t.DB.ListenerAll() {
        t.ListenerStart(listener.Protocol, listener.Config)
    }
    
    // 8. Restore agents from database
    Agents := t.DB.AgentAll()
    for _, Agent := range Agents {
        t.AgentAdd(Agent)
        t.AgentSendNotify(Agent)
    }
}

Data Storage Locations

Database

data/havoc.db - SQLite database

Logs

data/loot/YYYY.MM.DD_HH:MM:SS/ - Session logs

Certificates

data/server.cert, data/server.key - TLS certs

Profiles

profiles/*.yaotl - Configuration files

Service API (External C2)

The teamserver exposes an endpoint for custom agents:

// From teamserver.go
if t.Profile.Config.Service != nil {
    t.Service = service.NewService(t.Server.Engine)
    t.Service.Teamserver = t
    t.Service.Config = *t.Profile.Config.Service
    
    if len(t.Service.Config.Endpoint) > 0 {
        t.Service.Start()
        logger.Info(fmt.Sprintf(
            "starting service handle on %v",
            TeamserverWs+"/"+t.Service.Config.Endpoint,
        ))
    }
}

Configuration (in YAOTL profile):

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

Custom agents can POST to this endpoint with their own magic values and protocols.

Webhook Integration

Optional Discord webhooks for notifications:

if t.Profile.Config.WebHook != nil {
    if t.Profile.Config.WebHook.Discord != nil {
        t.WebHooks.SetDiscord(
            AvatarUrl,
            UserName,
            t.Profile.Config.WebHook.Discord.WebHook,
        )
    }
}

Best Practices

Security

Use strong operator passwords
Restrict teamserver to trusted networks
Enable TLS on HTTP listeners
Rotate AES keys between operations

Performance

Limit concurrent agent callbacks
Use appropriate sleep/jitter values
Monitor database size
Archive old sessions

Reliability

Backup database regularly
Test profiles before deployment
Monitor listener health
Set appropriate kill dates

Operations

Document operator credentials
Coordinate listener ports
Use unique listener names
Review logs after sessions

Get Started

Core Concepts

Demon Agent

Listeners

Extensibility

Advanced

Teamserver

Teamserver

Overview

Core Responsibilities

1. Client Connection Management

2. Listener Management

3. Agent Session Handling

4. Payload Generation

5. Event Broadcasting

6. Database Persistence

Starting the Teamserver

Basic Usage

Command Line Arguments

Startup Sequence

Data Storage Locations

Database

Logs

Certificates

Profiles

Service API (External C2)

Webhook Integration

Best Practices

Security

Performance

Reliability

Operations

Build docs developers (and LLMs) love

Get Started

Core Concepts

Demon Agent

Listeners

Extensibility

Advanced

Documentation Index

​Teamserver

​Overview

​Core Responsibilities

​1. Client Connection Management

​2. Listener Management

​3. Agent Session Handling

​4. Payload Generation

​5. Event Broadcasting

​6. Database Persistence

​Starting the Teamserver

​Basic Usage

​Command Line Arguments

​Startup Sequence

​Data Storage Locations

Database

Logs

Certificates

Profiles

​Service API (External C2)

​Webhook Integration

​Best Practices

Security

Performance

Reliability

Operations

Build docs developers (and LLMs) love

Teamserver

Overview

Core Responsibilities

1. Client Connection Management

2. Listener Management

3. Agent Session Handling

4. Payload Generation

5. Event Broadcasting

6. Database Persistence

Starting the Teamserver

Basic Usage

Command Line Arguments

Startup Sequence

Data Storage Locations

Service API (External C2)

Webhook Integration

Best Practices