Volver a actualizaciones
Nuevo releaseSep 1, 2026

beelzebub v3.9.1

Un framework de runtime de decepción seguro y de bajo código, que aprovecha la IA para la virtualización de sistemas.

Compartir

Beelzebub

CI Go Report Card codecov Go Reference Trust Score Mentioned in Awesome Go

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.

github beelzebub - inception program

Tabla de contenidos

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

demo-beelzebub

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

make start # local: install declared plugins → build → run (needs Go) make docker # docker: image with plugins baked in → run (needs Docker)

| Comando | Qué hace |
|---|---|
| `plugin install <link>` | obtiene un plugin, lo integra, reconstruye; también lo añade a `configurations/plugins.yaml` |
| `plugin install` | instala todo lo declarado en `configurations/plugins.yaml` |
| `plugin list` | muestra los plugins instalados frente a lo compilado en el binario |
| `plugin update [name]` | vuelve a obtener la referencia declarada y fija de nuevo el commit |
| `plugin remove <name>` | elimina un plugin de `configurations/plugins.yaml`, lo desvincula e indica el paso de reconstrucción |

Las fuentes de plugins de despliegue se configuran en `configurations/plugins.yaml`:```yaml
plugins:
  - source: github.com/your-org/myplugin
  - source: github.com/your-org/[email protected]

La configuración futura en tiempo de ejecución por plugin puede ubicarse en configurations/plugins/ como un archivo YAML por plugin.

Cada repositorio de plugins debe incluir un manifiesto plugins.yaml y auto-registrarse en init() (consulte Writing a Plugin):```yaml 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

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

## Observabilidad

### Métricas de Prometheus

Beelzebub expone métricas de Prometheus en el endpoint configurado (por defecto: `:2112/metrics`):

| Metric | Description |
|--------|-------------|
| `beelzebub_events_total` | Total de eventos de engaño en todos los servicios |
| `beelzebub_events_ssh_total` | Eventos SSH |
| `beelzebub_events_http_total` | Eventos HTTP |
| `beelzebub_events_tcp_total` | Eventos TCP |
| `beelzebub_events_telnet_total` | Eventos TELNET |
| `beelzebub_events_mcp_total` | Eventos MCP |

### Integración con RabbitMQ

Publica todos los eventos de engaño en una cola de mensajes para la integración posterior con SIEM:```yaml
core:
  tracings:
    rabbit-mq:
      enabled: true
      uri: "amqp://guest:guest@localhost:5672/"

Los eventos se publican como JSON estructurado en la cola event.

Pruebas```bash

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

## Calidad del Código

- **CI**: GitHub Actions en cada commit y pull request
- **Análisis estático**: CodeQL y Go Report Card
- **Cobertura**: Monitoreada mediante [Codecov](https://codecov.io/gh/beelzebub-labs/beelzebub)
- **Revisión de código**: Todas las contribuciones pasan por revisión de pares

## Licencia

Beelzebub está licenciado bajo la [Licencia GNU GPL v3](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/LICENSE).

## Contribuciones

El equipo de Beelzebub da la bienvenida a contribuciones y participación en el proyecto. Ya sea que desees reportar errores, contribuir con nuevas funciones o tengas alguna pregunta, consulta nuestra [Guía para Contribuyentes](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/CONTRIBUTING.md) para obtener información detallada. Animamos a todos los participantes y mantenedores a adherirse a nuestro [Código de Conducta](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/CODE_OF_CONDUCT.md) y a fomentar una comunidad solidaria y respetuosa.

¡Feliz hacking!

## Referencia de Configuración

Beelzebub utiliza un sistema de configuración de dos niveles:

1. **Configuración principal** (`beelzebub.yaml`)  configuración global: logging, tracing, Prometheus
2. **Configuraciones de servicios** (`services/*.yaml`)  un archivo por servicio señuelo

### Configuración Principal```yaml
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.

Configuración de servicios

Cada servicio señuelo se define en un archivo YAML separado ubicado en el directorio services/. El campo protocol determina el motor de engaño utilizado. Los comandos usan regex para la coincidencia de solicitudes y ya sea un handler estático o una referencia a un plugin para respuestas dinámicas.

Al usar el plugin LLMHoneypot, se recomienda encarecidamente usar guardarraíles para evitar que el LLM sea jailbroken o manipulado de otras formas que puedan comprometer el honeypot. Consulte la documentación del plugin LLMHoneypot para obtener más detalles.

Servicios de engaño

Servicio de engaño MCP

Los servicios de engaño MCP (Model Context Protocol) exponen herramientas señuelo diseñadas para detectar ataques de inyección de prompt contra agentes impulsados por LLM.

Cómo funciona

La herramienta señuelo está registrada en la lista de herramientas del agente, pero nunca debe invocarse durante la operación normal. Cualquier invocación indica que un ataque de inyección de prompt ha logrado evadir los guardarraíles del agente. Esto proporciona:

  • Detección de evasión de guardarraíles en tiempo real alerta instantánea cuando un atacante convence al agente de invocar una herramienta restringida
  • Recopilación auténtica de prompts de ataque cada activación registra el prompt malicioso exacto utilizado
  • Métricas medibles de superficie de ataque seguimiento de HAR, TPR y MTP a lo largo del tiempo

video-mcp-diagram

mcp-8000.yaml:```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: [email protected], 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: [email protected], last-login: 02/07/2025" } } }
Accesible a través de `http://beelzebub:port/mcp` (transporte HTTP Streamable).

### Servicio de Engaño HTTP

Los servicios de engaño HTTP responden a solicitudes web con respuestas configurables basadas en la coincidencia de patrones de URL. Admite TLS, manejadores estáticos, respuestas impulsadas por LLM y el generador de laberintos infinito.

**Simulación de WordPress** (`http-80.yaml`):```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

Servicio HTTP impulsado por LLM añade un fallbackCommand con plugin: LLMHoneypot para generar respuestas dinámicas ante cualquier solicitud no coincidente.

Generador de laberinto infinito utiliza plugin: MazeHoneypot para desplegar un listado de directorios estilo Apache que se expande infinitamente, atrapando escáneres y rastreadores automatizados.

Servicio de Decepción SSH

Los servicios de decepción SSH admiten tanto respuestas de comandos estáticas como sesiones interactivas impulsadas por LLM con historial de conversación por sesión.

SSH impulsado por LLM (OpenAI):```yaml 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"
**SSH potenciado por LLM** (Ollama local):```yaml
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"

SSH estático:```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"
  • regex: "^uname -m$" handler: "x86_64"
  • regex: "^docker ps$" handler: "CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES"
  • regex: "^(.+)$" handler: "command not found" serverVersion: "OpenSSH" serverName: "ubuntu" passwordRegex: "^(root|qwerty|Smoker666)$" deadlineTimeoutSeconds: 60
### Servicio de engaño TELNET

Los servicios de engaño TELNET emulan dispositivos basados en terminales (routers, switches, sistemas heredados) con un flujo de autenticación completo e integración con LLM.

**TELNET impulsado por LLM**:```yaml
apiVersion: "v1"
protocol: "telnet"
address: ":23"
description: "TELNET LLM"
commands:
  - regex: "^(.+)$"
    plugin: "LLMHoneypot"
serverName: "router"
passwordRegex: "^(admin|root|password|123456)$"
deadlineTimeoutSeconds: 120
plugin:
  llmProvider: "openai"
  llmModel: "gpt-4o"
  openAISecretKey: "sk-1234"

Simulación estática de Cisco IOS:```yaml apiVersion: "v1" protocol: "telnet" address: ":23" description: "Cisco IOS Router" commands:

  • regex: "^show version$" handler: "Cisco IOS Software, Version 15.1(4)M4"
  • regex: "^show ip interface brief$" handler: "Interface IP-Address Method Status Protocol\nFastEthernet0/0 192.168.1.1 YES NVRAM up up"
  • regex: "^(.+)$" handler: "% Unknown command" serverName: "router" passwordRegex: "^(admin|cisco|password)$" deadlineTimeoutSeconds: 60
### Servicio de engaño TCP

Los servicios de engaño TCP cubren protocolos binarios y basados en texto: bases de datos, brokers de mensajes, servicios de directorio, acceso remoto y más. Soporta modo solo banner, coincidencia interactiva de expresiones regulares e integración con LLM.

**Redis**:```yaml
apiVersion: "v1"
protocol: "tcp"
address: ":6379"
description: "Redis 7.0.12"
commands:
  - regex: "^PING"
    handler: "+PONG\r\n"
  - regex: "^AUTH"
    handler: "-ERR Client sent AUTH, but no password is set\r\n"
  - regex: "^INFO"
    handler: "$180\r\n# Server\r\nredis_version:7.0.12\r\nos:Linux 5.15.0-76-generic x86_64\r\ntcp_port:6379\r\n\r\n"
  - regex: "^(.+)$"
    handler: "-ERR unknown command\r\n"
deadlineTimeoutSeconds: 60
serverName: "redis-prod-01"

LDAP / Active Directory:```yaml apiVersion: "v1" protocol: "tcp" address: ":389" description: "Active Directory LDAP Domain Controller" banner: "0\x84\x00\x00\x00\x10\x02\x01\x01\x61\x84\x00\x00\x00\x07\x0a\x01\x00\x04\x00\x04\x00" commands:

  • regex: "\x30.*\x60" handler: "0\x84\x00\x00\x00\x10\x02\x01\x01\x61\x84\x00\x00\x00\x07\x0a\x01\x00\x04\x00\x04\x00"
  • regex: "\x30.*\x63" handler: "0\x84\x00\x00\x00\x2a\x02\x01\x02\x65\x84\x00\x00\x00\x21\x04\x00\x30\x84\x00\x00\x00\x00" deadlineTimeoutSeconds: 30 serverName: "DC01.corp.local"
**PostgreSQL impulsado por LLM**:```yaml
apiVersion: "v1"
protocol: "tcp"
address: ":5432"
description: "PostgreSQL 15.3"
commands:
  - regex: "^(.+)$"
    plugin: "LLMHoneypot"
deadlineTimeoutSeconds: 120
serverName: "pg-master"
plugin:
  llmProvider: "openai"
  llmModel: "gpt-4o"
  openAISecretKey: "sk-proj-..."
  prompt: "You are simulating a PostgreSQL 15.3 server. Respond to incoming TCP data as a PostgreSQL server would."

Hay configuraciones de ejemplo adicionales disponibles en configurations/services/ para Memcached, MS-SQL, SMB, RDP, VNC y MQTT.

Con el apoyo de

Logo de JetBrains.

logo de gitbook

Leer más

Categorías

Herramientas DefensivasSeguridad de ContenedoresVirtualización de SeguridadSeguridad WebSeguridad de RedesInteligencia de AmenazasDetección de IntrusionesRespuesta a IncidentesSeguridad de APIsSeguridad de IA