beelzebub

Beelzebub is an advanced honeypot framework that includes a dedicated MCP (Model Context Protocol) honeypot. It provides low-interaction scaffolding with an LLM-driven high-interaction façade to convincingly simulate real systems, while allowing you to detect prompt-injection attempts and collect attack prompts for analysis. The MCP component specifically exposes a model-driven interface designed to provoke and observe agent behavior in response to restricted tool usage, enabling real-time guardrail testing and telemetry. You can run Beelzebub via Docker, compile from source with Go, or deploy through Helm on Kubernetes, and then enable and configure MCP services alongside other honeypots in the same environment.

To use the MCP capabilities, start Beelzebub with the MCP service enabled and connect a client to the MCP endpoint (for example the MCP honeypot configuration that listens on a defined address/port). The MCP endpoint is designed to detect when an agent attempts to invoke restricted tools, log the prompts, and return structured results describing the attempted operation. You can customize the YAML-based service definitions under services/ to adjust protocol behavior and define how MCP interactions are logged and harvested for analysis. Expect metrics exposure on the configured Prometheus path for observability and optional RabbitMQ or Beelzebub Cloud integrations for event streaming.

Prerequisites:

• Docker (recommended for quick setup) or Go tooling if building from source
• Git to clone the repository
• Optional: Helm if deploying on Kubernetes

Install using Docker (quick start):

1. Install Docker and ensure it is running
2. Pull and run the Beelzebub MCP-enabled image: docker pull mariocandela/beelzebub:latest docker run -d --name beelzebub -p 2112:2112 -p 8000:8000 mariocandela/beelzebub:latest
3. Verify the service is up and MCP endpoints are reachable at the configured address/port (e.g., http://localhost:8000 for MCP).

Build from source (Go):

1. Install Go (1.20+ recommended) and set GO111MODULE=on
2. Clone the repository: git clone https://github.com/mariocandela/beelzebub.git
3. Change to the project directory and download modules: cd beelzebub go mod download
4. Build the executable: go build
5. Run the binary: ./beelzebub

Deploy on Kubernetes with Helm:

1. Ensure Helm is installed
2. Add or point to the Beelzebub chart (example path shown, adjust as needed): helm install beelzebub ./beelzebub-chart
3. Manage releases with helm upgrade beelzebub ./beelzebub-chart

Configuration guidance:

• Core configuration file (beelzebub.yaml) controls logging, tracing, and Prometheus metrics
• Service configurations (services/*.yaml) define individual MCP and other honeypot services
• Start Beelzebub with appropriate conf flags if you are running multiple services or custom paths

Environment setup tips:

• If using Docker, map ports for metrics and MCP endpoints as needed (e.g., -p 2112:2112 for Prometheus, -p 8000:8000 for MCP)
• For Kubernetes, consider enabling Prometheus and Beelzebub Cloud integration via the respective config flags

Tips and common issues:

• MCP endpoint typically listens on a specific address/port defined in the MCP service YAML. Ensure your network policy allows access to that port.
• If you’re using Docker, ensure the image tag corresponds to a build that includes MCP support; some tags may be minimal builds.
• Enable Prometheus metrics to monitor MCP interactions: check the core configuration under prometheus.path and prometheus.port.
• If you need to trigger MCP-specific tooling behaviors or custom handlers, modify the service YAML under services/ to include the MCP tool definitions and their handlers.
• Be aware of resource limits: Beelzebub supports memory limits via the --memLimitMiB flag; adjust as needed with a reasonable default (e.g., 100 MiB) and set -1 to disable if required.