Beelzebub

Deception-Laufzeit-Framework

Beelzebub ist eine Open-Source-Deception-Laufzeitumgebung, die adaptive, auf LLM basierende Täuschungsdienste über SSH-, HTTP-, TCP-, TELNET- und MCP-Protokolle bereitstellt. Sie geht über passive Honeypots hinaus, indem sie Angreifer aktiv in realistische Interaktionen verwickelt, hochwertige Threat Intelligence sammelt und Prompt-Injection-Angriffe auf KI-Agenten erkennt.

github beelzebub - Inception-Programm

Inhaltsverzeichnis

Beelzebub

Hauptfunktionen

Adaptive Deception-Engine: LLM-Integration (OpenAI, Ollama) generiert in Echtzeit kontextgenaue Antworten und hält Angreifer lange genug aktiv, um verwertbare TTPs zu sammeln.
Low-Code-Dienstdefinition: YAML-basierte Konfiguration mit Regex-Befehlsabgleich — kein benutzerdefinierter Code erforderlich, um einen neuen Täuschungsdienst bereitzustellen.
Multi-Protokoll-Abdeckung: SSH, HTTP, TCP, TELNET, MCP von Infrastrukturzielen bis zu Angriffsflächen von KI-Agenten.
Erweiterbares Plugin-System: Implementieren Sie das CommandPlugin- oder HTTPPlugin-Interface und registrieren Sie es über init() keine Kernänderungen erforderlich.
Vollständiger Observability-Stack: Prometheus-Metriken, RabbitMQ-Event-Streaming.
Produktionsreife Laufzeitumgebung: Docker, Kubernetes (Helm), Graceful Shutdown, Speicherlimits pro Dienst.

LLM-Deception-Demo

demo-beelzebub

Schnellstart

Installer```bash

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

Nicht-interaktiv: `./install.sh --local` oder `./install.sh --docker`. Verwenden Sie `./install.sh --local --no-run`, um zu installieren und zu bauen, ohne die lokale Laufzeit zu starten. Auf Nicht-Root-Hosts startet die lokale Installation nicht automatisch, wenn die Standardkonfiguration privilegierte Ports enthält.

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

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

CLI-Referenz

Beelzebub wird mit einer strukturierten CLI ausgeliefert. Führen Sie beelzebub --help aus, um alle verfügbaren Befehle anzuzeigen.

`beelzebub run`

Startet alle konfigurierten Täuschungsdienste.```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`

Parst und validiert alle Konfigurationsdateien, ohne Dienste zu starten. Nützlich in CI-Pipelines. Siehe [Konfigurationsvalidierung](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/docs/configuration-validation.md) für die Validierungsarchitektur und die Regelreferenz.```bash
beelzebub validate --conf-core ./configurations/beelzebub.yaml --conf-services ./configurations/services/

`beelzebub plugin`

Installieren, auflisten und entfernen von Plugins, die von GitHub abgerufen werden. Siehe Plugin-System.```bash beelzebub plugin install github.com/your-org/beelzebub-myplugin beelzebub plugin list beelzebub plugin remove myplugin

### `beelzebub version`

Gibt Version, Commit-SHA, Build-Datum und Go-Runtime-Informationen aus.```bash
beelzebub version

Plugin-System

Beelzebub stellt ein stabiles öffentliches SDK unter pkg/plugin bereit, um die Deception-Laufzeitumgebung zu erweitern, ohne den Kerncode zu modifizieren.

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

### Ein Plugin schreiben```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{})
}

Externe Plugins installieren```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)

| Befehl | Beschreibung |
|---|---|
| `plugin install <link>` | holt ein Plugin, bindet es ein, baut neu; fügt es außerdem zu `configurations/plugins.yaml` hinzu |
| `plugin install` | installiert alles, was in `configurations/plugins.yaml` deklariert ist |
| `plugin list` | zeigt installierte Plugins im Vergleich zu denen, die in die Binärdatei kompiliert sind |
| `plugin update [name]` | ruft den deklarierten Ref erneut ab und pinnt den Commit erneut fest |
| `plugin remove <name>` | entfernt ein Plugin aus `configurations/plugins.yaml`, bindet es aus und gibt den Rebuild-Schritt aus |

Die Quellen für Deployment-Plugins werden in `configurations/plugins.yaml` konfiguriert:```yaml
plugins:
  - source: github.com/your-org/myplugin
  - source: github.com/your-org/[email protected]

Zukünftige Laufzeitkonfigurationen pro Plugin können unter configurations/plugins/ als eine YAML-Datei pro Plugin abgelegt werden.

Jedes Plugin-Repository muss ein plugins.yaml-Manifest mitliefern und sich in init() selbst registrieren (siehe Plugin schreiben):```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]

Installierte Plugins werden in die Beelzebub-Binärdatei kompiliert und laufen im
selben Prozess wie die Laufzeitumgebung. Installieren Sie Plugins nur aus Repositories, denen Sie vertrauen.

## Beobachtbarkeit

### Prometheus-Metriken

Beelzebub stellt Prometheus-Metriken am konfigurierten Endpunkt bereit (Standard: `:2112/metrics`):

| Metrik | Beschreibung |
|--------|-------------|
| `beelzebub_events_total` | Gesamtzahl der Täuschungsereignisse über alle Dienste hinweg |
| `beelzebub_events_ssh_total` | SSH-Ereignisse |
| `beelzebub_events_http_total` | HTTP-Ereignisse |
| `beelzebub_events_tcp_total` | TCP-Ereignisse |
| `beelzebub_events_telnet_total` | TELNET-Ereignisse |
| `beelzebub_events_mcp_total` | MCP-Ereignisse |

### RabbitMQ-Integration

Veröffentlichen Sie alle Täuschungsereignisse in einer Nachrichtenwarteschlange für die nachgelagerte SIEM-Integration:```yaml
core:
  tracings:
    rabbit-mq:
      enabled: true
      uri: "amqp://guest:guest@localhost:5672/"

Events werden als strukturiertes JSON in die event-Warteschlange veröffentlicht.

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

## Code-Qualität

- **CI**: GitHub Actions bei jedem Commit und Pull Request
- **Statische Analyse**: CodeQL und Go Report Card
- **Testabdeckung**: Überwacht mittels [Codecov](https://codecov.io/gh/beelzebub-labs/beelzebub)
- **Code-Review**: Alle Beiträge durchlaufen ein Peer-Review

## Lizenz

Beelzebub ist unter der [GNU GPL v3 Lizenz](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/LICENSE) lizenziert.

## Mitwirken

Das Beelzebub-Team begrüßt Beiträge und Projektbeteiligung. Ob du Fehler melden, neue Funktionen beitragen oder Fragen haben möchtest, wirf bitte einen Blick in unseren [Mitwirkungsleitfaden](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/CONTRIBUTING.md) für detaillierte Informationen. Wir ermutigen alle Teilnehmer und Maintainer, sich an unseren [Verhaltenskodex](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/CODE_OF_CONDUCT.md) zu halten und eine unterstützende und respektvolle Gemeinschaft zu fördern.

Viel Spaß beim Hacken!

## Konfigurationsreferenz

Beelzebub verwendet ein zweistufiges Konfigurationssystem:

1. **Kernkonfiguration** (`beelzebub.yaml`)  globale Einstellungen: Logging, Tracing, Prometheus
2. **Service-Konfigurationen** (`services/*.yaml`)  eine Datei pro Decoy-Service

### Kernkonfiguration```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"

Umgebungsvariablen-Überschreibungen werden für alle Felder unterstützt (z. B. BEELZEBUB_RABBITMQ_ENABLED). Servicekonfigurationen können auch vollständig über BEELZEBUB_SERVICES_CONFIG als JSON-Array bereitgestellt werden.

Servicekonfiguration

Jeder Decoy-Dienst wird in einer separaten YAML-Datei im Verzeichnis services/ definiert. Das Feld protocol bestimmt die verwendete Deception-Engine. Befehle verwenden regex für den Abgleich von Anfragen sowie entweder einen statischen handler oder eine plugin-Referenz für dynamische Antworten.

Bei Verwendung des LLMHoneypot-Plugins wird dringend empfohlen, Guardrails einzusetzen, um zu verhindern, dass das LLM jailbroken oder auf andere Weise manipuliert wird, was den Honeypot gefährden könnte. Einzelheiten finden Sie in der Dokumentation zum LLMHoneypot-Plugin.

Deception-Dienste

MCP-Deception-Dienst

MCP-Deception-Dienste (Model Context Protocol) stellen Decoy-Werkzeuge bereit, die darauf ausgelegt sind, Prompt-Injection-Angriffe auf LLM-basierte Agenten zu erkennen.

So funktioniert es

Das Decoy-Tool wird in der Tool-Liste des Agenten registriert, sollte aber im normalen Betrieb niemals aufgerufen werden. Jeder Aufruf signalisiert, dass ein Prompt-Injection-Angriff die Guardrails des Agenten erfolgreich umgangen hat. Dies bietet:

Echtzeit-Erkennung von Guardrail-Bypasses sofortige Alarmierung, wenn ein Angreifer den Agenten dazu bringt, ein eingeschränktes Tool aufzurufen
Authentische Sammlung von Angriffs-Prompts jede Aktivierung protokolliert den exakten bösartigen Prompt, der verwendet wurde
Messbare Angriffsflächen-Metriken Verfolgung von HAR, TPR und MTP im Zeitverlauf

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

Zugänglich über `http://beelzebub:port/mcp` (Streamable-HTTP-Transport).

### HTTP-Täuschungsdienst

HTTP-Täuschungsdienste antworten auf Webanfragen mit konfigurierbaren Antworten, die auf URL-Musterabgleich basieren. Unterstützt TLS, statische Handler, LLM-gestützte Antworten und den Generator für das unendliche Labyrinth.

**WordPress-Simulation** (`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

LLM-gestützter HTTP-Dienst fügen Sie einen fallbackCommand mit plugin: LLMHoneypot hinzu, um dynamische Antworten für jede nicht übereinstimmende Anfrage zu generieren.

Unendlicher Labyrinth-Generator verwenden Sie plugin: MazeHoneypot, um eine Apache-ähnliche Verzeichnisliste bereitzustellen, die sich unendlich erweitert und automatisierte Scanner und Crawler einfängt.

SSH-Täuschungsdienst

SSH-Täuschungsdienste unterstützen sowohl statische Befehlsantworten als auch LLM-gestützte interaktive Sitzungen mit sitzungsbezogenem Konversationsverlauf.

LLM-gestütztes SSH (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"

**LLM-basiertes SSH** (lokales Ollama):```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"

Statisches SSH:```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

### TELNET-Täuschungsdienst

TELNET-Täuschungsdienste emulieren terminalbasierte Geräte (Router, Switches, Altsysteme) mit vollständigem Authentifizierungsablauf und LLM-Integration.

**LLM-gestütztes TELNET**:```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"

Statische Cisco-IOS-Simulation:```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

### TCP-Deception-Dienst

TCP-Täuschungsdienste decken binäre und textbasierte Protokolle ab: Datenbanken, Message-Broker, Verzeichnisdienste, Fernzugriff und mehr. Unterstützt Banner-only-Modus, interaktives Regex-Matching und LLM-Integration.

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

**LLM-gestütztes PostgreSQL**:```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."

Weitere Beispielkonfigurationen sind in configurations/services/ für Memcached, MS-SQL, SMB, RDP, VNC und MQTT verfügbar.

Unterstützt von

gitbook logo

beelzebub

Beliebteste