Beelzebub

What mariocandela/beelzebub MCP server does

The mariocandela/beelzebub MCP server is a deception runtime for creating decoy services intended to attract and record suspicious behavior. Its supported protocols include MCP, SSH, HTTP, TCP, and TELNET. The MCP service is relevant to agent-security testing: an agent can be given tools or interactions outside its normal task profile, allowing operators to observe whether it follows malicious instructions or attempts prompt injection.

Service behavior can be described with YAML rather than implemented entirely in code. Regular-expression command matching determines which configured response applies. Optional LLM support from OpenAI or Ollama can produce context-sensitive responses during an interaction.

How it works

The runtime loads a core configuration file and a directory of service definitions, then starts the enabled deception services. The run command accepts separate paths for these inputs and applies a configurable per-service memory limit. The validate command parses and checks the configuration without starting listeners, which makes it suitable for CI validation.

Extension points are provided through the Go SDK in pkg/plugin. Developers can implement command-response plugins, HTTP handlers, or binary TCP wire plugins. Plugins are registered through Go initialization and can be installed from GitHub, then included in a local or Docker build. TCP services can also define message framing and explicitly order wire plugins for stateful binary exchanges.

Setup and configuration

The repository provides an installer with local and Docker modes. Local development can also use make start; Docker builds and runs through make docker. A Helm chart is included for Kubernetes deployments. The documented default configuration locations are ./configurations/beelzebub.yaml for core settings and ./configurations/services/ for service definitions.

The CLI binary provides run, validate, plugin, and version commands. plugin install fetches an external plugin from GitHub and can append it to the plugin configuration. The project’s local build path requires Go, while the Docker path requires Docker; the excerpt does not specify an MCP client installation command or client-specific configuration.

Tools and capabilities

The mariocandela/beelzebub MCP server supports:

• MCP, SSH, HTTP, TCP, and TELNET deception services.
• YAML-defined services with regular-expression command matching.
• Adaptive response generation through OpenAI or Ollama integrations.
• Go plugins for command, HTTP, and binary TCP behavior.
• TCP framing modes including fixed length, BER, length-prefix, and varint length-prefix formats.
• Prometheus metrics and RabbitMQ event streaming.
• Docker images and Kubernetes deployment through Helm.
• Graceful shutdown and configurable memory limits.

Limitations and notes

This project is a deception and observation runtime, not a general-purpose MCP tool provider. Its usefulness depends on the decoy services and configuration supplied by the operator. The excerpt does not document a hosted endpoint, a required API key, supported desktop clients, or environment-variable configuration. OpenAI and Ollama are listed as LLM options, but their individual setup requirements are not specified here.

The MCP protocol is one part of a broader multi-protocol runtime, so deployment may involve listeners and service definitions beyond an MCP-only test. External plugins also introduce a build and installation step before they become part of a local or Docker runtime.