API REST de Sophos Firewall: acceso seguro y ciclo de vida de claves

La API REST local de SFOS 23.0 permite consultar y modificar la configuración directamente en el firewall. Empezar con un administrador dedicado de permisos limitados, autorizar solo el host de automatización, generar la clave con esa cuenta y validar primero una lectura. La disponibilidad de documentación no confirma una fecha GA ni compatibilidad con firmware anterior.

Tres interfaces, tres identidades

• API REST local: la clave de un administrador del firewall actúa como token Bearer; sus permisos proceden del perfil administrador.
• API XML local: cargas XML y credenciales de administrador, normalmente mediante HTTP POST a APIController. XML <Get> no es una solicitud REST.
• API de configuración de Sophos Central: principal de servicio cloud, token temporal, tenant y host API regional. Una clave local no sustituye estas credenciales.

Preparar acceso y administrador

1. En Profiles > Device access, crear un perfil con los permisos necesarios; para inventario, solo los permisos de lectura apropiados. En Authentication > Users, crear un administrador dedicado con ese perfil. La planificación de administradores y perfiles explica los roles. No usar cuentas personales ni el admin predeterminado con todos los privilegios para los trabajos.
2. En Hosts and services > IP host, definir el host real, por ejemplo api-inventory con 192.0.2.20. Sustituir nombre y dirección de documentación. Un origen fijo es más restrictivo que toda la red de gestión; con NAT importa el origen que ve el firewall.
3. En Administration > API access, activar API access, desactivado por defecto, seleccionar solo los orígenes necesarios en Allowed IP hosts y pulsar Apply. Se admiten direcciones, rangos y redes, hasta 64 entradas. Revisar los orígenes apiconfig migrados al actualizar a SFOS 22.0 o posterior.
4. En Administration > Device access, comprobar WebAdmin desde la zona correspondiente. Device Access y la lista API son controles distintos; no abrir el acceso WAN indiscriminadamente.

Generar y capturar la clave una sola vez

Iniciar sesión como administrador dedicado. En Administration > API access > REST API keys, pulsar Add API key, escribir un nombre descriptivo como inventory-prod-2026-10 y generar con Add API key.

Antes de Close: copiar la clave al almacén de secretos protegido del trabajo. Al cerrar la ventana no volverá a mostrarse. No incluirla en capturas, tickets, archivos del repositorio ni exportaciones de colecciones sin protección.

La clave es válida un año y hereda los permisos de su creador. Los administradores crean y eliminan sus propias claves; todos ven la lista, pero no recuperan el secreto. El admin predeterminado también puede eliminar claves ajenas. Límites: 10 claves por administrador, 1024 en total. No compartir claves entre administradores.

Construir la solicitud desde el esquema del firewall

En REST API help, descargar OpenAPI.yaml de este firewall e importarlo en Postman o Swagger. En REST API guide, comprobar URL base, autenticación, referencias de objetos y esquema del endpoint elegido. Los nombres se parecen a los de la interfaz, pero no siempre coinciden.

La referencia indica esta base y esta cabecera; obtener ruta, método y parámetros de la solicitud del esquema correspondiente:

https://<firewall-host>:<port>/firewall-config/v1
Authorization: Bearer <API_KEY>

Sustituir hostname y puerto HTTPS administrativo; insertar la clave mediante la función de secretos del cliente. Validar certificado TLS y hostname, sin omitir controles con -k. La introducción también contiene ejemplos con la ruta XML APIController: no copiarlos sin verificar como instrucciones REST. Si el esquema del firewall no contiene el endpoint, no inventar una ruta.

Prueba de lectura y control operativo

Enviar desde el host real una lectura inocua conforme al esquema. Comprobar respuesta y datos esperados, no solo el éxito HTTP. Repetir desde un origen controlado no autorizado: no debe devolver configuración. No retirar autorizaciones de producción para preparar esta prueba.

Antes de escribir, preparar copia de seguridad y recuperación, probar un pequeño cambio autorizado y comprobar el objeto en WebAdmin y el Audit Trail. Tras un timeout de escritura, consultar el estado real antes de reintentar. Consultas lentas, como firmas IPS, pueden necesitar un timeout mayor.

Caducidad, sustitución y eliminación

Documentar cuenta, trabajo, origen autorizado, creación, caducidad y equipo responsable, nunca la clave. Programar avisos y sustitución antes de caducar; no asumir renovación automática. Reservar un espacio libre para rotación con solapamiento. Con 10 claves propias o 1024 totales, identificar primero las innecesarias con su responsable, sin revocar trabajos activos indiscriminadamente.

Para una sustitución planificada, generar y capturar otra clave con la misma cuenta, cambiar el trabajo y validar una lectura. Después eliminar la clave antigua propia y comprobar que la nueva funciona y la anterior ya no concede acceso. No considerar recuperables las claves eliminadas. Sustituir también una clave cuya visualización única se haya perdido. Ante una posible filtración, revocar inmediatamente aunque interrumpa el servicio. Para claves ajenas, recurrir al responsable del admin predeterminado. Al retirar una integración, eliminar claves y orígenes innecesarios, revisando primero los compartidos.

Límites de SFOS 23.0

El alcance actual excluye de esta API REST:

• Web: Captive portal, Direct proxy authentication, Web filter notification settings, Advanced settings.
• Todas las funciones Email, Wireless y RED.
• Network: DDNS e IP tunnels; SD-WAN profiles.
• VPN: IPsec routes, GRE routes, L2TP, PPTP, clientes y servidores SSL VPN site-to-site.
• Authentication: Guest users y clientless users; Firewall rule groups.
• Let’s Encrypt certificates; High availability y TAP mode; System time.
• Información de estado, como concesiones DHCP, estado HA y almacenamiento de datos.

La lista no es exhaustiva ni promete una versión futura. Verificar cada operación en el esquema actual; un menú visible no demuestra compatibilidad API. XML o cloud no son sustitutos automáticamente equivalentes.

Si el trabajo falla

Para conexión, revisar origen tras NAT, routing, puerto administrativo, TLS, acceso API y Device Access. Para autenticación o permisos, revisar clave, caducidad, eliminación, cuenta creadora y perfil en vez de otorgar todos los derechos. Para errores de esquema, comparar método, ruta, campos obligatorios y referencias dependientes. Una clave perdida se sustituye, no se vuelve a visualizar.

Para escalar, conservar firmware, versión del esquema, hora, endpoint, estado HTTP y respuesta saneada, sin secretos. Sophos admite la API oficial y scripts sin modificar, no asesoramiento ni troubleshooting de integraciones personalizadas. Estas necesitan un responsable interno; recurrir a un partner o Sophos Professional Services cuando sea necesario.