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.

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

Build the Docker images:
```
$ docker compose build
```
Start Beelzebub in detached mode:
```
$ docker compose up -d
```

Using Go Compiler

Download the necessary Go modules:
```
$ go mod download
```
Build the Beelzebub executable:
```
$ go build
```
Run Beelzebub:
```
$ ./beelzebub
```

Deploy on kubernetes cluster using helm

Install helm

Deploy beelzebub:

$ helm install beelzebub ./beelzebub-chart

Next release

$ helm upgrade beelzebub ./beelzebub-chart

Configuration

Beelzebub uses a two-tier configuration system:

Core configuration (beelzebub.yaml) - Global settings for logging, tracing, and Prometheus
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>
      </html>
    headers:
      - "Content-Type: text/html"
      - "Server: Apache/2.4.53 (Debian)"
      - "X-Powered-By: PHP/7.4.29"
    statusCode: 404

http-8080.yaml (Apache 401 simulation):

apiVersion: "v1"
protocol: "http"
address: ":8080"
description: "Apache 401"
commands:
  - regex: ".*"
    handler: "Unauthorized"
    headers:
      - "www-Authenticate: Basic"
      - "server: Apache"
    statusCode: 401

SSH Honeypot

SSH honeypots support both static command responses and LLM-powered dynamic interactions.

LLM-Powered SSH Honeypot

Using OpenAI as the LLM provider:

apiVersion: "v1"
protocol: "ssh"
address: ":2222"
description: "SSH interactive OpenAI  GPT-4"
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" #Models https://platform.openai.com/docs/models
   openAISecretKey: "sk-proj-123456"

Using local Ollama instance:

apiVersion: "v1"
protocol: "ssh"
address: ":2222"
description: "SSH Ollama Llama3"
commands:
  - regex: "^(.+)$"
    plugin: "LLMHoneypot"
serverVersion: "OpenSSH"
serverName: "ubuntu"
passwordRegex: "^(root|qwerty|Smoker666|123456|jenkins|minecraft|sinus|alex|postgres|Ly123456)$"
deadlineTimeoutSeconds: 60
plugin:
   llmProvider: "ollama"
   llmModel: "codellama:7b"
   host: "http://localhost:11434/api/chat"

Using a custom prompt:

apiVersion: "v1"
protocol: "ssh"
address: ":2222"
description: "SSH interactive OpenAI  GPT-4"
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-123456"
   prompt: "You will act as an Ubuntu Linux terminal. The user will type commands, and you are to reply with what the terminal should show. Your responses must be contained within a single code block."

Static SSH Honeypot

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/"
  - regex: "^uname -m$"
    handler: "x86_64"
  - regex: "^docker ps$"
    handler: "CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES"
  - regex: "^docker .*$"
    handler: "Error response from daemon: dial unix docker.raw.sock: connect: connection refused"
  - regex: "^uname$"
    handler: "Linux"
  - regex: "^ps$"
    handler: "PID TTY TIME CMD\n21642 ttys000 0:00.07 /bin/dockerd"
  - regex: "^(.+)$"
    handler: "command not found"
serverVersion: "OpenSSH"
serverName: "ubuntu"
passwordRegex: "^(root|qwerty|Smoker666)$"
deadlineTimeoutSeconds: 60

TELNET Honeypot

TELNET honeypots provide terminal-based interaction similar to SSH, with support for both static responses and LLM integration.

LLM-Powered TELNET Honeypot

apiVersion: "v1"
protocol: "telnet"
address: ":23"
description: "TELNET LLM Honeypot"
commands:
  - regex: "^(.+)$"
    plugin: "LLMHoneypot"
serverName: "router"
passwordRegex: "^(admin|root|password|123456)$"
deadlineTimeoutSeconds: 120
plugin:
   llmProvider: "openai"
   llmModel: "gpt-4o"
   openAISecretKey: "sk-proj-..."

Static TELNET Honeypot

apiVersion: "v1"
protocol: "telnet"
address: ":23"
description: "TELNET Router Simulation"
commands:
  - regex: "^show version$"
    handler: "Cisco IOS Software, Version 15.1(4)M4"
  - regex: "^show ip interface brief$"
    handler: "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 Honeypot

TCP honeypots respond with a configurable banner to any TCP connection. Useful for simulating database servers or other TCP services.

apiVersion: "v1"
protocol: "tcp"
address: ":3306"
description: "MySQL 8.0.29"
banner: "8.0.29"
deadlineTimeoutSeconds: 10

Observability

Prometheus Metrics

Beelzebub exposes Prometheus metrics at the configured endpoint (default: :2112/metrics). Available metrics include:

beelzebub_events_total - Total number of honeypot events
beelzebub_events_ssh_total - SSH-specific events
beelzebub_events_http_total - HTTP-specific events
beelzebub_events_tcp_total - TCP-specific events
beelzebub_events_telnet_total - TELNET-specific events
beelzebub_events_mcp_total - MCP-specific events

RabbitMQ Integration

Enable RabbitMQ tracing to publish honeypot events to a message queue:

core:
  tracings:
    rabbit-mq:
      enabled: true
      uri: "amqp://guest:guest@localhost:5672/"

Events are published as JSON messages for downstream processing.

Testing

Unit Tests

make test.unit

Integration Tests

Integration tests require external dependencies (RabbitMQ, etc.):

make test.dependencies.start
make test.integration
make test.dependencies.down

Code Quality

We maintain high code quality through:

Automated Testing: Unit and integration tests run on every pull request
Static Analysis: Go Report Card and CodeQL for code quality and security checks
Code Coverage: Monitored via Codecov
Continuous Integration: GitHub Actions pipelines on every commit
Code Reviews: All contributions undergo peer review

Contributing

The Beelzebub team welcomes contributions and project participation. Whether you want to report bugs, contribute new features, or have any questions, please refer to our Contributor Guide for detailed information. We encourage all participants and maintainers to adhere to our Code of Conduct and foster a supportive and respectful community.

Happy hacking!

License

Beelzebub is licensed under the GNU GPL v3 License.

Name		Name	Last commit message	Last commit date
Latest commit History 316 Commits
.github		.github
beelzebub-chart		beelzebub-chart
builder		builder
configurations		configurations
historystore		historystore
integration_test		integration_test
parser		parser
plugins		plugins
protocols		protocols
tracer		tracer
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
Dockerfile		Dockerfile
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
SECURITY.md		SECURITY.md
docker-compose.yml		docker-compose.yml
go.mod		go.mod
go.sum		go.sum
main.go		main.go
pull_request_template.md		pull_request_template.md

Uh oh!

License

mariocandela/beelzebub

Folders and files

Latest commit

History

Repository files navigation

Beelzebub

Overview

Table of Contents

Global Threat Intelligence Community

Key Features

LLM Honeypot Demo

Quick Start

Using Docker Compose

Using Go Compiler

Deploy on kubernetes cluster using helm

Configuration

Core Configuration

Service Configuration

Protocol Examples

MCP Honeypot

Why Use an MCP Honeypot?

HTTP Honeypot

SSH Honeypot

LLM-Powered SSH Honeypot

Static SSH Honeypot

TELNET Honeypot

LLM-Powered TELNET Honeypot

Static TELNET Honeypot

TCP Honeypot

Observability

Prometheus Metrics

RabbitMQ Integration

Testing

Unit Tests

Integration Tests

Code Quality

Contributing

License

Supported By

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases 60

Sponsor this project

Uh oh!

Uh oh!

Contributors 13

Uh oh!

Languages