Beelzebub

Framework runtime di deception

Beelzebub è un runtime di deception open-source che distribuisce servizi esca adattivi basati su LLM sui protocolli SSH, HTTP, TCP, TELNET e MCP. Va oltre i semplici honeypot passivi ingaggiando attivamente gli attaccanti in interazioni realistiche, raccogliendo threat intelligence ad alta fedeltà e rilevando attacchi di prompt injection contro agenti AI.

Indice dei contenuti

• Beelzebub
  • Indice dei contenuti
  • Caratteristiche principali
  • Demo di deception con LLM
  • Avvio rapido
    • Installer
    • Locale (Go)
    • Docker
    • Con Helm (Kubernetes)
  • Riferimento CLI
    • beelzebub run
    • beelzebub validate
    • beelzebub plugin
    • beelzebub version
  • Sistema di plugin
    • Interfacce
    • Scrivere un plugin
    • Installare plugin esterni
  • Observability
    • Metriche Prometheus
    • Integrazione RabbitMQ
  • Test
  • Qualità del codice
  • Licenza
  • Contributi
  • Riferimento di configurazione
    • Configurazione principale
    • Configurazione dei servizi
  • Servizi di deception
    • Servizio di deception MCP
      • Come funziona
    • Servizio di deception HTTP
    • Servizio di deception SSH
    • Servizio di deception TELNET
    • Servizio di deception TCP
  • Supportato da

Caratteristiche principali

• Motore di deception adattivo: l'integrazione con LLM (OpenAI, Ollama) genera risposte contestualmente accurate in tempo reale, mantenendo gli attaccanti coinvolti abbastanza a lungo da raccogliere TTP utilizzabili
• Definizione dei servizi low-code: configurazione basata su YAML con corrispondenza dei comandi tramite regex — nessun codice personalizzato necessario per distribuire un nuovo servizio esca
• Copertura multi-protocollo: SSH, HTTP, TCP, TELNET, MCP — dagli obiettivi infrastrutturali alle superfici di attacco degli agenti AI
• Sistema di plugin estensibile: implementa l'interfaccia CommandPlugin o HTTPPlugin e registrala tramite init() — nessuna modifica al core richiesta
• Stack di observability completo: metriche Prometheus, streaming di eventi RabbitMQ
• Runtime pronto per la produzione: Docker, Kubernetes (Helm), spegnimento graduale, limiti di memoria per servizio

Demo di deception con LLM

Avvio rapido

Installer```bash

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

Non interattivo: `./install.sh --local` o `./install.sh --docker`. Usa
`./install.sh --local --no-run` per installare e compilare senza avviare il runtime
locale. Su host non-root, l'installazione locale non si avvia automaticamente quando
la configurazione predefinita include porte privilegiate.

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

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

Riferimento CLI

Beelzebub è dotato di una CLI strutturata. Esegui beelzebub --help per vedere tutti i comandi disponibili.

beelzebub run

Avvia tutti i servizi di deception configurati.```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`

Analizza e valida tutti i file di configurazione senza avviare alcun servizio. Utile nelle pipeline CI. Consulta [Validazione della configurazione](https://github.com/beelzebub-labs/beelzebub/blob/main/docs/configuration-validation.md) per l'architettura di validazione e il riferimento delle regole.```bash
beelzebub validate --conf-core ./configurations/beelzebub.yaml --conf-services ./configurations/services/

beelzebub plugin

Installa, elenca e rimuovi plugin scaricati da GitHub. Vedi Plugin System.```bash beelzebub plugin install github.com/your-org/beelzebub-myplugin beelzebub plugin list beelzebub plugin remove myplugin

### `beelzebub version`

Stampa la versione, il commit SHA, la data di build e le informazioni sul runtime Go.```bash
beelzebub version

Sistema di Plugin

Beelzebub espone un SDK pubblico stabile in pkg/plugin per estendere il runtime di deception senza modificare il codice core.

Interfacce```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 }

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

Installazione dei Plugin Esterni```bash

Declare plugins in configurations/plugins.yaml, or:

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