Beelzebub

إطار عمل تشغيلي للخداع

Beelzebub هو إطار عمل خداع مفتوح المصدر ينشر خدمات شرك تكيفية مدعومة بنماذج اللغات الكبيرة (LLM) عبر بروتوكولات SSH وHTTP وTCP وTELNET وMCP. يتجاوز مصائد العسل السلبية من خلال إشراك المهاجمين بنشاط في تفاعلات واقعية، وجمع استخبارات تهديدات عالية الدقة، واكتشاف هجمات حقن التعليمات الموجهة لوكلاء الذكاء الاصطناعي.

جدول المحتويات

• Beelzebub
  • جدول المحتويات
  • الميزات الرئيسية
  • عرض خداع LLM
  • بدء سريع
    • المثبّت
    • محلي (Go)
    • Docker
    • باستخدام Helm (Kubernetes)
  • مرجع CLI
    • beelzebub run
    • beelzebub validate
    • beelzebub plugin
    • beelzebub version
  • نظام الإضافات
    • الواجهات
    • كتابة إضافة
    • تثبيت الإضافات الخارجية
  • المراقبة
    • مقاييس Prometheus
    • تكامل RabbitMQ
  • الاختبار
  • جودة الكود
  • الترخيص
  • المساهمة
  • مرجع الإعدادات
    • الإعدادات الأساسية
    • إعدادات الخدمة
  • خدمات الخداع
    • خدمة خداع MCP
      • كيف تعمل

الميزات الرئيسية

• محرك خداع تكيفي: تكامل مع نماذج اللغات الكبيرة (OpenAI، Ollama) يولّد استجابات دقيقة سياقيًا في الوقت الفعلي، مما يُبقي المهاجمين منشغلين لفترة كافية لجمع TTPs قابلة للتنفيذ
• تعريف خدمات منخفض الكود: إعدادات قائمة على YAML مع مطابقة أوامر regex — لا حاجة لكتابة كود مخصص لنشر خدمة شرك جديدة
• تغطية متعددة البروتوكولات: SSH وHTTP وTCP وTELNET وMCP من أهداف البنية التحتية إلى أسطح هجوم وكلاء الذكاء الاصطناعي
• نظام إضافات قابل للتوسيع: نفّذ واجهة CommandPlugin أو HTTPPlugin وسجّلها عبر init() دون الحاجة إلى تغييرات في النواة
• حزمة مراقبة كاملة: مقاييس Prometheus، ودفق أحداث RabbitMQ
• بيئة تشغيل جاهزة للإنتاج: Docker وKubernetes (Helm) وإيقاف تشغيل آمن وحدود ذاكرة لكل خدمة

عرض خداع LLM

بدء سريع

المثبّت```bash

./install.sh # asks local or Docker, checks prerequisites, and starts it

غير تفاعلي: `./install.sh --local` أو `./install.sh --docker`. استخدم
`./install.sh --local --no-run` للتثبيت والبناء دون تشغيل بيئة التشغيل
المحلية. على المضيفين غير الجذر، لا يبدأ التثبيت المحلي تلقائيًا عندما يتضمن
التكوين الافتراضي منافذ مميزة.

### محلي (Go)```bash
make start     # installs any declared plugins, compiles them in, and runs

Docker```bash

make docker # builds an image with declared plugins baked in, then runs it

### استخدام Helm (Kubernetes)```bash
helm install beelzebub ./beelzebub-chart
# Upgrade:
helm upgrade beelzebub ./beelzebub-chart

مرجع CLI

يأتي Beelzebub مع CLI منظم. قم بتشغيل beelzebub --help لعرض جميع الأوامر المتاحة.

beelzebub run

تشغيل جميع خدمات الخداع المُعدّة.```bash beelzebub run [flags]

Flags: -c, --conf-core string Path to core configuration file (default "./configurations/beelzebub.yaml") -s, --conf-services string Path to services configuration directory (default "./configurations/services/") -m, --mem-limit-mib int Memory limit in MiB, -1 to disable (default 100)

### `beelzebub validate`

تحليل جميع ملفات التكوين والتحقق منها دون تشغيل أي خدمات. مفيد في خطوط أنابيب CI. راجع [التحقق من التكوين](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/docs/configuration-validation.md) للاطلاع على بنية التحقق ومرجع القواعد.```bash
beelzebub validate --conf-core ./configurations/beelzebub.yaml --conf-services ./configurations/services/

beelzebub plugin

قم بتثبيت وسرد وإزالة الإضافات التي يتم جلبها من GitHub. راجع نظام الإضافات.```bash beelzebub plugin install github.com/your-org/beelzebub-myplugin beelzebub plugin list beelzebub plugin remove myplugin

### `beelzebub version`

طباعة الإصدار، SHA للالتزام، تاريخ البناء، ومعلومات وقت تشغيل Go.```bash
beelzebub version

نظام الإضافات

يكشف Beelzebub عن SDK عام مستقر في pkg/plugin لتوسيع بيئة التشغيل الخادعة دون تعديل الكود الأساسي.

الواجهات```go

// CommandPlugin generates text responses for SSH, TCP, TELNET, and HTTP services. type CommandPlugin interface { Metadata() Metadata Execute(ctx context.Context, req CommandRequest) (string, error) }

// HTTPPlugin generates full HTTP responses with status code, headers, and body. type HTTPPlugin interface { Metadata() Metadata HandleHTTP(r *http.Request) HTTPResponse }

### كتابة إضافة```go
package myplugin

import (
    "context"
    "github.com/beelzebub-labs/beelzebub/v3/pkg/plugin"
)

type MyPlugin struct{}

func (p *MyPlugin) Metadata() plugin.Metadata {
    return plugin.Metadata{
        Name:        "MyPlugin",
        Description: "Custom deception response generator",
        Version:     "1.0.0",
        Author:      "your-name",
    }
}

func (p *MyPlugin) Execute(_ context.Context, req plugin.CommandRequest) (string, error) {
    return "simulated response to: " + req.Command, nil
}

func init() {
    plugin.Register(&MyPlugin{})
}

تثبيت الإضافات الخارجية```bash

Declare plugins in configurations/plugins.yaml, or:

beelzebub plugin install github.com/your-org/myplugin # also appends to the config

make start # local: install declared plugins → build → run (needs Go) make docker # docker: image with plugins baked in → run (needs Docker)

| الأمر | الوظيفة |
|---|---|
| `plugin install <link>` | جلب إضافة، وتوصيلها، وإعادة البناء؛ كما يضيفها إلى `configurations/plugins.yaml` |
| `plugin install` | تثبيت كل ما هو مُصرَّح به في `configurations/plugins.yaml` |
| `plugin list` | عرض الإضافات المثبتة مقارنةً بما هو مُضمَّن في الملف الثنائي |
| `plugin update [name]` | إعادة الجلب عند المرجع المصرَّح به وإعادة تثبيت الالتزام |
| `plugin remove <name>` | إزالة إضافة من `configurations/plugins.yaml`، وفصل توصيلها، وطباعة خطوة إعادة البناء |

يتم تكوين مصادر إضافات النشر في `configurations/plugins.yaml`:```yaml
plugins:
  - source: github.com/your-org/myplugin
  - source: github.com/your-org/[email protected]

يمكن أن يكون إعداد وقت التشغيل المستقبلي لكل إضافة تحت configurations/plugins/ كملف YAML واحد لكل إضافة.

يجب أن يتضمّن كل مستودع إضافة ملف plugins.yaml كبيان تعريف وأن يسجّل نفسه في init() (انظر كتابة إضافة):```yaml name: myplugin version: 1.0.0 module: github.com/your-org/myplugin # must match its go.mod entrypoint: . # package that calls plugin.Register (default ".") min-core-version: v3.8.0 # optional dependencies: # optional metadata; Go dependencies still come from go.mod

• github.com/your-org/[email protected]

يتم تجميع الإضافات المثبتة في ملف Beelzebub الثنائي وتعمل في نفس عملية بيئة التشغيل. قم بتثبيت الإضافات فقط من المستودعات التي تثق بها.

## المراقبة

### مقاييس بروميثيوس

يكشف Beelzebub عن مقاييس بروميثيوس عند نقطة النهاية المهيأة (الافتراضي: `:2112/metrics`):

| Metric | الوصف |
|--------|-------------|
| `beelzebub_events_total` | إجمالي أحداث الخداع عبر جميع الخدمات |
| `beelzebub_events_ssh_total` | أحداث SSH |
| `beelzebub_events_http_total` | أحداث HTTP |
| `beelzebub_events_tcp_total` | أحداث TCP |
| `beelzebub_events_telnet_total` | أحداث TELNET |
| `beelzebub_events_mcp_total` | أحداث MCP |

### تكامل RabbitMQ

قم بنشر جميع أحداث الخداع إلى قائمة انتظار الرسائل لتكامل SIEM النهائي:```yaml
core:
  tracings:
    rabbit-mq:
      enabled: true
      uri: "amqp://guest:guest@localhost:5672/"

يتم نشر الأحداث كـ JSON منظم إلى قائمة event.

اختبار```bash

Unit tests

make test.unit

Integration tests (requires Docker)

make test.dependencies.start make test.integration make test.dependencies.down

Validate configuration without starting services

beelzebub validate

## جودة الكود

- **CI**: GitHub Actions على كل commit و pull request
- **التحليل الثابت**: CodeQL و Go Report Card
- **التغطية**: تُراقب عبر [Codecov](https://codecov.io/gh/beelzebub-labs/beelzebub)
- **مراجعة الكود**: تخضع جميع المساهمات لمراجعة الأقران

## الترخيص

Beelzebub مرخّص بموجب [رخصة GNU GPL v3](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/LICENSE).

## المساهمة

يرحّب فريق Beelzebub بالمساهمات والمشاركة في المشروع. سواء كنت ترغب في الإبلاغ عن أخطاء أو المساهمة في ميزات جديدة أو كان لديك أي أسئلة، يرجى الرجوع إلى [دليل المساهمين](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/CONTRIBUTING.md) للحصول على معلومات مفصّلة. نشجّع جميع المشاركين والمشرفين على الالتزام بـ [مدونة قواعد السلوك](https://github.com/beelzebub-labs/beelzebub/blob/HEAD/CODE_OF_CONDUCT.md) وتعزيز مجتمع داعم ومحترم.

استمتع بالبرمجة!

## مرجع الإعدادات

يستخدم Beelzebub نظام إعدادات من مستويين:

1. **الإعداد الأساسي** (`beelzebub.yaml`) — الإعدادات العامة: التسجيل، التتبّع، Prometheus
2. **إعدادات الخدمات** (`services/*.yaml`) — ملف واحد لكل خدمة خادعة

### الإعداد الأساسي```yaml
core:
  logging:
    debug: false
    debugReportCaller: false
    logDisableTimestamp: true
    logsPath: ./logs
  tracings:
    rabbit-mq:
      enabled: false
      uri: "amqp://guest:guest@localhost:5672/"
  prometheus:
    path: "/metrics"
    port: ":2112"

تُدعم تجاوزات متغيرات البيئة لجميع الحقول (مثل BEELZEBUB_RABBITMQ_ENABLED). يمكن أيضًا توفير إعدادات الخدمات بالكامل عبر BEELZEBUB_SERVICES_CONFIG كمصفوفة JSON.

تكوين الخدمة

يتم تعريف كل خدمة خداع في ملف YAML منفصل داخل دليل services/. يحدد حقل protocol محرك الخداع المستخدم. تستخدم الأوامر regex لمطابقة الطلبات، وإما handler ثابت أو مرجع plugin للاستجابات الديناميكية.

عند استخدام إضافة LLMHoneypot، يُنصح بشدة باستخدام قواعد حماية (guardrails) لمنع تجاوز نموذج LLM أو التلاعب به بطرق قد تعرض honeypot للخطر. راجع توثيق إضافة LLMHoneypot للتفاصيل.

خدمات الخداع

خدمة خداع MCP

تكشف خدمات خداع MCP (بروتوكول سياق النموذج) عن أدوات شرك مصممة لاكتشاف هجمات حقن الأوامر (prompt injection) الموجهة إلى الوكلاء المدعومين بنماذج LLM.

كيف يعمل

يتم تسجيل الأداة الشِراك في قائمة أدوات الوكيل، لكن لا ينبغي أبدًا استدعاؤها أثناء التشغيل العادي. أي استدعاء يشير إلى أن هجوم حقن الأوامر نجح في تجاوز قواعد حماية الوكيل. وهذا يوفر:

• كشف تجاوز قواعد الحماية في الوقت الفعلي تنبيه فوري عندما يُقنع المهاجم الوكيل باستدعاء أداة مقيدة
• جمع أوامر الهجوم الأصلية يسجل كل تفعيل للأمر الضار الدقيق المستخدم
• مقاييس قابلة للقياس لسطح الهجوم تتبع HAR وTPR وMTP بمرور الوقت

mcp-8000.yaml:```yaml apiVersion: "v1" protocol: "mcp" address: ":8000" description: "MCP Honeypot" tools:

• name: "tool:user-account-manager" description: "Tool for querying and modifying user account details. Requires administrator privileges." params:
  • name: "user_id" description: "The ID of the user account to manage."
  • name: "action" description: "The action to perform on the user account, possible values are: get_details, reset_password, deactivate_account" handler: | { "tool_id": "tool:user-account-manager", "status": "completed", "output": { "message": "Tool 'tool:user-account-manager' executed successfully. Results are pending internal processing and will be logged.", "result": { "operation_status": "success", "details": "email: [email protected], role: admin, last-login: 02/07/2025" } } }
• name: "tool:system-log" description: "Tool for querying system logs. Requires administrator privileges." params:
  • name: "filter" description: "The input used to filter the logs." handler: | { "tool_id": "tool:system-log", "status": "completed", "output": { "message": "Tool 'tool:system-log' executed successfully.", "result": { "operation_status": "success", "details": "Info: email: [email protected], last-login: 02/07/2025" } } }

يمكن الوصول إليه عبر `http://beelzebub:port/mcp` (Streamable HTTP transport).

### خدمة الخداع HTTP

تستجيب خدمات الخداع HTTP لطلبات الويب باستجابات قابلة للتكوين بناءً على مطابقة أنماط URL. وتدعم TLS والمعالجات الثابتة والاستجابات المدعومة بـ LLM ومولّد المتاهة اللانهائي.

**محاكاة ووردبريس** (`http-80.yaml`):```yaml
apiVersion: "v1"
protocol: "http"
address: ":80"
description: "Wordpress 6.0"
commands:
  - regex: "^(/index.php|/index.html|/)$"
    handler: |
      <html><header><title>Wordpress 6 test page</title></header>
      <body><h1>Hello from Wordpress</h1></body></html>
    headers:
      - "Content-Type: text/html"
      - "Server: Apache/2.4.53 (Debian)"
      - "X-Powered-By: PHP/7.4.29"
    statusCode: 200
  - regex: "^(/wp-login.php|/wp-admin)$"
    handler: |
      <html><body>
        <form method="post">
          <input type="text" name="uname" placeholder="Username" required>
          <input type="password" name="psw" placeholder="Password" required>
          <button type="submit">Login</button>
        </form>
      </body></html>
    headers:
      - "Content-Type: text/html"
      - "Server: Apache/2.4.53 (Debian)"
    statusCode: 200
  - regex: "^.*$"
    handler: "<html><body><h1>Not found!</h1></body></html>"
    headers:
      - "Content-Type: text/html"
    statusCode: 404

LLM-powered HTTP service أضف fallbackCommand مع plugin: LLMHoneypot لتوليد استجابات ديناميكية لأي طلب غير مطابق.

Infinite maze generator استخدم plugin: MazeHoneypot لنشر قائمة دليل بأسلوب Apache تتوسع بلا حدود، مما يحاصر الماسحات الضوئية والزواحف الآلية.

خدمة خداع SSH

تدعم خدمات خداع SSH كلاً من استجابات الأوامر الثابتة والجلسات التفاعلية المدعومة بـ LLM مع سجل محادثة لكل جلسة.

SSH مدعوم بـ LLM (OpenAI):```yaml apiVersion: "v1" protocol: "ssh" address: ":2222" description: "SSH interactive GPT-4o" commands:

• regex: "^(.+)$" plugin: "LLMHoneypot" serverVersion: "OpenSSH" serverName: "ubuntu" passwordRegex: "^(root|qwerty|Smoker666|123456|jenkins|minecraft|sinus|alex|postgres|Ly123456)$" deadlineTimeoutSeconds: 60 plugin: llmProvider: "openai" llmModel: "gpt-4o" openAISecretKey: "sk-proj-1234"

**SSH مدعوم بـ LLM** (Ollama محلي):```yaml
apiVersion: "v1"
protocol: "ssh"
address: ":2222"
description: "SSH Ollama Llama3"
commands:
  - regex: "^(.+)$"
    plugin: "LLMHoneypot"
serverVersion: "OpenSSH"
serverName: "ubuntu"
passwordRegex: "^(root|qwerty|123456)$"
deadlineTimeoutSeconds: 60
plugin:
  llmProvider: "ollama"
  llmModel: "codellama:7b"
  host: "http://localhost:11434/api/chat"

SSH الثابت:```yaml apiVersion: "v1" protocol: "ssh" address: ":22" description: "SSH interactive" commands:

• regex: "^ls$" handler: "Documents Images Desktop Downloads .m2 .kube .ssh .docker"
• regex: "^pwd$" handler: "/home/user"
• regex: "^uname -m$" handler: "x86_64"
• regex: "^docker ps$" handler: "CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES"
• regex: "^(.+)$" handler: "command not found" serverVersion: "OpenSSH" serverName: "ubuntu" passwordRegex: "^(root|qwerty|Smoker666)$" deadlineTimeoutSeconds: 60

### خدمة خداع TELNET

تحاكي خدمات خداع TELNET الأجهزة القائمة على الطرفية (أجهزة التوجيه، والمبدلات، والأنظمة القديمة) مع تدفق مصادقة كامل وتكامل مع LLM.

**TELNET المدعوم بـ LLM**:```yaml
apiVersion: "v1"
protocol: "telnet"
address: ":23"
description: "TELNET LLM"
commands:
  - regex: "^(.+)$"
    plugin: "LLMHoneypot"
serverName: "router"
passwordRegex: "^(admin|root|password|123456)$"
deadlineTimeoutSeconds: 120
plugin:
  llmProvider: "openai"
  llmModel: "gpt-4o"
  openAISecretKey: "sk-1234"

محاكاة Cisco IOS الثابتة:```yaml apiVersion: "v1" protocol: "telnet" address: ":23" description: "Cisco IOS Router" commands:

• regex: "^show version$" handler: "Cisco IOS Software, Version 15.1(4)M4"
• regex: "^show ip interface brief$" handler: "Interface IP-Address Method Status Protocol\nFastEthernet0/0 192.168.1.1 YES NVRAM up up"
• regex: "^(.+)$" handler: "% Unknown command" serverName: "router" passwordRegex: "^(admin|cisco|password)$" deadlineTimeoutSeconds: 60

### خدمة خداع TCP

تغطي خدمات خداع TCP البروتوكولات الثنائية والنصية: قواعد البيانات، ووسطاء الرسائل، وخدمات الدليل، والوصول عن بُعد، وغيرها. تدعم وضع الشعار فقط، والمطابقة التفاعلية للتعبيرات النمطية، وتكامل LLM.

**Redis**:```yaml
apiVersion: "v1"
protocol: "tcp"
address: ":6379"
description: "Redis 7.0.12"
commands:
  - regex: "^PING"
    handler: "+PONG\r\n"
  - regex: "^AUTH"
    handler: "-ERR Client sent AUTH, but no password is set\r\n"
  - regex: "^INFO"
    handler: "$180\r\n# Server\r\nredis_version:7.0.12\r\nos:Linux 5.15.0-76-generic x86_64\r\ntcp_port:6379\r\n\r\n"
  - regex: "^(.+)$"
    handler: "-ERR unknown command\r\n"
deadlineTimeoutSeconds: 60
serverName: "redis-prod-01"

LDAP / Active Directory:```yaml apiVersion: "v1" protocol: "tcp" address: ":389" description: "Active Directory LDAP Domain Controller" banner: "0\x84\x00\x00\x00\x10\x02\x01\x01\x61\x84\x00\x00\x00\x07\x0a\x01\x00\x04\x00\x04\x00" commands:

• regex: "\x30.*\x60" handler: "0\x84\x00\x00\x00\x10\x02\x01\x01\x61\x84\x00\x00\x00\x07\x0a\x01\x00\x04\x00\x04\x00"
• regex: "\x30.*\x63" handler: "0\x84\x00\x00\x00\x2a\x02\x01\x02\x65\x84\x00\x00\x00\x21\x04\x00\x30\x84\x00\x00\x00\x00" deadlineTimeoutSeconds: 30 serverName: "DC01.corp.local"

**PostgreSQL مدعوم بـ LLM**:```yaml
apiVersion: "v1"
protocol: "tcp"
address: ":5432"
description: "PostgreSQL 15.3"
commands:
  - regex: "^(.+)$"
    plugin: "LLMHoneypot"
deadlineTimeoutSeconds: 120
serverName: "pg-master"
plugin:
  llmProvider: "openai"
  llmModel: "gpt-4o"
  openAISecretKey: "sk-proj-..."
  prompt: "You are simulating a PostgreSQL 15.3 server. Respond to incoming TCP data as a PostgreSQL server would."

تتوفر أمثلة إضافية للتكوينات في configurations/services/ لكل من Memcached وMS-SQL وSMB وRDP وVNC وMQTT.

بدعم من