Deploying Beelzebub

Introduction

Beelzebub is a modern, open-source honeypot framework designed to detect, monitor, and analyze attack patterns against your infrastructure. By simulating vulnerable services, Beelzebub attracts attackers and logs their activities, providing valuable threat intelligence.

Built with Go for high performance, Beelzebub can emulate multiple services simultaneously while maintaining low resource usage. It’s an essential tool for security researchers, SOC teams, and organizations looking to understand their threat landscape.

Key highlights of Beelzebub:

• Multi-Protocol Support: Emulate SSH, HTTP, TCP, and other services
• High Performance: Written in Go for minimal resource usage
• Detailed Logging: Comprehensive attack logging and analysis
• OpenAI Integration: AI-powered attack analysis (optional)
• Flexible Configuration: YAML-based service configuration
• Real-Time Alerts: Webhook notifications for attacks
• Geolocation: Track attacker locations
• Credential Harvesting: Capture attempted login credentials
• Command Logging: Record commands executed by attackers
• Docker Support: Easy deployment with containerization
• API Access: Programmatic access to collected data

This guide walks through deploying Beelzebub on Klutch.sh using Docker for threat intelligence gathering.

Why Deploy Beelzebub on Klutch.sh

Deploying Beelzebub on Klutch.sh provides several advantages for security research:

Internet Exposure: Klutch.sh provides public IP accessibility to attract real attacks.

Isolated Environment: Run honeypots without risking your production infrastructure.

Persistent Logging: Reliably store attack data for analysis.

Always Online: 24/7 availability captures attacks around the clock.

GitHub Integration: Deploy configuration updates automatically.

Scalable Resources: Adjust resources based on traffic volume.

Prerequisites

Before deploying Beelzebub on Klutch.sh, ensure you have:

• A Klutch.sh account
• A GitHub account with a repository for your configuration
• Basic understanding of Docker and containerization
• Knowledge of honeypot concepts and security research
• (Optional) OpenAI API key for AI analysis

Understanding Beelzebub Architecture

Beelzebub operates with several components:

Service Emulators: Simulate vulnerable services to attract attackers.

Logging Engine: Records all attack activities and interactions.

Analysis Engine: Processes and categorizes attack data.

API Server: Provides access to collected threat data.

Preparing Your Repository

Create a GitHub repository for your Beelzebub deployment.

Repository Structure

beelzebub-deploy/
├── Dockerfile
├── config/
│   ├── beelzebub.yaml
│   └── services/
│       ├── ssh.yaml
│       └── http.yaml
└── .dockerignore

Creating the Dockerfile

Create a Dockerfile for Beelzebub:

FROM golang:1.21-alpine AS builder

# Install dependencies
RUN apk add --no-cache git

# Clone and build Beelzebub
WORKDIR /build
RUN git clone https://github.com/mariocandela/beelzebub.git .
RUN go build -o beelzebub ./cmd/beelzebub

# Runtime image
FROM alpine:latest

# Install runtime dependencies
RUN apk add --no-cache ca-certificates

# Copy binary
COPY --from=builder /build/beelzebub /usr/local/bin/beelzebub

# Create directories
WORKDIR /opt/beelzebub
RUN mkdir -p /opt/beelzebub/config \
    && mkdir -p /opt/beelzebub/logs

# Copy configuration
COPY config/ /opt/beelzebub/config/

# Environment variables
ENV BEELZEBUB_CONFIG=/opt/beelzebub/config/beelzebub.yaml
ENV OPENAI_API_KEY=${OPENAI_API_KEY}

# Expose honeypot ports
EXPOSE 22 80 443 8080

# Volume for logs
VOLUME ["/opt/beelzebub/logs"]

# Start Beelzebub
CMD ["beelzebub", "-c", "/opt/beelzebub/config/beelzebub.yaml"]

Configuration Files

Create config/beelzebub.yaml:

core:
  log_level: info
  log_path: /opt/beelzebub/logs/beelzebub.log

api:
  enabled: true
  port: 8080
  auth_token: ${API_TOKEN}

services:
  - name: ssh-honeypot
    config: /opt/beelzebub/config/services/ssh.yaml
  - name: http-honeypot
    config: /opt/beelzebub/config/services/http.yaml

notifications:
  webhook:
    enabled: true
    url: ${WEBHOOK_URL}

Create config/services/ssh.yaml:

protocol: ssh
port: 22
banner: "SSH-2.0-OpenSSH_8.9p1 Ubuntu-3ubuntu0.1"

credentials:
  - username: root
    password: password123
  - username: admin
    password: admin

commands:
  - command: "whoami"
    response: "root"
  - command: "id"
    response: "uid=0(root) gid=0(root) groups=0(root)"

Environment Variables Reference

Variable	Required	Default	Description
API_TOKEN	Yes	-	Authentication token for API access
OPENAI_API_KEY	No	-	OpenAI API key for AI analysis
WEBHOOK_URL	No	-	Webhook URL for attack notifications
LOG_LEVEL	No	info	Logging verbosity

Deploying Beelzebub on Klutch.sh

Generate API Token

Create a secure API token:

openssl rand -hex 32

Push Your Repository to GitHub

Initialize and push your configuration to GitHub.

Create a New Project on Klutch.sh

Navigate to the Klutch.sh dashboard and create a new project named “beelzebub” or “honeypot”.

Create a New App

Within your project, create a new app and connect your GitHub repository.

Configure Network Traffic

Set up traffic for the API and honeypot services:

• For API: Select HTTP on port 8080
• For SSH honeypot: Configure TCP on port 22

Set Environment Variables

Configure the following:

Variable	Value
API_TOKEN	Your generated token
OPENAI_API_KEY	OpenAI key (optional)
WEBHOOK_URL	Alert webhook URL (optional)

Attach Persistent Volumes

Add storage for logs:

Mount Path	Recommended Size	Purpose
/opt/beelzebub/logs	10 GB	Attack logs and data

Deploy Your Application

Click Deploy to build and start Beelzebub.

Verify Operation

Check logs to confirm services are running and accepting connections.

Analyzing Attack Data

API Access

Query attack data via the API:

curl -H "Authorization: Bearer YOUR_TOKEN" \
  https://your-app.klutch.sh:8080/api/attacks

Log Analysis

Attack logs contain:

• Timestamp
• Source IP and geolocation
• Target service and port
• Attempted credentials
• Commands executed
• Session duration

Dashboard Integration

Export data to security platforms:

• SIEM integration via syslog
• Elasticsearch for log aggregation
• Grafana for visualization

Advanced Configuration

Custom Service Emulation

Create custom honeypot services:

1. Define service behavior in YAML
2. Configure realistic responses
3. Add to services list
4. Redeploy

AI-Powered Analysis

Enable OpenAI integration:

1. Set OPENAI_API_KEY environment variable
2. Configure analysis settings
3. View AI-generated attack summaries

Alert Configuration

Set up attack notifications:

• Webhook for real-time alerts
• Email notifications
• Slack/Discord integration

Security Considerations

Isolation

• Never run honeypots on production infrastructure
• Isolate network traffic from real services
• Monitor for honeypot escape attempts

Legal Considerations

• Understand legal requirements in your jurisdiction
• Document research purposes
• Handle collected data responsibly

Troubleshooting Common Issues

Service Not Starting

Solutions:

• Verify configuration YAML syntax
• Check port availability
• Review startup logs for errors

No Attacks Detected

Solutions:

• Confirm ports are publicly accessible
• Check service emulation is working
• Allow time for discovery by scanners

High Resource Usage

Solutions:

• Limit concurrent connections
• Adjust logging verbosity
• Filter excessive scanning traffic

Additional Resources

• Beelzebub GitHub Repository
• The Honeynet Project
• Awesome Honeypots List

Conclusion

Deploying Beelzebub on Klutch.sh provides a powerful platform for gathering threat intelligence through honeypot monitoring. With multi-protocol support, AI analysis capabilities, and comprehensive logging, Beelzebub helps security teams understand attack patterns and improve their defenses.