Beelzebub

What mariocandela/beelzebub does

mariocandela/beelzebub is an open-source deception framework for creating and operating decoy services. Its MCP support exposes bait tools that are intended to attract suspicious tool calls during controlled agent testing. Those interactions can provide evidence of prompt-injection attempts or other unusual behavior, although the MCP decoys are not presented as a complete detector for every attack.

The framework also covers SSH, HTTP, TCP, TELNET, and MCP services. Example configurations include remote-access services, web endpoints, database and cache protocols, network services, IoT protocols, and AI-agent bait tools. The examples range from fixed banners and responses to interactive exchanges.

How it works

Services and response rules are described in YAML. Beelzebub validates that configuration before starting listeners, then routes incoming interactions to the configured decoy service. Static handlers operate without an LLM provider. LLM-backed handlers require a configured provider and can generate responses for interactions that fall outside a fixed command or route set.

Trusted Go plugins can extend services and response behavior. Plugins are compiled into the runtime and execute in-process, so their source and versions should be reviewed before deployment.

Interactions produce evidence according to the protocol and configured output. Local logs are available by default, while structured events can optionally be published to RabbitMQ or sent to Beelzebub Platform. Prometheus metrics are separately configurable; the metrics listener is disabled and binds no port by default.

Setup and configuration

The quick-start path requires Git, a shell, and Docker Engine with Compose v2. The project recommends using an isolated lab host and authorizing all configured listeners because the installer starts a bundle of example services, some of which use privileged ports. Host networking may be enabled on Linux, which removes Docker's usual network isolation for that mode.

A basic Docker installation is:

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

After installation, the bundled HTTP example can be checked with curl -i http://localhost:8080/; its configured response is 401 Unauthorized. Runtime output can be followed with docker compose logs -f beelzebub, and the lab can be stopped with docker compose down. A Platform token is optional when running independently. Review the production-safety guidance and use synthetic credentials before exposing decoys to the internet.

Tools and capabilities

• Define decoy services, routes, and response behavior in YAML.
• Expose MCP bait tools for controlled agent-security testing.
• Run static handlers or provider-backed LLM responses.
• Extend the runtime with trusted Go plugins.
• Capture commands, HTTP request details, and session context where supported by the protocol.
• Export evidence through logs, RabbitMQ, or Beelzebub Platform.
• Enable Prometheus metrics for runtime monitoring.

Limitations and notes

MCP bait tools support observation of suspicious invocations but do not guarantee detection of every prompt-injection attempt. LLM examples depend on a configured provider, while static examples do not. The default installation launches multiple example listeners, so occupied ports and deployment exposure need to be managed. In-process plugins require particular trust because they run inside the framework runtime.