Beelzebub CLI
Open-source deception framework: decoy SSH, HTTP, database and MCP services in YAML, optional LLM responses, attacker activity logged as evidence
- 2,202 ★ on the repository
- Last commit
- GPL-3.0
Broad access
Why this level
- Opens network listeners, including on privileged ports, and accepts traffic from strangers, so it belongs on an isolated host
- Records attackers' commands and request data and can forward it to RabbitMQ or a cloud platform
- Go plugins run in-process with the same privileges
Install
Manual install
git clone https://github.com/beelzebub-labs/beelzebub.git && cd beelzebub && ./install.sh --dockerRun it only on an isolated lab host: the script takes privileged ports.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Opens network listeners, including on privileged ports, and accepts traffic from strangers, so it belongs on an isolated host
- Records attackers' commands and request data and can forward it to RabbitMQ or a cloud platform
- Go plugins run in-process with the same privileges
This is third-party code. Review the repository files before installing.
What it does
Beelzebub deploys decoys that look like real services and records everything done to them. Services, routes and response rules are defined in YAML. Static handlers respond predictably, and LLM responses can be switched on for adaptive conversations. SSH, HTTP, TCP, TELNET and MCP are supported. The `configurations/services` directory holds 18 ready examples: SSH, RDP, VNC, WordPress, MySQL, PostgreSQL, Redis, SMB, LDAP, MQTT and more. MCP decoys show agents bait tools. When an agent calls one, the call is recorded, which helps in controlled prompt-injection tests. The author notes that this does not guarantee detection of every attempt. Captured data (commands, HTTP request details, session context) can be read in local logs, published to RabbitMQ or sent to the Beelzebub Platform. Metrics go to Prometheus. You can run a local Go binary, Docker Compose or Kubernetes with Helm. Custom behavior comes from Go plugins that execute in-process.
Who it is for. For security teams and researchers who want to study attacker behavior and test agents for prompt injection in an isolated lab.
Good fit when
- You need a decoy SSH or TELNET service to record the commands an attacker types
- You test whether your agent is susceptible to prompt injection and place an MCP decoy with bait tools
- You want a WordPress, MySQL or Redis trap to record scans and see who tries what
- Decoy logs have to flow into a RabbitMQ queue or metrics into Prometheus
- The lab needs a set of 18 ready configurations instead of describing services by hand
Not a fit when
- You have no isolated lab host: the installer takes privileged ports and on Linux can enable host networking
- You need a firewall or intrusion prevention on a production server: decoys study activity and filter no traffic
- You need a guarantee that every prompt-injection attempt is noticed: the author gives none
- You lack Git, a shell and Docker Engine with Compose v2 for the repository install
Example request
Bring up Beelzebub in Docker on the lab host, test the HTTP decoy on port 8080 and show what its log looks likeLimitations
- The framework is licensed under GPL v3.
- The repository install needs Git, a shell and Docker Engine with Compose v2. The author advises an isolated lab host with authorization for all listeners: the script starts a bundle of examples, including on privileged ports, and on Linux it can enable host networking, where Docker provides no network isolation.
- LLM responses need a configured model provider. Static handlers run without one.
- Go plugins execute in-process, so review a plugin's source and pin trusted versions.
- Before exposing services to the internet the author requires reading the production safety guide and using synthetic credentials.
- Connecting to Beelzebub Platform is optional, but without it reports stay local.
How to disable. Stop the lab with `docker compose down` in the repository folder. To remove the install entirely, delete the cloned folder and the Docker images. If you enabled host networking, check that no decoy listeners remain open on the machine.
FAQ
What is Beelzebub and what does it do?
It is a deception framework. You describe decoy services in YAML, they respond to an attacker, and the framework records the activity for investigation.
How do I install Beelzebub?
Clone the repository and run `./install.sh --docker` in its folder. Git, a shell and Docker Engine with Compose v2 are required. The platform token can stay blank, and the framework then runs independently.
How do I check that a decoy works?
Run `curl -i http://localhost:8080/`. The bundled HTTP example answers `401 Unauthorized`: that is how the decoy is configured, and it confirms the listener is reachable. Open the log with `docker compose logs -f beelzebub`.
What are MCP decoys for?
They expose bait tools to agents. Suspicious calls are recorded in controlled tests, which helps notice prompt-injection attempts. The developer does not promise to detect every attempt.
Do decoys need a model to answer?
Only the LLM examples, such as SSH on port 2222 and PostgreSQL. They need a configured provider. Static handlers, such as HTTP 401 or MySQL, run without a model.
Discussion
No questions or reviews yet.
Related
CLI toolsAn authorized bug-bounty suite: 50 subagents, 26 commands and 2 bug-bounty-platform MCP servers for Claude Code, Codex and five more agents
Self-hosted AI pentesting framework: attack surface graph, Kali sandbox, human approval gates and an MCP server you can drive from Claude Code
Open-source adversary emulation for AI agents, LLM apps and MCP servers, checked against OWASP catalogs
An offensive security MCP server: the agent runs 150+ pentest and recon tools and drives automated target assessments
MCP server for the ARL-Next platform: returns ports, fingerprints, certificates, vulnerabilities and leaks for a domain, IP or URL from your asset database
A bridge between an MCP client and a Kali Linux terminal so the agent can run nmap, sqlmap, hydra and other tools for authorized pentesting and CTF
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Repository stars | Main difference |
|---|---|---|---|
| Beelzebub (this entry) | yes | 2,202 | |
| MCP Scanner | yes | 1,096 | statically checks MCP servers for suspicious tools, while Beelzebub exposes bait tools and waits for calls |
| Snyk Agent Scan | no | 3,155 | audits the skills and MCP servers you already installed, while Beelzebub catches calls on fake tools |
README in short
The README explains three ideas: decoys tailored to your environment, observing what happens after contact, and feeding the data into your workflow. It then shows a how-it-works diagram, a table of 18 examples by category, a lab install and a check. The page ends with the cloud platform, links to documentation, the plugin authoring guide and development rules.