# Beelzebub
[](https://github.com/beelzebub-labs/beelzebub/actions/workflows/ci.yml)
[](https://goreportcard.com/report/github.com/beelzebub-labs/beelzebub/v3)
[](https://codecov.io/gh/beelzebub-labs/beelzebub)
[](https://pkg.go.dev/github.com/beelzebub-labs/beelzebub/v3)
[](https://archestra.ai/mcp-catalog/beelzebub-labs__beelzebub)
[](https://github.com/avelino/awesome-go)
**Deception Runtime Framework**
Beelzebub is an open-source deception runtime that deploys adaptive, LLM-powered decoy services across SSH, HTTP, TCP, TELNET, and MCP protocols. It goes beyond passive honeypots by actively engaging attackers in realistic interactions, collecting high-fidelity threat intelligence, and detecting prompt injection attacks against AI agents.
## Table of Contents
- [Beelzebub](#beelzebub)
- [Table of Contents](#table-of-contents)
- [Key Features](#key-features)
- [LLM Deception Demo](#llm-deception-demo)
- [Quick Start](#quick-start)
- [Installer](#installer)
- [Local (Go)](#local-go)
- [Docker](#docker)
- [Using Helm (Kubernetes)](#using-helm-kubernetes)
- [CLI Reference](#cli-reference)
- [`beelzebub run`](#beelzebub-run)
- [`beelzebub validate`](#beelzebub-validate)
- [`beelzebub plugin`](#beelzebub-plugin)
- [`beelzebub version`](#beelzebub-version)
- [Plugin System](#plugin-system)
- [Interfaces](#interfaces)
- [Writing a Plugin](#writing-a-plugin)
- [Installing External Plugins](#installing-external-plugins)
- [Observability](#observability)
- [Prometheus Metrics](#prometheus-metrics)
- [RabbitMQ Integration](#rabbitmq-integration)
- [Testing](#testing)
- [Code Quality](#code-quality)
- [License](#license)
- [Contributing](#contributing)
- [Configuration Reference](#configuration-reference)
- [Core Configuration](#core-configuration)
- [Service Configuration](#service-configuration)
- [Deception Services](#deception-services)
- [MCP Deception Service](#mcp-deception-service)
- [How It Works](#how-it-works)
- [HTTP Deception Service](#http-deception-service)
- [SSH Deception Service](#ssh-deception-service)
- [TELNET Deception Service](#telnet-deception-service)
- [TCP Deception Service](#tcp-deception-service)
- [Supported By](#supported-by)
## Key Features
- **Adaptive deception engine**: LLM integration (OpenAI, Ollama) generates contextually accurate responses in real time, keeping attackers engaged long enough to collect actionable TTPs
- **Low-code service definition**: YAML-based configuration with regex command matching — no custom code required to deploy a new decoy service
- **Multi-protocol coverage**: SSH, HTTP, TCP, TELNET, MCP from infrastructure targets to AI agent attack surfaces
- **Extensible plugin system**: Implement the `CommandPlugin` or `HTTPPlugin` interface and register via `init()` no core changes required
- **Full observability stack**: Prometheus metrics, RabbitMQ event streaming
- **Production-ready runtime**: Docker, Kubernetes (Helm), graceful shutdown, per-service memory limits
## LLM Deception Demo
## Quick Start
### Installer
```bash
./install.sh # asks local or Docker, checks prerequisites, and starts it
```
Non-interactive: `./install.sh --local` or `./install.sh --docker`. Use
`./install.sh --local --no-run` to install and build without starting the local
runtime. On non-root hosts, local installation does not auto-start when the
default configuration includes privileged ports.
### Local (Go)
```bash
make start # installs any declared plugins, compiles them in, and runs
```
### Docker
```bash
make docker # builds an image with declared plugins baked in, then runs it
```
### Using Helm (Kubernetes)
```bash
helm install beelzebub ./beelzebub-chart
# Upgrade:
helm upgrade beelzebub ./beelzebub-chart
```
## CLI Reference
Beelzebub ships with a structured CLI. Run `beelzebub --help` to see all available commands.
### `beelzebub run`
Start all configured deception services.
```bash
beelzebub run [flags]
Flags:
-c, --conf-core string Path to core configuration file (default "./configurations/beelzebub.yaml")
-s, --conf-services string Path to services configuration directory (default "./configurations/services/")
-m, --mem-limit-mib int Memory limit in MiB, -1 to disable (default 100)
```
### `beelzebub validate`
Parse and validate all configuration files without starting any services. Useful in CI pipelines. See [Configuration Validation](docs/configuration-validation.md) for the validation architecture and rule reference.
```bash
beelzebub validate --conf-core ./configurations/beelzebub.yaml --conf-services ./configurations/services/
```
### `beelzebub plugin`
Install, list, and remove plugins fetched from GitHub. See [Plugin System](#plugin-system).
```bash
beelzebub plugin install github.com/your-org/beelzebub-myplugin
beelzebub plugin list
beelzebub plugin remove myplugin
```
### `beelzebub version`
Print version, commit SHA, build date, and Go runtime information.
```bash
beelzebub version
```
## Plugin System
Beelzebub exposes a stable public SDK at `pkg/plugin` for extending the deception runtime without modifying core code.
### Interfaces
```go
// CommandPlugin generates text responses for SSH, TCP, TELNET, and HTTP services.
type CommandPlugin interface {
Metadata() Metadata
Execute(ctx context.Context, req CommandRequest) (string, error)
}
// HTTPPlugin generates full HTTP responses with status code, headers, and body.
type HTTPPlugin interface {
Metadata() Metadata
HandleHTTP(r *http.Request) HTTPResponse
}
```
### Writing a Plugin
```go
package myplugin
import (
"context"
"github.com/beelzebub-labs/beelzebub/v3/pkg/plugin"
)
type MyPlugin struct{}
func (p *MyPlugin) Metadata() plugin.Metadata {
return plugin.Metadata{
Name: "MyPlugin",
Description: "Custom deception response generator",
Version: "1.0.0",
Author: "your-name",
}
}
func (p *MyPlugin) Execute(_ context.Context, req plugin.CommandRequest) (string, error) {
return "simulated response to: " + req.Command, nil
}
func init() {
plugin.Register(&MyPlugin{})
}
```
### Installing External Plugins
```bash
# Declare plugins in configurations/plugins.yaml, or:
beelzebub plugin install github.com/your-org/myplugin # also appends to the config
make start # local: install declared plugins → build → run (needs Go)
make docker # docker: image with plugins baked in → run (needs Docker)
```
| Command | What it does |
|---|---|
| `plugin install ` | fetch a plugin, wire it in, rebuild; also adds it to `configurations/plugins.yaml` |
| `plugin install` | install everything declared in `configurations/plugins.yaml` |
| `plugin list` | show installed plugins vs. what's compiled into the binary |
| `plugin update [name]` | re-fetch at the declared ref and re-pin the commit |
| `plugin remove ` | remove a plugin from `configurations/plugins.yaml`, unwire it, and print the rebuild step |
Deployment plugin sources are configured in `configurations/plugins.yaml`:
```yaml
plugins:
- source: github.com/your-org/myplugin
- source: github.com/your-org/private-plugin@v1.2.0
```
Future per-plugin runtime configuration can live under `configurations/plugins/`
as one YAML file per plugin.
Each plugin repo must ship a `plugins.yaml` manifest and self-register in `init()`
(see [Writing a Plugin](#writing-a-plugin)):
```yaml
name: myplugin
version: 1.0.0
module: github.com/your-org/myplugin # must match its go.mod
entrypoint: . # package that calls plugin.Register (default ".")
min-core-version: v3.8.0 # optional
dependencies: # optional metadata; Go dependencies still come from go.mod
- github.com/your-org/shared@v1.2.3
```
Installed plugins are compiled into the Beelzebub binary and run in the same
process as the runtime. Install plugins only from repositories you trust.
## Observability
### Prometheus Metrics
Beelzebub exposes Prometheus metrics at the configured endpoint (default: `:2112/metrics`):
| Metric | Description |
|--------|-------------|
| `beelzebub_events_total` | Total deception events across all services |
| `beelzebub_events_ssh_total` | SSH events |
| `beelzebub_events_http_total` | HTTP events |
| `beelzebub_events_tcp_total` | TCP events |
| `beelzebub_events_telnet_total` | TELNET events |
| `beelzebub_events_mcp_total` | MCP events |
### RabbitMQ Integration
Publish all deception events to a message queue for downstream SIEM integration:
```yaml
core:
tracings:
rabbit-mq:
enabled: true
uri: "amqp://guest:guest@localhost:5672/"
```
Events are published as structured JSON to the `event` queue.
## Testing
```bash
# Unit tests
make test.unit
# Integration tests (requires Docker)
make test.dependencies.start
make test.integration
make test.dependencies.down
# Validate configuration without starting services
beelzebub validate
```
## Code Quality
- **CI**: GitHub Actions on every commit and pull request
- **Static analysis**: CodeQL and Go Report Card
- **Coverage**: Monitored via [Codecov](https://codecov.io/gh/beelzebub-labs/beelzebub)
- **Code review**: All contributions undergo peer review
## License
Beelzebub is licensed under the [GNU GPL v3 License](LICENSE).
## Contributing
The Beelzebub team welcomes contributions and project participation. Whether you want to report bugs, contribute new features, or have any questions, please refer to our [Contributor Guide](CONTRIBUTING.md) for detailed information. We encourage all participants and maintainers to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md) and foster a supportive and respectful community.
Happy hacking!
## Configuration Reference
Beelzebub uses a two-tier configuration system:
1. **Core configuration** (`beelzebub.yaml`) global settings: logging, tracing, Prometheus
2. **Service configurations** (`services/*.yaml`) one file per decoy service
### Core Configuration
```yaml
core:
logging:
debug: false
debugReportCaller: false
logDisableTimestamp: true
logsPath: ./logs
tracings:
rabbit-mq:
enabled: false
uri: "amqp://guest:guest@localhost:5672/"
prometheus:
path: "/metrics"
port: ":2112"
```
Environment variable overrides are supported for all fields (e.g. `BEELZEBUB_RABBITMQ_ENABLED`). Service configurations can also be supplied entirely via `BEELZEBUB_SERVICES_CONFIG` as a JSON array.
### Service Configuration
Each decoy service is defined in a separate YAML file placed in the `services/` directory. The `protocol` field determines the deception engine used. Commands use `regex` for request matching and either a static `handler` or a `plugin` reference for dynamic responses.
When using the **LLMHoneypot** plugin, it is highly recommended to use guardrails to prevent the LLM from being jailbroken or otherwise manipulated in ways that could compromise the honeypot. See the [LLMHoneypot plugin documentation](https://docs.beelzebub.ai/basics/beelzebub-api-v1#llmhoneypot-plugin) for details.
## Deception Services
### MCP Deception Service
MCP (Model Context Protocol) deception services expose decoy tools designed to detect prompt injection attacks against LLM-powered agents.
#### How It Works
The decoy tool is registered in the agent's tool list but should never be invoked under normal operation. Any invocation signals that a prompt injection attack has successfully bypassed the agent's guardrails. This provides:
- **Real-time guardrail bypass detection** instant alerting when an attacker convinces the agent to invoke a restricted tool
- **Authentic attack prompt collection** every activation logs the exact malicious prompt used
- **Measurable attack surface metrics** track HAR, TPR, and MTP over time
**mcp-8000.yaml**:
```yaml
apiVersion: "v1"
protocol: "mcp"
address: ":8000"
description: "MCP Honeypot"
tools:
- name: "tool:user-account-manager"
description: "Tool for querying and modifying user account details. Requires administrator privileges."
params:
- name: "user_id"
description: "The ID of the user account to manage."
- name: "action"
description: "The action to perform on the user account, possible values are: get_details, reset_password, deactivate_account"
handler: |
{
"tool_id": "tool:user-account-manager",
"status": "completed",
"output": {
"message": "Tool 'tool:user-account-manager' executed successfully. Results are pending internal processing and will be logged.",
"result": {
"operation_status": "success",
"details": "email: kirsten@gmail.com, role: admin, last-login: 02/07/2025"
}
}
}
- name: "tool:system-log"
description: "Tool for querying system logs. Requires administrator privileges."
params:
- name: "filter"
description: "The input used to filter the logs."
handler: |
{
"tool_id": "tool:system-log",
"status": "completed",
"output": {
"message": "Tool 'tool:system-log' executed successfully.",
"result": {
"operation_status": "success",
"details": "Info: email: kirsten@gmail.com, last-login: 02/07/2025"
}
}
}
```
Accessible via `http://beelzebub:port/mcp` (Streamable HTTP transport).
### HTTP Deception Service
HTTP deception services respond to web requests with configurable responses based on URL pattern matching. Supports TLS, static handlers, LLM-powered responses, and the infinite maze generator.
**WordPress simulation** (`http-80.yaml`):
```yaml
apiVersion: "v1"
protocol: "http"
address: ":80"
description: "Wordpress 6.0"
commands:
- regex: "^(/index.php|/index.html|/)$"
methods: [GET, HEAD]
handler: |
Wordpress 6 test page