Beelzebub

Deception Runtime Framework

Beelzebub is an open-source deception runtime that deploys adaptive, LLM-powered decoy services across SSH, HTTP, TCP, TELNET, and MCP protocols. It goes beyond passive honeypots by actively engaging attackers in realistic interactions, collecting high-fidelity threat intelligence, and detecting prompt injection attacks against AI agents.

Table of Contents

• Beelzebub
  • Table of Contents
  • Key Features
  • LLM Deception Demo
  • Quick Start
    • Installer
    • Local (Go)
    • Docker
    • Using Helm (Kubernetes)
  • CLI Reference
    • beelzebub run
    • beelzebub validate
    • beelzebub plugin
    • beelzebub version
  • Plugin System
    • Interfaces
    • Writing a Plugin
    • Installing External Plugins
  • Observability
    • Prometheus Metrics
    • RabbitMQ Integration
  • Testing
  • Code Quality
  • License
  • Contributing
  • Configuration Reference
    • Core Configuration
    • Service Configuration
  • Deception Services
    • MCP Deception Service
      • How It Works
    • HTTP Deception Service
    • SSH Deception Service
    • TELNET Deception Service
    • TCP Deception Service
  • Supported By

Key Features

• Adaptive deception engine: LLM integration (OpenAI, Ollama) generates contextually accurate responses in real time, keeping attackers engaged long enough to collect actionable TTPs
• Low-code service definition: YAML-based configuration with regex command matching — no custom code required to deploy a new decoy service
• Multi-protocol coverage: SSH, HTTP, TCP, TELNET, MCP from infrastructure targets to AI agent attack surfaces
• Extensible plugin system: Implement the CommandPlugin or HTTPPlugin interface and register via init() no core changes required
• Full observability stack: Prometheus metrics, RabbitMQ event streaming
• Production-ready runtime: Docker, Kubernetes (Helm), graceful shutdown, per-service memory limits

LLM Deception Demo

Quick Start

Installer

./install.sh     # asks local or Docker, checks prerequisites, and starts it

Non-interactive: ./install.sh --local or ./install.sh --docker. Use ./install.sh --local --no-run to install and build without starting the local runtime. On non-root hosts, local installation does not auto-start when the default configuration includes privileged ports.

Local (Go)

make start     # installs any declared plugins, compiles them in, and runs

Docker

make docker    # builds an image with declared plugins baked in, then runs it

Using Helm (Kubernetes)

helm install beelzebub ./beelzebub-chart
# Upgrade:
helm upgrade beelzebub ./beelzebub-chart

CLI Reference

Beelzebub ships with a structured CLI. Run beelzebub --help to see all available commands.

beelzebub run

Start all configured deception services.

beelzebub run [flags]

Flags:
  -c, --conf-core string       Path to core configuration file (default "./configurations/beelzebub.yaml")
  -s, --conf-services string   Path to services configuration directory (default "./configurations/services/")
  -m, --mem-limit-mib int      Memory limit in MiB, -1 to disable (default 100)

beelzebub validate

Parse and validate all configuration files without starting any services. Useful in CI pipelines. See Configuration Validation for the validation architecture and rule reference.

beelzebub validate --conf-core ./configurations/beelzebub.yaml --conf-services ./configurations/services/

beelzebub plugin

Install, list, and remove plugins fetched from GitHub. See Plugin System.

beelzebub plugin install github.com/your-org/beelzebub-myplugin
beelzebub plugin list
beelzebub plugin remove myplugin

beelzebub version

Print version, commit SHA, build date, and Go runtime information.

beelzebub version

Plugin System

Beelzebub exposes a stable public SDK at pkg/plugin for extending the deception runtime without modifying core code.

Interfaces

// CommandPlugin generates text responses for SSH, TCP, TELNET, and HTTP services.
type CommandPlugin interface {
    Metadata() Metadata
    Execute(ctx context.Context, req CommandRequest) (string, error)
}

// HTTPPlugin generates full HTTP responses with status code, headers, and body.
type HTTPPlugin interface {
    Metadata() Metadata
    HandleHTTP(r *http.Request) HTTPResponse
}

Writing a Plugin

package myplugin

import (
    "context"
    "github.com/beelzebub-labs/beelzebub/v3/pkg/plugin"
)

type MyPlugin struct{}

func (p *MyPlugin) Metadata() plugin.Metadata {
    return plugin.Metadata{
        Name:        "MyPlugin",
        Description: "Custom deception response generator",
        Version:     "1.0.0",
        Author:      "your-name",
    }
}

func (p *MyPlugin) Execute(_ context.Context, req plugin.CommandRequest) (string, error) {
    return "simulated response to: " + req.Command, nil
}

func init() {
    plugin.Register(&MyPlugin{})
}

Installing External Plugins

# Declare plugins in configurations/plugins.yaml, or:
beelzebub plugin install github.com/your-org/myplugin   # also appends to the config

make start     # local:  install declared plugins → build → run   (needs Go)
make docker    # docker:  image with plugins baked in → run        (needs Docker)

Command	What it does
plugin install <link>	fetch a plugin, wire it in, rebuild; also adds it to configurations/plugins.yaml
plugin install	install everything declared in configurations/plugins.yaml
plugin list	show installed plugins vs. what's compiled into the binary
plugin update [name]	re-fetch at the declared ref and re-pin the commit
plugin remove <name>	remove a plugin from configurations/plugins.yaml, unwire it, and print the rebuild step