Beelzebub

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)

Deployment plugin sources are configured in configurations/plugins.yaml:

plugins:
  - source: github.com/your-org/myplugin
  - source: github.com/your-org/private-plugin@v1.2.0

Future per-plugin runtime configuration can live under configurations/plugins/ as one YAML file per plugin.

Each plugin repo must ship a plugins.yaml manifest and self-register in init() (see Writing a Plugin):

name: myplugin
version: 1.0.0
module: github.com/your-org/myplugin   # must match its go.mod
entrypoint: .                          # package that calls plugin.Register (default ".")
min-core-version: v3.8.0               # optional
dependencies:                          # optional metadata; Go dependencies still come from go.mod
  - github.com/your-org/shared@v1.2.3

Installed plugins are compiled into the Beelzebub binary and run in the same process as the runtime. Install plugins only from repositories you trust.

Observability

Prometheus Metrics

Beelzebub exposes Prometheus metrics at the configured endpoint (default: :2112/metrics):

RabbitMQ Integration

Publish all deception events to a message queue for downstream SIEM integration:

core:
  tracings:
    rabbit-mq:
      enabled: true
      uri: "amqp://guest:guest@localhost:5672/"

Events are published as structured JSON to the event queue.

Testing

# Unit tests
make test.unit

# Integration tests (requires Docker)
make test.dependencies.start
make test.integration
make test.dependencies.down

# Validate configuration without starting services
beelzebub validate

Code Quality

• CI: GitHub Actions on every commit and pull request
• Static analysis: CodeQL and Go Report Card
• Coverage: Monitored via Codecov
• Code review: All contributions undergo peer review

License

Beelzebub is licensed under the GNU GPL v3 License.

Contributing

The Beelzebub team welcomes contributions and project participation. Whether you want to report bugs, contribute new features, or have any questions, please refer to our Contributor Guide for detailed information. We encourage all participants and maintainers to adhere to our Code of Conduct and foster a supportive and respectful community.

Happy hacking!

Configuration Reference

Beelzebub uses a two-tier configuration system:

1. Core configuration (beelzebub.yaml) global settings: logging, tracing, Prometheus
2. Service configurations (services/*.yaml) one file per decoy service

Core Configuration

core:
  logging:
    debug: false
    debugReportCaller: false
    logDisableTimestamp: true
    logsPath: ./logs
  tracings:
    rabbit-mq:
      enabled: false
      uri: "amqp://guest:guest@localhost:5672/"
  prometheus:
    path: "/metrics"
    port: ":2112"

Environment variable overrides are supported for all fields (e.g. BEELZEBUB_RABBITMQ_ENABLED). Service configurations can also be supplied entirely via BEELZEBUB_SERVICES_CONFIG as a JSON array.

Service Configuration

Each decoy service is defined in a separate YAML file placed in the services/ directory. The protocol field determines the deception engine used. Commands use regex for request matching and either a static handler or a plugin reference for dynamic responses.

When using the LLMHoneypot plugin, it is highly recommended to use guardrails to prevent the LLM from being jailbroken or otherwise manipulated in ways that could compromise the honeypot. See the LLMHoneypot plugin documentation for details.

Deception Services

MCP De

…