Beelzebub

Beelzebub is a next‑generation, AI‑driven honeypot framework that blends low‑interaction security with high‑interaction deception. From a developer standpoint, it functions as a pluggable server that emulates common services (SSH, HTTP, TCP, MCP) while feeding realistic traffic into a language‑model backend. The framework is written in Go, exposing a lightweight HTTP API for configuration, metrics, and event ingestion. All state is persisted in an embedded SQLite database or a user‑supplied PostgreSQL instance, enabling seamless scaling across Kubernetes clusters.

Technical Stack

• Language & Runtime: Go 1.22+, compiled to static binaries for minimal runtime overhead.
• Web & Protocol Layer: net/http with custom handlers for SSH (via golang.org/x/crypto/ssh) and TCP listeners; optional MCP support for prompt‑injection detection.
• AI Engine: Integrates OpenAI/Claude LLMs through the standard openai-go client; the LLM is invoked only on user interaction, keeping the core low‑interaction architecture.
• Observability: Prometheus client exposes metrics (beelzebub_requests_total, beelzebub_alerts_triggered). Structured logs are emitted in JSON for ELK ingestion.
• Configuration: YAML‑based service definitions (services.yaml) parsed with gopkg.in/yaml.v3. The schema supports per‑service LLM prompts, response templates, and custom hooks.
• Deployment: Official Docker images are available on GitHub Container Registry; Helm charts and Kustomize overlays allow deployment in any Kubernetes cluster. The binary can also run natively on bare metal or VMs.

Core Capabilities

• Low‑Code Service Definition: Developers declare honeypot services in a single YAML file, specifying ports, protocols, and LLM prompts. No code changes are required to add a new decoy.
• LLM‑Based Interaction: The framework forwards user inputs to the LLM, which generates realistic responses, enabling high‑interaction deception without exposing a real backend.
• Multi‑Protocol Support: Out of the box support for SSH, HTTP(S), TCP, and MCP (for detecting prompt injection in AI agents).
• Event API: Webhooks (/api/webhook) allow external systems to receive real‑time alerts. The payload includes session metadata, attack vector, and LLM response.
• Observability Hooks: Custom metrics can be emitted via a Go plugin interface, allowing integration with Grafana dashboards or custom telemetry pipelines.

Deployment & Infrastructure

• Self‑Hosting: A single binary plus optional Docker image runs on any Linux host. The framework requires only TCP ports for the configured services and a connection to an LLM provider.
• Scalability: Horizontal scaling is achieved by running multiple instances behind a load balancer; session persistence is handled via Redis or shared database.
• Containerization: Dockerfile uses a multi‑stage build to keep images under 100 MB. The Helm chart supports statefulset for database persistence and deployment for stateless LLM interactions.
• Resource Footprint: Typical single‑node deployment consumes < 200 MiB RAM and 20 CPU cores (LLM calls are off‑loaded), making it suitable for edge or cloud environments.

Integration & Extensibility

• Plugin System: Go interfaces (EventHandler, MetricProvider) can be implemented and compiled into a shared library, loaded at runtime via Go plugin mechanism.
• Webhooks & Callbacks: External SIEMs, SOAR platforms, or custom dashboards can subscribe to /api/webhook events.
• Custom LLM Providers: The framework exposes a pluggable LLM client; developers can implement their own provider or use on‑prem models (e.g., llama.cpp) by providing a compatible API.
• API Documentation: Auto‑generated GoDoc and OpenAPI spec are available on pkg.go.dev and at /api/swagger.

Developer Experience

• Documentation: Comprehensive README, code comments, and API references are hosted on GitHub and pkg.go.dev. A dedicated docs/ directory contains deployment guides and plugin examples.
• Community & Support: Active GitHub discussions, a Discord channel for threat researchers, and a public Slack workspace facilitate rapid issue resolution.
• Testing & CI: The project uses GitHub Actions for unit, integration, and static analysis (CodeQL). Test coverage is > 90 %, ensuring stability for production deployments.
• Configuration Flexibility: YAML schemas support environment variable interpolation, making it trivial to inject secrets or runtime parameters.

Use Cases

1. Enterprise Lateral‑Movement Detection – Deploy decoys on internal networks; any interaction triggers a webhook to the SOC, enabling rapid containment.
2. API Honeypot – Expose a fake REST endpoint that mirrors production; malicious scanners are caught before they reach real services.
3. AI Agent Decoy – Use MCP support to trap prompt‑injection attempts against LLMs, protecting downstream AI services.
4. IoT Security – Spin up virtual devices that mimic firmware behavior, capturing attacks on edge hardware.

Advantages

• Performance & Low Overhead: Go’s compiled binaries and stateless design reduce latency, allowing dozens of decoys per node.
• **High‑Interaction without Risk