Beelzebub

Marco de ejecución de engaños

Beelzebub es un runtime de engaños de código abierto que despliega servicios señuelo adaptativos e impulsados por LLM en los protocolos SSH, HTTP, TCP, TELNET y MCP. Va más allá de los honeypots pasivos al involucrar activamente a los atacantes en interacciones realistas, recopilando inteligencia de amenazas de alta fidelidad y detectando ataques de inyección de prompts contra agentes de IA.

Tabla de contenidos

• Beelzebub
  • Tabla de contenidos
  • Características principales
  • Demo de engaño con LLM
  • Inicio rápido
    • Instalador
    • Local (Go)
    • Docker
    • Usando Helm (Kubernetes)
  • Referencia de CLI
    • beelzebub run
    • beelzebub validate
    • beelzebub plugin
    • beelzebub version
  • Sistema de plugins
    • Interfaces
    • Escribir un plugin
    • Instalación de plugins externos
  • Observabilidad
    • Métricas de Prometheus
    • Integración con RabbitMQ
  • Pruebas
  • Calidad del código
  • Licencia
  • Contribuciones
  • Referencia de configuración
    • Configuración central
    • Configuración de servicios
  • Servicios de engaño
    • Servicio de engaño MCP
      • Cómo funciona
    • Servicio de engaño HTTP
    • Servicio de engaño SSH
    • Servicio de engaño TELNET
    • Servicio de engaño TCP
  • Respaldado por

Características principales

• Motor de engaño adaptativo: la integración con LLM (OpenAI, Ollama) genera respuestas contextualmente precisas en tiempo real, manteniendo a los atacantes interesados el tiempo suficiente para recopilar TTPs accionables
• Definición de servicios low-code: configuración basada en YAML con coincidencia de comandos mediante regex — no se requiere código personalizado para desplegar un nuevo servicio señuelo
• Cobertura multiprotocolo: SSH, HTTP, TCP, TELNET, MCP desde objetivos de infraestructura hasta superficies de ataque de agentes de IA
• Sistema de plugins extensible: implementa la interfaz CommandPlugin o HTTPPlugin y regístrala mediante init() sin necesidad de cambios en el núcleo
• Stack de observabilidad completo: métricas de Prometheus, streaming de eventos con RabbitMQ
• Runtime listo para producción: Docker, Kubernetes (Helm), apagado controlado (graceful shutdown), límites de memoria por servicio

Demo de engaño con LLM

Inicio rápido

Instalador```bash

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

No interactivo: `./install.sh --local` o `./install.sh --docker`. Usa
`./install.sh --local --no-run` para instalar y compilar sin iniciar el entorno de
ejecución local. En hosts no root, la instalación local no se inicia automáticamente
cuando la configuración predeterminada incluye puertos privilegiados.

### 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

Referencia de CLI

Beelzebub incluye una CLI estructurada. Ejecuta beelzebub --help para ver todos los comandos disponibles.

beelzebub run

Inicia todos los servicios de engañ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`

Analiza y valida todos los archivos de configuración sin iniciar ningún servicio. Útil en pipelines de CI. Ver [Validación de Configuración](https://github.com/beelzebub-labs/beelzebub/blob/main/docs/configuration-validation.md) para conocer la arquitectura de validación y la referencia de reglas.```bash
beelzebub validate --conf-core ./configurations/beelzebub.yaml --conf-services ./configurations/services/

beelzebub plugin

Instala, lista y elimina plugins obtenidos de GitHub. Consulta Sistema de Plugins.```bash beelzebub plugin install github.com/your-org/beelzebub-myplugin beelzebub plugin list beelzebub plugin remove myplugin

### `beelzebub version`

Imprime la versión, el SHA del commit, la fecha de compilación y la información del runtime de Go.```bash
beelzebub version

Plugin System

Beelzebub expone un SDK público estable en pkg/plugin para extender el runtime de engaño sin modificar el 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 }

### Escribiendo un 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