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.

Related MCP server: Puppeteer-Extra MCP Server

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:

Service Configuration

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

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:

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):

http-8080.yaml (Apache 401 simulation):

SSH Honeypot

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

LLM-Powered SSH Honeypot

Using OpenAI as the LLM provider:

Using local Ollama instance:

Using a custom prompt:

Static SSH Honeypot

TELNET Honeypot

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

LLM-Powered TELNET Honeypot

Static TELNET Honeypot

TCP Honeypot

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

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:

Events are published as JSON messages for downstream processing.

Testing

Unit Tests

Integration Tests

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

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.

Supported By