Hello from Wordpress

1# Beelzebub
2 
3[![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)
4[![Go Report Card](https://goreportcard.com/badge/github.com/mariocandela/beelzebub/v3)](https://goreportcard.com/report/github.com/mariocandela/beelzebub/v3)
5[![codecov](https://codecov.io/gh/mariocandela/beelzebub/graph/badge.svg?token=8XTK7D4WHE)](https://codecov.io/gh/mariocandela/beelzebub)
6[![Go Reference](https://pkg.go.dev/badge/github.com/mariocandela/beelzebub/v3.svg)](https://pkg.go.dev/github.com/mariocandela/beelzebub/v3)
7[![Trust Score](https://archestra.ai/mcp-catalog/api/badge/quality/mariocandela/beelzebub)](https://archestra.ai/mcp-catalog/mariocandela__beelzebub)
8[![Mentioned in Awesome Go](https://awesome.re/mentioned-badge.svg)](https://github.com/avelino/awesome-go)
9 
10## Overview
11 
12Beelzebub 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.
13 
14![github beelzebub - inception program](https://github.com/user-attachments/assets/e180d602-6de9-4c48-92ad-eb0ef3c5322d)
15 
16## Table of Contents
17 
18- [Global Threat Intelligence Community](#global-threat-intelligence-community)
19- [Key Features](#key-features)
20- [Architecture](#architecture)
21- [Quick Start](#quick-start)
22- [Configuration](#configuration)
23  - [Core Configuration](#core-configuration)
24  - [Service Configuration](#service-configuration)
25- [Protocol Examples](#protocol-examples)
26  - [MCP Honeypot](#mcp-honeypot)
27  - [HTTP Honeypot](#http-honeypot)
28  - [SSH Honeypot](#ssh-honeypot)
29  - [TELNET Honeypot](#telnet-honeypot)
30  - [TCP Honeypot](#tcp-honeypot)
31- [Observability](#observability)
32  - [Prometheus Metrics](#prometheus-metrics)
33  - [RabbitMQ Integration](#rabbitmq-integration)
34  - [Beelzebub Cloud](#beelzebub-cloud)
35- [Testing](#testing)
36- [Code Quality](#code-quality)
37- [Contributing](#contributing)
38- [License](#license)
39 
40## Global Threat Intelligence Community
41 
42Our 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.
43 
44[![White Paper](https://img.shields.io/badge/White_Paper-v1.0-blue?style=for-the-badge)](https://github.com/beelzebub-labs/white-paper/)
45 
46The white paper includes information on how to join our Discord community and contribute to the global threat intelligence network. 
47 
48## Key Features
49 
50Beelzebub offers a wide range of features to enhance your honeypot environment:
51 
52- **Low-code configuration**: YAML-based, modular service definition
53- **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
54- **Multi-protocol support**: SSH, HTTP, TCP, TELNET, MCP (detect prompt injection against LLM agents)
55- **Prometheus metrics & observability**: Built-in metrics endpoint for monitoring
56- **Event tracing**: Multiple output strategies (stdout, RabbitMQ, Beelzebub Cloud)
57- **Docker & Kubernetes ready**: Deploy anywhere with provided configurations
58- **ELK stack ready**: Official integration available at [Elastic docs](https://www.elastic.co/docs/reference/integrations/beelzebub)
59 
60## LLM Honeypot Demo
61 
62![demo-beelzebub](https://github.com/user-attachments/assets/4dbb9a67-6c12-49c5-82ac-9b3e340406ca)
63 
64## Quick Start
65 
66You can run Beelzebub via Docker, Go compiler(cross device), or Helm (Kubernetes).
67 
68### Using Docker Compose
69 
701. Build the Docker images:
71 
72   ```bash
73   $ docker compose build
74   ```
75 
762. Start Beelzebub in detached mode:
77 
78   ```bash
79   $ docker compose up -d
80   ```
81 
82 
83### Using Go Compiler
84 
851. Download the necessary Go modules:
86 
87   ```bash
88   $ go mod download
89   ```
90 
912. Build the Beelzebub executable:
92 
93   ```bash
94   $ go build
95   ```
96 
973. Run Beelzebub:
98 
99   ```bash
100   $ ./beelzebub
101   ```
102 
103### Deploy on kubernetes cluster using helm
104 
1051. Install helm
106 
1072. Deploy beelzebub:
108 
109   ```bash
110   $ helm install beelzebub ./beelzebub-chart
111   ```
112 
1133. Next release
114 
115   ```bash
116   $ helm upgrade beelzebub ./beelzebub-chart
117   ```
118 
119## Configuration
120 
121Beelzebub uses a two-tier configuration system:
122 
1231. **Core configuration** (`beelzebub.yaml`) - Global settings for logging, tracing, and Prometheus
1242. **Service configurations** (`services/*.yaml`) - Individual honeypot service definitions
125 
126### Core Configuration
127 
128The core configuration file controls global behavior:
129 
130```yaml
131core:
132  logging:
133    debug: false
134    debugReportCaller: false
135    logDisableTimestamp: true
136    logsPath: ./logs
137  tracings:
138    rabbit-mq:
139      enabled: false
140      uri: "amqp://guest:guest@localhost:5672/"
141  prometheus:
142    path: "/metrics"
143    port: ":2112"
144  beelzebub-cloud:
145    enabled: false
146    uri: ""
147    auth-token: ""
148```
149 
150### Service Configuration
151 
152Each honeypot service is defined in a separate YAML file in the `services/` directory. To run Beelzebub with custom paths:
153 
154```bash
155./beelzebub --confCore ./configurations/beelzebub.yaml --confServices ./configurations/services/
156```
157 
158Additional flags:
159- `--memLimitMiB <value>` - Set memory limit in MiB (default: 100, use -1 to disable)
160 
161## Protocol Examples
162 
163Below are example configurations for each supported protocol.
164 
165### MCP Honeypot
166 
167MCP (Model Context Protocol) honeypots are decoy tools designed to detect prompt injection attacks against LLM agents.
168 
169#### Why Use an MCP Honeypot?
170 
171An 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:
172 
173- **Real-time detection of guardrail bypass attempts** - Instantly identify when a prompt injection attack successfully convinces the agent to invoke a restricted tool
174- **Automatic collection of real attack prompts** - Every activation logs genuine malicious prompts, enabling continuous improvement of your filtering mechanisms
175- **Continuous monitoring of attack trends** - Track exploit frequency and system resilience using objective, actionable measurements (HAR, TPR, MTP)
176 
177![video-mcp-diagram](https://github.com/user-attachments/assets/e04fd19e-9537-427e-9131-9bee31d8ebad)
178 
179**mcp-8000.yaml**:
180 
181```yaml
182apiVersion: "v1"
183protocol: "mcp"
184address: ":8000"
185description: "MCP Honeypot"
186tools:
187  - name: "tool:user-account-manager"
188    description: "Tool for querying and modifying user account details. Requires administrator privileges."
189    params:
190      - name: "user_id"
191        description: "The ID of the user account to manage."
192      - name: "action"
193        description: "The action to perform on the user account, possible values are: get_details, reset_password, deactivate_account"
194    handler: |
195      {
196        "tool_id": "tool:user-account-manager",
197        "status": "completed",
198        "output": {
199          "message": "Tool 'tool:user-account-manager' executed successfully. Results are pending internal processing and will be logged.",
200          "result": {
201            "operation_status": "success",
202            "details": "email: kirsten@gmail.com, role: admin, last-login: 02/07/2025"
203          }
204        }
205      }
206  - name: "tool:system-log"
207    description: "Tool for querying system logs. Requires administrator privileges."
208    params:
209      - name: "filter"
210        description: "The input used to filter the logs."
211    handler: |
212      {
213        "tool_id": "tool:system-log",
214        "status": "completed",
215        "output": {
216          "message": "Tool 'tool:system-log' executed successfully. Results are pending internal processing and will be logged.",
217          "result": {
218            "operation_status": "success",
219            "details": "Info: email: kirsten@gmail.com, last-login: 02/07/2025"
220          }
221        }
222      }
223```
224 
225Invoke remotely via `http://beelzebub:port/mcp` (Streamable HTTP Server).
226 
227### HTTP Honeypot
228 
229HTTP honeypots respond to web requests with configurable responses based on URL pattern matching.
230 
231**http-80.yaml** (WordPress simulation):
232 
233```yaml
234apiVersion: "v1"
235protocol: "http"
236address: ":80"
237description: "Wordpress 6.0"
238commands:
239  - regex: "^(/index.php|/index.html|/)$"
240    handler:
241      <html>
242        <header>
243          <title>Wordpress 6 test page</title>
244        </header>
245        <body>
246          <h1>Hello from Wordpress</h1>
247        </body>
248      </html>
249    headers:
250      - "Content-Type: text/html"
251      - "Server: Apache/2.4.53 (Debian)"
252      - "X-Powered-By: PHP/7.4.29"
253    statusCode: 200
254  - regex: "^(/wp-login.php|/wp-admin)$"
255    handler:
256      <html>
257        <header>
258          <title>Wordpress 6 test page</title>
259        </header>
260        <body>
261          <form action="" method="post">
262            <label for="uname"><b>Username</b></label>
263            <input type="text" placeholder="Enter Username" name="uname" required>
264 
265            <label for="psw"><b>Password</b></label>
266            <input type="password" placeholder="Enter Password" name="psw" required>
267 
268            <button type="submit">Login</button>
269          </form>
270        </body>
271      </html>
272    headers:
273      - "Content-Type: text/html"
274      - "Server: Apache/2.4.53 (Debian)"
275      - "X-Powered-By: PHP/7.4.29"
276    statusCode: 200
277  - regex: "^.*$"
278    handler:
279      <html>
280        <header>
281          <title>404</title>
282        </header>
283        <body>
284          <h1>Not found!</h1>
285        </body>
286      </html>
287    headers:
288      - "Content-Type: text/html"
289      - "Server: Apache/2.4.53 (Debian)"
290      - "X-Powered-By: PHP/7.4.29"
291    statusCode: 404
292```
293 
294**http-8080.yaml** (Apache 401 simulation):
295 
296```yaml
297apiVersion: "v1"
298protocol: "http"
299address: ":8080"
300description: "Apache 401"
301commands:
302  - regex: ".*"
303    handler: "Unauthorized"
304    headers:
305      - "www-Authenticate: Basic"
306      - "server: Apache"
307    statusCode: 401
308```
309 
310### SSH Honeypot
311 
312SSH honeypots support both static command responses and LLM-powered dynamic interactions.
313 
314#### LLM-Powered SSH Honeypot
315 
316Using OpenAI as the LLM provider:
317 
318```yaml
319apiVersion: "v1"
320protocol: "ssh"
321address: ":2222"
322description: "SSH interactive OpenAI  GPT-4"
323commands:
324  - regex: "^(.+)$"
325    plugin: "LLMHoneypot"
326serverVersion: "OpenSSH"
327serverName: "ubuntu"
328passwordRegex: "^(root|qwerty|Smoker666|123456|jenkins|minecraft|sinus|alex|postgres|Ly123456)$"
329deadlineTimeoutSeconds: 60
330plugin:
331   llmProvider: "openai"
332   llmModel: "gpt-4o" #Models https://platform.openai.com/docs/models
333   openAISecretKey: "sk-proj-123456"
334```
335 
336Using local Ollama instance:
337 
338```yaml
339apiVersion: "v1"
340protocol: "ssh"
341address: ":2222"
342description: "SSH Ollama Llama3"
343commands:
344  - regex: "^(.+)$"
345    plugin: "LLMHoneypot"
346serverVersion: "OpenSSH"
347serverName: "ubuntu"
348passwordRegex: "^(root|qwerty|Smoker666|123456|jenkins|minecraft|sinus|alex|postgres|Ly123456)$"
349deadlineTimeoutSeconds: 60
350plugin:
351   llmProvider: "ollama"
352   llmModel: "codellama:7b"
353   host: "http://localhost:11434/api/chat"
354```
355 
356Using a custom prompt:
357 
358```yaml
359apiVersion: "v1"
360protocol: "ssh"
361address: ":2222"
362description: "SSH interactive OpenAI  GPT-4"
363commands:
364  - regex: "^(.+)$"
365    plugin: "LLMHoneypot"
366serverVersion: "OpenSSH"
367serverName: "ubuntu"
368passwordRegex: "^(root|qwerty|Smoker666|123456|jenkins|minecraft|sinus|alex|postgres|Ly123456)$"
369deadlineTimeoutSeconds: 60
370plugin:
371   llmProvider: "openai"
372   llmModel: "gpt-4o"
373   openAISecretKey: "sk-proj-123456"
374   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."
375```
376 
377#### Static SSH Honeypot
378 
379```yaml
380apiVersion: "v1"
381protocol: "ssh"
382address: ":22"
383description: "SSH interactive"
384commands:
385  - regex: "^ls$"
386    handler: "Documents Images Desktop Downloads .m2 .kube .ssh .docker"
387  - regex: "^pwd$"
388    handler: "/home/"
389  - regex: "^uname -m$"
390    handler: "x86_64"
391  - regex: "^docker ps$"
392    handler: "CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES"
393  - regex: "^docker .*$"
394    handler: "Error response from daemon: dial unix docker.raw.sock: connect: connection refused"
395  - regex: "^uname$"
396    handler: "Linux"
397  - regex: "^ps$"
398    handler: "PID TTY TIME CMD\n21642 ttys000 0:00.07 /bin/dockerd"
399  - regex: "^(.+)$"
400    handler: "command not found"
401serverVersion: "OpenSSH"
402serverName: "ubuntu"
403passwordRegex: "^(root|qwerty|Smoker666)$"
404deadlineTimeoutSeconds: 60
405```
406 
407### TELNET Honeypot
408 
409TELNET honeypots provide terminal-based interaction similar to SSH, with support for both static responses and LLM integration.
410 
411#### LLM-Powered TELNET Honeypot
412 
413```yaml
414apiVersion: "v1"
415protocol: "telnet"
416address: ":23"
417description: "TELNET LLM Honeypot"
418commands:
419  - regex: "^(.+)$"
420    plugin: "LLMHoneypot"
421serverName: "router"
422passwordRegex: "^(admin|root|password|123456)$"
423deadlineTimeoutSeconds: 120
424plugin:
425   llmProvider: "openai"
426   llmModel: "gpt-4o"
427   openAISecretKey: "sk-proj-..."
428```
429 
430#### Static TELNET Honeypot
431 
432```yaml
433apiVersion: "v1"
434protocol: "telnet"
435address: ":23"
436description: "TELNET Router Simulation"
437commands:
438  - regex: "^show version$"
439    handler: "Cisco IOS Software, Version 15.1(4)M4"
440  - regex: "^show ip interface brief$"
441    handler: "Method Status Protocol\nFastEthernet0/0 192.168.1.1 YES NVRAM up up"
442  - regex: "^(.+)$"
443    handler: "% Unknown command"
444serverName: "router"
445passwordRegex: "^(admin|cisco|password)$"
446deadlineTimeoutSeconds: 60
447```
448 
449### TCP Honeypot
450 
451TCP honeypots respond with a configurable banner to any TCP connection. Useful for simulating database servers or other TCP services.
452 
453```yaml
454apiVersion: "v1"
455protocol: "tcp"
456address: ":3306"
457description: "MySQL 8.0.29"
458banner: "8.0.29"
459deadlineTimeoutSeconds: 10
460```
461 
462## Observability
463 
464### Prometheus Metrics
465 
466Beelzebub exposes Prometheus metrics at the configured endpoint (default: `:2112/metrics`). Available metrics include:
467 
468- `beelzebub_events_total` - Total number of honeypot events
469- `beelzebub_events_ssh_total` - SSH-specific events
470- `beelzebub_events_http_total` - HTTP-specific events
471- `beelzebub_events_tcp_total` - TCP-specific events
472- `beelzebub_events_telnet_total` - TELNET-specific events
473- `beelzebub_events_mcp_total` - MCP-specific events
474 
475### RabbitMQ Integration
476 
477Enable RabbitMQ tracing to publish honeypot events to a message queue:
478 
479```yaml
480core:
481  tracings:
482    rabbit-mq:
483      enabled: true
484      uri: "amqp://guest:guest@localhost:5672/"
485```
486 
487Events are published as JSON messages for downstream processing.
488 
489## Testing
490 
491### Unit Tests
492 
493```bash
494make test.unit
495```
496 
497### Integration Tests
498 
499Integration tests require external dependencies (RabbitMQ, etc.):
500 
501```bash
502make test.dependencies.start
503make test.integration
504make test.dependencies.down
505```
506 
507## Code Quality
508 
509We maintain high code quality through:
510 
511- **Automated Testing**: Unit and integration tests run on every pull request
512- **Static Analysis**: Go Report Card and CodeQL for code quality and security checks
513- **Code Coverage**: Monitored via [Codecov](https://codecov.io/gh/mariocandela/beelzebub)
514- **Continuous Integration**: GitHub Actions pipelines on every commit
515- **Code Reviews**: All contributions undergo peer review
516 
517## Contributing
518 
519The 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.
520 
521Happy hacking!
522 
523## License
524 
525Beelzebub is licensed under the [GNU GPL v3 License](LICENSE).
526 
527## Supported By
528 
529[![JetBrains logo.](https://resources.jetbrains.com/storage/products/company/brand/logos/jetbrains.svg)](https://jb.gg/OpenSourceSupport)
530 
531![gitbook logo](https://i.postimg.cc/VNQh5hnk/gitbook.png)
532