Beelzebub

Overview

Beelzebub is an advanced honeypot framework designed to provide a highly secure environment for detecting and analyzing cyber attacks. It offers a low code approach for easy implementation and uses AI to mimic the behavior of a high-interaction honeypot.

Table of Contents

• Global Threat Intelligence Community
• Key Features
• Architecture
• Quick Start
• Configuration
  • Core Configuration
  • Service Configuration
• Protocol Examples
  • MCP Honeypot
  • HTTP Honeypot
  • SSH Honeypot
  • TELNET Honeypot
  • TCP Honeypot
• Observability
  • Prometheus Metrics
  • RabbitMQ Integration
  • Beelzebub Cloud
• Testing
• Code Quality
• Contributing
• License

Global Threat Intelligence Community

Our mission is to establish a collaborative ecosystem of security researchers and white hat professionals worldwide, dedicated to creating a distributed honeypot network that identifies emerging malware, discovers zero-day vulnerabilities, and neutralizes active botnets.

The white paper includes information on how to join our Discord community and contribute to the global threat intelligence network.

Key Features

Beelzebub offers a wide range of features to enhance your honeypot environment:

• Low-code configuration: YAML-based, modular service definition
• LLM integration: The LLM convincingly simulates a real system, creating high-interaction honeypot experiences, while actually maintaining low-interaction architecture for enhanced security and easy management
• Multi-protocol support: SSH, HTTP, TCP, TELNET, MCP (detect prompt injection against LLM agents)
• Prometheus metrics & observability: Built-in metrics endpoint for monitoring
• Event tracing: Multiple output strategies (stdout, RabbitMQ, Beelzebub Cloud)
• Docker & Kubernetes ready: Deploy anywhere with provided configurations
• ELK stack ready: Official integration available at Elastic docs

LLM Honeypot Demo

Quick Start

You can run Beelzebub via Docker, Go compiler(cross device), or Helm (Kubernetes).

Using Docker Compose

1. Build the Docker images:

   $ docker compose build
   

2. Start Beelzebub in detached mode:

   $ docker compose up -d
   

Using Go Compiler

1. Download the necessary Go modules:

   $ go mod download
   

2. Build the Beelzebub executable:

   $ go build
   

3. Run Beelzebub:

   $ ./beelzebub
   

Deploy on kubernetes cluster using helm

1. Install helm

2. Deploy beelzebub:

   $ helm install beelzebub ./beelzebub-chart
   

3. Next release

   $ helm upgrade beelzebub ./beelzebub-chart
   

Configuration

Beelzebub uses a two-tier configuration system:

1. Core configuration (beelzebub.yaml) - Global settings for logging, tracing, and Prometheus
2. Service configurations (services/*.yaml) - Individual honeypot service definitions

Core Configuration

The core configuration file controls global behavior:

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"
  beelzebub-cloud:
    enabled: false
    uri: ""
    auth-token: ""

Service Configuration

Each honeypot service is defined in a separate YAML file in the services/ directory. To run Beelzebub with custom paths:

./beelzebub --confCore ./configurations/beelzebub.yaml --confServices ./configurations/services/

Additional flags:

• --memLimitMiB <value> - Set memory limit in MiB (default: 100, use -1 to disable)

Protocol Examples

Below are example configurations for each supported protocol.

MCP Honeypot

MCP (Model Context Protocol) honeypots are decoy tools designed to detect prompt injection attacks against LLM agents.

Why Use an MCP Honeypot?

An MCP honeypot is a decoy tool that the agent should never invoke under normal circumstances. Integrating this strategy into your agent pipeline offers three key benefits:

• Real-time detection of guardrail bypass attempts - Instantly identify when a prompt injection attack successfully convinces the agent to invoke a restricted tool
• Automatic collection of real attack prompts - Every activation logs genuine malicious prompts, enabling continuous improvement of your filtering mechanisms
• Continuous monitoring of attack trends - Track exploit frequency and system resilience using objective, actionable measurements (HAR, TPR, MTP)

mcp-8000.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: kirsten@gmail.com, 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. Results are pending internal processing and will be logged.",
          "result": {
            "operation_status": "success",
            "details": "Info: email: kirsten@gmail.com, last-login: 02/07/2025"
          }
        }
      }

Invoke remotely via http://beelzebub:port/mcp (Streamable HTTP Server).

HTTP Honeypot

HTTP honeypots respond to web requests with configurable responses based on URL pattern matching.

http-80.yaml (WordPress simulation):

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>
        <header>
          <title>Wordpress 6 test page</title>
        </header>
        <body>
          <form action="" method="post">
            <label for="uname"><b>Username</b></label>
            <input type="text" placeholder="Enter Username" name="uname" required>

            <label for="psw"><b>Password</b></label>
            <input type="password" placeholder="Enter Password" name="psw" required>

            <button type="submit">Login</button>
          </form>
        </body>
      </html>
    headers:
      - "Content-Type: text/html"
      - "Server: Apache/2.4.53 (Debian)"
      - "X-Powered-By: PHP/7.4.29"
    statusCode: 200
  - regex: "^.*$"
    handler:
      <html>
        <header>
          <title>404</title>
        </header>
        <body>
          <h1>Not found!</h1>
        </body>