0xOb5k-J/havoc-mcp

Havoc MCP Server

Model Context Protocol (MCP) server for Havoc C2 Framework. Enables AI assistants to interact with Havoc operations through natural language.

Features

• WebSocket Protocol: Native Havoc C2 protocol implementation
• Command Execution: Shell, PowerShell, process listing, and more
• Session Management: List and interact with Demon agents
• Real-time Output: Captures command results with proper routing
• Type Safety: Pydantic models for all data structures
• Production Ready: Error handling, timeouts, logging

Quick Start

Installation

git clone https://github.com/0xOb5k-J/havoc-mcp.git
cd havoc-mcp

# Install dependencies
pip install -r requirements.txt

# Or install as editable package
pip install -e .

Configuration

Create .env file:

HAVOC_TEAMSERVER_URL=https://your-server:40056
HAVOC_USERNAME=operator
HAVOC_PASSWORD=your_password

Usage with VS Code Copilot

Add to mcp.json:

{
  "havoc": {
    "command": "python",
    "args": ["/path/to/launcher.py"],
    "env": {
      "HAVOC_TEAMSERVER_URL": "https://localhost:40056",
      "HAVOC_USERNAME": "operator",
      "HAVOC_PASSWORD": "password"
    },
    "type": "stdio"
  }
}

Usage with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "havoc": {
      "command": "python",
      "args": ["-m", "havoc_mcp"],
      "env": {
        "HAVOC_TEAMSERVER_URL": "https://localhost:40056",
        "HAVOC_USERNAME": "operator",
        "HAVOC_PASSWORD": "password"
      }
    }
  }
}

Example Usage

User: "List all Havoc sessions"
User: "Execute whoami on session <session_id>"
User: "Run Get-ComputerInfo in PowerShell"
User: "Show process list from <hostname>"
User: "Adjust sleep to 10 seconds with 20% jitter"

Available Commands

Implemented

• shell <command> - Execute cmd.exe commands
• powershell <command> - Execute PowerShell cmdlets
• ps - List running processes
• checkin - Get agent information
• sleep <seconds> [jitter] - Adjust beacon interval

Planned

• screenshot - Capture screenshots
• upload - Upload files
• download - Download files
• token - Token manipulation
• net - Network enumeration

Architecture

AI Assistant
     MCP Protocol (stdio)
MCP Server (server.py)
     WebSocket (wss://)
HavocClient (client.py)
     Havoc Protocol
Teamserver
     C2 Channel
Demon Agents

MCP Tools

Technical Details

Protocol

Reverse-engineered from Havoc C++ client:

• Connection: WebSocket with TLS
• Auth: SHA3-256 password hashing
• Format: JSON messages with Head/Body
• Events: InitConnection, Session, Listener, Teamserver
• Commands: TaskID-based routing

Command Implementation

# Shell command
await client.execute_command(session_id, "shell", ["whoami"])

# PowerShell
await client.execute_command(session_id, "powershell", ["Get-Process"])

# Process list
await client.execute_command(session_id, "ps", [])

# Sleep configuration
await client.execute_command(session_id, "sleep", ["10", "20"])

Project Structure

havoc-mcp/
 src/havoc_mcp/
    client.py          # WebSocket client
    server.py          # MCP server
    types.py           # Type definitions
    __init__.py
    __main__.py
 examples/
    claude_desktop_config.json
    client_example.py
 tests/
 .env.example
 pyproject.toml
 README.md
 INTEGRATION_STATUS.md

Testing

# Run test suite
pytest tests/

# Test client connection
python examples/client_example.py

Security

C2 Framework Access - Use Responsibly

• Authorized environments only
• Secure credential storage
• Enable TLS/SSL
• Audit all operations
• Follow responsible disclosure

Contributing

1. Fork the repository
2. Create feature branch
3. Add tests
4. Submit pull request

Please follow existing code style and add type hints.

Resources

• Havoc Framework
• Model Context Protocol
• MCP Python SDK

License

- See LICENSE file

Disclaimer

For authorized security testing only. Unauthorized access to computer systems is illegal. Authors are not responsible for misuse of this software.