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.

github beelzebub - inception program

Indice dei contenuti

Beelzebub

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

demo-beelzebub

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

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

| Comando | Cosa fa |
|---|---|
| `plugin install <link>` | recupera un plugin, lo integra, ricompila; lo aggiunge anche a `configurations/plugins.yaml` |
| `plugin install` | installa tutto ciò che è dichiarato in `configurations/plugins.yaml` |
| `plugin list` | mostra i plugin installati rispetto a quelli compilati nel binario |
| `plugin update [name]` | recupera di nuovo al ref dichiarato e ri-fissa il commit |
| `plugin remove <name>` | rimuove un plugin da `configurations/plugins.yaml`, lo scollega e stampa il passaggio di ricompilazione |

Le sorgenti dei plugin di deployment sono configurate in `configurations/plugins.yaml`:```yaml
plugins:
  - source: github.com/your-org/myplugin
  - source: github.com/your-org/[email protected]

La futura configurazione runtime per plugin può risiedere in configurations/plugins/ come un file YAML per plugin.

Ogni repository di plugin deve includere un manifest plugins.yaml e auto-registrarsi in init() (vedi Scrivere un 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

github.com/your-org/[email protected]

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

## Osservabilità

### Metriche Prometheus

Beelzebub espone le metriche Prometheus all'endpoint configurato (predefinito: `:2112/metrics`):

| Metrica | Descrizione |
|--------|-------------|
| `beelzebub_events_total` | Eventi di deception totali su tutti i servizi |
| `beelzebub_events_ssh_total` | Eventi SSH |
| `beelzebub_events_http_total` | Eventi HTTP |
| `beelzebub_events_tcp_total` | Eventi TCP |
| `beelzebub_events_telnet_total` | Eventi TELNET |
| `beelzebub_events_mcp_total` | Eventi MCP |

### Integrazione RabbitMQ

Pubblica tutti gli eventi di deception in una coda di messaggi per l'integrazione a valle con SIEM:```yaml
core:
  tracings:
    rabbit-mq:
      enabled: true
      uri: "amqp://guest:guest@localhost:5672/"

Gli eventi vengono pubblicati come JSON strutturato nella coda event.

Test```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

## Qualità del codice

- **CI**: GitHub Actions a ogni commit e pull request
- **Analisi statica**: CodeQL e Go Report Card
- **Copertura**: Monitorata tramite [Codecov](https://codecov.io/gh/beelzebub-labs/beelzebub)
- **Revisione del codice**: Tutti i contributi vengono sottoposti a revisione tra pari

## Licenza

Beelzebub è rilasciato sotto la [GNU GPL v3 License](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/LICENSE).

## Contribuire

Il team di Beelzebub accoglie con favore contributi e partecipazione al progetto. Che tu voglia segnalare bug, contribuire con nuove funzionalità o avere domande, consulta la nostra [Guida per i contributori](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/CONTRIBUTING.md) per informazioni dettagliate. Incoraggiamo tutti i partecipanti e i manutentori ad attenersi al nostro [Codice di condotta](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/CODE_OF_CONDUCT.md) e a promuovere una community solidale e rispettosa.

Happy hacking!

## Riferimento di configurazione

Beelzebub utilizza un sistema di configurazione a due livelli:

1. **Configurazione principale** (`beelzebub.yaml`) - impostazioni globali: logging, tracing, Prometheus
2. **Configurazioni dei servizi** (`services/*.yaml`) - un file per ogni servizio esca

### Configurazione principale```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"

Le sostituzioni tramite variabili d'ambiente sono supportate per tutti i campi (ad es. BEELZEBUB_RABBITMQ_ENABLED). Le configurazioni dei servizi possono anche essere fornite interamente tramite BEELZEBUB_SERVICES_CONFIG come array JSON.

Configurazione dei servizi

Ogni servizio esca è definito in un file YAML separato collocato nella directory services/. Il campo protocol determina il motore di inganno utilizzato. I comandi usano regex per il matching delle richieste e un handler statico oppure un riferimento a plugin per le risposte dinamiche.

Quando si utilizza il plugin LLMHoneypot, è fortemente consigliato usare le guardrail per impedire che l'LLM venga jailbreakkato o comunque manipolato in modi che possano compromettere l'honeypot. Vedere la documentazione del plugin LLMHoneypot per i dettagli.

Servizi di inganno

Servizio di inganno MCP

I servizi di inganno MCP (Model Context Protocol) espongono strumenti esca progettati per rilevare attacchi di prompt injection contro agenti basati su LLM.

Come funziona

Lo strumento esca è registrato nell'elenco degli strumenti dell'agente ma non dovrebbe mai essere invocato in condizioni operative normali. Qualsiasi invocazione segnala che un attacco di prompt injection ha bypassato con successo le guardrail dell'agente. Questo fornisce:

Rilevamento in tempo reale del bypass delle guardrail alert immediato quando un attaccante convince l'agente a invocare uno strumento ristretto
Raccolta autentica dei prompt d'attacco ogni attivazione registra il prompt malevolo esatto utilizzato
Metriche misurabili della superficie d'attacco monitoraggio di HAR, TPR e MTP nel tempo

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

Accessibile tramite `http://beelzebub:port/mcp` (trasporto HTTP Streamable).

### Servizio di Deception HTTP

I servizi di deception HTTP rispondono alle richieste web con risposte configurabili in base al pattern di corrispondenza dell'URL. Supportano TLS, handler statici, risposte basate su LLM e il generatore di labirinti infiniti.

**Simulazione di 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

Servizio HTTP potenziato da LLM aggiungi un fallbackCommand con plugin: LLMHoneypot per generare risposte dinamiche per ogni richiesta non corrispondente.

Generatore di labirinti infiniti usa plugin: MazeHoneypot per distribuire un elenco di directory in stile Apache che si espande all'infinito, intrappolando scanner e crawler automatizzati.

Servizio di Deception SSH

I servizi di deception SSH supportano sia risposte a comandi statiche sia sessioni interattive potenziate da LLM con cronologia della conversazione per sessione.

SSH potenziato da 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 potenziato da LLM** (Ollama locale):```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 statico:```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

### Servizio di Deception TELNET

I servizi di deception TELNET emulano dispositivi basati su terminale (router, switch, sistemi legacy) con flusso di autenticazione completo e integrazione LLM.

**TELNET basato su 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"

Simulazione statica di 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

### Servizio di Deception TCP

I servizi di deception TCP coprono protocolli binari e basati su testo: database, message broker, servizi directory, accesso remoto e altro. Supporta la modalità solo-banner, il matching regex interattivo e l'integrazione 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 potenziato da 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."

Configurazioni di esempio aggiuntive sono disponibili in configurations/services/ per Memcached, MS-SQL, SMB, RDP, VNC e MQTT.

Supportato da

gitbook logo

Più Popolari

beelzebub