Beelzebub

Framework de Runtime de Engano

Beelzebub é um runtime de engano de código aberto que implanta serviços isca adaptativos com tecnologia LLM nos protocolos SSH, HTTP, TCP, TELNET e MCP. Ele vai além de honeypots passivos ao envolver ativamente atacantes em interações realistas, coletando inteligência de ameaças de alta fidelidade e detectando ataques de injeção de prompt contra agentes de IA.

Índice

• Beelzebub
  • Índice
  • Principais Recursos
  • Demonstração de Engano com LLM
  • Início Rápido
    • Instalador
    • Local (Go)
    • Docker
    • Usando Helm (Kubernetes)
  • Referência da CLI
    • beelzebub run
    • beelzebub validate
    • beelzebub plugin
    • beelzebub version
  • Sistema de Plugins
    • Interfaces
    • Escrevendo um Plugin
    • Instalando Plugins Externos
  • Observabilidade
    • Métricas do Prometheus
    • Integração com RabbitMQ
  • Testes
  • Qualidade de Código
  • Licença
  • Contribuição
  • Referência de Configuração
    • Configuração Central
    • Configuração de Serviço
  • Serviços de Engano
    • Serviço de Engano MCP
      • Como Funciona
    • Serviço de Engano HTTP
    • Serviço de Engano SSH
    • Serviço de Engano TELNET
    • Serviço de Engano TCP
  • Apoiado Por

Principais Recursos

• Mecanismo de engano adaptativo: a integração com LLM (OpenAI, Ollama) gera respostas contextualmente precisas em tempo real, mantendo os atacantes engajados tempo suficiente para coletar TTPs acionáveis
• Definição de serviço low-code: configuração baseada em YAML com correspondência de comandos por regex — nenhum código personalizado é necessário para implantar um novo serviço isca
• Cobertura multiprotocolo: SSH, HTTP, TCP, TELNET, MCP de alvos de infraestrutura a superfícies de ataque de agentes de IA
• Sistema de plugins extensível: implemente a interface CommandPlugin ou HTTPPlugin e registre via init() nenhuma alteração no núcleo é necessária
• Stack de observabilidade completo: métricas do Prometheus, streaming de eventos RabbitMQ
• Runtime pronto para produção: Docker, Kubernetes (Helm), desligamento gracioso, limites de memória por serviço

Demonstração de Engano com LLM

Início Rápido

Instalador```bash

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

Não interativo: `./install.sh --local` ou `./install.sh --docker`. Use `./install.sh --local --no-run` para instalar e compilar sem iniciar o runtime local. Em hosts não root, a instalação local não inicia automaticamente quando a configuração padrão inclui portas privilegiadas.

### Local (Go)```bash
make start     # installs any declared plugins, compiles them in, and runs

Docker```bash

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

### Usando Helm (Kubernetes)```bash
helm install beelzebub ./beelzebub-chart
# Upgrade:
helm upgrade beelzebub ./beelzebub-chart

Referência da CLI

O Beelzebub vem com uma CLI estruturada. Execute beelzebub --help para ver todos os comandos disponíveis.

beelzebub run

Inicia todos os serviços de decepção configurados.```bash 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`

Analisa e valida todos os arquivos de configuração sem iniciar nenhum serviço. Útil em pipelines de CI. Consulte [Validação de Configuração](https://github.com/beelzebub-labs/beelzebub/blob/main/docs/configuration-validation.md) para obter a arquitetura de validação e a referência de regras.```bash
beelzebub validate --conf-core ./configurations/beelzebub.yaml --conf-services ./configurations/services/

beelzebub plugin

Instale, liste e remova plugins obtidos do GitHub. Consulte Sistema de Plugins.```bash beelzebub plugin install github.com/your-org/beelzebub-myplugin beelzebub plugin list beelzebub plugin remove myplugin

### `beelzebub version`

Imprime a versão, o commit SHA, a data de compilação e as informações de runtime do Go.```bash
beelzebub version

Sistema de Plugins

O Beelzebub expõe um SDK público estável em pkg/plugin para estender o runtime de decepção sem modificar o código central.

Interfaces```go

// 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 }

### Escrevendo um Plugin```go
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{})
}

Instalando Plugins Externos```bash

Declare plugins in configurations/plugins.yaml, or:

beelzebub plugin install github.com/your-org/myplugin # also appends to the config