Asegurar el acceso a la API XML de Sophos Firewall

La API XML de Sophos Firewall es útil para automatización, monitoreo, copias de seguridad, análisis e integraciones. También permite aplicar de forma reproducible la misma configuración a varios firewalls cuando el proceso está estrictamente delimitado y probado. Precisamente por eso, también forma parte de la superficie de ataque de gestión. Permitir acceso a la API otorga a un sistema la capacidad de leer datos de configuración o realizar cambios según los permisos.

Por lo tanto, el acceso a la API no debe permitirse ampliamente desde redes internas o fuentes arbitrarias. Es mejor tener un conjunto pequeño y documentado de redes de gestión, hosts de automatización o accesos de socios fijos.

Desde SFOS 22, Sophos ha ampliado el control de acceso a la API. Las configuraciones de acceso a la API se encuentran en el área de Administration > API access, y las fuentes permitidas pueden definirse como hosts IP. Esto permite modelar no solo direcciones IP individuales, sino también rangos de IP y redes de manera ordenada.

En versiones anteriores de SFOS, la configuración de la API se encontraba en Backup and firmware > API. Este cambio de ruta de menú debe tenerse en cuenta al comparar instrucciones antiguas.

Cuándo es útil el acceso a la API XML

La API XML no es un acceso estándar para el trabajo administrativo normal. Su uso es adecuado cuando hay un proceso técnico concreto detrás.

Casos de uso típicos:

• Monitoreo o inventario.
• Verificaciones de configuración automatizadas.
• Procesos de copia de seguridad o documentación.
• Plataformas MSP o de integración.
• Scripts para tareas administrativas recurrentes.
• Cambios preparados desde herramientas como Sophos Firewall Config Studio.

Si un proceso puede funcionar sin la API, no se debe dejar el acceso a la API activado por precaución. Cada interfaz adicional necesita un propietario, una fuente, un concepto de acceso y un control.

Cambios con SFOS 22

Con SFOS 22, el control de acceso a la API XML se ha vuelto mucho más manejable en operación:

• Las configuraciones de acceso a la API se han movido al menú Administration > API access.
• El acceso a la API está desactivado por defecto y debe activarse conscientemente.
• El acceso a la API puede restringirse a hosts IP.
• Como fuentes, son posibles direcciones IP, rangos de IP y redes.
• Se pueden permitir hasta 64 hosts IP.
• Al actualizar, las direcciones IP permitidas anteriormente se convierten automáticamente en objetos de host IP.
• Los objetos migrados reciben el prefijo apiconfig.

Esto es útil en operación porque las fuentes de la API ya no tienen que mantenerse solo como direcciones individuales sueltas. Se puede nombrar de manera ordenada una red de gestión, un host de automatización o un grupo de hosts dedicado y reconocerlos en revisiones posteriores.

Regla básica: permitir API solo desde fuentes definidas

API access debe tratarse igual que WebAdmin o SSH: tan restringido como sea posible y tan amplio como sea necesario.

Fuentes adecuadas pueden ser:

• un servidor de automatización dedicado,
• un sistema de monitorización,
• un host de gestión de configuración,
• una red interna de gestión,
• una red VPN o de administración,
• una dirección de origen de partner o MSP claramente definida.

No son adecuadas:

• redes de clientes completas,
• redes de invitados o IoT,
• Any,
• permisos imprecisos tipo “toda la red de servidores”,
• direcciones IP temporales de prueba que luego se olvidan.

Si proveedores externos necesitan acceso API, la fuente debe definirse con la mayor precisión posible. Además debe documentarse para qué se usa el acceso y cuándo se eliminará.

Procedimiento recomendado

La ruta exacta en la interfaz puede variar ligeramente según la versión de SFOS. En SFOS 22, la configuración de la API se encuentra en Administration > API access.

Procedimiento práctico:

1. Comprobar qué sistema necesita acceso API.
2. En Hosts and services > IP host, crear un objeto IP Host claro para este sistema.
3. Si se requieren varias fuentes, nombrar correctamente IP Hosts, IP ranges o redes.
4. En Administration > API access, activar API access.
5. En Allowed IP hosts, permitir solo esos objetos.
6. Hacer clic en Apply.
7. No añadir redes amplias de clientes o servidores.
8. Probar el acceso desde el host real de automatización o monitorización, no desde el portátil del administrador.
9. Eliminar las fuentes que ya no sean necesarias.
10. Documentar el cambio en el proceso de change.

En instalaciones existentes después de una actualización a SFOS 22, también se deben buscar objetos con el prefijo apiconfig. Estos objetos se crearon a partir de entradas antiguas de autorización API y deben revisarse, renombrarse o limpiarse.

Probar el acceso de forma dirigida

El endpoint de la API suele estar en:

https://<IP-o-hostname-del-firewall>:<Port>/webconsole/APIController

El puerto es el puerto HTTPS de la WebAdmin Console. Si el puerto de administración se cambió en Administration > Admin settings, la herramienta API debe usar el mismo puerto. La API trabaja con payloads XML mediante HTTP POST, no como una API REST clásica con endpoints GET, POST, PUT y DELETE separados.

HTTPS solo protege de forma fiable las credenciales contra la interceptación y manipulación cuando el cliente valida el certificado del firewall. Por tanto, el sistema de automatización debe usar el nombre incluido en el certificado, confiar en la CA emisora y detenerse ante errores de certificado o hostname. Opciones como curl -k omiten esta comprobación y no deben utilizarse en tareas de producción.

Una prueba útil no solo responde si el inicio de sesión es posible. Debe mostrar si la fuente correcta está permitida, si la cuenta puede ejecutar la operación necesaria y si el resultado queda trazable en el proceso de auditoría o change.

Para la aceptación, comprobar estos puntos por separado:

• Fuente: La prueba se ejecuta desde el host real de automatización, monitorización o integración, no desde el portátil del administrador.
• Acceso: El firewall acepta la IP de origen solo si el objeto IP Host correspondiente está permitido en API access.
• Prueba negativa: Desde un host de prueba controlado, excluido deliberadamente de Allowed IP hosts, enviar la misma solicitud de lectura inocua y comprobar que la API la rechaza sin devolver datos de configuración. No ampliar ni eliminar un permiso de producción solo para crear este caso de prueba.
• Cuenta: La cuenta API o de servicio utilizada tiene solo los permisos necesarios.
• Secreto: Usuario, contraseña o token no terminan en el historial de shell, tickets, chats o capturas de pantalla.
• Auditoría: El acceso o el cambio queda trazable en el proceso de auditoría o change.
• Rollback: Antes de operaciones de escritura existen un backup, un punto de rollback y una prueba de lectura inofensiva.

Los ejemplos curl con usuario y contraseña en la URL se copian rápido y luego son difíciles de eliminar de los registros. Es mejor una prueba breve con una cuenta de servicio dedicada, un secreto temporal, almacenamiento seguro y rotación posterior si un secreto se usó en un contexto no seguro.

Para pruebas estructuradas, una colección Postman suele ser más limpia que un comando shell copiado rápidamente. También allí, dirección del firewall, puerto, usuario, contraseña y valores de objetos deben mantenerse como variables o secretos, no codificados en requests, capturas o tickets. La colección no es un concepto de seguridad, pero ayuda a probar operaciones de lectura y escritura de forma más reproducible.

Una API accesible aún no demuestra que el cambio previsto sea técnicamente seguro. Antes de operaciones de escritura en producción debe funcionar primero una consulta de lectura inofensiva y después probarse un pequeño cambio controlado.

Construir y evaluar conscientemente las solicitudes XML

Límite de versión: Las instrucciones de SFOS 22 incluyen navegadores como clientes XML. Desde SFOS 23.0, la guía específica para enviar solicitudes XML excluye expresamente los navegadores; usar Postman o una línea de comandos Linux controlada para estos POST. El resumen general de XML todavía menciona navegadores, pero no autoriza POST desde navegador en SFOS 23.0. La API REST local con claves de administrador es una interfaz distinta, no otro método de autenticación para estos payloads XML.

Las consultas y los cambios mostrados aquí utilizan HTTP POST hacia el mismo APIController. La acción de leer, crear, actualizar o eliminar se define en el payload XML, no mediante el método HTTP. XML <Get> indica lectura, no automáticamente HTTP GET; la consulta Object Usage denominada «API GET request» también se envía por HTTP POST. La exportación de certificados descrita abajo es una excepción HTTP GET documentada por separado. La estructura externa consta de <Request>, <Login> y exactamente la operación necesaria:

• <Set operation="add"> crea objetos, reglas o políticas compatibles.
• <Set operation="update"> modifica ajustes que no se pueden crear como objetos nuevos.
• <Get> lee configuraciones o datos de estado.
• <Remove> elimina objetos compatibles. Los ajustes fijos, como la configuración de SSL/TLS Inspection, no se pueden eliminar, solo actualizar.
• <Filter> limita una consulta de lectura. La referencia XML general solo documenta el nombre del objeto Name, con los criterios =, != y like y la sintaxis <key name="Name" ...>. Las estadísticas de Object Usage, documentadas por separado, admiten otras claves y criterios; no trasladarlos a las consultas de objetos normales.

En las operaciones de escritura, no confiar en la omisión de operation en <Set>. La documentación describe el valor omitido de forma contradictoria: el resumen de XML indica add, mientras que la referencia XML completa de SFOS 22 y 23 indica Add seguido de Update. Esto no permite deducir ni un valor predeterminado de solo creación comprobado mediante pruebas ni un comportamiento universal de upsert o sobrescritura. Utilizar únicamente una operación explícita que API help confirme para el objeto correspondiente y el build instalado; si no se aclara, no ejecutar la solicitud de escritura y consultar con Support. APIXMLTags documenta el atributo alfanumérico opcional transactionid en <Set>; facilita la correlación entre la solicitud y la respuesta. Para las operaciones especializadas, debe seguirse el ejemplo del objeto en API help del build de SFOS instalado. El ejemplo de certificados sitúa transactionid en <Certificate>; esta excepción no establece una regla general para colocarlo en las etiquetas de objeto dentro de <Set>.

APIVersion en <Request> es específico de la versión: la referencia XML de SFOS 22 muestra 2200.1 y la de SFOS 23, 2300.1. Son ejemplos de la documentación, no una recomendación de utilizar ese valor en todos los builds. Según la referencia, APIVersion en <Response> contiene el valor indicado en la solicitud; si se omite en ella, se tiene en cuenta la versión de API del firmware activo. Al mismo tiempo, el apartado sobre las solicitudes considera necesario indicar la versión, mientras que los ejemplos posteriores la omiten. Esta contradicción interna no demuestra que sea universalmente obligatoria ni universalmente opcional durante la ejecución. Por ello, las etiquetas de objeto, los atributos, los códigos de estado y las configuraciones de ejemplo exactos deben proceder de API help del build de SFOS instalado; confirmar la versión y la compatibilidad del objeto antes de su uso y no trasladar payloads entre versiones sin verificarlos.

Una pequeña consulta de lectura tiene esta estructura básica:

<Request>
  <Login>
    <Username>api-reader</Username>
    <Password>SECRET</Password>
  </Login>
  <Get>
    <IPHost></IPHost>
  </Get>
</Request>

api-reader y SECRET son marcadores de posición. El secreto real debe guardarse en el almacén de secretos protegido de la herramienta, no en un archivo XML del repositorio. La prueba solo es satisfactoria si la respuesta contiene el resultado esperado en <Response> y un estado adecuado en <Status>. Un éxito HTTP o Send successful en Postman no demuestra por sí solo que SFOS haya ejecutado la operación prevista. En operaciones de escritura, comprobar también el objeto de destino en WebAdmin y el cambio en Audit Trail.

Los siguientes valores son códigos de estado XML documentados en el atributo code de <Status>, no códigos de estado HTTP. El mensaje y Status Message Information del objeto correspondiente en el build instalado determinan su interpretación exacta:

• 200: configuración aplicada correctamente; 201: operación solo parcialmente correcta. Con 203, la operación se realizó correctamente, pero algunas configuraciones no se aplicaron; la referencia indica que se debe contactar con Support. 204–210 indican un fallo parcial, no un éxito completo.
• 211–215: advertencias; 216: éxito cuya interpretación se explica para el objeto concreto. En ambos casos, leer la sección Status Message Information correspondiente, en lugar de tratar todos los valores XML 2xx como una aplicación completa y correcta de la configuración.
• 500: no se puede realizar la operación sobre el objeto; 501: fallo en la validación de parámetros; 502: ya existe ese nombre; 503: ya existen los mismos parámetros. Con 504–510, una referencia desde otro objeto impide la eliminación; comprobar primero las dependencias. Para 511–520, la referencia exige consultar con Support.
• 521: solicitud incompatible con la versión actual de la API; 522–525: límite de objetos alcanzado; 526: el registro no existe; 528: objeto predeterminado no editable; 529: XML no válido para el objeto; 530: versión de API no compatible con este objeto. 541–590 son errores específicos del objeto con más información en Status Message Information; 599 indica que faltan permisos para crear o modificar.

Ante un éxito parcial o advertencias, contrastar la respuesta con el estado real del objeto antes de volver a intentar una escritura; no dar por hecho que todo se ha aplicado ni que un reintento sea inocuo. Compartir con Support únicamente respuestas y logs de los que se hayan eliminado los datos sensibles.

Utilizar de forma segura la colección oficial de Postman

Descargar e importar la colección de Postman actual. La colección solo cubre una parte de las solicitudes admitidas; la API help local del firewall muestra el conjunto completo de operaciones y las configuraciones de ejemplo y definiciones de entidades específicas del build. Antes de la primera solicitud, sustituir en Collection Variables los cuatro valores de ejemplo incluidos apiadmin, Admin@12345, 172.16.16.16 y 4444 por los valores username, password, firewall-ip y firewall-port del entorno. Los valores de objetos incluidos también son ejemplos y no deben enviarse sin revisarlos.

Para una solicitud propia se utiliza el método POST, el endpoint mostrado arriba y la clave reqxml en Body > form-data. Probar primero Authenticate > Sign in y después una consulta <Get> inofensiva. Solo cuando origen, cuenta, respuesta y auditoría sean correctos debe realizarse una pequeña operación de escritura con rollback preparado.

Importaciones XML sensibles: Antes de importar contraseñas u otros valores sensibles, comprobar en API help del build instalado si la operación concreta requiere SecureStorageMasterKey y el atributo Token en <Request>, y qué datos son válidos. En el ejemplo POST de SFOS 23, SecureStorageMasterKey es un dato separado del cuerpo; Token figura en <Request> dentro del XML del campo reqxml del cuerpo. Enviar únicamente los datos confirmados para esa operación en las ubicaciones POST/XML aprobadas. En este flujo, mantener claves, contraseñas y tokens fuera de las URL, el historial de la shell y los logs; esto no implica que cada consulta XML requiera un token.

En cuanto a su procedencia, la referencia XML describe SecureStorageMasterKey como la clave maestra del firewall de origen, desde el que se exportó la configuración. Según la referencia, sin esta clave no se importan los datos sensibles, como las contraseñas, ni los ajustes que dependen de ellos; si no se dispone de la clave, indica que se debe consultar al administrador predeterminado con nombre de usuario admin. Token y los valores de contraseña cifrados proceden del resultado de Get o de exportación documentado. La marca hashform="mode1", por ejemplo en <Password>, identifica allí un valor de contraseña cifrado; la referencia también contempla una contraseña sin cifrar como alternativa. Esta información explica la procedencia y la interpretación, pero no autoriza a copiar texto cifrado, tokens ni marcadores entre objetos y builds arbitrarios. XML <Get> no permite automáticamente utilizar el método HTTP GET. Aquí no se introduce ningún comando nuevo de importación o exportación; siguen siendo obligatorias la confirmación específica para el objeto y el build y la detención indicada a continuación si los datos de entrada no están aclarados.

La documentación también conserva un ejemplo de URL contradictorio para la clave maestra. Mientras siga sin resolverse un conflicto entre fuentes, un dato requerido o su interpretación para el build instalado, no ejecutar la importación sensible y solicitar una aclaración a Support. La exportación de certificados mediante HTTP GET descrita abajo, con sus precauciones específicas, sigue siendo una excepción distinta.

Una colección exportada puede contener credenciales o valores del entorno. Limpiar las colecciones antes de compartirlas, no guardar secretos en texto claro como Initial Values y rotar las contraseñas de prueba después de una filtración.

Consultar Object Usage antes de realizar cambios

La API puede devolver los nombres y el Usage Count de los objetos compatibles. Para ello se utilizan tags de estadísticas como <IPHostStatistics> en lugar del tag normal del objeto. Un filtro por nombres de IP Host tiene este aspecto:

<Request>
  <Login>
    <Username>api-reader</Username>
    <Password>SECRET</Password>
  </Login>
  <Get>
    <IPHostStatistics>
      <Filter>
        <key name="Name" criteria="like">branch</key>
      </Filter>
    </IPHostStatistics>
  </Get>
</Request>

SFOS 22 admite esta consulta de uso para IP Hosts, IP Host Groups, MAC Hosts, FQDN Hosts y sus grupos, Country Groups, Services y Service Groups, así como Interfaces, Zones, Gateways y SD-WAN Profiles. Los filtros de nombre incluyen like, not like, startswith, in, = y !=; el Usage Count admite además >, >= y listas numéricas con in.

Actualmente, la respuesta solo contiene el nombre del objeto y el número de usos, no las configuraciones dependientes. Por tanto, un Usage Count de 3 no identifica las tres reglas o perfiles afectados. Antes de una operación update o remove, comprobar también Object usage en WebAdmin o Config Studio. Un valor de 0 tampoco autoriza una eliminación sin control: backup, comprobación de dependencias y prueba limitada siguen siendo obligatorios.

En WebAdmin, Usage aparece para interfaces, zonas, gateways, perfiles SD-WAN y hosts y servicios. El contador se actualiza una vez al día; antes de un cambio, actualizarlo con el control junto a Usage. Pulsar el contador del objeto, desplegar la categoría correspondiente y abrir la regla o política indicada para sustituir o eliminar allí el objeto. Esto elimina la referencia, no automáticamente el objeto. Algunas configuraciones de gateways WAN y de CLI no se pueden editar desde la ventana de Object Usage; usar su página de configuración o la CLI.

Iniciar y cerrar sesiones de Live Users mediante la API

SFOS puede iniciar o cerrar la sesión de un usuario como Live User mediante la API. Esto resulta útil para una integración con un sistema de autenticación externo que tenga una responsabilidad claramente definida, pero no es un atajo general para evitar el inicio de sesión normal. Un login incorrecto asigna tráfico a una identidad y puede afectar a reglas de firewall o web basadas en usuarios.

Para el administrador que ejecuta la operación, Manage live users debe estar en Read-write bajo Profiles > Device access > Identity. El endpoint previsto es:

https://<Firewall-IP-o-FQDN>:<Port>/xmlapi/v1/authentication/networkuser

Este endpoint procesa los inicios y cierres de sesión en paralelo. El APIController general puede procesar las mismas operaciones de forma secuencial. Por tanto, una integración existente no debe migrarse sin pruebas solo por esta diferencia de comportamiento.

Un payload de inicio de sesión puede tener este aspecto:

<Request>
  <LiveUserLogin>
    <Admin>
      <UserName>api-liveusers</UserName>
      <Password>ADMIN_SECRET</Password>
    </Admin>
    <UserName>testuser</UserName>
    <IPAddress>192.0.2.25</IPAddress>
    <MacAddress>AA-BB-CC-DD-EE-FF</MacAddress>
  </LiveUserLogin>
</Request>

Para cerrar la sesión, se envía el mismo usuario lógico con LiveUserLogout:

<Request>
  <LiveUserLogout>
    <Admin>
      <UserName>api-liveusers</UserName>
      <Password>ADMIN_SECRET</Password>
    </Admin>
    <UserName>testuser</UserName>
    <IPAddress>192.0.2.25</IPAddress>
    <MacAddress>AA-BB-CC-DD-EE-FF</MacAddress>
  </LiveUserLogout>
</Request>

api-liveusers, ADMIN_SECRET, testuser, 192.0.2.25 y la dirección MAC son valores de ejemplo. El nombre de usuario, la IP y la MAC deben corresponder a la sesión real. El secreto de administrador debe guardarse en el almacén de secretos protegido de la herramienta y enviarse en el cuerpo HTTP POST, no en una URL, el historial de la shell, un archivo de log o una colección compartida.

Tras el inicio de sesión, el usuario debe aparecer en Current activities > Live users con Client type API client. Una prueba controlada comprueba después la decisión esperada de la regla basada en usuarios. Tras el cierre de sesión, la sesión ya no debe figurar como cliente API activo. Si el usuario sigue visible, hay que comprobar primero el payload, el nombre de usuario, la IP, la MAC y la respuesta de la API; no se debe cerrar por sospecha una sesión de Live User ajena.

Transferir o exportar certificados mediante la API

En Postman, crear una solicitud con New > HTTP Request, asignarle un nombre con Save y guardarla en una colección. Usar POST y el endpoint APIController anterior con el puerto WebAdmin real. La aplicación de escritorio envía por defecto desde ese equipo; permitir su IP de origen tal como la ve el firewall. En Body > form-data, crear una entrada con nombre de tipo File para el certificado y otra para la clave privada, y seleccionar los archivos locales; la tercera entrada, reqxml, es de tipo Text. Guardar los archivos en una ubicación local con acceso restringido, no en una carpeta sincronizada con la nube.

El ejemplo de Postman utiliza C:/Users/[yourname]/Postman/files como ubicación en Windows. Sustituir [yourname] y comprobar las restricciones de acceso y el acceso local a archivos de la aplicación; esta ruta no es un parámetro general de SFOS.

⚠️ Ejemplo del fabricante con fines documentales, no autorizado para su ejecución: El siguiente payload de certificado PEM para reqxml omite operation en <Set>. Debido a las descripciones contradictorias del comportamiento predeterminado, no enviarlo, ni siquiera para crear un certificado nuevo. Aclarar primero la operación explícita y el payload completo del certificado para el objeto y el build instalado en API help o con Support. Todos los nombres de cuenta, secreto, objeto y archivos son valores de ejemplo:

<Request><Login><Username>api-certificates</Username><Password>SECRET</Password></Login><Set><Certificate transactionid="10"><Name>TestCertificate</Name><Action>UploadCertificate</Action><CertificateFormat>pem</CertificateFormat><CertificateFile>TestCertificate.pem</CertificateFile><PrivateKeyFile>TestCertificate.key</PrivateKeyFile></Certificate></Set></Request>

CertificateFile y PrivateKeyFile identifican los archivos seleccionados para la carga. El atributo opcional transactionid permite relacionar esta solicitud con su respuesta. La omisión de operation no demuestra que se trate de una creación ni de una actualización; el ejemplo del fabricante, conservado sin cambios, sigue bloqueado hasta que se aclare su uso para el objeto y el build concretos. Especialmente si el certificado ya existe, consultar el payload de actualización exacto en API help y no reenviarlo a ciegas. Enviar un payload confirmado únicamente después de esta aclaración; después, comprobar la respuesta en Body y, a continuación, el certificado de destino en WebAdmin.

Los certificados son un caso especial porque, además de XML, se transfieren archivos. Para un payload de creación o actualización confirmado, se utiliza en la aplicación de escritorio de Postman una solicitud form-data con tres partes: el archivo del certificado, el archivo de la clave privada y reqxml con la operación explícita confirmada en <Set> y los campos <Certificate> correspondientes. La estructura abreviada del ejemplo bloqueado no es una plantilla ejecutable. Los nombres de archivo, el formato, la acción y el nombre del certificado en el XML deben coincidir con los archivos cargados.

Las Private Keys deben permanecer exclusivamente en el endpoint de administración protegido y nunca llegar a una colección cloud, un ticket o un repositorio. Después de Send, evaluar primero <Response> y <Status>; después comprobar en Certificates > Certificates que estén presentes exactamente el certificado esperado, la clave correspondiente y la cadena correcta. La asignación y la prueba del servicio siguen el procedimiento Importar y asignar certificados en Sophos Firewall. El recorrido completo de automatización, desde la CA pública y la carga específica de la versión hasta la asignación al servicio y la verificación externa, se describe en Renovar un certificado de Sophos Firewall mediante la API XML y verificar los servicios.

Una solicitud <Get><Certificate/></Get> devuelve un archivo .tar con certificados, Private Keys y Entities.xml, no un resultado XML normal. Por eso no funciona como respuesta normal de Postman. La guía específica documenta HTTP GET desde Linux o un navegador; ambas variantes incluyen credenciales en el reqxml de la URL.

SFOS 23.0: Esta guía GET todavía menciona navegadores, mientras la guía POST los excluye. Esto no demuestra una prohibición de todos los HTTP GET ni una exportación por navegador probada en este firmware. No trasladar instrucciones de navegador de versiones anteriores ni asumir que POST produce la misma descarga. Antes de exportar, verificar con Support o en un sistema de prueba autorizado la ruta CLI GET y el manejo seguro de credenciales para el build instalado; sin esa verificación, no ejecutar la exportación.

Para una exportación verificada, usar solo una cuenta temporal de permisos limitados en un host protegido, no registrar URL ni comando y rotar después el secreto. Validar certificado TLS y hostname; no trasladar -k de los ejemplos del fabricante a producción. El archivo es altamente sensible: guardarlo cifrado con acceso restringido, extraerlo de forma controlada y eliminar con seguridad las copias innecesarias.

Para una exportación CLI autorizada, definir una ruta de salida local explícita para filename.tar. Antes de extraer, comprobar las entradas con tar -tf filename.tar; no aceptar rutas ni enlaces inesperados. Extraer con tar -xvf filename.tar únicamente dentro de un directorio de destino vacío y con acceso restringido. filename.tar es un marcador de posición. La salida de estos comandos puede revelar nombres de archivo sensibles y no debe llegar a logs públicos.

Acceso a la API y derechos de usuario

Una IP de origen por sí sola no es un concepto de seguridad completo. La restricción solo limita desde dónde es accesible la API. Además, debe estar claro con qué cuenta se realiza el acceso a la API y qué derechos tiene esa cuenta.

Para entornos productivos, se debe verificar:

• ¿Se utiliza una cuenta de servicio o API propia?
• ¿La cuenta solo tiene los permisos necesarios?
• ¿Está claramente documentado qué persona o equipo es responsable de la cuenta?
• ¿Se almacena la contraseña o secreto de manera segura?
• ¿Se elimina el acceso cuando la integración ya no se utiliza?
• ¿Son rastreables los cambios a través de registros de auditoría?

Las cuentas de administrador compartidas son problemáticas para los procesos de API. Si varios sistemas o personas utilizan la misma cuenta, la trazabilidad se debilita. Para los análisis de cambios, es relevante revisar los registros de auditoría de Sophos Firewall.

Para una cuenta API dedicada, un proceso restringido es mejor que copiar rápidamente un administrador completo. Configurar de forma segura administradores y perfiles en Sophos Firewall explica la planificación general de cuentas personales y perfiles restringidos; para las automatizaciones sigue siendo determinante la cuenta de servicio independiente descrita aquí. En la documentación de Sophos este bloque aparece como Allow API access to administrators: no solo se permite la fuente, también el administrador o el perfil debe tener el acceso adecuado.

1. Crear un perfil de administrador con los permisos necesarios en Profiles > Device access.
2. Crear un usuario administrador para el proceso API en Authentication > Users.
3. Asignar el perfil de administrador correspondiente.
4. Para el acceso temporal a la API, designar un responsable y programar la eliminación manual de la cuenta API dedicada y/o de la autorización de origen dedicada para la API al finalizar el periodo aprobado; después, comprobar que ese acceso a la API se ha revocado sin desactivar accesos compartidos legítimos. Access Time para usuarios normales controla el acceso a internet; Schedule for device access para administradores controla los inicios de sesión en WebAdmin. Aquí no se documenta que ninguno de estos ajustes permita la caducidad automática del acceso a la API XML: no confiar en ellos para finalizar el acceso a la API. Si se necesita aplicar un horario, obtener antes una confirmación en la documentación primaria de la compilación instalada o mediante una verificación autorizada.
5. Si es posible, restringir Login restriction for device access a las fuentes previstas.
6. Después permitir API access y Device Access para la fuente correspondiente.

En el ejemplo oficial, el perfil recibe Read-write para Objects y Network. No es una recomendación general: para integraciones de solo lectura y otras tareas de API, las áreas innecesarias permanecen en None o Read-only; el permiso de escritura solo se concede después de una prueba de lectura controlada.

Sophos soporta las APIs oficiales y los scripts de ejemplo sin modificar. El soporte técnico de Sophos no ofrece asesoramiento ni resolución de problemas para integraciones personalizadas; Sophos remite este trabajo al Sophos Partner responsable o a Sophos Professional Services. Por ello, las integraciones, wrappers y automatizaciones propias necesitan un responsable interno, pruebas y un concepto de rollback. “Funciona en el lab” no es suficiente para operaciones de escritura en producción.

Los permisos de perfil no autorizan el origen: Los perfiles de Profiles > Device access se aplican a WebAdmin y API; la ACL de servicios locales de Administration > Device access es un control distinto. Los perfiles predeterminados no se pueden editar. Usar Edit para consultar los permisos; crear y editar un perfil personalizado para ajustarlos. Antes de eliminar un perfil, retirarlo de todos los administradores. Cada área admite None, Read-only o Read-write. Con None, la configuración no es visible en WebAdmin ni accesible por API; la falta de datos de API no implica necesariamente un fallo de red.

Los perfiles predeterminados tienen alcances distintos: Administrator, incluida la cuenta predeterminada admin, tiene acceso completo a WebAdmin y CLI, todos los tipos de solicitud API y puede crear administradores. Audit admin tiene Read-write para logs e informes; Crypto admin, para certificados de seguridad. HAProfile tiene acceso Read-only al equipo Auxiliary si HA está configurada. Security admin tiene Read-write para todas las funciones salvo perfiles, logs e informes. No asumir que uno de ellos es un perfil API de privilegios mínimos; comprobar los permisos efectivos del objeto necesario.

MFA y usuarios API después de SFOS 22

La MFA es importante para accesos administrativos interactivos. Para procesos API y de automatización, sin embargo, hay que planificar conscientemente cómo debe funcionar la autenticación. Un script, herramienta de monitorización o sistema de integración no puede introducir sin más un código OTP si la cuenta usada exige MFA.

La lista actual de Known Issues documenta NC-177609 para SFOS 22.0.0 GA Respin Build 411: tras una actualización, los cambios de configuración basados en API pueden fallar para usuarios migrados si MFA está activa y no se entrega un one-time token. Los usuarios no migrados mantienen el comportamiento anterior hasta completar el onboarding de MFA. El workaround oficial es una cuenta API separada sin MFA o excluir esa cuenta de MFA. Esto no justifica desactivar MFA para administradores interactivos; en builds posteriores, revisar primero las Release Notes y Known Issues.

Enfoque recomendado:

1. Usar una cuenta de servicio propia para procesos API.
2. Conceder a la cuenta solo los permisos necesarios.
3. Limitar además API access a IP Hosts fijos o redes de gestión.
4. Comprobar si MFA es técnica y operativamente razonable para esta cuenta.
5. Si MFA no es práctica para la cuenta API, controlar la cuenta de forma especialmente estricta mediante fuente, permisos, almacenamiento de secretos y audit trail.
6. Tras una actualización a SFOS 22, probar todos los procesos API con operaciones de lectura y escritura.

⚠️ Los usuarios API sin MFA no son una vía libre para permisos amplios. Si por motivos técnicos una cuenta API funciona sin MFA, la IP de origen, los permisos, el almacenamiento de contraseñas, la responsabilidad y la auditabilidad deben controlarse más estrictamente.

Este punto es especialmente importante en automatizaciones que no solo leen, sino que también cambian configuración.

Antes de cambios API en producción, comprobar al menos tres cosas:

• Existe un backup de Sophos Firewall actual.
• La cuenta API prevista puede ejecutar correctamente una consulta de lectura inofensiva.
• En cambios masivos preparados con Sophos Firewall Config Studio, las llamadas API o curl generadas funcionan con la cuenta prevista.

Distinción con Device Access

El control de acceso a la API no es lo mismo que Device Access, pero ambos controles interactúan. Device Access controla servicios locales del firewall como WebAdmin, SSH, User Portal, VPN Portal, DNS o Ping. Los ajustes de API access controlan además qué hosts IP pueden usar la API XML. Importante: los permisos de Device Access para la WebAdmin Console también se aplican al acceso API.

En la práctica, API access debe estar habilitado, la fuente debe estar permitida en sus ajustes y Device Access no debe bloquear el acceso de gestión local al firewall. Cada capa limita una parte diferente de la superficie de ataque:

• Configurar correctamente Device Access: servicios locales de firewall como WebAdmin, SSH, User Portal, VPN Portal, DNS o Ping
• Control de acceso a la API: hosts IP que también pueden usar la API XML
• Activar MFA para Sophos Firewall WebAdmin, VPN Portal y Remote Access: Inicios de sesión interactivos para WebAdmin, VPN Portal y Remote Access
• Administradores nombrados y roles claros: Trazabilidad y radio de daño de cuentas de administrador y servicio

Si una red de administración puede utilizar WebAdmin, SSH y API, esa red debe estar especialmente bien protegida. Un cliente comprometido en la red de gestión es de otro modo una entrada directa a la gestión del firewall.

Para el acceso desde WAN, no se debe habilitar HTTPS/WebAdmin para toda la zona WAN. Si realmente se necesita acceso externo a la API o a la administración, debe utilizarse una Local service ACL exception rule con una Source restringida, el Service HTTPS adecuado, una posición de regla definida y un periodo documentado.

HA: comprobar el acceso después de un failover

En un clúster HA, la configuración del firewall se sincroniza del Primary al Auxiliary; el enlace HA dedicado y los Administration Ports no se sincronizan. Por tanto, los clientes API deben usar el nombre de clúster o la dirección de interfaz compartida previstos y no depender inadvertidamente de una IP de administración específica de un nodo.

Después de configurar HA, cambiar el certificado o producirse un failover, repetir una prueba de lectura y una prueba negativa. Comprobar la resolución DNS, el nombre del certificado, la IP de origen, el puerto admin, API access y Device Access. Un objeto host sincronizado no demuestra por sí solo que toda la ruta de red y TLS funcione tras el cambio de roles.

Operación y revisión

El acceso a la API debe revisarse regularmente. Especialmente después de migraciones, cambios de proveedores, proyectos de automatización o actualizaciones de firewall, a menudo quedan fuentes antiguas.

Preguntas de revisión útiles:

• ¿Qué hosts IP pueden actualmente utilizar el acceso a la API?
• ¿Existen objetos con el prefijo apiconfig?
• ¿Son necesarios estos objetos?
• ¿Coinciden los nombres y descripciones con el propósito real?
• ¿Existen responsables documentados?
• ¿Se consideran los accesos a la API en un proceso de cambio o auditoría?
• ¿Existe una copia de seguridad actual antes de cambios importantes basados en API?

Antes de cambios basados en API, siempre debe haber una copia de seguridad. El artículo Crear o restaurar una copia de seguridad de Sophos Firewall describe en qué se debe prestar atención en cuanto a copia de seguridad, restauración y compatibilidad.

Errores típicos

• API access permitido para toda una red de clientes: Cualquier cliente comprometido de esa red puede alcanzar la API.
• Objetos apiconfig antiguos sin revisar: Excepciones heredadas migradas permanecen activas sin notarse.
• La cuenta de servicio usa permisos de administrador completos: Un secreto comprometido tiene un radio de daño innecesariamente grande.
• La automatización API usa un administrador con MFA obligatoria: El script o la herramienta pueden fallar en operaciones de escritura tras una actualización SFOS.
• Puerto incorrecto en la herramienta: El puerto HTTPS de administración se cambió, pero la herramienta sigue usando el puerto antiguo.
• Se espera lógica REST: La herramienta envía métodos REST en lugar de payload XML mediante HTTP POST a APIController.
• Solo se comprobó el estado HTTP: La operación real de la API falló aunque el transporte fuera correcto. Evaluar <Response> y <Status>.
• Set se envió sin operación: No confiar en un valor predeterminado ni repetir la solicitud a ciegas. Las descripciones documentadas se contradicen; antes de cualquier escritura, confirmar la operación explícita para el objeto y el build; de lo contrario, detenerse.
• No se pueden importar configuraciones o tokens MFA: El payload debe contener el elemento vacío <tokenid/>.
• No se puede eliminar un usuario: En el payload <Remove>, indicar el nombre de usuario exacto como <Name>username</Name>. Antes de enviar la solicitud, verificar la cuenta, las dependencias, el backup y el rollback.
• Usage Count se interpretó como una lista completa de dependencias: La estadística devuelve número y nombre, pero no las reglas o perfiles afectados.
• Se inicia un Live User sin correlacionar la sesión: El nombre de usuario, la IP y la MAC no corresponden a la sesión real, por lo que las reglas basadas en usuarios pueden decidir de forma incorrecta.
• El archivo de certificados se almacenó sin protección: La exportación de API puede contener Private Keys y no debe guardarse en Descargas, tickets ni ubicaciones compartidas.
• IP temporal del proveedor sigue activa: El acceso externo sigue siendo posible durante más tiempo del previsto.
• No hay documentación del propósito: Administradores posteriores no saben si la autorización sigue siendo necesaria.
• Cambios API sin backup: Una automatización defectuosa es más difícil de revertir.

Solución de problemas

Si una herramienta no alcanza la API XML, se debe verificar de manera estructurada:

1. ¿La IP de origen es correcta desde la perspectiva del firewall?
2. ¿La fuente está permitida como host IP, rango de IP o red?
3. ¿Se generó un objeto apiconfig después de una actualización, pero no se ajustó adecuadamente?
4. ¿Device Access permite el acceso local WebAdmin/API desde esta zona?
5. ¿La herramienta usa la dirección correcta del firewall y el puerto HTTPS de administración correcto?
6. ¿Son correctos el nombre de usuario, contraseña o secreto?
7. ¿La cuenta tiene los derechos necesarios?
8. ¿La cuenta impone MFA, aunque la herramienta no puede proporcionar un token de un solo uso?
9. ¿Existen efectos de enrutamiento, NAT o proxy entre la herramienta y el firewall?
10. ¿Se eliminó el acceso intencionalmente mediante una medida de endurecimiento?
11. ¿La prueba se realizó desde el sistema de origen correcto o solo desde el cliente de administración?

Si un cambio en la API tiene efectos inesperados, primero asegure la última copia de seguridad y luego revise el registro de auditoría, la comparación de Config Studio y los objetos de firewall afectados. En problemas de tráfico en vivo, el Log Viewer y el Packet Capture son más útiles que la propia API.

Ante una operación XML rechazada o defectuosa, guardar primero <Response> y <Status>. Después revisar apiparser.log, validation.log y validationError.log en Diagnostics > Tools > Troubleshooting logs; Sophos asigna estos archivos a la traducción y validación de la API. Archivos de servicio y logs de Sophos Firewall explica el filtrado y la exportación. Eliminar los secretos antes de compartir un fragmento de log.

Lista de verificación

Antes de la activación:

• Documentar el propósito del acceso a la API.
• Determinar claramente el sistema de origen.
• Crear un objeto de host IP con un nombre descriptivo.
• Verificar la cuenta de servicio y los permisos.
• Establecer conscientemente el comportamiento de MFA de la cuenta de API.
• Establecer un proceso de copia de seguridad y reversión.
• Definir un método de prueba sin fuga de secretos.
• Documentar la operación XML prevista y el <Status> esperado.

Durante la operación:

• Permitir acceso a la API solo para fuentes definidas.
• No permitir redes amplias de clientes, invitados o IoT.
• Revisar objetos apiconfig después de actualizaciones.
• Controlar accesos de proveedores en términos de tiempo y función.
• Almacenar secretos de manera segura y renovarlos en caso de cambios de personal o herramientas.
• Rotar los secretos si han acabado en el historial de shell, tickets o ubicaciones inseguras.
• Probar operaciones de lectura y escritura de API después de actualizaciones de SFOS.
• Comprobar Object Usage y las configuraciones dependientes antes de operaciones update o remove.
• Validar los inicios de sesión de Live Users mediante API con API client, la decisión de regla y un cierre de sesión limpio.
• Procesar archivos de certificado, Private Keys y exportaciones de API únicamente en ubicaciones protegidas.

Durante la revisión:

• Revisar regularmente las fuentes de API permitidas.
• Eliminar hosts IP que ya no se necesiten.
• Comparar cambios con el registro de auditoría y tickets de cambio.
• Probar procesos de automatización después de actualizaciones de firmware.

FAQ