beelzebub-labs/beelzebub
GitHub: beelzebub-labs/beelzebub
一个基于 AI 与低代码的现代蜜罐框架，提供多协议欺骗与可观测能力，用于捕获真实攻击行为。
Stars: 1963 | Forks: 186
# Beelzebub
[](https://github.com/mariocandela/beelzebub/actions/workflows/ci.yml) [](https://github.com/mariocandela/beelzebub/actions/workflows/docker-image.yml) [](https://github.com/mariocandela/beelzebub/actions/workflows/codeql.yml)
[](https://goreportcard.com/report/github.com/mariocandela/beelzebub/v3)
[](https://codecov.io/gh/mariocandela/beelzebub)
[](https://pkg.go.dev/github.com/mariocandela/beelzebub/v3)
[](https://archestra.ai/mcp-catalog/mariocandela__beelzebub)
[](https://github.com/avelino/awesome-go)
## 概述
Beelzebub 是一个高级蜜罐框架，旨在为检测和分析网络攻击提供一个高度安全的环境。它提供低代码方法以实现轻松部署，并使用 AI 来模拟高交互蜜罐的行为。
## 目录
- [Global Threat Intelligence Community](#global-threat-intelligence-community)
- [Key Features](#key-features)
- [Architecture](#architecture)
- [Quick Start](#quick-start)
- [Configuration](#configuration)
- [Core Configuration](#core-configuration)
- [Service Configuration](#service-configuration)
- [Protocol Examples](#protocol-examples)
- [MCP Honeypot](#mcp-honeypot)
- [HTTP Honeypot](#http-honeypot)
- [SSH Honeypot](#ssh-honeypot)
- [TELNET Honeypot](#telnet-honeypot)
- [TCP Honeypot](#tcp-honeypot)
- [Observability](#observability)
- [Prometheus Metrics](#prometheus-metrics)
- [RabbitMQ Integration](#rabbitmq-integration)
- [Beelzebub Cloud](#beelzebub-cloud)
- [Testing](#testing)
- [Code Quality](#code-quality)
- [Contributing](#contributing)
- [License](#license)
## 全球威胁情报社区
Our mission is to establish a collaborative ecosystem of security researchers and white hat professionals worldwide, dedicated to creating a distributed honeypot network that identifies emerging malware, discovers zero-day vulnerabilities, and neutralizes active botnets.
[](https://github.com/beelzebub-labs/white-paper/)
The white paper includes information on how to join our Discord community and contribute to the global threat intelligence network.
## 关键特性
Beelzebub offers a wide range of features to enhance your honeypot environment:
- **Low-code configuration**: YAML-based, modular service definition
- **LLM integration**: The LLM convincingly simulates a real system, creating high-interaction honeypot experiences, while actually maintaining low-interaction architecture for enhanced security and easy management
- **Multi-protocol support**: SSH, HTTP, TCP, TELNET, MCP (detect prompt injection against LLM agents)
- **Prometheus metrics & observability**: Built-in metrics endpoint for monitoring
- **Event tracing**: Multiple output strategies (stdout, RabbitMQ, Beelzebub Cloud)
- **Docker & Kubernetes ready**: Deploy anywhere with provided configurations
- **ELK stack ready**: Official integration available at [Elastic docs](https://www.elastic.co/docs/reference/integrations/beelzebub)
## LLM 蜜罐演示
## 快速开始
You can run Beelzebub via Docker, Go compiler(cross device), or Helm (Kubernetes).
### 使用 Docker Compose
1. Build the Docker images:
$ docker compose build
2. Start Beelzebub in detached mode:
$ docker compose up -d
### 使用 Go 编译器
1. Download the necessary Go modules:
$ go mod download
2. Build the Beelzebub executable:
$ go build
3. Run Beelzebub:
$ ./beelzebub
### 使用 Helm 部署到 Kubernetes 集群
1. Install helm
2. Deploy beelzebub:
$ helm install beelzebub ./beelzebub-chart
3. Next release
$ helm upgrade beelzebub ./beelzebub-chart
## 配置
Beelzebub uses a two-tier configuration system:
1. **Core configuration** (`beelzebub.yaml`) - Global settings for logging, tracing, and Prometheus
2. **Service configurations** (`services/*.yaml`) - Individual honeypot service definitions
### 核心配置
The core configuration file controls global behavior:
```
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"
beelzebub-cloud:
enabled: false
uri: ""
auth-token: ""
```
### 服务配置
Each honeypot service is defined in a separate YAML file in the `services/` directory. To run Beelzebub with custom paths:
```
./beelzebub --confCore ./configurations/beelzebub.yaml --confServices ./configurations/services/
```
Additional flags:
- `--memLimitMiB ` - Set memory limit in MiB (default: 100, use -1 to disable)
## 协议示例
Below are example configurations for each supported protocol.
### MCP 蜜罐
MCP (Model Context Protocol) honeypots are decoy tools designed to detect prompt injection attacks against LLM agents.
#### 为什么使用 MCP 蜜罐？
An MCP honeypot is a **decoy tool** that the agent should never invoke under normal circumstances. Integrating this strategy into your agent pipeline offers three key benefits:
- **Real-time detection of guardrail bypass attempts** - Instantly identify when a prompt injection attack successfully convinces the agent to invoke a restricted tool
- **Automatic collection of real attack prompts** - Every activation logs genuine malicious prompts, enabling continuous improvement of your filtering mechanisms
- **Continuous monitoring of attack trends** - Track exploit frequency and system resilience using objective, actionable measurements (HAR, TPR, MTP)
**mcp-8000.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. Results are pending internal processing and will be logged.",
"result": {
"operation_status": "success",
"details": "Info: email: kirsten@gmail.com, last-login: 02/07/2025"
}
}
}
```
Invoke remotely via `http://beelzebub:port/mcp` (Streamable HTTP Server).
### HTTP 蜜罐
HTTP honeypots respond to web requests with configurable responses based on URL pattern matching.
**http-80.yaml** (WordPress simulation):
```
apiVersion: "v1"
protocol: "http"
address: ":80"
description: "Wordpress 6.0"
commands:
- regex: "^(/index.php|/index.html|/)$"
handler:
Wordpress 6 test page
Wordpress 6 test page
headers:
- "Content-Type: text/html"
- "Server: Apache/2.4.53 (Debian)"
- "X-Powered-By: PHP/7.4.29"
statusCode: 200
- regex: "^.*$"
handler:
404
Hello from Wordpress
headers: - "Content-Type: text/html" - "Server: Apache/2.4.53 (Debian)" - "X-Powered-By: PHP/7.4.29" statusCode: 200 - regex: "^(/wp-login.php|/wp-admin)$" handler:Not found!
headers: - "Content-Type: text/html" - "Server: Apache/2.4.53 (Debian)" - "X-Powered-By: PHP/7.4.29" statusCode: 404 ``` **http-8080.yaml** (Apache 401 simulation): ``` apiVersion: "v1" protocol: "http" address: ":8080" description: "Apache 401" commands: - regex: ".*" handler: "Unauthorized" headers: - "www-Authenticate: Basic" - "server: Apache" statusCode: 401 ``` ### SSH 蜜罐 SSH honeypots support both static command responses and LLM-powered dynamic interactions. #### LLM 驱动的 SSH 蜜罐 Using OpenAI as the LLM provider: ``` apiVersion: "v1" protocol: "ssh" address: ":2222" description: "SSH interactive OpenAI GPT-4" commands: - regex: "^(.+)$" plugin: "LLMHoneypot" serverVersion: "OpenSSH" serverName: "ubuntu" passwordRegex: "^(root|qwerty|Smoker666|123456|jenkins|minecraft|sinus|alex|postgres|Ly123456)$" deadlineTimeoutSeconds: 60 plugin: llmProvider: "openai" llmModel: "gpt-4o" #Models https://platform.openai.com/docs/models openAISecretKey: "sk-proj-123456" ``` Using local Ollama instance: ``` apiVersion: "v1" protocol: "ssh" address: ":2222" description: "SSH Ollama Llama3" commands: - regex: "^(.+)$" plugin: "LLMHoneypot" serverVersion: "OpenSSH" serverName: "ubuntu" passwordRegex: "^(root|qwerty|Smoker666|123456|jenkins|minecraft|sinus|alex|postgres|Ly123456)$" deadlineTimeoutSeconds: 60 plugin: llmProvider: "ollama" llmModel: "codellama:7b" host: "http://localhost:11434/api/chat" ``` Using a custom prompt: ``` apiVersion: "v1" protocol: "ssh" address: ":2222" description: "SSH interactive OpenAI GPT-4" commands: - regex: "^(.+)$" plugin: "LLMHoneypot" serverVersion: "OpenSSH" serverName: "ubuntu" passwordRegex: "^(root|qwerty|Smoker666|123456|jenkins|minecraft|sinus|alex|postgres|Ly123456)$" deadlineTimeoutSeconds: 60 plugin: llmProvider: "openai" llmModel: "gpt-4o" openAISecretKey: "sk-proj-123456" prompt: "You will act as an Ubuntu Linux terminal. The user will type commands, and you are to reply with what the terminal should show. Your responses must be contained within a single code block." ``` #### 静态 SSH 蜜罐 ``` apiVersion: "v1" protocol: "ssh" address: ":22" description: "SSH interactive" commands: - regex: "^ls$" handler: "Documents Images Desktop Downloads .m2 .kube .ssh .docker" - regex: "^pwd$" handler: "/home/" - regex: "^uname -m$" handler: "x86_64" - regex: "^docker ps$" handler: "CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES" - regex: "^docker .*$" handler: "Error response from daemon: dial unix docker.raw.sock: connect: connection refused" - regex: "^uname$" handler: "Linux" - regex: "^ps$" handler: "PID TTY TIME CMD\n21642 ttys000 0:00.07 /bin/dockerd" - regex: "^(.+)$" handler: "command not found" serverVersion: "OpenSSH" serverName: "ubuntu" passwordRegex: "^(root|qwerty|Smoker666)$" deadlineTimeoutSeconds: 60 ``` ### TELNET 蜜罐 TELNET honeypots provide terminal-based interaction similar to SSH, with support for both static responses and LLM integration. #### LL 驱动的 TELNET 蜜罐 ``` apiVersion: "v1" protocol: "telnet" address: ":23" description: "TELNET LLM Honeypot" commands: - regex: "^(.+)$" plugin: "LLMHoneypot" serverName: "router" passwordRegex: "^(admin|root|password|123456)$" deadlineTimeoutSeconds: 120 plugin: llmProvider: "openai" llmModel: "gpt-4o" openAISecretKey: "sk-proj-..." ``` #### 静态 TELNET 蜜罐 ``` apiVersion: "v1" protocol: "telnet" address: ":23" description: "TELNET Router Simulation" commands: - regex: "^show version$" handler: "Cisco IOS Software, Version 15.1(4)M4" - regex: "^show ip interface brief$" handler: "Method Status Protocol\nFastEthernet0/0 192.168.1.1 YES NVRAM up up" - regex: "^(.+)$" handler: "% Unknown command" serverName: "router" passwordRegex: "^(admin|cisco|password)$" deadlineTimeoutSeconds: 60 ``` ### TCP 蜜罐 TCP honeypots respond with a configurable banner to any TCP connection. Useful for simulating database servers or other TCP services. ``` apiVersion: "v1" protocol: "tcp" address: ":3306" description: "MySQL 8.0.29" banner: "8.0.29" deadlineTimeoutSeconds: 10 ``` ## 可观测性 ### Prometheus 指标 Beelzebub exposes Prometheus metrics at the configured endpoint (default: `:2112/metrics`). Available metrics include: - `beelzebub_events_total` - Total number of honeypot events - `beelzebub_events_ssh_total` - SSH-specific events - `beelzebub_events_http_total` - HTTP-specific events - `beelzebub_events_tcp_total` - TCP-specific events - `beelzebub_events_telnet_total` - TELNET-specific events - `beelzebub_events_mcp_total` - MCP-specific events ### RabbitMQ 集成 Enable RabbitMQ tracing to publish honeypot events to a message queue: ``` core: tracings: rabbit-mq: enabled: true uri: "amqp://guest:guest@localhost:5672/" ``` Events are published as JSON messages for downstream processing. ## 测试 ### 单元测试 ``` make test.unit ``` ### 集成测试 Integration tests require external dependencies (RabbitMQ, etc.): ``` make test.dependencies.start make test.integration make test.dependencies.down ``` ## 代码质量 We maintain high code quality through: - **Automated Testing**: Unit and integration tests run on every pull request - **Static Analysis**: Go Report Card and CodeQL for code quality and security checks - **Code Coverage**: Monitored via [Codecov](https://codecov.io/gh/mariocandela/beelzebub) - **Continuous Integration**: GitHub Actions pipelines on every commit - **Code Reviews**: All contributions undergo peer review ## 许可证 Beelzebub is licensed under the [GNU GPL v3 License](LICENSE). ## 支持者 [](https://jb.gg/OpenSourceSupport) 标签：AI虚拟化, Docker, EDR绕过, EVTX分析, Golang, Go语言, NIDS, PB级数据处理, PFX证书, 低代码, 单元测试, 威胁情报, 子域名突变, 安全编程, 安全运维, 安全防御评估, 容器化, 开发者工具, 开源框架, 持续集成, 攻击检测, 日志审计, 程序破解, 系统仿真, 系统虚拟化, 网络安全, 自动化防御, 自定义请求头, 蜜罐, 行为模仿, 覆盖率, 证书利用, 请求拦截, 隐私保护, 高交互蜜罐