蜜蜂魔方

Integration tests (requires Docker)

make test.dependencies.start make test.integration make test.dependencies.down

Using Docker Compose

docker compose build
docker compose up -d

Quick Start

LLM Deception Demo

Validate configuration without starting services

beelzebub validate ```

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.

CLI Reference

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

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
}

`beelzebub plugin list`

List all registered plugins available in the current build.

beelzebub plugin list

Plugin System

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

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.

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.