knocker

Knocker هي خدمة ذاتية الاستضافة توفر بوابة "طرق-طرق" (knock-knock) للترخيص أحادي الحزمة (SPA) قائمة على HTTP لبيئة Homelab الخاصة بك، مع عملاء للويب و CLI وجنوم وأندرويد. يمكن استخدامها كمصادقة للوكيل العكسي الخاص بك مثل Caddy، أو حتى على مستوى جدار الحماية باستخدام تكامل FirewallD. تتيح لك إبقاء خدماتك خاصة تمامًا، وفتحها عند الطلب فقط لعناوين IP المصرح بها.

هذا مثالي لبيئات Homelab حيث تريد كشف الخدمات للإنترنت دون اتصال VPN دائم، مع تقليل سطح الهجوم العام المواجه للجمهور.

الميزات

• مصادقة مفتاح API: قم بتأمين نقطة الطرق لديك بمفاتيح API متعددة وقابلة للتكوين.
• TTL قابل للتكوين: يمكن أن يكون لكل مفتاح API مدة صلاحية (Time-To-Live/TTL) خاصة به، تحدد المدة التي يظل فيها عنوان IP المدرج في القائمة البيضاء نشطًا.
• القائمة البيضاء عن بُعد: امنح مفاتيح إدارية محددة الإذن بإدراج أي عنوان IP أو نطاق CIDR في القائمة البيضاء، وليس عناوينهم الخاصة فقط.
• قائمة بيضاء ثابتة لعناوين IP/CIDR: اسمح دائمًا لعناوين أو نطاقات IP معينة بتجاوز القائمة البيضاء الديناميكية.
• الاستثناء المستند إلى المسار: استثنِ مسارات URL محددة (مثل فحوصات الصحة أو واجهات برمجة التطبيقات العامة) من المصادقة تمامًا.
• IPv6 مواطن من الدرجة الأولى: دعم كامل لـ IPv6 و IPv4 في القوائم البيضاء والوكلاء الموثوقين وشبكات Docker.
• تكامل Firewalld: تحكم متقدم في جدار الحماية بقواعد مؤقتة تنتهي تلقائيًا استنادًا إلى TTL. ينشئ قواعد ديناميكية لجدار الحماية باستخدام قواعد firewalld الغنية (rich rules) لتعزيز الأمان. (اختياري، يتطلب وصول الجذر للحاوية)

عملاء Knocker

• Knocker-Web تطبيق ويب PWA ثابت يدعم الطرق (الإدراج في القائمة البيضاء) عند إعادة التحميل

• Knocker-CLI أداة CLI مكتوبة بلغة Go مع دعم للطرق الخلفية التي تُفعَّل اختياريًا عند تغيير عنوان IP.

• Knocker-gnome امتداد جنوم مبني على Knocker-cli.

• Knocker-EXPO تطبيق أندرويد تجريبي مكتوب بـ React EXPO مع دعم لطلبات الطرق الخلفية

مخطط التسلسل

sequenceDiagram
    participant User
    participant Caddy as Reverse Proxy (Caddy)
    participant Knocker
    participant Service as Protected Service

    User->>Caddy: HTTP request to protected service
    Caddy->>Knocker: GET /verify (copies X-Forwarded-For)
    Knocker-->>Knocker: check always_allowed_ips / excluded_paths / whitelist
    alt IP whitelisted
        Knocker-->>Caddy: 200 OK (empty body)
        Caddy->>Service: forward request
        Service-->>Caddy: 200 OK
        Caddy-->>User: 200 OK
    else IP not whitelisted
        Knocker-->>Caddy: 401 Unauthorized (empty body)
        Caddy-->>User: 401 Unauthorized
    end

    Note over User,Knocker: Performing a "knock" (to add whitelist entry)
    User->>Knocker: POST /knock (X-Api-Key, optional ip_address, ttl)
    Knocker->>Knocker: validate API key, determine client IP
    Knocker->>Knocker: update whitelist.json with expiry
    Knocker-->>User: 200 OK (whitelisted_entry, expires_at, expires_in_seconds)

النشر

صُمم هذا المشروع ليُنشر كحاوية Docker باستخدام ملف docker-compose.yml المرفق. يستخدم صور Docker المجمعة مسبقًا مع دعم لـ AMD64 و ARMv8 و ARMv7

علامات صور Docker

يوفر Knocker علامات صور مختلفة لحالات استخدام مختلفة:

• latest أحدث إصدار مستقر (موصى به للإنتاج)
• v1.2.3 علامات إصدارات محددة (إصدارات مثبتة)
• main فرع التطوير (تحديثات مستمرة، قد يكون غير مستقر)

السجلات

• oci.fariszr.com (quay.io)
• ghcr.io

1. المتطلبات الأساسية

• تثبيت Docker و Docker Compose.
• خادم مواجه للجمهور لتشغيل الحاويات (لا يلزم حتى أن يكون على نفس الخادم الذي تشغّل عليه الخدمات! في وضع الوكيل)
• (اختياري) Firewalld 2.0+ مثبت ويعمل على المضيف لتكامل متقدم مع جدار الحماية.

1. الإعداد:

   • أعد تسمية knocker.example.yaml إلى knocker.yaml.
   • الأهم: غيّر مفاتيح API الافتراضية في knocker.yaml إلى سلاسل عشوائية آمنة خاصة بك.
   • راجع قائمة trusted_proxies في knocker.yaml، يجب أن تطابق الشبكة الفرعية لشبكة الوكيل العكسي (docker network inspect xxx)
   • أبقِ whitelist.storage_path داخل دليل عمل التطبيق، أو /data، أو /tmp.
   • (اختياري) قم بتكوين تكامل firewalld عن طريق تعيين firewalld.enabled: true وضبط الإعدادات ذات الصلة. ملاحظة: يتطلب ذلك تشغيل الحاوية بصلاحيات الجذر.

2. تشغيل الخدمة:

   root@kitploit:~

   docker compose up -d
   

   سيقوم هذا بسحب صورة knocker المجمعة مسبقًا وبدء كل من خدمتي و .

استخدام Knocker مع وكيل عكسي

يعمل Knocker كبوابة مصادقة للوكيل العكسي الخاص بك. يوفر مسار تحقق (verify) للتحقق مما إذا كان عنوان IP الطالب مدرجًا في القائمة البيضاء أم لا، وإذا لم يكن كذلك، فسيرد برمز 401 وسيرفض الوكيل العكسي الاتصال.

Caddy

لدى Caddy توجيه forward_auth للتحقق من الاتصالات باستخدام مسار مصادقة.

1. تعريف مقتطف قابل لإعادة الاستخدام: من أفضل الممارسات تعريف مقتطف في Caddyfile الخاص بك لفحص المصادقة.

2. حماية خدماتك: استورد المقتطف لأي خدمة تريد حمايتها.

مثال Caddyfile:

# Caddyfile

# Define a reusable snippet for the knock-knock check.
# It points to the knocker service using Docker's internal DNS.
(knocker_auth) {
  forward_auth knocker:8000 {
    uri /verify
  }
}

# The public endpoint for performing the knock.
# Make sure this domain points to your Caddy server's IP.
knock.your-domain.com {
  reverse_proxy knocker:8000
}

# An example protected service.
jellyfin.your-domain.com {
  import knocker_auth  # Apply the forward_auth check
  reverse_proxy jellyfin_service_name:8096
}

حالات فشل الترخيص

عندما لا يكون المستخدم مدرجًا في القائمة البيضاء، سيعيد توجيه forward_auth في Caddy استجابة 401 Unauthorized بجسم فارغ.

ملاحظة مهمة: توجيه handle_errors في Caddy لا يعمل مع استجابات forward_auth. تأتي استجابة الخطأ مباشرة من خدمة المصادقة (knocker)، وليس من Caddy نفسه، لذلك لا يمكن لـ handle_errors اعتراض هذه الاستجابات أو تعديلها.

تكامل FirewallD

يوفر Knocker تكاملًا متقدمًا مع جدار الحماية عبر firewalld، حيث ينشئ قواعد ديناميكية ومؤقتة لجدار الحماية تنتهي تلقائيًا استنادًا إلى TTL المحدد في طلبات الطرق. تعمل هذه الميزة على مستوى الشبكة، مما يتيح لك استخدام knocker للخدمات غير المعتمدة على HTTP مثل SSH أو خوادم الألعاب.

مخطط التسلسل (firewalld)

sequenceDiagram
    participant Client as User
    participant Firewall as Firewalld (knocker zone)
    participant Knocker
    participant Service as Protected Service (port 22)

    Note over Client,Firewall: Initial state — monitored port is blocked by default
    Client->>Firewall: TCP SYN to Service:22
    Firewall-->>Client: DROP (no response)

    Note over Client,Knocker: User performs a knock to whitelist their IP
    Client->>Knocker: POST /knock (X-Api-Key, optional ip_address, ttl)
    Knocker->>Knocker: validate API key & determine client IP
    Knocker->>Firewall: add rich accept rule for client IP on port 22 with timeout
    Firewall-->>Knocker: success

    Note over Firewall,Client: New rule overrides DROP due to higher priority
    Client->>Firewall: TCP SYN to Service:22
    Firewall->>Service: forward packet
    Service-->>Client: TCP SYN-ACK (connection established)
    Knocker->>Knocker: update whitelist.json with expiry

يتطلب Knocker إصدار FirewallD 2.0+ بسبب الاعتماد على ميزة أولوية المنطقة (zone priority). وهو متوفر في Debian 13 و Ubuntu 24.04 LTS وغيرها من التوزيعات المستقرة الحديثة.

لماذا FirewallD؟

تم اختيار FirewallD لقدرته على فصل واجهة سطر الأوامر (CLI) عن البرنامج الخفي (daemon). يتيح ذلك لـ Knocker التحكم في firewalld من داخل حاوية Docker عن طريق تركيب مقبس D-Bus الخاص بالنظام، كما يدعم FirewallD القواعد المؤقتة، لذا تنتهي قواعد knocker تلقائيًا عند انتهاء TTL.

لن يعمل FIREWALLD مع المنافذ المنشورة عبر Docker (PUBLISHED PORTS)، راجع هذه المشكلة لمزيد من التفاصيل.

كيف يعمل

1. ينشئ منطقة firewalld مخصصة بأولوية عالية
2. يضيف قواعد DROP/REJECT للمنافذ المراقبة لمنع الوصول غير المصرح به
3. يضيف ديناميكيًا قواعد ALLOW لعناوين IP المدرجة في القائمة البيضاء تتجاوز قواعد الحظر
4. تنتهي القواعد تلقائيًا استنادًا إلى TTL باستخدام آلية المهلة (timeout) في firewalld
5. يستعيد القواعد عند بدء التشغيل بمقارنة whitelist.json بقواعد firewalld النشطة

تفعيل تكامل FirewallD

1. المتطلبات الأساسية

   • FirewallD 2.0+ مثبت ويعمل على النظام المضيف
   • يجب تشغيل حاوية Docker بصلاحيات الجذر للوصول إلى D-Bus

2. الإعداد

• فعّل FirewallD في إعدادات knocker.yaml، الإعدادات متاحة بالفعل في مثال الإعداد
• ثبّت مقبس Dbus في حاوية Docker وتأكد من تشغيلها بصلاحيات الجذر، الإدخالات المطلوبة موجودة كتعليقات في ملف docker-compose.yml.

الاختبار واستكشاف الأخطاء وإصلاحها

راقب القواعد النشطة:

# Check knocker zone
firewall-cmd --zone=knocker --list-all

# View rich rules
firewall-cmd --zone=knocker --list-rich-rules

# Monitor rule changes
journalctl -u firewalld -f

للحصول على معلومات مفصلة حول الإعداد والبنية واستكشاف الأخطاء وإصلاحها، راجع دليل تكامل FirewallD الكامل.

المشكلات المتعلقة بـ Userland-proxy

إذا كنت تفعّل الطرق لعناوين IP خلف tailscale أو عناوين IP أخرى، فقد تواجه مشكلات بسبب طريقة عمل userland-proxy، فقد تظهر لك عنوان IP للطلب مختلف عن العنوان الفعلي.

يجب أن يؤدي تعطيل Userland-proxy إلى إصلاح ذلك، ولكن تأكد من اختبار الإعداد لديك. يمكنك أيضًا استخدام شبكة المضيف (host networking).

استخدام API

/knock (POST)

يتحقق هذا المسار من صحة مفتاح API ويضيف عنوان IP إلى القائمة البيضاء.

• الترويسات:

  • X-Api-Key: مفتاح API السري الخاص بك.

• النص (اختياري):

  • لإضافة عنوان IP/CIDR عن بُعد إلى القائمة البيضاء (يتطلب allow_remote_whitelist: true):
    root@kitploit:~

    {"ip_address": "YOUR_TARGET_IP_OR_CIDR"}
    

• مثال (إضافة عنوان IP الخاص بك إلى القائمة البيضاء):

  root@kitploit:~

  curl -i -H "X-Api-Key: YOUR_SECRET_KEY" https://knock.your-domain.com/knock
  

• استجابة النجاح (200 OK):

  root@kitploit:~

  {
    "whitelisted_entry": "1.2.3.4",
    "expires_at": 1672534800,
    "expires_in_seconds": 3600
  }
  

/verify (GET)

يُستخدم هذا المسار من قبل forward_auth في Caddy للتحقق مما إذا كان عنوان IP الخاص بالعميل مدرجًا في القائمة البيضاء. يُرجع 200 OK عند النجاح و 401 Unauthorized عند الفشل. تُوثق ترويسات X-Forwarded-For و X-Forwarded-Host و X-Forwarded-Uri فقط عندما يصدر الطلب من server.trusted_proxies.

يقوم Caddy بالفعل بإعادة توجيه ترويسات الطلب X-Forwarded-* ذات الصلة إلى Knocker ليتمكن /verify من اتخاذ قرار المصادقة.

الاختبارات

يتضمن المشروع مجموعة اختبارات كاملة

الأدوات

يستخدم هذا المشروع مجموعة أدوات Python من Astral:

• uv لإدارة التبعيات والبيئات وتنفيذ الأوامر
• ruff للفحص والتنسيق
• ty لفحص الأنواع

اختبارات الوحدة

لتشغيل الاختبارات محليًا:

1. تثبيت uv:

   root@kitploit:~

   curl -LsSf https://astral.sh/uv/install.sh | sh
   

2. مزامنة بيئة المشروع:

   root@kitploit:~

   uv sync --all-groups
   

3. تشغيل الفحوصات:

   root@kitploit:~

   uv run pytest
   uv run --group lint ruff check .
   uv run --group lint ruff format --check .
   uv run --group type ty check
   

اختبارات التكامل

توجد بيئة تطوير داخل dev، مع نصوص bash لاختبارات التكامل مع caddy ونص منفصل مع firewalld. مجموعات الاختبار القياسية هي dev/docker-compose.yml و dev/docker-compose.ci.yml؛ وكلاهما يعرض Caddy على http://localhost:18080 و https://localhost:18443. تشغّل CI اختبارات caddy، لكن firewalld يتطلب مشغلًا بصلاحيات مميزة (privileged runner)، ولهذا يجب تشغيله محليًا ولا يُعد جزءًا من CI.

التوثيق

مسارات التوثيق التفاعلية (/docs, /redoc, /openapi.json) معطلة افتراضيًا. لكشفها، عيّن ما يلي في knocker.yaml:

documentation:
  enabled: true
  openapi_output_path: "openapi.json"

عندما يكون التوثيق معطلًا (الوضع الافتراضي)، يزيل Knocker هذه المسارات ويحذف أي ملف مخطط (schema) تم إنشاؤه مسبقًا لمنع بقاء قطع أثرية قديمة.

للحصول على مواصفات API رسمية وملخص للخيارات المعمارية، يرجى مراجعة التوثيق.

مُبرمَج بالكامل بأسلوب Vibe Coding

تمت برمجة Knocker بالكامل بأسلوب Vibe Coding. تم التنفيذ الأولي باستخدام Gemini 2.5 pro، بفضل الرموز (tokens) المقدمة في هاكاثون roo code/requesty.

أما الميزات الإضافية فقد أُنجزت في الغالب باستخدام GitHub copilot Agent (sonnet 4/ثم 4.5)، الأمر الذي تطلب الكثير من الإصلاحات، نُفذت في الغالب بواسطة GPT-5 mini/CODEX في Roo code و Opencode وامتداد Copilot القياسي.

بذلت قصارى جهدي في هذا، إذ كنت أخطط دائمًا للتغييرات وأختبر كل شيء بعد كل تغيير، ولكن إذا كنت مناهضًا للذكاء الاصطناعي، فربما لن أتمكن من تغيير رأيك في هذا.