Beelzebub

Framework d'exécution de leurre

Beelzebub est un runtime de leurre open source qui déploie des services leurres adaptatifs propulsés par LLM sur les protocoles SSH, HTTP, TCP, TELNET et MCP. Il va au-delà des honeypots passifs en engageant activement les attaquants dans des interactions réalistes, en collectant des renseignements sur les menaces de haute fidélité et en détectant les attaques par injection de prompt contre les agents IA.

Table des matières

• Beelzebub
  • Table des matières
  • Fonctionnalités clés
  • Démonstration de leurre LLM
  • Démarrage rapide
    • Installeur
    • Local (Go)
    • Docker
    • Avec Helm (Kubernetes)
  • Référence CLI
    • beelzebub run
    • beelzebub validate
    • beelzebub plugin
    • beelzebub version
  • Système de plugins
    • Interfaces
    • Écrire un plugin
    • Installer des plugins externes
  • Observabilité
    • Métriques Prometheus
    • Intégration RabbitMQ
  • Tests
  • Qualité du code
  • Licence
  • Contribuer
  • Référence de configuration
    • Configuration de base
    • Configuration du service
  • Services de leurre
    • Service de leurre MCP
      • Comment ça fonctionne
    • Service de leurre HTTP
    • Service de leurre SSH
    • Service de leurre TELNET
    • Service de leurre TCP
  • Soutenu par

Fonctionnalités clés

• Moteur de leurre adaptatif : l'intégration LLM (OpenAI, Ollama) génère des réponses contextuellement précises en temps réel, maintenant les attaquants engagés assez longtemps pour collecter des TTP exploitables
• Définition de services low-code : configuration basée sur YAML avec correspondance de commandes par expressions régulières — aucun code personnalisé requis pour déployer un nouveau service leurre
• Couverture multi-protocoles : SSH, HTTP, TCP, TELNET, MCP — des cibles d'infrastructure aux surfaces d'attaque des agents IA
• Système de plugins extensible : implémentez l'interface CommandPlugin ou HTTPPlugin et enregistrez-la via init() — aucune modification du cœur requise
• Pile d'observabilité complète : métriques Prometheus, flux d'événements RabbitMQ
• Runtime prêt pour la production : Docker, Kubernetes (Helm), arrêt propre, limites de mémoire par service

Démonstration de leurre LLM

Démarrage rapide

Installeur```bash

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

Non interactif : `./install.sh --local` ou `./install.sh --docker`. Utilisez
`./install.sh --local --no-run` pour installer et compiler sans démarrer l’exécution
locale. Sur les hôtes non root, l’installation locale ne démarre pas automatiquement lorsque la
configuration par défaut inclut des ports privilégiés.

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

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

Référence CLI

Beelzebub est fourni avec une CLI structurée. Exécutez beelzebub --help pour voir toutes les commandes disponibles.

beelzebub run

Démarrez tous les services de leurre configurés.```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`

Analyse et valide tous les fichiers de configuration sans démarrer aucun service. Utile dans les pipelines CI. Voir [Validation de la configuration](https://github.com/beelzebub-labs/beelzebub/blob/main/docs/configuration-validation.md) pour l'architecture de validation et la référence des règles.```bash
beelzebub validate --conf-core ./configurations/beelzebub.yaml --conf-services ./configurations/services/

beelzebub plugin

Installer, lister et supprimer des plugins récupérés depuis GitHub. Voir Système de plugins.```bash beelzebub plugin install github.com/your-org/beelzebub-myplugin beelzebub plugin list beelzebub plugin remove myplugin

### `beelzebub version`

Affiche la version, le SHA du commit, la date de build et les informations sur le runtime Go.```bash
beelzebub version

Système de plugins

Beelzebub expose un SDK public stable dans pkg/plugin pour étendre le runtime de déception sans modifier le code 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 }

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

Installation de plugins externes```bash

Declare plugins in configurations/plugins.yaml, or:

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