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`을 사용하여 로컬 런타임을 시작하지 않고 설치 및 빌드를 수행합니다.
루트가 아닌 호스트에서는 기본 구성에 권한 있는 포트가 포함된 경우 로컬 설치가 자동으로 시작되지 않습니다.

### 로컬 (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 참조

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는 핵심 코드를 수정하지 않고도 디셉션 런타임을 확장할 수 있는 안정적인 공개 SDK를 pkg/plugin에 제공합니다.

인터페이스```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)

| 명령 | 기능 |
|---|---|
| `plugin install <link>` | 플러그인을 가져와 연결하고 다시 빌드합니다. 또한 `configurations/plugins.yaml`에 추가합니다. |
| `plugin install` | `configurations/plugins.yaml`에 선언된 모든 것을 설치합니다. |
| `plugin list` | 설치된 플러그인과 바이너리에 컴파일된 플러그인을 보여줍니다. |
| `plugin update [name]` | 선언된 ref로 다시 가져와 커밋을 다시 고정합니다. |
| `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 바이너리에 컴파일되어 런타임과 동일한 프로세스에서 실행됩니다. 신뢰하는 저장소의 플러그인만 설치하세요.

## Observability

### 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 통합