Repolode
Submit
beelzebub-labs

beelzebub-labs/beelzebub

Open-source deception framework in Go for deploying decoy SSH, HTTP, TCP, TELNET and MCP services and capturing attacker interactions as evidence.

View on GitHubWebsite
Stars
2,232
Forks
221
Open issues
11
Last commit
5 days ago

What is it?

Beelzebub is a deception framework for security teams that want to study activity directed at decoy services. Services, routes and response rules are defined in YAML, and each response can be static or generated by an LLM provider. Trusted Go plugins can be compiled in to extend services and responses.

When an attacker interacts with a decoy, the runtime captures evidence such as commands, HTTP request details and session context, depending on the protocol. Events can be written to local logs, published to RabbitMQ, or sent to Beelzebub Platform, and Prometheus metrics can be enabled separately.

The project supports SSH, HTTP, TCP, TELNET and MCP decoys, with 18 example configurations covering services such as MySQL, Redis, SMB and MQTT. It can run as a Go binary, through Docker Compose, or on Kubernetes with Helm.

Key features

  • 01Define decoy services, routes and responses in YAML.
  • 02Generate adaptive responses with LLM providers, or use static handlers without one.
  • 03Capture commands, HTTP request details and session context from interactions.
  • 04Send events to local logs, RabbitMQ or Beelzebub Platform.
  • 05Expose bait tools for MCP decoys to observe suspicious agent invocations.

Use cases

  • Studying how attackers probe SSH, Telnet or database-style services in an isolated lab.
  • Placing HTTP or MCP decoys to collect evidence of suspicious requests or prompt-injection attempts.
  • Feeding decoy interaction events into an existing logging or alerting pipeline via RabbitMQ.

Quick start

  1. 1

    Clone the repository

    git clone https://github.com/beelzebub-labs/beelzebub.git
  2. 2

    Enter the project directory

    cd beelzebub
  3. 3

    Run the installer in Docker mode

    ./install.sh --docker
  4. 4

    Test the default HTTP decoy on port 8080

    curl -i http://localhost:8080/

Things to know

  • Licensed under GPL-3.0, a copyleft license that requires derivative works to be distributed under the same terms.
  • The installer starts example services on privileged ports, so it should only run on an isolated lab host you are authorized to use.
  • LLM-powered decoys require a configured provider, and the Docker setup needs Docker Engine with Compose v2.

In collections

Security scanners, audits & threat intel tools

Topics

#honeypot#security#deception#llm-security#cybersecurity#threat-detection#acis#agentic-ai-security#cloudnative#cloudsecurity

FAQ

What is beelzebub?
Open-source deception framework in Go for deploying decoy SSH, HTTP, TCP, TELNET and MCP services and capturing attacker interactions as evidence. Beelzebub is a deception framework for security teams that want to study activity directed at decoy services. Services, routes and response rules are defined in YAML, and each response can be static or generated by an LLM provider. Trusted Go plugins can be compiled in to extend services and responses.
Is beelzebub free to use? What license does it have?
beelzebub is open source under the GPL-3.0 license. Check the license terms before using it in commercial products.
Is beelzebub still maintained?
Actively maintained. The last commit to beelzebub was on Nov 3, 2026.
What can I use beelzebub for?
Studying how attackers probe SSH, Telnet or database-style services in an isolated lab. Placing HTTP or MCP decoys to collect evidence of suspicious requests or prompt-injection attempts. Feeding decoy interaction events into an existing logging or alerting pipeline via RabbitMQ.
How do I install beelzebub?
Clone the repository: git clone https://github.com/beelzebub-labs/beelzebub.git Enter the project directory: cd beelzebub Run the installer in Docker mode: ./install.sh --docker Test the default HTTP decoy on port 8080: curl -i http://localhost:8080/
Where can I get beelzebub?
The source code and installation instructions are on GitHub: https://github.com/beelzebub-labs/beelzebub

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects