OPNsense MCP

Un servidor remoto de Model Context Protocol orientado a la seguridad para la API MVC de OPNsense. Expone HTTP Streamable con estado para agentes remotos, utiliza la autenticación HTTP Basic nativa de la API en el upstream y bloquea la operación en modo seguro (fail closed) cuando no puede determinar si un comando de OPNsense es de solo lectura.

Una instancia del servidor representa un firewall de OPNsense. La URL del firewall y las credenciales de la API permanecen en el entorno del servidor; los agentes se autentican ante el MCP con un token de autorización independiente y no pueden redirigir solicitudes a destinos de red arbitrarios. Al gestionar varios equipos, despliegue una instancia aislada por firewall.

Arquitectura

Remote agent --HTTPS + MCP bearer token--> OPNsense MCP --HTTPS + API key/secret--> OPNsense

El endpoint MCP utiliza el transporte Streamable HTTP actual en /mcp. Las sesiones tienen estado, de modo que los tokens de mutación de un solo uso siguen vinculados a la sesión MCP del agente. Las sesiones tienen un límite máximo, caducan por inactividad y se autentican en cada solicitud HTTP.

El listener HTTP incorporado está pensado para colocarse detrás de un proxy inverso TLS, un controlador de ingress, una VPN o una red superpuesta privada. No exponga su puerto HTTP sin cifrar directamente a una red no fiable.

Modelo de API de OPNsense

OPNsense enruta las solicitudes de API de la siguiente manera:

/api/<module>/<controller>/<command>/<parameter...>

Los comportamientos importantes para la automatización son:

• Las combinaciones de API usan autenticación HTTP Basic: la clave como nombre de usuario y el secreto como contraseña.

• El acceso sigue estando restringido por los privilegios ACL que el propietario de la clave tiene en OPNsense.

• Las solicitudes y la mayoría de las respuestas son JSON. Las descargas y los flujos de datos pueden no serlo.

• GET y POST no se corresponden claramente con operaciones seguras e inseguras. Algunas lecturas usan POST y algunas mutaciones usan GET.

• Los controladores de modelos mutables suelen exponer operaciones get, search, add, set, del y toggle.

• Los registros de modelos de tipo vector utilizan UUID. Una llamada get sin UUID suele devolver un registro en blanco cumplimentado con valores predeterminados.

• Una mutación de modelo exitosa suele escribir la configuración en etapas provisionales. Una llamada apply o reconfigure la activa.

• Las escrituras de modelo devuelven valores como {"result":"saved"} o {"result":"failed","validations":...}; un HTTP 200 por sí solo no demuestra el éxito semántico.

• El bloqueo de configuración de OPNsense, la validación de modelos, el contexto de revisión y las comprobaciones ACL se realizan en el servidor y no deben eludirse.

Referencias oficiales:

• https://docs.opnsense.org/development/api.html

• https://docs.opnsense.org/development/how-tos/api.html

• https://docs.opnsense.org/development/architecture.html

• https://docs.opnsense.org/development/frontend/controller.html

• https://docs.opnsense.org/development/frontend/models_fieldtypes.html

• https://github.com/opnsense/core

• https://github.com/opnsense/plugins

Modelo de seguridad

opnsense_request solo acepta comandos clasificados como lectura. La clasificación se basa en el comando, no en el método HTTP.

Las mutaciones se realizan con dos herramientas:

• opnsense_plan_change informa de la solicitud exacta y de su riesgo sin contactar con OPNsense.

• opnsense_execute_change requiere un token de un solo uso coincidente que caduca pasados cinco minutos.

Las clases de riesgo distinguen entre escrituras provisionales, activación, operaciones disruptivas de servicio o firmware y operaciones catastróficas de restablecimiento/restauración. Los comandos desconocidos se tratan como mutaciones y se bloquean en modo seguro (fail closed).

El modo de escritura se controla fuera del agente:

• disabled solo permite lecturas.

• plan permite analizar mutaciones, pero nunca genera un token de ejecución.

• enabled permite la ejecución con un token coincidente.

Utilice un usuario OPNsense dedicado y otorgue únicamente los privilegios efectivos que requieran las herramientas previstas. Para implementaciones de solo lectura, conceda también System: Deny config write (user-config-readonly) en OPNsense.

Herramientas de lectura seleccionadas

El cliente genérico protegido se complementa con herramientas de solo lectura fijas para tareas operativas habituales:

• opnsense_get_firewall_logs lee eventos estructurados del filtro de paquetes.

• opnsense_get_logs lee páginas limitadas de los registros del núcleo y los servicios, incluidos los registros de sistema, configd, pasarelas, VPN, DNS, DHCP, IDS, enrutamiento y la interfaz web.

• opnsense_list_firewall_rules lee las reglas de filtro visibles para la API de automatización.

• opnsense_list_nat_rules lee las reglas de destino, de origen, de uno a uno o de NPT.

• opnsense_get_route_table lee la tabla de rutas del kernel en tiempo real o las rutas estáticas configuradas.

Estas herramientas invocan directamente endpoints de consulta determinados. No pueden implementar acciones alternativas de mutación, como limpiar registros, vaciar estados, modificar reglas o implementar cambios. Los resultados siguen estando sujetos a los privilegios ACL del usuario de API en OPNsense.

Configuración inicial

npm install
npm run build

Configure elenlace con el entorno usando .env.example como referencia. Los archivos de entorno no se cargan automáticamente y Git los ignora. Genere un token MCP independiente con openssl rand -hex 32; no reutilice una credencial de API de OPNsense.

Para ejecutar, prefiera un certificado de confianza pública o establezca OPNSENSE_CA_FILE para indicar el certificado de la CA privada. OPNSENSE_TLS_VERIFY=false existe únicamente para desarrollo aislado.

Ejecute el servidor remoto en bucle de retorno local parao darle un proxy TSL inverso local:

OPNSENSE_URL=https://firewall.example \
OPNSENSE_API_KEY=... \
OPNSENSE_API_SECRET=... \
MCP_AUTH_TOKEN=<random-token-at-least-32-characters> \
node dist/index.js

La URL MCP es http://127.0.0.1:3000/mcp. Publíquela como HTTPS a través del proxy inverso inverso y transmite el token de la siguiente manera:

Authorization: Bearer <MCP_AUTH_TOKEN>

Ejemplo de configuración de cliente remoto para clientes que admiten URL y encabezados personalizados:

{
  "mcpServers": {
    "opnsense": {
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer ${MCP_AUTH_TOKEN}"
      }
    }
  }
}

Los formatos de configuración del cliente varían. Almacene el token en el gestor de secretos del cliente en lugar de guardarlo en un archivo de configuración.

Docker Compose

compose.yaml vincula el puerto 3000 al loopback del host para que un proxy inverso pueda neutralizar TLS con seguridad.

export OPNSENSE_URL=https://firewall.example
export OPNSENSE_API_KEY=...
export OPNSENSE_API_SECRET=...
export MCP_AUTH_TOKEN="$(openssl rand -hex 32)"
export MCP_ALLOWED_HOSTS=mcp.example.com
docker compose up -d --build

Cuando se conecte directamente a localhost:3000 durante el desarrollo, incluya localhost en MCP_ALLOWED_HOSTS. El endpoint de salud no autenticado está disponible en /health y no proporciona detalles sobre el destino ni las credenciales.

Seguridad remota

• MCP_AUTH_TOKEN es obligatorio para el transporte HTTP y debe contener al menos 32 caracteres.

• MCP_ALLOWED_HOSTS es obligatorio cuando se conecta a una dirección distinta de loopback y evita el "DNS rebinding" con la cabecera Host.

• Las solicitudes con la cabecera Origin de un navegador se rechazan a menos que el origen exacto esté presente en MCP_ALLOWED_ORIGINS.

• MCP_MAX_SESSIONS, MCP_SESSION_TTL_MS y MCP_RATE_LIMIT_PER_MINUTE limitan el uso remoto de recursos.

• Mantenga OPNSENSE_TLS_VERIFY=true. Use OPNSENSE_CA_FILE para una CA interna en lugar de desactivar la verificación.

• Mantenga OPNSENSE_WRITE_MODE=disabled para implementaciones de solo supervisión.

• Restrinja el usuario de API OPNsense con privilegios ACL efectivos y user-config-readonly donde corresponda.

• Coloque el endpoint MCP detrás de HTTPS, con política de firewall y preferiblemente detrás de una VPN o una red privada.

MCP_ALLOW_UNAUTHENTICATED=true existe solo para desarrollo local aislado y nunca debe utilizarse con un listener accesible remotamente.

Compatibilidad con Stdio

Los clientes locales pueden continuar lanzando el servidor como subproceso:

OPNSENSE_URL=https://firewall.example \
OPNSENSE_API_KEY=... \
OPNSENSE_API_SECRET=... \
MCP_TRANSPORT=stdio \
node dist/index.js

Configuración

• OPNSENSE_URL: URL base fija del firewall.

• OPNSENSE_API_KEY: clave de API del usuario OPNsense dedicado.

• OPNSENSE_API_SECRET: secreto de API para esa clave.

• OPNSENSE_WRITE_MODE: disabled, plan o enabled.

• OPNSENSE_CA_FILE: archivo PEM opcional de la CA privada.

• OPNSENSE_TLS_VERIFY: por defecto true.

• MCP_TRANSPORT: http de forma predeterminada, o stdio.

• MCP_HOST: dirección del listener, por defecto 127.0.0.1.

• MCP_PORT: puerto del listener, por defecto 3000.

• MCP_PATH: ruta del endpoint MCP, por defecto /mcp.

• MCP_AUTH_TOKEN: token portador para los agentes remotos.

• MCP_ALLOWED_HOSTS: nombres de host aceptados en la cabecera HTTP Host, separados por comas.

• MCP_ALLOWED_ORIGINS: orígenes de navegador aceptados, separados por callbacks; vacío rechaza suspensiones de navegador.

• MCP_MAX_SESSIONS: tope de sesiones simultáneas, por defecto 100.

• MCP_SESSION_TTL_MS: tiempo de vida de una sesión inactiva, por defecto una hora.

• MCP_RATE_LIMIT_PER_MINUTE: límite de solicitudes HTTP por cliente y minuto, por defecto 120.

Por ejemplo, una llamada de lectura sobre el estado del sistema utiliza:

{
  "module": "core",
  "controller": "system",
  "command": "status"
}

Limitaciones actuales

• OPNsense no publica un contrato OpenAPI completo. La referencia generada identifica rutas y métodos probables, pero normalmente omite los esquemas de los cuerpos de solicitud.

• Los endpoints de los plugins solo existen cuando sus paquetes están instalados y autorizados por ACL.

• La validación semántica de las respuestas aún no es específica de cada endpoint.

• El clasificador de riesgo léxico es deliberadamente conservador. Las herramientas seleccionadas deberían emplear, con el tiempo, un manifiesto de endpoints auditado con esquemas explícitos de solicitud y respuesta.

• Los tokens de planificación reducen la ejecución accidental o no deseada, pero los hosts MCP deben seguir presentando la aprobación de una persona para herramientas destructivas.

• La autenticación remota utiliza un token portador estático para todo el despliegue, en lugar de un servidor de autorización OAuth. Utilice despliegues separados o un proxy inverso autenticador cuando los agentes necesiten identidades distintas.

• El estado de las sesiones se guarda en memoria y no se comparte entre réplicas. Ejecute una única réplica salvo que se agreguen almacenamiento de sesión externo y afinidad de enrutamiento.