beelzebub
starsforks
How to install beelzebub?
beelzebub-labs/beelzebub
$git clone https://github.com/beelzebub-labs/beelzebubDeception Runtime Framework
README.md
| 1 | # Beelzebub |
| 2 | |
| 3 | [](https://github.com/beelzebub-labs/beelzebub/actions/workflows/ci.yml) |
| 4 | [](https://goreportcard.com/report/github.com/beelzebub-labs/beelzebub/v3) |
| 5 | [](https://codecov.io/gh/beelzebub-labs/beelzebub) |
| 6 | [](https://pkg.go.dev/github.com/beelzebub-labs/beelzebub/v3) |
| 7 | [](https://archestra.ai/mcp-catalog/beelzebub-labs__beelzebub) |
| 8 | [](https://github.com/avelino/awesome-go) |
| 9 | |
| 10 | **Deception Runtime Framework** |
| 11 | |
| 12 | 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. |
| 13 | |
| 14 |  |
| 15 | |
| 16 | ## Table of Contents |
| 17 | |
| 18 | - [Key Features](#key-features) |
| 19 | - [Quick Start](#quick-start) |
| 20 | - [CLI Reference](#cli-reference) |
| 21 | - [Plugin System](#plugin-system) |
| 22 | - [Observability](#observability) |
| 23 | - [Prometheus Metrics](#prometheus-metrics) |
| 24 | - [RabbitMQ Integration](#rabbitmq-integration) |
| 25 | - [Testing](#testing) |
| 26 | - [Code Quality](#code-quality) |
| 27 | - [Contributing](#contributing) |
| 28 | - [License](#license) |
| 29 | - [Configuration Reference](#configuration-reference) |
| 30 | - [Core Configuration](#core-configuration) |
| 31 | - [Service Configuration](#service-configuration) |
| 32 | - [Deception Services](#deception-services) |
| 33 | - [MCP Deception Service](#mcp-deception-service) |
| 34 | - [HTTP Deception Service](#http-deception-service) |
| 35 | - [SSH Deception Service](#ssh-deception-service) |
| 36 | - [TELNET Deception Service](#telnet-deception-service) |
| 37 | - [TCP Deception Service](#tcp-deception-service) |
| 38 | |
| 39 | ## Key Features |
| 40 | |
| 41 | - **Adaptive deception engine**: LLM integration (OpenAI, Ollama) generates contextually accurate responses in real time, keeping attackers engaged long enough to collect actionable TTPs |
| 42 | - **Low-code service definition**: YAML-based configuration with regex command matching — no custom code required to deploy a new decoy service |
| 43 | - **Multi-protocol coverage**: SSH, HTTP, TCP, TELNET, MCP from infrastructure targets to AI agent attack surfaces |
| 44 | - **Extensible plugin system**: Implement the `CommandPlugin` or `HTTPPlugin` interface and register via `init()` no core changes required |
| 45 | - **Full observability stack**: Prometheus metrics, RabbitMQ event streaming |
| 46 | - **Production-ready runtime**: Docker, Kubernetes (Helm), graceful shutdown, per-service memory limits |
| 47 | |
| 48 | ## LLM Deception Demo |
| 49 | |
| 50 |  |
| 51 | |
| 52 | ## Quick Start |
| 53 | |
| 54 | ### Using Docker Compose |
| 55 | |
| 56 | ```bash |
| 57 | docker compose build |
| 58 | docker compose up -d |
| 59 | ``` |
| 60 | |
| 61 | ### Using Go |
| 62 | |
| 63 | ```bash |
| 64 | go mod download |
| 65 | go build -o beelzebub . |
| 66 | ./beelzebub run |
| 67 | ``` |
| 68 | |
| 69 | ### Using Helm (Kubernetes) |
| 70 | |
| 71 | ```bash |
| 72 | helm install beelzebub ./beelzebub-chart |
| 73 | # Upgrade: |
| 74 | helm upgrade beelzebub ./beelzebub-chart |
| 75 | ``` |
| 76 | |
| 77 | ## CLI Reference |
| 78 | |
| 79 | Beelzebub ships with a structured CLI. Run `beelzebub --help` to see all available commands. |
| 80 | |
| 81 | ### `beelzebub run` |
| 82 | |
| 83 | Start all configured deception services. |
| 84 | |
| 85 | ```bash |
| 86 | beelzebub run [flags] |
| 87 | |
| 88 | Flags: |
| 89 | -c, --conf-core string Path to core configuration file (default "./configurations/beelzebub.yaml") |
| 90 | -s, --conf-services string Path to services configuration directory (default "./configurations/services/") |
| 91 | -m, --mem-limit-mib int Memory limit in MiB, -1 to disable (default 100) |
| 92 | ``` |
| 93 | |
| 94 | ### `beelzebub valida |
People who liked this also viewed
6 picksType
- mcp-scannerScan MCP servers for potential threats & security findings.MCP ServersJul 2026
- hol-guardOpen-source antivirus for AI agents: block risky tools, secret access, prompt injection, malicious packages, MCP servers, plugins, and skills at runtime.MCP ServersJul 2026
- agent-scanSecurity scanner for AI agents, MCP servers and agent skills.MCP ServersJul 2026
- falcon-mcpConnect AI agents to CrowdStrike Falcon for automated security analysis and threat huntingMCP ServersJul 2026
- python🔐 Plug-and-play auth for Python MCP servers.MCP ServersAug 2025
- auth0-mcp-serverConnect LLMs and AI agents to Auth0 Management APIs via an MCP server. Use natural-language commands to create apps, deploy Actions, and query logs—runs locally and supports interactive tenant authentication for secure Auth0 administration from AI tools/CLIs.MCP ServersJul 2026
