OPNsense en PegaProx: monitoring del firewall sin abrir la GUI
Publicamos el plugin OPNsense para PegaProx v1.4.1 — overview, network, VPN, logs, NAT con CRUD, sparklines SVG y drilldown modal en una pestaña dentro del cluster manager. 98 tests, axe-core 0 violaciones, lab live en 190.160.10.108.
TL;DR
Después del Docker Manager, el segundo plugin que liberamos para PegaProx es opnsense — una pestaña que vive dentro del cluster manager y trae a primera plana las métricas que normalmente requieren entrar a la GUI de OPNsense, navegar entre tabs y armar el panorama mentalmente. Versión actual: v1.4.1 (2026-05-10), corriendo en lab contra una VM real de OPNsense 26.1.2_5. 98 tests verdes y 0 violaciones axe-core en las cinco pestañas.
El operador no tiene que abrir tres pestañas para saber si el firewall está sano. Una sola lectura: tráfico, sesiones, túneles, alertas.
Qué resuelve
OPNsense es un firewall excelente, pero su UI está optimizada para configuración, no para vigilancia. Cuando administras varios sitios, lo que necesitas es:
- Resumen rápido: estado WAN/LAN, sesiones activas, CPU, memoria.
- Tráfico en tiempo real: throughput por interfaz con tendencia de los últimos minutos.
- Túneles VPN: estado de WireGuard / IPsec con peers conectados.
- Logs filtrados: solo lo que importa hoy (drops nuevos, IDS alerts, DHCP renovations sospechosas).
Construirlo dentro de PegaProx tiene una ventaja extra: queda al mismo nivel que el Docker Manager, el monitor de Proxmox y el resto del cluster. Una sola consola.
Lo que trae el plugin
Cinco pestañas dentro de la card OPNsense de PegaProx:
Overview
Tarjetas resumen con CPU, memoria, sesiones de pf, throughput agregado WAN/LAN, uptime y versión del firmware. Sparklines SVG inline (sin librerías externas) para tendencia de los últimos 60 minutos.
Network
Tabla de interfaces con IP, MAC, MTU, errores, throughput in/out actual y un chart de área stacked con la última hora de tráfico por interfaz. Drilldown modal al hacer click en una interfaz para ver el desglose de los últimos puntos. La idea es que al primer vistazo veas si algo está saturado y puedas profundizar sin abrir otra herramienta.
VPN
Estado de WireGuard e IPsec. Peers conectados, último handshake, bytes intercambiados, latencia. Útil cuando un cliente reporta “se cayó la VPN” — abres la pestaña, confirmas, sigues.
Logs
Stream filtrado de los logs de pf y suricata. Filtros por severidad, interfaz, IP origen. Nada de scroll infinito sobre 30 MB de log: solo lo relevante de los últimos minutos.
NAT (write-enabled)
Listado de port-forwards y outbound rules con CRUD inline (NatWriter). Crea, edita o desactiva una regla NAT desde PegaProx sin abrir la GUI de OPNsense. Las escrituras pasan por la API REST oficial con confirmación de doble paso para no romper el firewall por error.
Endpoints expuestos
Para integraciones externas y CLI:
| Endpoint | Devuelve |
|---|---|
GET /api/plugins/opnsense/api/overview | Resumen agregado |
GET /api/plugins/opnsense/api/network | Interfaces + throughput |
GET /api/plugins/opnsense/api/logs | Últimos N logs filtrables |
GET /api/plugins/opnsense/api/metrics | Métricas raw (cpu/mem/sesiones) |
GET /api/plugins/opnsense/api/health | Liveness probe (200/503) |
Auth manejada por PegaProx (capability plugins.view). Los endpoints son seguros para llamarse desde scripts internos o dashboards Grafana adicionales.
Stack y oficio
- Backend: Python 3.12, llamadas firmadas a la API REST de OPNsense con API key. Sin parsing de HTML, sin scraping.
- Frontend: vanilla TS dentro del frontend nativo de PegaProx (sin React, sin Vue — el plugin se integra al mismo bundle del manager).
- Charts: SVG inline propio. Sin Chart.js ni d3 cargados solo para esto.
- Accesibilidad: axe-core 0 violaciones en las cinco pestañas. Tabulación coherente, contraste verificado en modo claro y oscuro.
Lab vs producción
Hoy el plugin está corriendo contra una VM lab opnsense-lab (VMID 125, IP 190.160.10.108) con un usuario API dedicado de scope amplio. La razón: queremos exprimir bordes de la API y romper cosas en un host aislado antes de apuntarlo al par HA productivo (NODOA 190.160.10.2 / NODOB 190.160.10.3).
El plan es promoverlo al cluster productivo en cuanto cerremos:
- Permisos finos (reemplazar el rol
GUI - All pagespor capabilities mínimas). - Modo M-LAG aware: detectar par CARP y agregar el estado de failover en Overview.
- Tabla de address-list y bogons activos, con audit trail.
Open source, mismo patrón
El repo es público en github.com/idkmanager/pegaprox-plugin-opnsense. Mismo flujo de instalación que el Docker Manager: clonar a /opt/PegaProx/plugins/opnsense/, generar config.json con la URL del firewall y la API key, recargar PegaProx y la pestaña aparece.
Si tienes OPNsense en producción y PegaProx en infraestructura: el plugin te ahorra abrir cuatro pestañas distintas para responder “¿está todo bien?”. Esa pregunta debería tomar tres segundos, no tres minutos.