Beelzebub

欺骗运行时框架

Beelzebub 是一个开源欺骗运行时，可跨 SSH、HTTP、TCP、TELNET 和 MCP 协议部署自适应的、由 LLM 驱动的诱饵服务。它超越了被动蜜罐，通过主动让攻击者参与逼真的交互，收集高保真威胁情报，并检测针对 AI 代理的提示注入攻击。

目录

• Beelzebub
  • 目录
  • 主要特性
  • LLM 欺骗演示
  • 快速开始
    • 安装器
    • 本地（Go）
    • Docker
    • 使用 Helm（Kubernetes）
  • CLI 参考
    • beelzebub run
    • beelzebub validate
    • beelzebub plugin
    • beelzebub version
  • 插件系统
    • 接口
    • 编写插件
    • 安装外部插件
  • 可观测性
    • Prometheus 指标
    • RabbitMQ 集成
  • 测试
  • 代码质量
  • 许可证
  • 贡献
  • 配置参考
    • 核心配置
    • 服务配置
  • 欺骗服务
    • MCP 欺骗服务
      • 工作原理
    • HTTP 欺骗服务
    • SSH 欺骗服务
    • TELNET 欺骗服务
    • TCP 欺骗服务
  • 支持方

主要特性

• 自适应欺骗引擎：LLM 集成（OpenAI、Ollama）实时生成上下文相关的准确响应，让攻击者保持足够长时间的参与，以收集可操作的 TTP
• 低代码服务定义：基于 YAML 的配置与正则表达式命令匹配——无需自定义代码即可部署新的诱饵服务
• 多协议覆盖：SSH、HTTP、TCP、TELNET、MCP 从基础设施目标到 AI 代理攻击面
• 可扩展插件系统：实现 CommandPlugin 或 HTTPPlugin 接口并通过 init() 注册——无需修改核心
• 完整可观测性栈：Prometheus 指标、RabbitMQ 事件流
• 生产就绪运行时：Docker、Kubernetes（Helm）、优雅停机、每服务内存限制

LLM 欺骗演示

快速开始

安装器```bash

./install.sh # asks local or Docker, checks prerequisites, and starts it

非交互式：`./install.sh --local` 或 `./install.sh --docker`。使用
`./install.sh --local --no-run` 安装并构建，但不启动本地运行时。
在非 root 主机上，当默认配置包含特权端口时，
本地安装不会自动启动。

### 本地 (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

### 使用 Helm (Kubernetes)```bash
helm install beelzebub ./beelzebub-chart
# Upgrade:
helm upgrade beelzebub ./beelzebub-chart

CLI Reference

Beelzebub 附带一个结构化的 CLI。运行 beelzebub --help 可查看所有可用命令。

beelzebub run

启动所有配置的欺骗服务。```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`

无需启动任何服务，即可解析并验证所有配置文件。在 CI 流水线中非常有用。有关验证架构和规则参考，请参阅 [配置验证](https://github.com/beelzebub-labs/beelzebub/blob/main/docs/configuration-validation.md)。```bash
beelzebub validate --conf-core ./configurations/beelzebub.yaml --conf-services ./configurations/services/

beelzebub plugin

安装、列出和移除从 GitHub 获取的插件。参见 插件系统。```bash beelzebub plugin install github.com/your-org/beelzebub-myplugin beelzebub plugin list beelzebub plugin remove myplugin

### `beelzebub version`

打印版本、提交 SHA、构建日期和 Go 运行时信息。```bash
beelzebub version

插件系统

Beelzebub 在 pkg/plugin 暴露了一个稳定的公共 SDK，用于扩展欺骗运行时，而无需修改核心代码。

接口```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 }

### 编写插件```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{})
}

安装外部插件```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 | 作用 |
|---|---|
| `plugin install <link>` | 获取插件，接入并重新构建；同时将其添加到 `configurations/plugins.yaml` |
| `plugin install` | 安装 `configurations/plugins.yaml` 中声明的所有插件 |
| `plugin list` | 显示已安装的插件与已编译进二进制的插件对比 |
| `plugin update [name]` | 按声明的引用重新获取并重新固定提交 |
| `plugin remove <name>` | 从 `configurations/plugins.yaml` 中移除插件，解除接入，并打印重新构建步骤 |

部署插件的源在 `configurations/plugins.yaml` 中配置：```yaml
plugins:
  - source: github.com/your-org/myplugin
  - source: github.com/your-org/[email protected]

未来的每个插件的运行时配置可以放在 configurations/plugins/ 下，每个插件对应一个 YAML 文件。

每个插件仓库必须附带一个 plugins.yaml 清单，并在 init() 中自行注册（参见 编写插件）：```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/[email protected]

已安装的插件会被编译进 Beelzebub 二进制文件，并与运行时在同一进程中运行。请仅从您信任的仓库安装插件。

## 可观测性

### Prometheus 指标

Beelzebub 在配置的端点（默认：`:2112/metrics`）暴露 Prometheus 指标：

| 指标 | 描述 |
|--------|-------------|
| `beelzebub_events_total` | 所有服务的欺骗事件总数 |
| `beelzebub_events_ssh_total` | SSH 事件 |
| `beelzebub_events_http_total` | HTTP 事件 |
| `beelzebub_events_tcp_total` | TCP 事件 |
| `beelzebub_events_telnet_total` | TELNET 事件 |
| `beelzebub_events_mcp_total` | MCP 事件 |

### RabbitMQ 集成

将所有欺骗事件发布到消息队列，以便下游 SIEM 集成：```yaml
core:
  tracings:
    rabbit-mq:
      enabled: true
      uri: "amqp://guest:guest@localhost:5672/"

事件以结构化 JSON 的形式发布到 event 队列。

测试```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

## 代码质量