beelzebub

Introduzione

Beelzebub è un framework open source per runtime di deception che distribuisce servizi esca adattativi e potenziati da modelli linguistici (LLM) su protocolli SSH, HTTP, TCP, TELNET e MCP. Supera gli honeypot passivi coinvolgendo attivamente gli attaccanti con interazioni realistiche, raccogliendo dati di intelligence sulle minacce e rilevando attacchi di prompt injection contro agenti AI.

Caratteristiche

Installazione

Usando Docker Compose

docker compose build
docker compose up -d

Usando Go

go mod download
go build -o beelzebub .
./beelzebub run

Usando Helm (Kubernetes)

helm install beelzebub ./beelzebub-chart
# Per aggiornare:
helm upgrade beelzebub ./beelzebub-chart

Utilizzo

Beelzebub offre una CLI strutturata con comandi come:

Esecuzione dei servizi

beelzebub run -c path/to/core.yaml -s path/to/services/ -m 100

Validazione configurazioni

beelzebub validate --conf-core ./configurations/beelzebub.yaml --conf-services ./configurations/services/

Lista plugin registrati

beelzebub plugin list

Informazioni versione

beelzebub version

Sistema Plugin

Beelzebub espone un SDK a pkg/plugin per creare plugin senza modificare il core. Le interfacce principali sono:

// CommandPlugin per risposte testuali nei protocolli SSH, TCP, TELNET e HTTP.
type CommandPlugin interface {
    Metadata() Metadata
    Execute(ctx context.Context, req CommandRequest) (string, error)
}

// HTTPPlugin per risposte HTTP complete.
type HTTPPlugin interface {
    Metadata() Metadata
    HandleHTTP(r *http.Request) HTTPResponse
}

Esempio base di 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: "Generatore custom di risposte deception",
        Version:     "1.0.0",
        Author:      "tuo-nome",
    }
}

func (p *MyPlugin) Execute(_ context.Context, req plugin.CommandRequest) (string, error) {
    return "risposta simulata a: " + req.Command, nil
}

func init() {
    plugin.Register(&MyPlugin{})
}

Per caricarlo, basta importarlo nel tuo main con una importazione vuota.

Osservabilità

Metriche Prometheus

Beelzebub espone varie metriche di evento:

Integrazione RabbitMQ

Gli eventi possono essere pubblicati su una coda RabbitMQ per l'integrazione con SIEM:

core:
  tracings:
    rabbit-mq:
      enabled: true
      uri: "amqp://guest:guest@localhost:5672/"

Testing

make test.unit
make test.dependencies.start
make test.integration
make test.dependencies.down
beelzebub validate

Qualità del Codice

Il progetto usa GitHub Actions, CodeQL, Go Report Card e Codecov per assicurare qualità e copertura test. Contributi sono tutti revisionati.

Licenza

Beelzebub è rilasciato sotto licenza GNU GPL v3.

Configurazione

Beelzebub usa due livelli di configurazione:

• Core config per impostazioni globali come logging, tracing, Prometheus
• Config servizi per ogni servizio escamotage, con YAML in services/

Esempio core:

core:
  logging:
    debug: false
    logsPath: ./logs
  tracings:
    rabbit-mq:
      enabled: false
      uri: "amqp://guest:guest@localhost:5672/"
  prometheus:
    path: "/metrics"
    port: ":2112"

Le variabili ambiente permettono override.

Servizi Deception

MCP Deception Service

Detect prompt injection su agenti AI. Strumento esca mai da invocare normalmente, eventuale uso indica bypass guardrail.

Benefici:

• Alert in tempo reale
• Raccolta prompt maligni
• Metriche di superficie di attacco

HTTP Deception Service

Risponde a richieste web simulando server reali, con matching URL regex, risposte statiche o LLM dinamici.

SSH Deception Service

Supporta sessioni SSH con risposte statiche o LLM interattivi, mantenendo la cronologia della conversazione per sessione.

Contributi

Il team accoglie contributi, bug report e domande. Vi invitiamo a leggere la guida ai contributi e il codice di condotta per mantenere una comunità rispettosa.

Buon hacking!