Um framework de runtime de decepção seguro e low-code, que aproveita IA para Virtualização de Sistemas.
Framework de Runtime de Engano
Beelzebub é um runtime de engano de código aberto que implanta serviços isca adaptativos com tecnologia LLM nos protocolos SSH, HTTP, TCP, TELNET e MCP. Ele vai além de honeypots passivos ao envolver ativamente atacantes em interações realistas, coletando inteligência de ameaças de alta fidelidade e detectando ataques de injeção de prompt contra agentes de IA.
CommandPlugin ou HTTPPlugin e registre via init() nenhuma alteração no núcleo é necessária
./install.sh # asks local or Docker, checks prerequisites, and starts it
Não interativo: `./install.sh --local` ou `./install.sh --docker`. Use `./install.sh --local --no-run` para instalar e compilar sem iniciar o runtime local. Em hosts não root, a instalação local não inicia automaticamente quando a configuração padrão inclui portas privilegiadas.
### Local (Go)```bash
make start # installs any declared plugins, compiles them in, and runs
make docker # builds an image with declared plugins baked in, then runs it
### Usando Helm (Kubernetes)```bash
helm install beelzebub ./beelzebub-chart
# Upgrade:
helm upgrade beelzebub ./beelzebub-chart
O Beelzebub vem com uma CLI estruturada. Execute beelzebub --help para ver todos os comandos disponíveis.
beelzebub runInicia todos os serviços de decepção configurados.```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`
Analisa e valida todos os arquivos de configuração sem iniciar nenhum serviço. Útil em pipelines de CI. Consulte [Validação de Configuração](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/docs/configuration-validation.md) para obter a arquitetura de validação e a referência de regras.```bash
beelzebub validate --conf-core ./configurations/beelzebub.yaml --conf-services ./configurations/services/
beelzebub pluginInstale, liste e remova plugins obtidos do GitHub. Consulte Sistema de Plugins.```bash beelzebub plugin install github.com/your-org/beelzebub-myplugin beelzebub plugin list beelzebub plugin remove myplugin
### `beelzebub version`
Imprime a versão, o commit SHA, a data de compilação e as informações de runtime do Go.```bash
beelzebub version
O Beelzebub expõe um SDK público estável em pkg/plugin para estender o runtime de decepção sem modificar o código central.
// 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 }
### Escrevendo um 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{})
}
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)
| Comando | O que faz |
|---|---|
| `plugin install <link>` | buscar um plugin, integrá-lo e reconstruir; também o adiciona a `configurations/plugins.yaml` |
| `plugin install` | instala tudo o que está declarado em `configurations/plugins.yaml` |
| `plugin list` | mostra os plugins instalados em comparação com o que está compilado no binário |
| `plugin update [name]` | buscar novamente no ref declarado e fixar novamente o commit |
| `plugin remove <name>` | remove um plugin de `configurations/plugins.yaml`, desfaz sua integração e imprime a etapa de reconstrução |
As fontes de plugins de implantação são configuradas em `configurations/plugins.yaml`:```yaml
plugins:
- source: github.com/your-org/myplugin
- source: github.com/your-org/[email protected]
A configuração de runtime por plugin no futuro pode ficar em configurations/plugins/
como um arquivo YAML por plugin.
Cada repositório de plugin deve fornecer um manifesto plugins.yaml e se auto-registrar em init()
(veja Escrevendo um 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
Os plugins instalados são compilados no binário do Beelzebub e executados no mesmo
processo do runtime. Instale plugins apenas de repositórios em que você confia.
## Observabilidade
### Métricas do Prometheus
O Beelzebub expõe métricas do Prometheus no endpoint configurado (padrão: `:2112/metrics`):
| Métrica | Descrição |
|--------|-------------|
| `beelzebub_events_total` | Total de eventos de decepção em todos os serviços |
| `beelzebub_events_ssh_total` | Eventos SSH |
| `beelzebub_events_http_total` | Eventos HTTP |
| `beelzebub_events_tcp_total` | Eventos TCP |
| `beelzebub_events_telnet_total` | Eventos TELNET |
| `beelzebub_events_mcp_total` | Eventos MCP |
### Integração com RabbitMQ
Publique todos os eventos de decepção em uma fila de mensagens para integração com SIEM a jusante:```yaml
core:
tracings:
rabbit-mq:
enabled: true
uri: "amqp://guest:guest@localhost:5672/"
Eventos são publicados como JSON estruturado na fila event.
make test.unit
make test.dependencies.start make test.integration make test.dependencies.down
beelzebub validate
## Qualidade do Código
- **CI**: GitHub Actions em cada commit e pull request
- **Análise estática**: CodeQL e Go Report Card
- **Cobertura**: Monitorada via [Codecov](https://codecov.io/gh/beelzebub-labs/beelzebub)
- **Revisão de código**: Todas as contribuições passam por revisão por pares
## Licença
O Beelzebub é licenciado sob a [Licença GNU GPL v3](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/LICENSE).
## Contribuindo
A equipe do Beelzebub acolhe contribuições e participação no projeto. Quer você queira relatar bugs, contribuir com novos recursos ou tenha alguma dúvida, consulte nosso [Guia do Contribuidor](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/CONTRIBUTING.md) para obter informações detalhadas. Incentivamos todos os participantes e mantenedores a seguir nosso [Código de Conduta](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/CODE_OF_CONDUCT.md) e a promover uma comunidade acolhedora e respeitosa.
Happy hacking!
## Referência de Configuração
O Beelzebub usa um sistema de configuração em dois níveis:
1. **Configuração principal** (`beelzebub.yaml`) configurações globais: logging, tracing, Prometheus
2. **Configurações de serviço** (`services/*.yaml`) um arquivo por serviço isca
### Configuração Principal```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"
Sobrescritas de variáveis de ambiente são suportadas para todos os campos (ex.: BEELZEBUB_RABBITMQ_ENABLED). Configurações de serviços também podem ser fornecidas inteiramente via BEELZEBUB_SERVICES_CONFIG como um array JSON.
Cada serviço de isca é definido em um arquivo YAML separado localizado no diretório services/. O campo protocol determina o mecanismo de decepção usado. Os comandos usam regex para correspondência de requisições e um handler estático ou uma referência de plugin para respostas dinâmicas.
Ao usar o plugin LLMHoneypot, é altamente recomendado usar guardrails para impedir que o LLM seja alvo de jailbreak ou manipulado de outras formas que possam comprometer o honeypot. Consulte a documentação do plugin LLMHoneypot para obter detalhes.
Os serviços de decepção MCP (Model Context Protocol) expõem ferramentas isca projetadas para detectar ataques de injeção de prompt contra agentes baseados em LLM.
A ferramenta isca é registrada na lista de ferramentas do agente, mas nunca deve ser invocada sob operação normal. Qualquer invocação sinaliza que um ataque de injeção de prompt contornou com sucesso os guardrails do agente. Isso fornece:
mcp-8000.yaml:```yaml apiVersion: "v1" protocol: "mcp" address: ":8000" description: "MCP Honeypot" tools:
Acessível via `http://beelzebub:port/mcp` (transporte HTTP Streamable).
### Serviço de Decepção HTTP
Os serviços de decepção HTTP respondem a requisições web com respostas configuráveis com base na correspondência de padrões de URL. Suporta TLS, handlers estáticos, respostas alimentadas por LLM e o gerador de labirinto infinito.
**Simulação de WordPress** (`http-80.yaml`):```yaml
apiVersion: "v1"
protocol: "http"
address: ":80"
description: "Wordpress 6.0"
commands:
- regex: "^(/index.php|/index.html|/)$"
handler: |
<html><header><title>Wordpress 6 test page</title></header>
<body><h1>Hello from Wordpress</h1></body></html>
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: |
<html><body>
<form method="post">
<input type="text" name="uname" placeholder="Username" required>
<input type="password" name="psw" placeholder="Password" required>
<button type="submit">Login</button>
</form>
</body></html>
headers:
- "Content-Type: text/html"
- "Server: Apache/2.4.53 (Debian)"
statusCode: 200
- regex: "^.*$"
handler: "<html><body><h1>Not found!</h1></body></html>"
headers:
- "Content-Type: text/html"
statusCode: 404
Serviço HTTP com tecnologia LLM adicione um fallbackCommand com plugin: LLMHoneypot para gerar respostas dinâmicas para qualquer requisição não correspondida.
Gerador de labirinto infinito use plugin: MazeHoneypot para implantar uma listagem de diretório no estilo Apache que se expande infinitamente, prendendo scanners e crawlers automatizados.
Os serviços de decepção SSH suportam tanto respostas estáticas de comandos quanto sessões interativas com tecnologia LLM, com histórico de conversa por sessão.
SSH com tecnologia LLM (OpenAI):```yaml apiVersion: "v1" protocol: "ssh" address: ":2222" description: "SSH interactive GPT-4o" commands:
**SSH com tecnologia de LLM** (Ollama local):```yaml
apiVersion: "v1"
protocol: "ssh"
address: ":2222"
description: "SSH Ollama Llama3"
commands:
- regex: "^(.+)$"
plugin: "LLMHoneypot"
serverVersion: "OpenSSH"
serverName: "ubuntu"
passwordRegex: "^(root|qwerty|123456)$"
deadlineTimeoutSeconds: 60
plugin:
llmProvider: "ollama"
llmModel: "codellama:7b"
host: "http://localhost:11434/api/chat"
SSH Estático:```yaml apiVersion: "v1" protocol: "ssh" address: ":22" description: "SSH interactive" commands:
### Serviço de Decepção TELNET
Os serviços de decepção TELNET emulam dispositivos baseados em terminal (roteadores, switches, sistemas legados) com fluxo de autenticação completo e integração com LLM.
**TELNET com tecnologia LLM**:```yaml
apiVersion: "v1"
protocol: "telnet"
address: ":23"
description: "TELNET LLM"
commands:
- regex: "^(.+)$"
plugin: "LLMHoneypot"
serverName: "router"
passwordRegex: "^(admin|root|password|123456)$"
deadlineTimeoutSeconds: 120
plugin:
llmProvider: "openai"
llmModel: "gpt-4o"
openAISecretKey: "sk-1234"
Simulação estática do Cisco IOS:```yaml apiVersion: "v1" protocol: "telnet" address: ":23" description: "Cisco IOS Router" commands:
### Serviço de Decepção TCP
Os serviços de decepção TCP abrangem protocolos binários e baseados em texto: bancos de dados, brokers de mensagens, serviços de diretório, acesso remoto e muito mais. Suporta modo somente banner, correspondência interativa com regex e integração com LLM.
**Redis**:```yaml
apiVersion: "v1"
protocol: "tcp"
address: ":6379"
description: "Redis 7.0.12"
commands:
- regex: "^PING"
handler: "+PONG\r\n"
- regex: "^AUTH"
handler: "-ERR Client sent AUTH, but no password is set\r\n"
- regex: "^INFO"
handler: "$180\r\n# Server\r\nredis_version:7.0.12\r\nos:Linux 5.15.0-76-generic x86_64\r\ntcp_port:6379\r\n\r\n"
- regex: "^(.+)$"
handler: "-ERR unknown command\r\n"
deadlineTimeoutSeconds: 60
serverName: "redis-prod-01"
LDAP / Active Directory:```yaml apiVersion: "v1" protocol: "tcp" address: ":389" description: "Active Directory LDAP Domain Controller" banner: "0\x84\x00\x00\x00\x10\x02\x01\x01\x61\x84\x00\x00\x00\x07\x0a\x01\x00\x04\x00\x04\x00" commands:
**PostgreSQL com tecnologia de LLM**:```yaml
apiVersion: "v1"
protocol: "tcp"
address: ":5432"
description: "PostgreSQL 15.3"
commands:
- regex: "^(.+)$"
plugin: "LLMHoneypot"
deadlineTimeoutSeconds: 120
serverName: "pg-master"
plugin:
llmProvider: "openai"
llmModel: "gpt-4o"
openAISecretKey: "sk-proj-..."
prompt: "You are simulating a PostgreSQL 15.3 server. Respond to incoming TCP data as a PostgreSQL server would."
Exemplos adicionais de configurações estão disponíveis em configurations/services/ para Memcached, MS-SQL, SMB, RDP, VNC e MQTT.
