knocker

Knocker es un servicio autoalojado que proporciona una pasarela de autorización de paquete único (SPA) "knock-knock" basada en HTTP para tu Homelab, con clientes web, cli + gnome y Android. Puede utilizarse como autenticación para tu proxy inverso como Caddy, o incluso a nivel de firewall mediante la integración con FirewallD. Te permite mantener tus servicios completamente privados, abriéndolos bajo demanda únicamente para direcciones IP autorizadas.

Esto es ideal para entornos de homelab donde quieres exponer servicios a internet sin una conexión VPN persistente, minimizando al mismo tiempo tu superficie de ataque pública.

Características

• Autenticación mediante API Key: Asegura tu endpoint de knock con múltiples claves API configurables.
• TTL configurable: Cada clave API puede tener su propio Time-To-Live (TTL), que define cuánto tiempo permanece activa una IP en la lista blanca.
• Lista blanca remota: Otorga a claves de administrador específicas permiso para añadir a la lista blanca cualquier IP o rango CIDR, no solo las suyas.
• Lista blanca estática de IP/CIDR: Permite siempre que ciertas direcciones o rangos de IP omitan la lista blanca dinámica.
• Exclusión basada en rutas: Excluye rutas de URL específicas (como health checks o APIs públicas) de la autenticación por completo.
• IPv6 como ciudadano de primera clase: Soporte completo para IPv6 e IPv4 en la lista blanca, proxies de confianza y redes Docker.
• Integración con Firewalld: Control avanzado del firewall con reglas temporizadas que expiran automáticamente según el TTL. Crea reglas dinámicas de firewall utilizando rich rules de firewalld para mayor seguridad. (Opcional, requiere acceso root al contenedor)

Clientes de Knocker

• Knocker-Web Aplicación web PWA estática que admite knocking (lista blanca) al recargar

• Knocker-CLI Una CLI escrita en Go con soporte para knocks en segundo plano, opcionalmente activados por cambios de IP.

• Knocker-gnome una extensión de GNOME construida sobre Knocker-cli.

• Knocker-EXPO Una aplicación Android experimental escrita en React EXPO con soporte para solicitudes de knocking en segundo plano

Diagrama de secuencia

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)

Despliegue

Este proyecto está diseñado para desplegarse como un contenedor Docker utilizando el archivo docker-compose.yml proporcionado. Utiliza las imágenes docker precompiladas con soporte para AMD64, ARMv8 y ARMv7

Etiquetas de imágenes Docker

Knocker proporciona diferentes etiquetas de imagen para diferentes casos de uso:

• latest Última versión estable (recomendada para producción)
• v1.2.3 Etiquetas de versiones específicas (versiones fijadas)
• main Rama de desarrollo (actualizaciones continuas, puede ser inestable)

Registros

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

1. Requisitos previos

• Docker y Docker Compose instalados.
• Un servidor con acceso público para ejecutar los contenedores (¡ni siquiera tiene que estar en el mismo servidor donde se ejecutan los servicios! EN MODO PROXY)
• (Opcional) Firewalld 2.0+ instalado y ejecutándose en el host para la integración avanzada con el firewall.

1. Configuración:

   • Renombra knocker.example.yaml a knocker.yaml.
   • Fundamental: cambia las claves API predeterminadas en knocker.yaml por tus propias cadenas aleatorias y seguras.
   • Revisa la lista trusted_proxies en knocker.yaml; deben coincidir con la subred de la red del proxy inverso (docker network inspect xxx)
   • Mantén whitelist.storage_path dentro del directorio de trabajo de la aplicación, /data o /tmp.
   • (Opcional) Configura la integración con firewalld estableciendo firewalld.enabled: true y ajustando las opciones relacionadas. Nota: Esto requiere que el contenedor se ejecute como root.

2. Ejecutar el servicio:

   root@kitploit:~

   docker compose up -d
   

Usar Knocker con un proxy inverso

Knocker funciona actuando como una pasarela de autenticación para tu proxy inverso. Ofrece un endpoint de verificación para comprobar si la IP solicitante está o no en la lista blanca; si no lo está, responderá con un 401 y el proxy inverso rechazará la conexión.

Caddy

Caddy tiene la directiva forward_auth para comprobar las conexiones mediante un endpoint de autenticación.

1. Define un snippet reutilizable: Es una buena práctica definir un snippet en tu Caddyfile para la comprobación de autenticación.

2. Protege tus servicios: Importa el snippet para cualquier servicio que quieras proteger.

Ejemplo de 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
}

Errores de autorización

Cuando un usuario no está en la lista blanca, la directiva forward_auth de Caddy devolverá una respuesta 401 Unauthorized con el cuerpo vacío.

Nota importante: la directiva handle_errors de Caddy no funciona con las respuestas de forward_auth. La respuesta de error proviene directamente del servicio de autenticación (knocker), no de Caddy en sí, por lo que handle_errors no puede interceptar ni modificar estas respuestas.

Integración con FirewallD

Knocker proporciona una integración avanzada con el firewall a través de firewalld, creando reglas de firewall dinámicas y temporales que expiran automáticamente según el TTL especificado en las solicitudes de knock. Esta función opera a nivel de red, lo que te permite usar knocker para servicios no HTTP como SSH o servidores de juego.

Diagrama de secuencia (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 requiere FirewallD 2.0+ debido a su dependencia de la función de prioridad de zonas. Está disponible en Debian 13, Ubuntu 24.04 LTS y otras distribuciones estables recientes.

¿Por qué FirewallD?

FirewallD fue elegido por su capacidad de separar la interfaz CLI del daemon. Esto permite que Knocker controle firewalld desde dentro de un contenedor Docker montando el socket D-Bus del sistema. FirewallD también tiene soporte para reglas temporizadas, por lo que las reglas de knocker expiran automáticamente al final del TTL.

FIREWALLD NO FUNCIONARÁ CON PUERTOS PUBLICADOS POR DOCKER; consulta este problema para más detalles

Cómo funciona

1. Crea una zona firewalld dedicada con alta prioridad
2. Añade reglas DROP/REJECT para los puertos monitoreados y bloquear el acceso no autorizado
3. Añade dinámicamente reglas ALLOW para las IP en la lista blanca que anulan las reglas de bloqueo
4. Expira las reglas automáticamente según el TTL utilizando el mecanismo de timeout de firewalld
5. Recupera las reglas al iniciar comparando whitelist.json con las reglas activas de firewalld

Habilitar la integración con FirewallD

1. Requisitos previos

   • FirewallD 2.0+ instalado y ejecutándose en el sistema host
   • El contenedor Docker debe ejecutarse como root para el acceso a D-Bus

2. Configuración

   • Habilita FirewallD en la configuración de knocker.yaml; los ajustes ya están disponibles en la configuración de ejemplo
   • Monta el socket D-Bus en el contenedor Docker y asegúrate de que se ejecute como root; las entradas necesarias están comentadas en el archivo docker-compose.yml.

Pruebas y solución de problemas

Monitorea las reglas activas:

# 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

Para obtener información detallada sobre configuración, arquitectura y solución de problemas, consulta la Guía de integración con FirewallD completa.

Problemas relacionados con userland-proxy

Si estás habilitando el knocking para IPs detrás de Tailscale u otras IPs, puedes enfrentar problemas debido a cómo funciona userland-proxy; es posible que obtengas una IP de solicitud diferente de la dirección IP real.

Deshabilitar Userland-proxy debería solucionarlo, pero asegúrate de probar tu configuración. También podrías usar la red del host (host networking).

Uso de la API

/knock (POST)

Este endpoint valida una clave API y añade una IP a la lista blanca.

• Headers:

  • X-Api-Key: Tu clave API secreta.

• Body (opcional):

  • Para añadir una IP/CIDR remota a la lista blanca (requiere allow_remote_whitelist: true):
    root@kitploit:~

    {"ip_address": "YOUR_TARGET_IP_OR_CIDR"}
    

• Ejemplo (añadir tu propia IP a la lista blanca):

  root@kitploit:~

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

• Respuesta de éxito (200 OK):

  root@kitploit:~

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

/verify (GET)

Este endpoint es utilizado por forward_auth de Caddy para comprobar si la IP del cliente está en la lista blanca. Devuelve 200 OK en caso de éxito y 401 Unauthorized en caso de fallo. X-Forwarded-For, X-Forwarded-Host y X-Forwarded-Uri solo se confían cuando la solicitud se origina desde server.trusted_proxies.

Caddy ya reenvía las cabeceras de solicitud X-Forwarded-* relevantes a Knocker para que /verify pueda tomar la decisión de autenticación.

Pruebas

El proyecto incluye un conjunto completo de pruebas

Herramientas

Este proyecto utiliza el conjunto de herramientas Python de Astral:

• uv para la gestión de dependencias, entornos y ejecución de comandos
• ruff para linting y formateo
• ty para la comprobación de tipos

Pruebas unitarias

Para ejecutar las pruebas localmente:

1. Instala uv:

   root@kitploit:~

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

2. Sincroniza el entorno del proyecto:

   root@kitploit:~

   uv sync --all-groups
   

3. Ejecuta las comprobaciones:

   root@kitploit:~

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

Pruebas de integración

Hay un entorno de desarrollo en dev, con scripts bash para pruebas de integración con Caddy y otro separado con firewalld. Los stacks de prueba estándar son dev/docker-compose.yml y dev/docker-compose.ci.yml; ambos exponen Caddy en http://localhost:18080 y https://localhost:18443. El CI ejecuta las pruebas de Caddy, pero firewalld necesita un runner privilegiado, por lo que debe ejecutarse localmente y no forma parte del CI.

Documentación

Los endpoints de documentación interactiva (/docs, /redoc, /openapi.json) están deshabilitados por defecto. Para exponerlos, establece lo siguiente en knocker.yaml:

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

Cuando la documentación está deshabilitada (por defecto), Knocker elimina estos endpoints y borra cualquier archivo de esquema generado previamente para evitar artefactos obsoletos.

Para una especificación formal de la API y un resumen de las decisiones arquitectónicas, consulta la documentación.

Totalmente vibe-coded

Knocker fue totalmente vibe-coded. La implementación inicial se realizó con Gemini 2.5 Pro, gracias a los tokens proporcionados en el hackathon de roo code/requesty.

Las funciones adicionales se realizaron principalmente con el agente de GitHub Copilot (sonnet 4/más tarde 4.5), que necesitó muchas correcciones, hechas principalmente por GPT-5 mini/CODEX en Roo code, Opencode y la extensión estándar de Copilot.

Hice todo lo posible con esto, planificando siempre los cambios y probando todo después de cada cambio, pero si eres anti-IA, probablemente no podría cambiar tu opinión al respecto.