theus-cli 0.2.83 → 0.2.84

package/vendor/theus-arsenal/skills/homelab-dns-pihole/SKILL.md

@@ -1,264 +0,0 @@
----
-name: homelab-dns-pihole
-description: Instalación de Pi-hole, gestión de listas de bloqueo, DNS-over-HTTPS, integración con DHCP, registros DNS locales y diagnóstico de resolución DNS rota en una red doméstica.
----
-
-# DNS con Pi-hole para homelab
-
-Pi-hole es un bloqueador de anuncios a nivel de DNS para toda la red, que corre en una Raspberry Pi o en cualquier host Linux. Todos los dispositivos de la red obtienen bloqueo automático de dominios de publicidad y malware — sin extensiones de navegador.
-
-## Cuándo usarla
-
-- Instalar Pi-hole en una Raspberry Pi o un host Linux
-- Configurar Pi-hole como servidor DNS de una red doméstica
-- Añadir o gestionar listas de bloqueo
-- Configurar resolutores upstream con DNS-over-HTTPS (DoH)
-- Crear registros DNS locales (p. ej. `nas.home.lan`, `pi.home.lan`)
-- Diagnosticar dispositivos que pierden internet tras instalar Pi-hole
-- Ejecutar Pi-hole junto al DHCP del router o en su lugar
-
-## Cómo funciona Pi-hole
-
-```
-Flujo normal (sin Pi-hole):
-  Dispositivo → pide ads.tracker.com → DNS del ISP → IP real → cargan los anuncios
-
-Con Pi-hole:
-  Dispositivo → pide ads.tracker.com → DNS de Pi-hole → bloqueado (devuelve 0.0.0.0) → sin anuncio
-
-Todas las consultas DNS pasan primero por Pi-hole.
-Pi-hole las contrasta con las listas de bloqueo.
-Los dominios bloqueados reciben una respuesta nula — el anuncio/rastreador nunca carga.
-Los dominios permitidos se reenvían al resolutor upstream (Cloudflare, Google, etc.).
-```
-
-## Instalación
-
-### Docker (recomendado)
-
-Docker es la forma más sencilla de instalar Pi-hole y facilita actualizaciones y respaldos.
-
-```yaml
-# docker-compose.yml
-services:
-  pihole:
-    image: pihole/pihole:<tag-de-release-fijado>
-    container_name: pihole
-    ports:
-      - "53:53/tcp"
-      - "53:53/udp"
-      - "80:80/tcp"          # Panel de administración web
-    environment:
-      TZ: "America/Lima"
-      WEBPASSWORD: "${PIHOLE_WEBPASSWORD}"   # definir vía archivo .env o secreto
-      PIHOLE_DNS_: "1.1.1.1;1.0.0.1"
-      DNSMASQ_LISTENING: "all"
-    volumes:
-      - "./etc-pihole:/etc/pihole"
-      - "./etc-dnsmasq.d:/etc/dnsmasq.d"
-    restart: unless-stopped
-    cap_add:
-      - NET_ADMIN              # solo necesario si Pi-hole servirá DHCP
-```
-
-Sustituye `<tag-de-release-fijado>` por un tag de release vigente de Pi-hole antes de desplegar. Evita `latest` en infraestructura DNS de larga vida, para que las actualizaciones sean deliberadas y revisables.
-
-Define `PIHOLE_WEBPASSWORD` en un archivo `.env` junto al `docker-compose.yml`, ponle permisos `600` y mantenlo fuera de git — no pongas la contraseña directamente en el archivo compose.
-
-Accede al panel web en: `http://<ip-del-pi>/admin`
-
-### Instalación directa (Raspberry Pi OS / Debian / Ubuntu)
-
-Pi-hole requiere una IP estática antes de instalarse.
-
-```bash
-# Paso 1: asigna una IP estática (edita /etc/dhcpcd.conf en Pi OS)
-sudo nano /etc/dhcpcd.conf
-# Añade al final:
-interface eth0
-static ip_address=192.168.3.2/24
-static routers=192.168.3.1
-static domain_name_servers=192.168.3.1
-
-# Paso 2: descarga e inspecciona el instalador antes de ejecutarlo.
-# Prefiere el paquete o la ruta de instalación documentada por Pi-hole para tu SO/versión.
-curl -sSL https://install.pi-hole.net -o pi-hole-install.sh
-less pi-hole-install.sh   # revisar antes de continuar
-
-# Paso 3: ejecuta
-bash pi-hole-install.sh
-
-# Sigue el instalador interactivo:
-# 1. Selecciona la interfaz de red (eth0 por cable — recomendado)
-# 2. Selecciona el DNS upstream (Cloudflare o el predeterminado — se puede cambiar luego)
-# 3. Confirma la IP estática
-# 4. Instala la interfaz web de administración (recomendado)
-# 5. Anota la contraseña de administración que se muestra al final
-```
-
-## Apuntar la red a Pi-hole
-
-```
-# Método 1: cambiar el DNS en el DHCP del router (recomendado)
-  Panel del router → Ajustes de DHCP → Servidor DNS
-  DNS primario: 192.168.3.2  (IP de Pi-hole)
-  DNS secundario: déjalo vacío para bloqueo estricto, o usa un segundo Pi-hole.
-                 Un fallback público como 1.1.1.1 mejora la disponibilidad durante
-                 el despliegue, pero puede saltarse el bloqueo porque los clientes
-                 pueden consultarlo directamente.
-
-  Todos los dispositivos reciben Pi-hole como DNS en la próxima renovación DHCP.
-  Forzar renovación: reconecta el Wi-Fi o ejecuta 'sudo dhclient -r && sudo dhclient' en Linux
-
-# Método 2: DNS por dispositivo (útil para probar antes del despliegue global)
-  Windows: Panel de control → Adaptador de red → Propiedades IPv4 → DNS manual
-  macOS: Ajustes del Sistema → Red → Detalles → DNS → configurar manualmente
-  Linux: /etc/resolv.conf o NetworkManager
-
-# Método 3: Pi-hole como servidor DHCP (reemplaza al DHCP del router)
-  Panel de Pi-hole → Settings → DHCP → Enable
-  Desactiva primero el DHCP del router — dos servidores DHCP en la misma red causan conflictos
-  Ventaja: la resolución de nombres de host funciona automáticamente (los dispositivos registran su nombre)
-```
-
-## Gestión de listas de bloqueo
-
-```
-# Panel de Pi-hole → Adlists → Add new adlist
-
-# Listas de bloqueo recomendadas:
-  https://raw.githubusercontent.com/StevenBlack/hosts/master/hosts
-  # predeterminada — más de 200 000 dominios
-
-  https://blocklistproject.github.io/Lists/malware.txt
-  # dominios de malware
-
-  https://blocklistproject.github.io/Lists/tracking.txt
-  # rastreo/telemetría
-
-# Después de añadir una lista:
-  Tools → Update Gravity  (descarga y compila todas las listas de bloqueo)
-
-# Si un sitio queda bloqueado y no debería (falso positivo):
-  Panel de Pi-hole → Whitelist → Add domain
-  Ejemplo: api.mi-servicio-legitimo.com
-
-# Ver qué se está bloqueando en tiempo real:
-  Dashboard → Query Log  (flujo en vivo de consultas DNS con estado bloqueado/permitido)
-```
-
-## Upstream con DNS-over-HTTPS
-
-DNS-over-HTTPS cifra tus consultas DNS para que tu ISP no pueda ver qué sitios resuelves.
-
-```bash
-# Instala cloudflared (el proxy DoH de Cloudflare).
-# Prefiere el repositorio de paquetes de Cloudflare para verificación automática de firmas.
-# Si descargas el binario directamente, fija una versión de release y verifica su checksum.
-CLOUDFLARED_VERSION="<version-fijada>"
-curl -LO "https://github.com/cloudflare/cloudflared/releases/download/${CLOUDFLARED_VERSION}/cloudflared-linux-arm64"
-# Verifica el checksum/firma en las notas de release de Cloudflare antes de instalar.
-sudo mv cloudflared-linux-arm64 /usr/local/bin/cloudflared
-sudo chmod +x /usr/local/bin/cloudflared
-
-# Crea la configuración de cloudflared
-sudo mkdir -p /etc/cloudflared
-sudo tee /etc/cloudflared/config.yml << EOF
-proxy-dns: true
-proxy-dns-port: 5053
-proxy-dns-upstream:
-  - https://1.1.1.1/dns-query
-  - https://1.0.0.1/dns-query
-EOF
-
-# Crea el servicio systemd
-sudo cloudflared service install
-sudo systemctl start cloudflared
-sudo systemctl enable cloudflared
-
-# Ahora apunta Pi-hole al proxy DoH local:
-# Panel de Pi-hole → Settings → DNS → Custom upstream DNS
-# Configura: 127.0.0.1#5053
-# Desmarca el resto de resolutores upstream
-```
-
-## Registros DNS locales
-
-Haz que tus servicios sean accesibles por nombre (p. ej. `nas.home.lan`, `grafana.home.lan`).
-
-> **Nota sobre el nombre de dominio:** `.home.lan` es muy usado en homelabs y funciona en la práctica. El sufijo reservado por el IETF para uso local es `.home.arpa` (RFC 8375) — úsalo si quieres seguir el estándar. Evita `.local` para registros DNS de Pi-hole porque entra en conflicto con mDNS/Bonjour.
-
-```
-# Panel de Pi-hole → Local DNS → DNS Records
-
-  Dominio             IP
-  nas.home.lan        192.168.30.10
-  pi.home.lan         192.168.30.2
-  grafana.home.lan    192.168.30.3
-  proxmox.home.lan    192.168.30.4
-
-# Desde cualquier dispositivo de tu red:
-  ping nas.home.lan        → 192.168.30.10
-  http://grafana.home.lan  → tu panel de Grafana
-
-# Para subdominios, añade un CNAME:
-  Panel de Pi-hole → Local DNS → CNAME Records
-  Dominio: portainer.home.lan → Destino: pi.home.lan
-```
-
-## Diagnóstico
-
-```bash
-# Pi-hole bloquea algo que no debería
-pihole -q ejemplo.com          # Comprueba si el dominio está bloqueado y en qué lista
-pihole -w ejemplo.com          # Añádelo a la lista blanca de inmediato
-
-# El DNS no resuelve nada
-pihole status                  # Comprueba si pihole-FTL está corriendo
-dig @192.168.3.2 google.com   # Prueba el DNS directamente contra Pi-hole
-
-# Reinicia el DNS de Pi-hole
-pihole restartdns
-
-# Revisa las consultas de un dispositivo concreto
-pihole -t                      # Cola en vivo de todas las consultas
-# O filtra por cliente en el Query Log del panel web
-
-# Actualización de gravity (refrescar listas de bloqueo)
-pihole -g
-```
-
-## Antipatrones
-
-```
-# MAL: depender de un solo Pi-hole sin ruta de recuperación
-# Si Pi-hole se cae o el Pi pierde energía, el DNS puede dejar de funcionar
-# BIEN: mantén documentado el fallback del router para poder revertir durante la puesta en marcha
-# MEJOR: ejecuta dos instancias de Pi-hole para redundancia; evita un DNS público de fallback si quieres bloqueo estricto
-
-# MAL: instalar Pi-hole sin IP estática
-# Si el Pi recibe una nueva IP por DHCP, todos los dispositivos pierden el DNS
-# BIEN: fija primero la IP estática y luego instala Pi-hole
-
-# MAL: activar el DHCP de Pi-hole sin desactivar antes el del router
-# Dos servidores DHCP en la misma red reparten IPs conflictivas
-# BIEN: desactiva el DHCP del router y luego activa el de Pi-hole
-
-# MAL: no actualizar nunca gravity (las listas de bloqueo)
-# Los dominios nuevos de anuncios y malware se acumulan — las listas viejas no los cubren
-# BIEN: programa una actualización semanal: pihole -g (o actívala en Settings → API)
-```
-
-## Buenas prácticas
-
-- Asigna al Pi una IP estática o una reserva DHCP antes de instalar Pi-hole
-- Usa Pi-hole como DNS primario; para redundancia, añade un segundo Pi-hole en lugar de un resolutor público si necesitas bloqueo estricto
-- Activa DoH (DNS-over-HTTPS) con cloudflared para cifrar las consultas upstream
-- Usa `home.lan` como dominio local y crea registros DNS para todos tus servicios
-- Revisa el Query Log de vez en cuando — las consultas bloqueadas te muestran qué hacen tus dispositivos
-
-## Skills relacionadas
-
-- `homelab-diseno-red`
-- `homelab-segmentacion-vlan`
-- `homelab-vpn-wireguard`

package/vendor/theus-arsenal/skills/homelab-preparacion-red/SKILL.md

@@ -1,144 +0,0 @@
----
-name: homelab-preparacion-red
-description: Lista de preparación para segmentación VLAN de homelab, filtrado DNS local y acceso remoto tipo WireGuard antes de tocar la configuración del router, firewall, DHCP o VPN.
----
-
-# Preparación de red para homelab
-
-Usa esta skill antes de cambiar una red doméstica o de laboratorio pequeño que mezcla VLANs, Pi-hole u otro resolutor DNS local, reglas de firewall y acceso VPN remoto.
-
-Es una skill de planificación y revisión. No la conviertas en configuración copiable de router, firewall o VPN salvo que la plataforma objetivo, la topología actual, la ruta de rollback, el acceso por consola y la ventana de mantenimiento sean todos conocidos.
-
-## Cuándo usarla
-
-- Al preparar la división de una red plana en VLANs de confianza, IoT, invitados, servidores o gestión.
-- Al mover los clientes DHCP a Pi-hole, AdGuard Home, Unbound u otro resolutor DNS local.
-- Al añadir acceso mediante WireGuard, Tailscale, ZeroTier, OpenVPN o la VPN nativa del router.
-- Al revisar si un cambio del homelab puede dejar al operador sin acceso al gateway, switch, punto de acceso, servidor DNS o servidor VPN.
-- Al convertir una idea informal de red doméstica en un plan de migración por etapas con evidencia de validación.
-
-## Reglas de seguridad
-
-- Mantén la primera respuesta en modo solo lectura: inventario, riesgos, plan por etapas, validación y rollback.
-- No expongas paneles de administración del gateway, resolutores DNS, SSH, consolas de NAS ni interfaces de gestión de VPN directamente a internet.
-- No des comandos de firewall, NAT, VLAN, DHCP o VPN sin una plataforma confirmada y un procedimiento de rollback.
-- Exige acceso por consola fuera de banda o en la misma sala antes de cambiar VLANs de gestión, puertos troncales, políticas por defecto del firewall o ajustes de DHCP/DNS.
-- Conserva una ruta funcional de vuelta a internet antes de apuntar toda la red a un nuevo resolutor DNS o ruta VPN.
-- Trata las redes de IoT, invitados, cámaras y servidores de laboratorio como zonas de confianza distintas hasta que el operador decida explícitamente lo contrario.
-
-## Inventario obligatorio
-
-Recopila esto antes de dar pasos de implementación:
-
-| Área | Preguntas |
-| --- | --- |
-| Borde de internet | ¿Cuál es el módem u ONT? ¿El router del ISP está en modo bridge o sigue enrutando? |
-| Gateway | ¿Qué equipo enruta, hace de firewall, gestiona DHCP y termina las VPNs? |
-| Conmutación | ¿Qué puertos del switch son uplinks, puertos de acceso, troncales o no gestionados? |
-| Wi-Fi | ¿Qué SSIDs se mapean a qué redes, y los APs van por cable o en mesh? |
-| Direccionamiento | ¿Qué subredes existen hoy y qué rangos chocan con sitios de la VPN? |
-| DNS/DHCP | ¿Qué servicio entrega actualmente los leases y las direcciones de resolutor? |
-| Gestión | ¿Cómo alcanzará el operador el gateway, switch y AP después de los cambios? |
-| Recuperación | ¿Qué puede revertirse localmente si el DNS, DHCP, las VLANs o las rutas VPN se rompen? |
-
-## Plan de VLANs y zonas de confianza
-
-Empieza por la intención, no por la sintaxis del fabricante.
-
-| Zona | Contenido típico | Política por defecto |
-| --- | --- | --- |
-| Confianza | Portátiles, teléfonos, estaciones de administración | Alcanza servicios compartidos y gestión solo cuando hace falta |
-| Servidores | NAS, Home Assistant, hosts de laboratorio, resolutor DNS | Acepta flujos entrantes acotados desde clientes de confianza |
-| IoT | TVs, enchufes inteligentes, cámaras, altavoces | Solo internet más excepciones explícitas |
-| Invitados | Dispositivos de visitas | Solo internet, sin alcance a la LAN |
-| Gestión | Gateway, switches, APs, controladoras | Alcanzable solo desde equipos de administración de confianza |
-| VPN | Clientes remotos | Acceso igual o más estrecho que los clientes de confianza |
-
-Antes de recomendar IDs de VLAN o subredes, confirma:
-
-1. El gateway soporta enrutamiento inter-VLAN y reglas de firewall.
-2. El switch soporta el comportamiento de puertos etiquetados y sin etiquetar que se necesita.
-3. Los APs pueden mapear SSIDs a VLANs.
-4. El operador sabe por qué puerto está conectado durante el cambio.
-5. La red de gestión sigue siendo alcanzable tras los cambios de troncales y SSIDs.
-
-## Preparación del filtrado DNS
-
-Pi-hole u otro resolutor local debe introducirse como una dependencia, no como un punto único de fallo.
-
-1. Da al resolutor una dirección reservada antes de usarlo en las opciones de DHCP.
-2. Confirma que resuelve DNS público y nombres locales `home.arpa`.
-3. Mantén el gateway o un segundo resolutor disponible como respaldo temporal.
-4. Prueba con un cliente o una VLAN antes de cambiar todos los ámbitos DHCP.
-5. Documenta qué redes pueden saltarse el filtrado y por qué.
-6. Comprueba que las reglas de bloqueo no rompan portales cautivos, VPNs de trabajo, actualizaciones de firmware ni dispositivos médicos o de seguridad.
-
-Evidencia de validación útil:
-
-```text
-El cliente recibe el lease DHCP esperado
-El cliente recibe el resolutor DNS esperado
-La resolución de DNS público funciona
-La resolución local de home.arpa funciona
-El dominio de prueba bloqueado se bloquea solo donde se pretende
-Las interfaces de administración del gateway y del DNS no son alcanzables desde las redes de invitados o IoT
-```
-
-## Preparación del acceso remoto
-
-Para acceso tipo WireGuard, decide qué puede alcanzar la VPN antes de generar claves o abrir puertos.
-
-| Modo | Cuándo usarlo | Notas de riesgo |
-| --- | --- | --- |
-| Túnel dividido a una subred | Administración remota de NAS o hosts de laboratorio | Mantén la lista de rutas estrecha |
-| Túnel dividido a servicios de confianza | Acceso a apps concretas por IP o DNS | Requiere reglas de firewall precisas |
-| Túnel completo | Redes no confiables o viajes | Más ancho de banda y responsabilidad sobre el DNS |
-| VPN overlay | Acceso remoto más simple con controles de identidad | Aun así requiere revisión de ACLs |
-
-No recomiendes reenvío de puertos hasta que el operador confirme:
-
-- El endpoint VPN está parcheado y con mantenimiento activo.
-- El puerto reenviado va únicamente al servicio VPN, no a una interfaz de administración.
-- Se entienden el DNS dinámico, el comportamiento de la IP pública y el estado de CGNAT del ISP.
-- Las claves de los peers pueden revocarse sin reconstruir toda la red.
-- Los logs o el estado de conexión permiten verificar quién se conectó y cuándo.
-
-## Secuencia de cambios
-
-Prefiere cambios pequeños y reversibles:
-
-1. Toma una instantánea de la topología actual, el plan de IPs, los ajustes de DHCP y DNS y las reglas de firewall.
-2. Reserva direcciones de infraestructura para gateway, DNS, controladora, APs, NAS y endpoint VPN.
-3. Crea la nueva zona o VLAN sin mover dispositivos críticos.
-4. Mueve un cliente de prueba y valida DHCP, DNS, enrutamiento, internet y comportamiento de bloqueo.
-5. Añade excepciones de firewall estrechas para los flujos necesarios.
-6. Mueve un grupo de dispositivos de bajo riesgo.
-7. Añade el acceso VPN con la ruta y la política de firewall más estrechas que satisfagan el caso de uso.
-8. Documenta el estado final, las excepciones conocidas y los comandos o pasos de UI del rollback.
-
-## Lista de verificación de revisión
-
-- Cada red tiene una razón de existir y un límite de confianza claro.
-- Ninguna interfaz de gestión es alcanzable desde invitados, IoT o internet público.
-- Un fallo del DNS no deja al operador sin capacidad de recuperación local.
-- Los cambios de ámbito DHCP se probaron en un cliente antes del despliegue amplio.
-- Los clientes VPN reciben solo las rutas y ajustes DNS que necesitan.
-- Las reglas de firewall son de denegación por defecto entre zonas, con excepciones nombradas.
-- El operador sigue pudiendo alcanzar las superficies de administración del gateway, switch, AP, DNS y VPN.
-- El rollback está documentado en el mismo vocabulario que la UI o CLI de la plataforma elegida.
-
-## Antipatrones
-
-- Segmentar redes antes de saber qué puertos del switch y qué SSIDs transportan qué VLANs.
-- Mover la estación de administración fuera de la única red de gestión alcanzable.
-- Apuntar todos los ámbitos DHCP a un Pi-hole antes de probar el DNS de respaldo.
-- Publicar la gestión del NAS, DNS, router o hipervisor directamente a internet.
-- Tratar el acceso VPN como equivalente al acceso completo a la LAN de confianza.
-- Añadir reglas de firewall permitir-todo "temporales" y olvidarse de quitarlas.
-- Copiar comandos de otro fabricante o versión de firmware sin comprobar la sintaxis exacta de la plataforma.
-
-## Skills relacionadas
-
-- `homelab-diseno-red`
-- `validacion-config-red`
-- `salud-interfaces-red`