knocker

Knocker एक self-hosted सेवा है जो आपके Homelab के लिए web, cli + gnome और android क्लाइंट्स के साथ HTTP आधारित "knock-knock" single-packet authorization (SPA) गेटवे प्रदान करती है। इसका उपयोग आपके reverse proxy जैसे Caddy के लिए authentication के रूप में, या FirewallD integration का उपयोग करके firewall स्तर पर भी किया जा सकता है। यह आपको अपनी सेवाओं को पूरी तरह से निजी रखने की अनुमति देता है, उन्हें केवल अधिकृत IP addresses के लिए on-demand खोलता है।

यह homelab वातावरणों के लिए आदर्श है जहाँ आप बिना किसी स्थायी VPN कनेक्शन के सेवाओं को इंटरनेट पर उजागर करना चाहते हैं, साथ ही अपने public-facing attack surface को न्यूनतम करना चाहते हैं।

विशेषताएँ

• API Key Authentication: अपने knock endpoint को कई, configurable API keys के साथ सुरक्षित करें।
• Configurable TTL: प्रत्येक API key का अपना Time-To-Live (TTL) हो सकता है, जो यह परिभाषित करता है कि whitelisted IP कितने समय तक सक्रिय रहता है।
• Remote Whitelisting: विशिष्ट admin keys को किसी भी IP या CIDR range को whitelist करने की अनुमति दें, न कि केवल अपने स्वयं के।
• Static IP/CIDR Whitelisting: कुछ IP addresses या ranges को हमेशा dynamic whitelist को bypass करने की अनुमति दें।
• Host-Scoped Exclusion: जानबूझकर public paths को सही virtual host तक सीमित रखें।
• IPv6 First-Class Citizen: whitelisting, trusted proxies, और Docker networking में IPv6 और IPv4 के लिए पूर्ण समर्थन।
• Firewalld Integration: timed rules के साथ उन्नत firewall नियंत्रण जो TTL के आधार पर स्वचालित रूप से समाप्त हो जाते हैं। बेहतर सुरक्षा के लिए firewalld rich rules का उपयोग करके dynamic firewall नियम बनाता है। (वैकल्पिक, root container access की आवश्यकता है)

Knocker Clients

• Knocker-Web Static PWA web app जो reload पर knocking(whitelisting) का समर्थन करता है

• Knocker-CLI go में लिखा गया एक cli जो background knocks का समर्थन करता है, वैकल्पिक रूप से ip changes द्वारा ट्रिगर किया जाता है।

• Knocker-gnome Knocker-cli के ऊपर बनाया गया एक gnome extension।

• Knocker-EXPO React EXPO में लिखा गया एक प्रायोगिक Android App जो background knocking requests का समर्थन करता है

Sequence diagram

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)

Deployment

यह प्रोजेक्ट प्रदान की गई docker-compose.yml फ़ाइल का उपयोग करके Docker container के रूप में deploy करने के लिए डिज़ाइन किया गया है। यह AMD64, ARMv8 और ARMv7 के समर्थन के साथ pre-built docker images का उपयोग करता है

Docker Image Tags

Knocker विभिन्न उपयोग मामलों के लिए अलग-अलग image tags प्रदान करता है:

• latest नवीनतम स्थिर रिलीज़ (production के लिए अनुशंसित)
• v1.2.3 विशिष्ट संस्करण tags (pinned versions)
• main Development branch (rolling updates, अस्थिर हो सकता है)

Registeries

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

1. Prerequisites

• Docker और Docker Compose स्थापित।
• containers चलाने के लिए एक public-facing server (सेवाओं को चलाने वाले उसी server पर होना भी ज़रूरी नहीं! IN PROXY MODE)
• (वैकल्पिक) उन्नत firewall integration के लिए host पर Firewalld 2.0+ स्थापित और चल रहा हो।

1. Configuration:

   • knocker.example.yaml का नाम बदलकर knocker.yaml करें।
   • knocker.yaml में कम से कम एक सुरक्षित, random API key जोड़ें; उदाहरण में जानबूझकर कोई उपयोगी default शामिल नहीं है।
   • knocker.yaml में trusted_proxies सूची की समीक्षा करें: इसमें केवल reverse proxy के अपने address(es) होने चाहिए, उसका subnet नहीं। चूँकि knocker केवल सूचीबद्ध peer से X-Forwarded-For पर भरोसा करता है, पूरे-subnet की entry (जैसे 172.16.238.0/24) उस network पर हर container को एक identity authority बना देती है -- उनमें से कोई भी किसी भी client IP का दावा कर सकता है, या नियमित key के साथ मनमाने addresses को whitelist कर सकता है। Docker डिफ़ॉल्ट रूप से स्थिर container IPs असाइन नहीं करता, इसलिए proxy को ipv4_address / ipv6_address के साथ pin करें (docker-compose.yml में commented-out caddy service देखें) और उन सटीक /32 और /128 addresses को सूचीबद्ध करें।
   • whitelist.storage_path को app working directory, /data, या /tmp के अंतर्गत रखें।
   • (वैकल्पिक) firewalld.enabled: true सेट करके और संबंधित settings को समायोजित करके firewalld integration कॉन्फ़िगर करें। नोट: इसके लिए container को root के रूप में चलाने की आवश्यकता है।

2. Run the Service:

   docker compose up -d
   

   यह pre-built knocker image को pull करेगा और knocker और caddy दोनों services शुरू करेगा।

Use knocker with a Reverse Proxy

Knocker आपके reverse Proxy के लिए एक auth gateway के रूप में कार्य करके काम करता है। यह एक verify endpoint प्रदान करता है, यह जाँचने के लिए कि अनुरोध करने वाला IP whitelisted है या नहीं, यदि नहीं है तो यह 401 के साथ जवाब देगा और reverse proxy कनेक्शन से इनकार कर देगा।

Caddy

Caddy में auth endpoint का उपयोग करके कनेक्शन जाँचने के लिए forward_auth directive है।

1. Define a Reusable Snippet: auth check के लिए अपने Caddyfile में एक snippet परिभाषित करना सर्वोत्तम अभ्यास है।

2. Protect Your Services: जिस भी service को आप सुरक्षित करना चाहते हैं उसके लिए snippet import करें।

Example 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
}

Authorization Failures

जब कोई उपयोगकर्ता whitelisted नहीं होता, तो Caddy का forward_auth directive खाली body के साथ 401 Unauthorized response लौटाएगा।

महत्वपूर्ण नोट: Caddy का handle_errors directive forward_auth responses के साथ काम नहीं करता। error response सीधे authentication service (knocker) से आता है, Caddy से नहीं, इसलिए handle_errors इन responses को intercept या संशोधित नहीं कर सकता।

FirewallD Integration

Knocker firewalld के माध्यम से उन्नत firewall integration प्रदान करता है, जो dynamic, time-based firewall नियम बनाता है जो knock requests में निर्दिष्ट TTL के आधार पर स्वचालित रूप से समाप्त हो जाते हैं। यह सुविधा network स्तर पर संचालित होती है, जिससे आप knocker का उपयोग non-http services जैसे ssh या game servers के लिए कर सकते हैं।

Sequence diagram (firewalld)

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