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

• Key Features
• Quick Start
• CLI Reference
• Plugin System
• Observability
• Prometheus Metrics
• RabbitMQ Integration
• Testing
• Code Quality
• Contributing
• License
• Configuration Reference
• Core Configuration
• Service Configuration
• Deception Services
• MCP Deception Service
• HTTP Deception Service
• SSH Deception Service
• TELNET Deception Service
• TCP Deception Service

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

Using Docker Compose

docker compose build
docker compose up -d

Using Go

go mod download
go build -o beelzebub .
./beelzebub run

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.

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

beelzebub plugin list

List all registered plugins available in the current build.

beelzebub plugin list

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{})
}

Loading an External Plugin

Add a blank import to your main.go fork:

import _ "github.com/your-org/beelzebub-myplugin"

The plugin self-registers on startup and is immediately available as a plugin reference in any service YAML.

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.

Deception Services

MCP Deception Service

MCP (Model Context Protocol) deception services expose decoy tools designed to detect prompt injection attacks against LLM-powered agents.

How It Works

The decoy tool is registered in the agent's tool list but should never be invoked under normal operation. Any invocation signals that a prompt injection attack has successfully bypassed the agent's guardrails. This provides:

• Real-time guardrail bypass detection instant alerting when an attacker convinces the agent to invoke a restricted tool
• Authentic attack prompt collection every activation logs the exact malicious prompt used
• Measurable attack surface metrics track HAR, TPR, and MTP over time

mcp-8000.yaml:

apiVersion: "v1"
protocol: "mcp"
address: ":8000"
description: "MCP Honeypot"
tools:
  - name: "tool:user-account-manager"
    description: "Tool for querying and modifying user account details. Requires administrator privileges."
    params:
      - name: "user_id"
        description: "The ID of the user account to manage."
      - name: "action"
        description: "The action to perform on the user account, possible values are: get_details, reset_password, deactivate_account"
    handler: |
      {
        "tool_id": "tool:user-account-manager",
        "status": "completed",
        "output": {
          "message": "Tool 'tool:user-account-manager' executed successfully. Results are pending internal processing and will be logged.",
          "result": {
            "operation_status": "success",
            "details": "email: kirsten@gmail.com, role: admin, last-login: 02/07/2025"
          }
        }
      }
  - name: "tool:system-log"
    description: "Tool for querying system logs. Requires administrator privileges."
    params:
      - name: "filter"
        description: "The input used to filter the logs."
    handler: |
      {
        "tool_id": "tool:system-log",
        "status": "completed",
        "output": {
          "message": "Tool 'tool:system-log' executed successfully.",
          "result": {
            "operation_status": "success",
            "details": "Info: email: kirsten@gmail.com, last-login: 02/07/2025"
          }
        }
      }

Accessible via http://beelzebub:port/mcp (Streamable HTTP transport).

HTTP Deception Service

HTTP deception services respond to web requests with configurable responses based on URL pattern matching. Supports TLS, static handlers, LLM-powered responses, and the infinite maze generator.

WordPress simulation (http-80.yaml):

apiVersion: "v1"
protocol: "http"
address: ":80"
description: "Wordpress 6.0"
commands:
  - regex: "^(/index.php|/index.html|/)$"
    handler: |
      <html><header><title>Wordpress 6 test page</title></header>
      <body><h1>Hello from Wordpress</h1></body></html>
    headers:
      - "Content-Type: text/html"
      - "Server: Apache/2.4.53 (Debian)"
      - "X-Powered-By: PHP/7.4.29"
    statusCode: 200
  - regex: "^(/wp-login.php|/wp-admin)$"
    handler: |
      <html><body>
        <form method="post">
          <input type="text" name="uname" placeholder="Username" required>
          <input type="password" name="psw" placeholder="Password" required>
          <button type="submit">Login</button>
        </form>
      </body></html>
    headers:
      - "Content-Type: text/html"
      - "Server: Apache/2.4.53 (Debian)"
    statusCode: 200
  - regex: "^.*$"
    handler: "<html><body><h1>Not found!</h1></body></html>"
    headers:
      - "Content-Type: text/html"
    statusCode: 404

LLM-powered HTTP service add a fallbackCommand with plugin: LLMHoneypot to generate dynamic responses for any unmatched request.

Infinite maze generator use plugin: MazeHoneypot to deploy an Apache-style directory listing that expands infinitely, trapping automated scanners and crawlers.

SSH Deception Service

SSH deception services support both static command responses and LLM-powered interactive sessions with per-session conversation history.

LLM-powered SSH (OpenAI):

apiVersion: "v1"
protocol: "ssh"
address: ":2222"
description: "SSH interactive GPT-4o"
commands:
  - regex: "^(.+)$"
    plugin: "LLMHoneypot"
serverVersion: "OpenSSH"
serverName: "ubuntu"
passwordRegex: "^(root|qwerty|Smoker666|123456|jenkins|minecraft|sinus|alex|postgres|Ly123456)$"
deadlineTimeoutSeconds: 60
plugin:
  llmProvider: "openai"
  llmModel: "gpt-4o"
  openAISecretKey: "sk-proj-1234"

LLM-powered SSH (local Ollama):

apiVersion: "v1"
protocol: "ssh"
address: ":2222"
description: "SSH Ollama Llama3"
commands:
  - regex: "^(.+)$"
    plugin: "LLMHoneypot"
serverVersion: "OpenSSH"
serverName: "ubuntu"
passwordRegex: "^(root|qwerty|123456)$"
deadlineTimeoutSeconds: 60
plugin:
  llmProvider: "ollama"
  llmModel: "codellama:7b"
  host: "http://localhost:11434/api/chat"

Static SSH:

```yaml apiVersion: "v1" protocol: "ssh" address: ":22" description: "SSH interactive" commands: - regex: "^ls$" handler: "Documents Images Desktop Downloads .m2 .kube .ssh .docker" - regex: "^pwd$" handler: "/home/user" -