theus-cli-darwin-x64 0.2.84

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

@@ -0,0 +1,264 @@
+---
+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

@@ -0,0 +1,144 @@
+---
+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`