[opensourcedex]

beelzebub is a free, open source ai security & privacy project written in Go and released under GPL-3.0. It has 2,177 GitHub stars, 209 forks and 5 open issues, and was last pushed 4 days ago. On this registry it ranks #15 of 34 tracked projects in AI Security & Privacy, with 5 head-to-head comparisons available. It gained 1 stars over the last 3 tracked days.

What is beelzebub?

What it is

Beelzebub is an open-source deception runtime framework written in Go and released under GPL-3.0. It operates in the cybersecurity and AI security ecosystem, where teams need controlled systems that attract and record activity aimed at decoy services. The project is a configurable runtime for honeypots, decoys, and agent-facing bait tools, with documentation at docs.beelzebub.ai.

It addresses the problem of studying activity directed at decoy services. Beelzebub lets operators define the environment an attacker encounters, choose how that environment responds, and capture the interaction as security evidence. The framework can run independently, or connect to Beelzebub Platform for reporting.

Key capabilities

  • YAML configuration lets operators define services, routes, and response rules, with validation before runtime startup.
  • The runtime supports SSH, HTTP, TCP, TELNET, and MCP, covering remote access, web, raw ports, and model-context tools.
  • Static handlers provide predictable responses, while LLM-powered responses enable adaptive interactions when a provider is configured.
  • Trusted Go plugins are compiled into the runtime to extend services and responses.
  • Evidence capture records commands, HTTP request details, and session context depending on protocol.
  • Structured events can be inspected locally, published to RabbitMQ, or sent to Beelzebub Platform reporting.
  • Prometheus metrics expose runtime activity separately from event data.

Who uses it and how

  • Security teams deploy realistic decoys that fit their environment, then study activity aimed at those services instead of production assets.
  • Analysts use captured evidence to investigate attacker behavior, including commands, HTTP request details, and session context where supported.
  • Cloud-native operators use Docker Compose, Kubernetes, and Helm to run the framework in containerized or orchestrated environments.
  • Teams testing agentic AI systems use MCP decoys to expose bait tools and observe suspicious invocations during controlled testing.
  • Operators extend the runtime with Go plugins when custom service behavior is not available through YAML alone.

Getting started

Typical deployment methods include a local Go binary, Docker Compose, and Kubernetes with Helm. Operators can start from the 18 example configurations and adapt the YAML rules.

When to use it — and when not to

Beelzebub is useful when an organization wants a self-hosted, configurable deception runtime that produces evidence from decoy interactions and integrates it into logging, messaging, or monitoring workflows. It is less suitable when an operator needs guaranteed detection of every prompt-injection attempt, because MCP decoys provide evidence but do not guarantee detection. A self-hoster must operate the runtime or container platform, supply an LLM provider for adaptive responses, and run or integrate event and metrics systems such as RabbitMQ or Prometheus when those outputs are used.

project readme (upstream, from github) — read inline

Beelzebub — open-source deception framework

Beelzebub

Open-source deception framework.

Deploy realistic decoys. Observe attacker behavior. Turn interactions into security evidence.

Explore Beelzebub Platform · Documentation · Quick start

CI Coverage License: GPL v3 Go Reference Mentioned in Awesome Go

Beelzebub gives security teams a configurable way to study activity directed at decoy services. Define the environment an attacker encounters, choose how it responds, and capture the interaction for investigation. Run the framework independently or connect it to Beelzebub Platform.

Why Beelzebub

  • Deploy decoys that fit your environment. Define services, routes, and response rules in YAML. Use static handlers for predictable behavior or LLM-powered responses for adaptive interactions. Extend the runtime with trusted Go plugins when you need custom behavior.
  • Observe what happens after contact. Capture evidence from decoy interactions, including commands, HTTP request details, and session context, depending on the protocol. Give analysts a record of activity directed at the service to support investigation.
  • Bring evidence into your workflow. Inspect logs locally, publish structured events to RabbitMQ, or enable Beelzebub Platform reporting. Monitor runtime activity through Prometheus metrics and choose where captured data is sent.

See it in action

Watch an LLM-powered decoy respond to attacker input. The demo illustrates how generated responses can sustain an interaction beyond a fixed set of command handlers.

Demo of an LLM-powered Beelzebub decoy responding to attacker input

How it works

Interactions reach decoy services, receive responses from the Beelzebub runtime, and produce security events. YAML configuration feeds the runtime through validation; Go plugins are compiled into the runtime to extend services and responses. Events go to logs with optional RabbitMQ or Platform reporting, while Prometheus exposes metrics separately.

Define services and rules in YAML, validate the configuration, and start the runtime. Trusted Go plugins are compiled into the runtime to extend services and responses. Each service handles incoming interactions and emits evidence through the configured event output. LLM responses require a configured provider; static handlers can run without one.

The framework supports SSH, HTTP, TCP, TELNET, and MCP. MCP decoys expose bait tools that make suspicious invocations observable during controlled agent testing. They can provide evidence of prompt-injection attempts; they do not guarantee detection of every attempt.

Deployment options include a local Go binary, Docker Compose, and Kubernetes with Helm. See the architecture guide for runtime behavior and extension boundaries.

Explore the decoys

Start with one of the 18 example configurations in configurations/services. Open a YAML file to inspect its rules and adapt it to your environment.

Category Example decoys
Remote access SSH · SSH (LLM) · TELNET · RDP · VNC
Web WordPress (LLM fallback) · HTTP 401 · HTTP methods · Apache directory maze
Databases & caches MySQL · PostgreSQL (LLM) · SQL Server · Redis · Memcached
Network services SMB · LDAP
IoT MQTT
AI agents MCP bait tools

Examples range from banners and selected responses to interactive exchanges. LLM examples require a configured provider; WordPress uses it for its catch-all route. Check your deployment's port mappings when enabling additional examples.

Get started

You need Git, a shell, and Docker Engine with Compose v2. Use an isolated lab host with authorization for all configured listeners: the installer starts a bundle of example services, including privileged ports. On Linux it can enable host networking; Docker does not provide network isolation in that mode.

Use synthetic credentials and review the production safety guide before exposing services to the internet.

git clone https://github.com/beelzebub-labs/beelzebub.git
cd beelzebub
./install.sh --docker

Platform reporting is optional. Leave the Platform token blank when prompted to run independently. The runtime validates its configuration before starting listeners.

Test the default HTTP decoy and inspect its logs:

curl -i http://localhost:8080/
docker compose logs -f beelzebub

Expect 401 Unauthorized from the bundled HTTP example on port 8080. This is the decoy's configured response, confirming that the listener is reachable. If the installer skipped an occupied port, resolve the conflict before testing. Press Ctrl+C to stop following logs.

Stop the lab when finished:

docker compose down

For a single-service setup or another deployment method, follow the installation guide.

Beelzebub Platform

The open-source framework is the foundation: deploy, operate, and extend it independently. Beelzebub Platform is the managed product for teams that need to coordinate deception across environments and connect runtime evidence to a broader security workflow.

Explore the platform's deployment, investigation, and reporting capabilities, and see how they fit your team's requirements.

Explore Beelzebub Platform →

Resources and community

  • Documentation: configuration, protocols, operations, integrations, and recipes.
  • Plugin authoring: build extensions with the public Go SDK. Plugins execute in-process; review their source and pin trusted versions.
  • Contributing: contribute code, examples, or documentation under the Code of Conduct. Report vulnerabilities privately through SECURITY.md.

For development, use the Go version declared in go.mod, Git, and Make. Build with make build; run make test.unit, go vet ./..., and make validate-all before submitting runtime changes. The development workflow covers integration tests and their Docker dependencies.

Thank you to JetBrains for supporting development with tools through its open-source support program.

Licensed under the GNU General Public License v3.0.

Frequently asked questions

Is beelzebub free to use?

beelzebub is open source under the GPL-3.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does beelzebub do?

A secure low code deception runtime framework, leveraging AI for System Virtualization.

What is beelzebub written in?

beelzebub is primarily written in Go. Its source is publicly available at https://github.com/beelzebub-labs/beelzebub, and it has 2,177 GitHub stars.