{"id":13413768,"url":"https://github.com/mariocandela/beelzebub","last_synced_at":"2026-01-26T09:02:54.784Z","repository":{"id":49367231,"uuid":"490028114","full_name":"mariocandela/beelzebub","owner":"mariocandela","description":"A secure low code honeypot framework, leveraging AI for System Virtualization.","archived":false,"fork":false,"pushed_at":"2026-01-16T02:42:42.000Z","size":478,"stargazers_count":1814,"open_issues_count":7,"forks_count":169,"subscribers_count":20,"default_branch":"main","last_synced_at":"2026-01-22T09:25:35.683Z","etag":null,"topics":["acis","agentic-ai-security","cloudnative","cloudsecurity","cybersecurity","deception","decoys","framework","go","honeypot","llama","llm","llm-honeypot","llm-security","mcp","mcp-honeypot","preemptive-cybersecurity","research-project","security","whitehat"],"latest_commit_sha":null,"homepage":"https://docs.beelzebub.ai","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mariocandela.png","metadata":{"files":{"readme":"README.md","changelog":"historystore/history_store.go","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":"mariocandela"}},"created_at":"2022-05-08T18:47:02.000Z","updated_at":"2026-01-21T16:46:12.000Z","dependencies_parsed_at":"2023-10-16T10:49:14.458Z","dependency_job_id":"ec557c6c-cc8e-4381-96fb-ec4713823382","html_url":"https://github.com/mariocandela/beelzebub","commit_stats":{"total_commits":230,"total_committers":5,"mean_commits":46.0,"dds":0.4043478260869565,"last_synced_commit":"f1b35e9e439eec82605d46fd81b913f261408b20"},"previous_names":[],"tags_count":62,"template":false,"template_full_name":null,"purl":"pkg:github/mariocandela/beelzebub","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariocandela%2Fbeelzebub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariocandela%2Fbeelzebub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariocandela%2Fbeelzebub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariocandela%2Fbeelzebub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mariocandela","download_url":"https://codeload.github.com/mariocandela/beelzebub/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mariocandela%2Fbeelzebub/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28668815,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-22T17:07:18.858Z","status":"ssl_error","status_checked_at":"2026-01-22T17:05:02.040Z","response_time":144,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["acis","agentic-ai-security","cloudnative","cloudsecurity","cybersecurity","deception","decoys","framework","go","honeypot","llama","llm","llm-honeypot","llm-security","mcp","mcp-honeypot","preemptive-cybersecurity","research-project","security","whitehat"],"created_at":"2024-07-30T20:01:48.698Z","updated_at":"2026-01-26T09:02:54.778Z","avatar_url":"https://github.com/mariocandela.png","language":"Go","funding_links":["https://github.com/sponsors/mariocandela"],"categories":["Security","Uncategorized","Web apps","Security \u0026 Attestation Mcp Servers","MCP Servers","SDK, Libraries, Frameworks","Official Resources","Channel Resources","Developer Libraries, SDKs, and APIs","Cybersecurity","[↑](#table-of-contents)Tools \u003ca name=\"tools\"\u003e\u003c/a\u003e","Honeypots","Golang","📚 Projects (1974 total)","پیاده‌سازی‌های سرور","Go","\u003ca name=\"tools\"\u003e\u003c/a\u003eTools","📦 Other","Thanks to all the contributors!","Tools","安全"],"sub_categories":["SIEM \u0026 SecOps","HTTP Clients","Uncategorized","Self-hosted","Security \u0026 Reverse Engineering","Golang library, sdk or frameworks","Cybersecurity","GitHub Projects","Golang","Other","Agent Tooling and MCP Security","MCP Servers","🔒 \u003ca name=\"security\"\u003e\u003c/a\u003eامنیت","Investigation","HTTP客户端"],"readme":"# Beelzebub\n\n\n[![CI](https://github.com/mariocandela/beelzebub/actions/workflows/ci.yml/badge.svg)](https://github.com/mariocandela/beelzebub/actions/workflows/ci.yml) [![Docker](https://github.com/mariocandela/beelzebub/actions/workflows/docker-image.yml/badge.svg)](https://github.com/mariocandela/beelzebub/actions/workflows/docker-image.yml) [![codeql](https://github.com/mariocandela/beelzebub/actions/workflows/codeql.yml/badge.svg)](https://github.com/mariocandela/beelzebub/actions/workflows/codeql.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/mariocandela/beelzebub/v3)](https://goreportcard.com/report/github.com/mariocandela/beelzebub/v3)\n[![codecov](https://codecov.io/gh/mariocandela/beelzebub/graph/badge.svg?token=8XTK7D4WHE)](https://codecov.io/gh/mariocandela/beelzebub)\n[![Go Reference](https://pkg.go.dev/badge/github.com/mariocandela/beelzebub/v3.svg)](https://pkg.go.dev/github.com/mariocandela/beelzebub/v3)\n[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/mariocandela/beelzebub)](https://archestra.ai/mcp-catalog/mariocandela__beelzebub)\n[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)\n\n## Overview\n\nBeelzebub is an advanced honeypot framework designed to provide a highly secure environment for detecting and analyzing cyber attacks. It offers a low code approach for easy implementation and uses AI to mimic the behavior of a high-interaction honeypot.\n\n![github beelzebub - inception program](https://github.com/user-attachments/assets/e180d602-6de9-4c48-92ad-eb0ef3c5322d)\n\n## 🌍 Global Threat Intelligence Community\n\nOur mission is to establish a collaborative ecosystem of security researchers and white hat professionals worldwide, dedicated to creating a distributed honeypot network that identifies emerging malware, discovers zero-day vulnerabilities, and neutralizes active botnets. \n\nFor a comprehensive overview of our distributed threat intelligence framework and community vision, please refer to our white paper:\n\n[![White Paper](https://img.shields.io/badge/White_Paper-v1.0-blue?style=for-the-badge)](https://github.com/beelzebub-labs/white-paper/)\n\n*The white paper includes information on how to join our Discord community and contribute to the global threat intelligence network.* \n\n## Key Features\n\nBeelzebub offers a wide range of features to enhance your honeypot environment:\n\n- Low-code configuration: YAML-based, modular service definition\n- LLM integration: The LLM convincingly simulates a real system, creating high-interaction honeypot experiences, while actually maintaining low-interaction architecture for enhanced security and easy management.\n- Multi-protocol support: SSH, HTTP, TCP, MCP(Detect prompt injection against LLM agents)\n- Prometheus metrics \u0026 observability \n- Docker \u0026 Kubernetes ready\n- ELK stack ready, docs: [Official ELK integration](https://www.elastic.co/docs/reference/integrations/beelzebub)\n\n## LLM Honeypot Demo\n![demo-beelzebub](https://github.com/user-attachments/assets/4dbb9a67-6c12-49c5-82ac-9b3e340406ca)\n\n## Code Quality\n\nWe are strongly committed to maintaining high code quality in the Beelzebub project. Our development workflow includes comprehensive testing, code reviews, static analysis, and continuous integration to ensure the reliability and maintainability of the codebase.\n\n### What We Do\n\n* **Automated Testing:**\n  Both unit and integration tests are run on every pull request to catch regressions and ensure stability.\n\n* **Static Analysis:**\n  We use tools like Go Report Card and CodeQL to automatically check for code quality, style, and security issues.\n\n* **Code Coverage:**\n  Our test coverage is monitored with [Codecov](https://codecov.io/gh/mariocandela/beelzebub), and we aim for extensive coverage of all core components.\n\n* **Continuous Integration:**\n  Every commit triggers automated CI pipelines on GitHub Actions, which run all tests and quality checks.\n\n* **Code Reviews:**\n  All new contributions undergo peer review to maintain consistency and high standards across the project.\n\n## Quick Start\n\nYou can run Beelzebub via Docker, Go compiler(cross device), or Helm (Kubernetes).\n\n### Using Docker Compose\n\n1. Build the Docker images:\n\n   ```bash\n   $ docker compose build\n   ```\n\n2. Start Beelzebub in detached mode:\n\n   ```bash\n   $ docker compose up -d\n   ```\n\n\n### Using Go Compiler\n\n1. Download the necessary Go modules:\n\n   ```bash\n   $ go mod download\n   ```\n\n2. Build the Beelzebub executable:\n\n   ```bash\n   $ go build\n   ```\n\n3. Run Beelzebub:\n\n   ```bash\n   $ ./beelzebub\n   ```\n\n### Deploy on kubernetes cluster using helm\n\n1. Install helm\n\n2. Deploy beelzebub:\n\n   ```bash\n   $ helm install beelzebub ./beelzebub-chart\n   ```\n\n3. Next release\n\n   ```bash\n   $ helm upgrade beelzebub ./beelzebub-chart\n   ```\n\n## Example Configuration\n\nBeelzebub allows easy configuration for different services and ports. Simply create a new file for each service/port within the `/configurations/services` directory.\n\nTo execute Beelzebub with your custom path, use the following command:\n\n```bash\n$ ./beelzebub --confCore ./configurations/beelzebub.yaml --confServices ./configurations/services/\n```\n\nHere are some example configurations for different honeypot scenarios:\n\n### MCP Honeypot\n\n#### Why choose an MCP Honeypot?\n\nAn MCP honeypot is a **decoy tool** that the agent should never invoke under normal circumstances. Integrating this strategy into your agent pipeline offers three key benefits:\n\n* **Real-time detection of guardrail bypass attempts.**\n  \n  Instantly identify when a prompt injection attack successfully convinces the agent to invoke a restricted tool.\n* **Automatic collection of real attack prompts for guardrail fine-tuning.**\n  \n   Every activation logs genuine malicious prompts, enabling continuous improvement of your filtering mechanisms.\n* **Continuous monitoring of attack trends through key metrics (HAR, TPR, MTP).**\n  \n   Track exploit frequency and system resilience using objective, actionable measurements.\n\n![video-mcp-diagram](https://github.com/user-attachments/assets/e04fd19e-9537-427e-9131-9bee31d8ebad)\n\n##### Example MCP Honeypot Configuration\n\n###### mcp-8000.yaml\n\n```yaml\napiVersion: \"v1\"\nprotocol: \"mcp\"\naddress: \":8000\"\ndescription: \"MCP Honeypot\"\ntools:\n  - name: \"tool:user-account-manager\"\n    description: \"Tool for querying and modifying user account details. Requires administrator privileges.\"\n    params:\n      - name: \"user_id\"\n        description: \"The ID of the user account to manage.\"\n      - name: \"action\"\n        description: \"The action to perform on the user account, possible values are: get_details, reset_password, deactivate_account\"\n    handler: |\n      {\n        \"tool_id\": \"tool:user-account-manager\",\n        \"status\": \"completed\",\n        \"output\": {\n          \"message\": \"Tool 'tool:user-account-manager' executed successfully. Results are pending internal processing and will be logged.\",\n          \"result\": {\n            \"operation_status\": \"success\",\n            \"details\": \"email: kirsten@gmail.com, role: admin, last-login: 02/07/2025\"\n          }\n        }\n      }\n  - name: \"tool:system-log\"\n    description: \"Tool for querying system logs. Requires administrator privileges.\"\n    params:\n      - name: \"filter\"\n        description: \"The input used to filter the logs.\"\n    handler: |\n      {\n        \"tool_id\": \"tool:system-log\",\n        \"status\": \"completed\",\n        \"output\": {\n          \"message\": \"Tool 'tool:system-log' executed successfully. Results are pending internal processing and will be logged.\",\n          \"result\": {\n            \"operation_status\": \"success\",\n            \"details\": \"Info: email: kirsten@gmail.com, last-login: 02/07/2025\"\n          }\n        }\n      }\n```\n\n#### Invoke remotely: beelzebub:port/mcp (Streamable HTTPServer).\n\n### HTTP Honeypot\n\n###### http-80.yaml\n\n```yaml\napiVersion: \"v1\"\nprotocol: \"http\"\naddress: \":80\"\ndescription: \"Wordpress 6.0\"\ncommands:\n  - regex: \"^(/index.php|/index.html|/)$\"\n    handler:\n      \u003chtml\u003e\n        \u003cheader\u003e\n          \u003ctitle\u003eWordpress 6 test page\u003c/title\u003e\n        \u003c/header\u003e\n        \u003cbody\u003e\n          \u003ch1\u003eHello from Wordpress\u003c/h1\u003e\n        \u003c/body\u003e\n      \u003c/html\u003e\n    headers:\n      - \"Content-Type: text/html\"\n      - \"Server: Apache/2.4.53 (Debian)\"\n      - \"X-Powered-By: PHP/7.4.29\"\n    statusCode: 200\n  - regex: \"^(/wp-login.php|/wp-admin)$\"\n    handler:\n      \u003chtml\u003e\n        \u003cheader\u003e\n          \u003ctitle\u003eWordpress 6 test page\u003c/title\u003e\n        \u003c/header\u003e\n        \u003cbody\u003e\n          \u003cform action=\"\" method=\"post\"\u003e\n            \u003clabel for=\"uname\"\u003e\u003cb\u003eUsername\u003c/b\u003e\u003c/label\u003e\n            \u003cinput type=\"text\" placeholder=\"Enter Username\" name=\"uname\" required\u003e\n\n            \u003clabel for=\"psw\"\u003e\u003cb\u003ePassword\u003c/b\u003e\u003c/label\u003e\n            \u003cinput type=\"password\" placeholder=\"Enter Password\" name=\"psw\" required\u003e\n\n            \u003cbutton type=\"submit\"\u003eLogin\u003c/button\u003e\n          \u003c/form\u003e\n        \u003c/body\u003e\n      \u003c/html\u003e\n    headers:\n      - \"Content-Type: text/html\"\n      - \"Server: Apache/2.4.53 (Debian)\"\n      - \"X-Powered-By: PHP/7.4.29\"\n    statusCode: 200\n  - regex: \"^.*$\"\n    handler:\n      \u003chtml\u003e\n        \u003cheader\u003e\n          \u003ctitle\u003e404\u003c/title\u003e\n        \u003c/header\u003e\n        \u003cbody\u003e\n          \u003ch1\u003eNot found!\u003c/h1\u003e\n        \u003c/body\u003e\n      \u003c/html\u003e\n    headers:\n      - \"Content-Type: text/html\"\n      - \"Server: Apache/2.4.53 (Debian)\"\n      - \"X-Powered-By: PHP/7.4.29\"\n    statusCode: 404\n```\n\n### HTTP Honeypot\n\n###### http-8080.yaml\n\n```yaml\napiVersion: \"v1\"\nprotocol: \"http\"\naddress: \":8080\"\ndescription: \"Apache 401\"\ncommands:\n  - regex: \".*\"\n    handler: \"Unauthorized\"\n    headers:\n      - \"www-Authenticate: Basic\"\n      - \"server: Apache\"\n    statusCode: 401\n```\n\n### SSH Honeypot\n\n###### LLM Honeypots\n\nFollow a SSH LLM Honeypot using OpenAI as provider LLM:\n\n```yaml\napiVersion: \"v1\"\nprotocol: \"ssh\"\naddress: \":2222\"\ndescription: \"SSH interactive OpenAI  GPT-4\"\ncommands:\n  - regex: \"^(.+)$\"\n    plugin: \"LLMHoneypot\"\nserverVersion: \"OpenSSH\"\nserverName: \"ubuntu\"\npasswordRegex: \"^(root|qwerty|Smoker666|123456|jenkins|minecraft|sinus|alex|postgres|Ly123456)$\"\ndeadlineTimeoutSeconds: 60\nplugin:\n   llmProvider: \"openai\"\n   llmModel: \"gpt-4o\" #Models https://platform.openai.com/docs/models\n   openAISecretKey: \"sk-proj-123456\"\n```\n\nExamples with local Ollama instance using model codellama:7b:\n\n```yaml\napiVersion: \"v1\"\nprotocol: \"ssh\"\naddress: \":2222\"\ndescription: \"SSH Ollama Llama3\"\ncommands:\n  - regex: \"^(.+)$\"\n    plugin: \"LLMHoneypot\"\nserverVersion: \"OpenSSH\"\nserverName: \"ubuntu\"\npasswordRegex: \"^(root|qwerty|Smoker666|123456|jenkins|minecraft|sinus|alex|postgres|Ly123456)$\"\ndeadlineTimeoutSeconds: 60\nplugin:\n   llmProvider: \"ollama\"\n   llmModel: \"codellama:7b\" #Models https://ollama.com/search\n   host: \"http://example.com/api/chat\" #default http://localhost:11434/api/chat\n```\nExample with custom prompt:\n\n```yaml\napiVersion: \"v1\"\nprotocol: \"ssh\"\naddress: \":2222\"\ndescription: \"SSH interactive OpenAI  GPT-4\"\ncommands:\n  - regex: \"^(.+)$\"\n    plugin: \"LLMHoneypot\"\nserverVersion: \"OpenSSH\"\nserverName: \"ubuntu\"\npasswordRegex: \"^(root|qwerty|Smoker666|123456|jenkins|minecraft|sinus|alex|postgres|Ly123456)$\"\ndeadlineTimeoutSeconds: 60\nplugin:\n   llmProvider: \"openai\"\n   llmModel: \"gpt-4o\"\n   openAISecretKey: \"sk-proj-123456\"\n   prompt: \"You will act as an Ubuntu Linux terminal. The user will type commands, and you are to reply with what the terminal should show. Your responses must be contained within a single code block.\"\n```\n\n###### SSH Honeypot\n\n###### ssh-22.yaml\n\n```yaml\napiVersion: \"v1\"\nprotocol: \"ssh\"\naddress: \":22\"\n\n\ndescription: \"SSH interactive\"\ncommands:\n  - regex: \"^ls$\"\n    handler: \"Documents Images Desktop Downloads .m2 .kube .ssh .docker\"\n  - regex: \"^pwd$\"\n    handler: \"/home/\"\n  - regex: \"^uname -m$\"\n    handler: \"x86_64\"\n  - regex: \"^docker ps$\"\n    handler: \"CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES\"\n  - regex: \"^docker .*$\"\n    handler: \"Error response from daemon: dial unix docker.raw.sock: connect: connection refused\"\n  - regex: \"^uname$\"\n    handler: \"Linux\"\n  - regex: \"^ps$\"\n    handler: \"PID TTY TIME CMD\\n21642 ttys000 0:00.07 /bin/dockerd\"\n  - regex: \"^(.+)$\"\n    handler: \"command not found\"\nserverVersion: \"OpenSSH\"\nserverName: \"ubuntu\"\npasswordRegex: \"^(root|qwerty|Smoker666)$\"\ndeadlineTimeoutSeconds: 60\n```\n\n## Testing\n\nMaintaining excellent code quality is essential for security-focused projects like Beelzebub. We welcome all contributors who share our commitment to robust, readable, and reliable code!\n\n### Unit Tests\n\nFor contributor, we have a comprehensive suite of unit/integration tests that cover the core functionality of Beelzebub. To run the unit tests, use the following command:\n\n```bash\n$ make test.unit\n```\n\n### Integration Tests\n\nTo run integration tests:\n\n```bash\n$ make test.dependencies.start\n$ make test.integration\n$ make test.dependencies.down\n```\n\n## Contributing\n\nThe Beelzebub team welcomes contributions and project participation. Whether you want to report bugs, contribute new features, or have any questions, please refer to our [Contributor Guide](CONTRIBUTING.md) for detailed information. We encourage all participants and maintainers to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md) and foster a supportive and respectful community.\n\nHappy hacking!\n\n## License\n\nBeelzebub is licensed under the [GNU GPL v3 License](LICENSE).\n\n## Supported by\n[![JetBrains logo.](https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.svg)](https://jb.gg/OpenSourceSupport)\n\n![gitbook logo](https://i.postimg.cc/VNQh5hnk/gitbook.png)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmariocandela%2Fbeelzebub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmariocandela%2Fbeelzebub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmariocandela%2Fbeelzebub/lists"}