Retour aux mises à jour
New releaseSep 1, 2026

beelzebub v3.9.1

Un framework d'exécution de leurres low code sécurisé, exploitant l'IA pour la virtualisation des systèmes.

Partager

Beelzebub

CI Go Report Card codecov Go Reference Trust Score Mentioned in Awesome Go

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.

github beelzebub - programme d'inception

Table des matières

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

demo-beelzebub

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

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

| Commande | Rôle |
|---|---|
| `plugin install <link>` | récupère un plugin, l'intègre, reconstruit ; l'ajoute également à `configurations/plugins.yaml` |
| `plugin install` | installe tout ce qui est déclaré dans `configurations/plugins.yaml` |
| `plugin list` | affiche les plugins installés par rapport à ceux compilés dans le binaire |
| `plugin update [name]` | récupère à nouveau à la réf. déclarée et re-épingle le commit |
| `plugin remove <name>` | supprime un plugin de `configurations/plugins.yaml`, le débranche et affiche l'étape de reconstruction |

Les sources des plugins de déploiement sont configurées dans `configurations/plugins.yaml` :```yaml
plugins:
  - source: github.com/your-org/myplugin
  - source: github.com/your-org/[email protected]

La future configuration d'exécution par plugin peut se trouver sous configurations/plugins/ sous la forme d'un fichier YAML par plugin.

Chaque dépôt de plugin doit fournir un manifeste plugins.yaml et s'auto-enregistrer dans init() (voir Écriture d'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

Les plugins installés sont compilés dans le binaire Beelzebub et s'exécutent dans le même processus que le runtime. N'installez les plugins qu'à partir de dépôts de confiance.

## Observabilité

### Métriques Prometheus

Beelzebub expose les métriques Prometheus sur le point de terminaison configuré (par défaut : `:2112/metrics`) :

| Métrique | Description |
|--------|-------------|
| `beelzebub_events_total` | Total des événements de déception sur tous les services |
| `beelzebub_events_ssh_total` | Événements SSH |
| `beelzebub_events_http_total` | Événements HTTP |
| `beelzebub_events_tcp_total` | Événements TCP |
| `beelzebub_events_telnet_total` | Événements TELNET |
| `beelzebub_events_mcp_total` | Événements MCP |

### Intégration RabbitMQ

Publiez tous les événements de déception dans une file de messages pour une intégration SIEM en aval :```yaml
core:
  tracings:
    rabbit-mq:
      enabled: true
      uri: "amqp://guest:guest@localhost:5672/"

Les événements sont publiés sous forme de JSON structuré dans la file d'attente event.

Tests```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é du code

- **CI** : GitHub Actions à chaque commit et pull request
- **Analyse statique** : CodeQL et Go Report Card
- **Couverture** : surveillée via [Codecov](https://codecov.io/gh/beelzebub-labs/beelzebub)
- **Revue de code** : toutes les contributions passent par une revue par les pairs

## Licence

Beelzebub est sous licence [GNU GPL v3](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/LICENSE).

## Contribuer

L’équipe Beelzebub accueille favorablement les contributions et la participation au projet. Que vous souhaitiez signaler des bogues, contribuer de nouvelles fonctionnalités ou poser des questions, veuillez consulter notre [Guide du contributeur](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/CONTRIBUTING.md) pour des informations détaillées. Nous encourageons tous les participants et mainteneurs à adhérer à notre [Code de conduite](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/CODE_OF_CONDUCT.md) et à favoriser une communauté solidaire et respectueuse.

Bon hacking !

## Référence de configuration

Beelzebub utilise un système de configuration à deux niveaux :

1. **Configuration principale** (`beelzebub.yaml`)  paramètres globaux : journalisation, tracing, Prometheus
2. **Configurations de services** (`services/*.yaml`)  un fichier par service leurre

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

Les variables d'environnement peuvent remplacer tous les champs (par exemple BEELZEBUB_RABBITMQ_ENABLED). Les configurations de services peuvent également être fournies entièrement via BEELZEBUB_SERVICES_CONFIG sous forme de tableau JSON.

Configuration des services

Chaque service leurre est défini dans un fichier YAML séparé placé dans le répertoire services/. Le champ protocol détermine le moteur de leurre utilisé. Les commandes utilisent regex pour la correspondance des requêtes et soit un handler statique, soit une référence plugin pour les réponses dynamiques.

Lorsque vous utilisez le plugin LLMHoneypot, il est fortement recommandé d'utiliser des garde-fous pour empêcher le LLM d'être « jailbroken » ou autrement manipulé de manières qui pourraient compromettre le honeypot. Consultez la documentation du plugin LLMHoneypot pour plus de détails.

Services de leurre

Service de leurre MCP

Les services de leurre MCP (Model Context Protocol) exposent des outils leurres conçus pour détecter les attaques par injection de prompt contre les agents propulsés par LLM.

Fonctionnement

L'outil leurre est enregistré dans la liste d'outils de l'agent mais ne devrait jamais être invoqué en fonctionnement normal. Toute invocation signale qu'une attaque par injection de prompt a contourné avec succès les garde-fous de l'agent. Cela permet de :

  • Détection en temps réel du contournement des garde-fous alerte instantanée lorsqu'un attaquant convainc l'agent d'invoquer un outil restreint
  • Collecte authentique des prompts d'attaque chaque activation journalise le prompt malveillant exact utilisé
  • Métriques mesurables de la surface d'attaque suivi de HAR, TPR et MTP au fil du temps

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" } } }
Accessible via `http://beelzebub:port/mcp` (transport HTTP Streamable).

### Service HTTP de déception

Les services de déception HTTP répondent aux requêtes web avec des réponses configurables basées sur la correspondance de motifs d'URL. Prend en charge TLS, les gestionnaires statiques, les réponses basées sur LLM et le générateur de labyrinthe infini.

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

Service HTTP propulsé par LLM ajoutez un fallbackCommand avec plugin: LLMHoneypot pour générer des réponses dynamiques à toute requête non correspondante.

Générateur de labyrinthe infini utilisez plugin: MazeHoneypot pour déployer un listing de répertoire de style Apache qui s'étend à l'infini, piégeant les scanneurs automatisés et les robots d'exploration.

Service de leurre SSH

Les services de leurre SSH prennent en charge à la fois des réponses de commande statiques et des sessions interactives propulsées par LLM avec un historique de conversation par session.

SSH propulsé par 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 propulsé par LLM** (Ollama local) :```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 statique:```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
### Service de leurre TELNET

Les services de leurre TELNET émulent des dispositifs à base de terminal (routeurs, commutateurs, systèmes hérités) avec un flux d'authentification complet et une intégration LLM.

**TELNET propulsé par 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"

Simulation statique 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
### Service de déception TCP

Les services de déception TCP couvrent les protocoles binaires et textuels : bases de données, courtiers de messages, services d'annuaire, accès distant, et plus encore. Prend en charge le mode bannière uniquement, la correspondance regex interactive et l'intégration 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 propulsé par 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."

Des exemples de configurations supplémentaires sont disponibles dans configurations/services/ pour Memcached, MS-SQL, SMB, RDP, VNC et MQTT.

Avec le soutien de

Logo JetBrains.

logo gitbook

Lire plus

Catégories

Outils DéfensifsSécurité des ConteneursVirtualisation de SécuritéSécurité WebSécurité RéseauRenseignement sur les MenacesDétection d'IntrusionRéponse aux IncidentsSécurité des APISécurité de l'IA