knocker

नॉकर एक स्व-होस्टेड सेवा है जो आपके होमलैब के लिए वेब, CLI + GNOME और Android क्लाइंट्स के साथ HTTP आधारित "नॉक-नॉक" सिंगल-पैकेट ऑथराइज़ेशन (SPA) गेटवे प्रदान करती है। इसका उपयोग आपके रिवर्स प्रॉक्सी जैसे Caddy के लिए प्रमाणीकरण के रूप में या FirewallD एकीकरण का उपयोग करके फ़ायरवॉल स्तर पर भी किया जा सकता है। यह आपकी सेवाओं को पूरी तरह से निजी रखने की अनुमति देता है, उन्हें केवल अधिकृत IP पतों के लिए ऑन-डिमांड खोलता है।

यह होमलैब वातावरण के लिए आदर्श है जहां आप बिना किसी स्थायी VPN कनेक्शन के इंटरनेट पर सेवाओं को एक्सपोज़ करना चाहते हैं, जबकि अपने सार्वजनिक-सामना करने वाले हमले की सतह को कम करते हैं।

विशेषताएँ

• API कुंजी प्रमाणीकरण: कई, कॉन्फ़िगरेबल API कुंजियों के साथ अपने नॉक एंडपॉइंट को सुरक्षित करें।
• कॉन्फ़िगरेबल TTL: प्रत्येक API कुंजी का अपना टाइम-टू-लिव (TTL) हो सकता है, जो परिभाषित करता है कि श्वेतसूचीबद्ध IP कितने समय तक सक्रिय रहेगा।
• रिमोट श्वेतसूचीकरण: विशिष्ट व्यवस्थापक कुंजियों को किसी भी IP या CIDR रेंज को श्वेतसूचीबद्ध करने की अनुमति दें, न कि केवल अपने स्वयं के IP को।
• स्थैतिक IP/CIDR श्वेतसूचीकरण: कुछ IP पतों या रेंजों को हमेशा डायनामिक श्वेतसूची को बायपास करने दें।
• पथ-आधारित बहिष्करण: प्रमाणीकरण से विशिष्ट URL पथ (जैसे हेल्थ चेक या सार्वजनिक APIs) को पूरी तरह से बाहर करें।
• IPv6 प्रथम श्रेणी का नागरिक: श्वेतसूचीकरण, विश्वसनीय प्रॉक्सी और Docker नेटवर्किंग में IPv6 और IPv4 के लिए पूर्ण समर्थन।
• Firewalld एकीकरण: TTL के आधार पर स्वचालित रूप से समाप्त होने वाले समयबद्ध नियमों के साथ उन्नत फ़ायरवॉल नियंत्रण। बढ़ी हुई सुरक्षा के लिए firewalld रिच रूल्स का उपयोग करके डायनामिक फ़ायरवॉल नियम बनाता है। (वैकल्पिक, रूट कंटेनर एक्सेस की आवश्यकता है)

नॉकर क्लाइंट्स

• Knocker-Web स्थैतिक PWA वेब ऐप जो रीलोड पर नॉकिंग (श्वेतसूचीकरण) का समर्थन करता है
• Knocker-CLI Go में लिखा गया एक CLI जो IP परिवर्तनों द्वारा वैकल्पिक रूप से ट्रिगर किए गए पृष्ठभूमि नॉक का समर्थन करता है।
• Knocker-gnome Knocker-cli के शीर्ष पर बनाया गया एक GNOME एक्सटेंशन।
• Knocker-EXPO React EXPO में लिखा गया एक प्रायोगिक Android ऐप जो पृष्ठभूमि नॉकिंग अनुरोधों का समर्थन करता है

अनुक्रम आरेख

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-compose.yml फ़ाइल का उपयोग करके Docker कंटेनर के रूप में तैनात करने के लिए डिज़ाइन किया गया है। यह AMD64, ARMv8 और ARMv7 के समर्थन के साथ पूर्व-निर्मित Docker इमेज का उपयोग करता है

Docker इमेज टैग

नॉकर विभिन्न उपयोग मामलों के लिए विभिन्न इमेज टैग प्रदान करता है:

• 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 करें।
   • महत्वपूर्ण: knocker.yaml में डिफ़ॉल्ट API कुंजियों को अपनी स्वयं की सुरक्षित, यादृच्छिक स्ट्रिंग्स में बदलें।
   • knocker.yaml में trusted_proxies सूची की समीक्षा करें, उन्हें रिवर्स प्रॉक्सी के नेटवर्क सबनेट से मेल खाना चाहिए (docker network inspect xxx)
   • whitelist.storage_path को ऐप वर्किंग डायरेक्टरी, /data, या /tmp के अंतर्गत रखें।
   • (वैकल्पिक) firewalld.enabled: true सेट करके और संबंधित सेटिंग्स को समायोजित करके firewalld एकीकरण कॉन्फ़िगर करें। नोट: इसके लिए कंटेनर को रूट के रूप में चलाने की आवश्यकता है।

2. सेवा चलाएं:

   root@kitploit:~

   docker compose up -d
   

नॉकर को रिवर्स प्रॉक्सी के साथ उपयोग करें

नॉकर आपके रिवर्स प्रॉक्सी के लिए एक प्रमाणीकरण गेटवे के रूप में कार्य करता है। यह अनुरोधित 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
}

प्रमाणीकरण विफलताएँ

जब कोई उपयोगकर्ता श्वेतसूचीबद्ध नहीं होता है, तो Caddy का forward_auth निर्देश खाली बॉडी के साथ 401 Unauthorized प्रतिक्रिया लौटाएगा।

महत्वपूर्ण नोट: Caddy का handle_errors निर्देश forward_auth प्रतिक्रियाओं के साथ काम नहीं करता। त्रुटि प्रतिक्रिया सीधे प्रमाणीकरण सेवा (नॉकर) से आती है, न कि Caddy से, इसलिए handle_errors इन प्रतिक्रियाओं को इंटरसेप्ट या संशोधित नहीं कर सकता है।

FirewallD एकीकरण

नॉकर firewalld के माध्यम से उन्नत फ़ायरवॉल एकीकरण प्रदान करता है, जो नॉक अनुरोधों में निर्दिष्ट TTL के आधार पर स्वचालित रूप से समाप्त होने वाले डायनामिक, समय-आधारित फ़ायरवॉल नियम बनाता है। यह सुविधा नेटवर्क स्तर पर काम करती है, जिससे आप SSH या गेम सर्वर जैसी गैर-HTTP सेवाओं के लिए नॉकर का उपयोग कर सकते हैं।

अनुक्रम आरेख (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

नॉकर को ज़ोन प्राथमिकता सुविधा पर निर्भरता के कारण FirewallD 2.0+ की आवश्यकता है। यह Debian 13, Ubuntu 24.04 LTS और अन्य हालिया स्थिर वितरणों में उपलब्ध है।

FirewallD क्यों?

FirewallD को CLI इंटरफ़ेस को डेमॉन से अलग करने की क्षमता के लिए चुना गया था। यह नॉकर को सिस्टम के D-Bus सॉकेट को माउंट करके Docker कंटेनर के भीतर से firewalld को नियंत्रित करने की अनुमति देता है, और FirewallD में समयबद्ध नियमों के लिए भी समर्थन है, इसलिए नॉकर नियम TTL के अंत तक स्वचालित रूप से समाप्त हो जाते हैं।

FIREWALLD DOCKER PUBLISHED PORTS के साथ काम नहीं करेगा, अधिक जानकारी के लिए यह मुद्दा देखें

यह कैसे काम करता है

1. उच्च प्राथमिकता के साथ एक समर्पित firewalld ज़ोन बनाता है
2. अनधिकृत पहुंच को ब्लॉक करने के लिए मॉनिटर किए गए पोर्ट के लिए DROP/REJECT नियम जोड़ता है
3. श्वेतसूचीबद्ध IP के लिए गतिशील रूप से ALLOW नियम जोड़ता है जो अवरोधन नियमों को ओवरराइड करते हैं
4. firewalld के टाइमआउट तंत्र का उपयोग करके TTL के आधार पर नियमों को स्वचालित रूप से समाप्त करता है
5. whitelist.json की तुलना सक्रिय firewalld नियमों से करके स्टार्टअप पर नियमों को पुनर्प्राप्त करता है

FirewallD एकीकरण सक्षम करना

1. पूर्वापेक्षाएँ

   • होस्ट सिस्टम पर FirewallD 2.0+ स्थापित और चल रहा हो
   • D-Bus एक्सेस के लिए Docker कंटेनर को रूट के रूप में चलना चाहिए

2. कॉन्फ़िगरेशन

• knocker.yaml कॉन्फ़िगरेशन में FirewallD सक्षम करें, सेटिंग्स पहले से उदाहरण कॉन्फ़िग में उपलब्ध हैं
• 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 एकीकरण गाइड देखें।

यूज़रलैंड-प्रॉक्सी से संबंधित समस्याएं

यदि आप tailscale या अन्य IP के पीछे IP के लिए नॉकिंग सक्षम कर रहे हैं, तो userland-proxy के काम करने के तरीके के कारण आपको समस्याओं का सामना करना पड़ सकता है, आपको वास्तविक IP पते से भिन्न अनुरोध IP मिल सकता है।

यूज़रलैंड-प्रॉक्सी को अक्षम करने से यह ठीक हो जाना चाहिए, लेकिन अपने सेटअप का परीक्षण करना सुनिश्चित करें। आप होस्ट नेटवर्किंग का भी उपयोग कर सकते हैं।

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)

इस एंडपॉइंट का उपयोग Caddy के forward_auth द्वारा यह जांचने के लिए किया जाता है कि क्लाइंट का IP श्वेतसूचीबद्ध है या नहीं। यह सफलता पर 200 OK और विफलता पर 401 Unauthorized लौटाता है। X-Forwarded-For, X-Forwarded-Host, और X-Forwarded-Uri केवल तभी विश्वसनीय होते हैं जब अनुरोध server.trusted_proxies से उत्पन्न होता है।

Caddy पहले से ही प्रासंगिक X-Forwarded-* अनुरोध हेडर्स को नॉकर को अग्रेषित करता है ताकि /verify प्रमाणीकरण निर्णय ले सके।

परीक्षण

प्रोजेक्ट में एक पूर्ण परीक्षण सूट शामिल है

उपकरण

यह प्रोजेक्ट Astral के Python टूलचेन का उपयोग करता है:

• 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 के अंतर्गत एक देव वातावरण है, जिसमें caddy के साथ एकीकरण परीक्षणों के लिए bash स्क्रिप्ट और firewalld के साथ एक अलग स्क्रिप्ट है। मानक परीक्षण स्टैक dev/docker-compose.yml और dev/docker-compose.ci.yml हैं; दोनों Caddy को http://localhost:18080 और https://localhost:18443 पर एक्सपोज़ करते हैं। CI caddy परीक्षण चलाता है, लेकिन firewalld को एक विशेषाधिकार प्राप्त रनर की आवश्यकता होती है, यही कारण है कि इसे स्थानीय रूप से चलाने की आवश्यकता है और यह CI का हिस्सा नहीं है।

दस्तावेज़ीकरण

इंटरैक्टिव दस्तावेज़ीकरण एंडपॉइंट (/docs, /redoc, /openapi.json) डिफ़ॉल्ट रूप से अक्षम हैं। उन्हें एक्सपोज़ करने के लिए, knocker.yaml में निम्नलिखित सेट करें:

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

जब दस्तावेज़ीकरण अक्षम होता है (डिफ़ॉल्ट), तो नॉकर इन एंडपॉइंट्स को हटा देता है और पुरानी कलाकृतियों को रोकने के लिए पहले से उत्पन्न किसी भी स्कीमा फ़ाइल को हटा देता है।

औपचारिक API विनिर्देश और वास्तुशिल्प विकल्पों के सारांश के लिए, कृपया दस्तावेज़ीकरण देखें।

पूरी तरह से वाइब-कोडेड

नॉकर पूरी तरह से वाइब कोडेड था। प्रारंभिक कार्यान्वयन Gemini 2.5 pro के साथ किया गया था, roo code/requesty हैकथॉन में प्रदान किए गए टोकन के लिए धन्यवाद।

आगे की सुविधाएँ अधिकतर GitHub Copilot Agent (sonnet 4/later 4.5) के साथ की गई थीं, जिसमें बहुत सारे फिक्स की आवश्यकता थी, जो अधिकतर GPT-5 mini/CODEX द्वारा Roo code, Opencode और मानक Copilot एक्सटेंशन में किए गए थे।

मैंने इसके साथ अपनी पूरी कोशिश की, हमेशा परिवर्तनों की योजना बनाकर और प्रत्येक परिवर्तन के बाद सब कुछ का परीक्षण करके, लेकिन यदि आप AI-विरोधी हैं तो मैं शायद इस पर आपकी राय नहीं बदल पाऊंगा।