beelzebub-labs/beelzebub

**Open-source deception framework.**
Deploy realistic decoys. Observe attacker behavior. Turn interactions into security evidence.
**Explore Beelzebub Platform** · Documentation · Quick start
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.
How it works
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.