knocker

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

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

الميزات

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

عملاء Knocker

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

• Knocker-CLI أداة cli مكتوبة بلغة go مع دعم knocks في الخلفية يتم تشغيلها اختياريًا عند تغييرات ip.

• Knocker-gnome إضافة gnome مبنية على Knocker-cli.

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

مخطط التسلسل

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.
• خادم مواجه للعامة لتشغيل الحاويات (لا يجب أن يكون حتى على نفس الخادم الذي يشغل الخدمات! في وضع PROXY)
• (اختياري) تثبيت Firewalld 2.0+ وتشغيله على المضيف لتكامل الجدار الناري المتقدم.

1. التكوين:

   • أعد تسمية knocker.example.yaml إلى knocker.yaml.
   • أضف مفتاح API آمنًا وعشوائيًا واحدًا على الأقل إلى knocker.yaml؛ يحتوي المثال عمدًا على أي إعدادات افتراضية قابلة للاستخدام.
   • راجع قائمة trusted_proxies في knocker.yaml: يجب أن تحتوي فقط على عنوان (عناوين) الوكيل العكسي نفسه، وليس شبكته الفرعية. لأن knocker يثق فقط بـ X-Forwarded-For من نظير مدرج، فإن إدخال شبكة فرعية كاملة (مثل 172.16.238.0/24) يحول كل حاوية على تلك الشبكة إلى سلطة هوية -- يمكن لأي منها ادعاء أي عنوان IP للعميل، أو إدراج عناوين عشوائية في القائمة البيضاء بمفتاح عادي. لا يعين Docker عناوين IP ثابتة للحاويات افتراضيًا، لذا ثبّت الوكيل باستخدام ipv4_address / ipv6_address (انظر خدمة caddy المعلقة في docker-compose.yml) وأدرج تلك العناوين الدقيقة /32 و /128.
   • أبقِ whitelist.storage_path تحت دليل عمل التطبيق، أو /data، أو /tmp.
   • (اختياري) قم بتكوين تكامل firewalld عن طريق تعيين firewalld.enabled: true وضبط الإعدادات ذات الصلة. ملاحظة: يتطلب هذا تشغيل الحاوية كـ root.

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

   docker compose up -d
   

   سيقوم هذا بسحب صورة knocker الجاهزة وبدء خدمتي knocker و caddy.

استخدام 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 {
  request_body {
    max_size 4KB
  }
  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 المحدد في طلبات knock. تعمل هذه الميزة على مستوى الشبكة، مما يتيح لك استخدام 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+ نظرًا لاعتمادها على ميزة أولوية المنطقة. وهي متاحة في Debian 13 و Ubuntu 24.04 LTS وتوزيعات مستقرة حديثة أخرى.

لماذا FirewallD؟