Which integrations are available for this server?

Monitors test coverage for the Beelzebub project, with integration visible through badges and references to coverage reports Provides containerized deployment for Beelzebub with ready-to-use Docker Compose configurations Offers official ELK stack integration for log management and analysis through documented integration paths Supported documentation platform shown in the project's sponsors section Runs automated CI pipelines for testing, code quality checks, and Docker image building Enables Kubernetes deployment through Helm charts with support for installation and upgrades Official support from JetBrains for the open-source project Provides native deployment support through Helm charts for container orchestration Member of NVIDIA Inception program, suggesting enhanced AI/ML capabilities and support Integrates with Ollama LLM provider for SSH honeypot functionality, supporting models like codellama:7b Connects to OpenAI's API for LLM honeypot functionality, supporting models like GPT-4o Provides metrics and observability data in Prometheus format for monitoring

How do I use Beelzebub MCP Honeypot?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Beelzebub MCP Honeypot deploy a decoy SSH service on port 2222" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Beelzebub

Docker codeql Go Report Card codecov Go Reference Trust Score

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.

github beelzebub - inception program

Related MCP server: Puppeteer-Extra MCP Server

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

demo-beelzebub

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)

video-mcp-diagram

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.

Supported By

JetBrains logo.

gitbook logo

Beelzebub MCP Honeypot