knocker
Knocker es un servicio de control de acceso basado en 'knock-knock' para homelabs que proporciona autenticación SPA vía HTTP, integrándose con reverse proxies como Caddy y firewalls como FirewallD para proteger servicios sin VPN persistente.
Ficha actualizada 19 sept 2026, 0:07 · upstream 19 sept 2026, 0:07 · release v1.0.0
Qué es knocker
Descripción editorial construida a partir del repositorio, su documentación y sus señales de mantenimiento.
Knocker es un servicio autoalojado diseñado para proporcionar una puerta de entrada de autorización basada en paquetes únicos (SPA) a través de HTTP para entornos de homelab. Funciona como mecanismo de autenticación para reverse proxies como Caddy, o incluso a nivel de firewall mediante integración con FirewallD, permitiendo mantener servicios completamente privados y exponiéndolos bajo demanda solo para direcciones IP autorizadas.
El sistema utiliza un modelo 'knock-knock' donde los usuarios realizan solicitudes POST al endpoint /knock con una API key secreta para whitelisteear su propia IP o rangos CIDR específicos. Cada entrada en la whitelist tiene una vida útil (TTL) configurable que define cuánto tiempo permanece activa la dirección IP autorizada antes de expirar automáticamente. Esto es ideal para entornos de homelab donde se desea exponer servicios a internet sin mantener una conexión VPN persistente, minimizando así la superficie de ataque pública.
La arquitectura incluye clientes web (PWA), CLI en Go con soporte para knocks de fondo y extensiones GNOME, además de una aplicación Android experimental. El backend utiliza FastAPI con React para la interfaz web, soporta IPv6 como ciudadano de primera clase, y ofrece integración avanzada con FirewallD mediante reglas dinámicas que expiran automáticamente según el TTL especificado en las solicitudes de knock.
- Proteger servicios detrás de reverse proxies (Caddy) sin VPN persistente mediante autenticación SPA
- Gestionar acceso granular a servicios internos usando API keys con TTL configurable por usuario
- Integrar control de acceso en nivel firewall para servicios no HTTP como SSH o game servers
- Whitelisteo dinámico de IPs/CIDR remotas mediante API keys administrativas con expiración automática
- Autenticación SPA que minimiza superficie de ataque al exponer servicios solo bajo demanda
- Integración nativa con Caddy vía forward_auth para protección transparente de endpoints
- Soporte multiplataforma (AMD64/ARMv8/ARMv7) con imágenes Docker pre-construidas
- FirewallD integration con reglas dinámicas que expiran automáticamente según TTL
- Dependencia de FirewallD 2.0+ para integración avanzada, requiriendo acceso root al contenedor
- Incompatibilidad con Docker published ports en modo firewall (requiere host networking o proxy)
- Problemas potenciales con IPs detrás de tailscale debido a userland-proxy que devuelve IPs incorrectas
- Necesidad de configurar manualmente trusted_proxies para evitar resolución incorrecta de IPs cliente
Perfil de infraestructura
Estimación inicial derivada del repositorio y de los servicios detectados.
Despliegue detectado
Qué señales reales de instalación hemos encontrado.
Usar docker-compose.yml con imagen tagged latest o versión específica (no main en producción). Configurar API keys seguras en knocker.yaml sin valores por defecto. Montar /data o /tmp para whitelist.storage_path. Si se usa FirewallD, ejecutar contenedor como root con D-Bus socket montado y verificar firewall-cmd --zone=knocker --list-all. Asegurar que trusted_proxies coincidan con subnet del reverse proxy.
Stack y dependencias
Componentes inferidos a partir de manifests, configuración y documentación.
Puede sustituir a
Relaciones detectadas por el análisis del repositorio y su categoría.
Experiencia real de la comunidad
Ayuda a contrastar la estimación automática con instalaciones reales.
Todavía no hay datos comunitarios para este proyecto.