Automatizar de forma segura la API de Sophos Central Endpoint
La API de Sophos Central es adecuada para inventarios recurrentes, cambios masivos controlados y la integración con procesos operativos propios. Sin embargo, no es una segunda interfaz de Reporting sin consecuencias. Dependiendo del rol, una aplicación puede escanear endpoints, modificar grupos, editar políticas, asignar software, migrar dispositivos o iniciar consultas de Live Discover.
Por ello, una automatización segura comienza con tres preguntas: qué tenant se verá afectado, cuál es el permiso mínimo necesario y cómo se puede demostrar y revertir cada cambio.
API Credentials como identidad propia
En Global Settings > Access Control > API Credentials, un Super Admin crea un Service Principal. El nombre y la descripción indican la aplicación, el responsable, la finalidad y la fecha de caducidad. Las credenciales personales de administrador o una cuenta Super Admin no deben utilizarse en scripts.
Sophos ofrece varios roles. Para tareas de Endpoint son especialmente relevantes los siguientes:
| Rol | Uso apropiado | Límite importante |
|---|---|---|
| Service Principal Read-Only | inventario, estado y Reporting | sin cambios ni consultas de Live Discover |
| Service Principal Management | dispositivos, usuarios, políticas y gestión de protección | sin consultas forenses |
| Service Principal Forensics | Live Discover | sin administración general de Endpoint |
| Service Principal Active Directory Sync | sincronización de AD | exclusivamente sincronización de directorios |
| Service Principal Super Admin | casos especiales que requieren expresamente acceso total | máximo daño posible en caso de uso indebido |
El Client Secret solo se muestra una vez y debe guardarse inmediatamente en un Secret Store. Sophos no envía avisos antes de que caduque una API Credential. Tras la caducidad, la entrada se elimina automáticamente y la aplicación no puede volver a autenticarse hasta que se creen nuevas credenciales. Por tanto, la supervisión de la caducidad y la rotación deben realizarse fuera de Central.
Los Legacy API Tokens de la SIEM Integration API están siendo sustituidos. Los tokens existentes solo funcionan hasta su caducidad; las nuevas integraciones utilizan API Credentials.
Autenticación y host de API correcto
Sophos utiliza OAuth2 con Client Credentials Flow. La aplicación envía Client ID y Client Secret al endpoint de Sophos ID y recibe un Bearer Token de duración limitada. El token, el secreto y los Request Headers completos no se escriben en tickets ni en registros sin protección.
Tras la autenticación, primero se consulta la interfaz global Who Am I. Su respuesta proporciona el Tenant ID y el host de API de la región de datos. Solo entonces la aplicación llama a un endpoint regional como api-eu01.central.sophos.com o api-eu02.central.sophos.com. Además del Bearer Token, la solicitud regional necesita el header X-Tenant-ID.
Para una comprobación manual, Central también muestra la región en Profile > Support settings. Como alternativa, puede reconocerse en el hostname de un enlace de descarga del instalador. Las automatizaciones siguen utilizando Who Am I, porque una región leída en la interfaz no es un mecanismo fiable para varios tenants.
Importante: La región no se deduce de la ubicación de la empresa ni del idioma. Un host escrito de forma fija en el script puede ser incorrecto para el siguiente tenant. Who Am I o la lista de tenants es la fuente vinculante.
Las automatizaciones de Partner y Enterprise trabajan con varios tenants. Primero determinan el Partner ID o el Organization ID, leen todos los tenants con su región de datos y después ejecutan la solicitud para cada tenant con su host regional y Tenant ID.
Qué cubren las API de Endpoint
Las interfaces oficiales permiten, entre otras cosas:
- inventariar dispositivos y ejecutar acciones como un scan,
- crear y modificar grupos de Endpoint y asignarles dispositivos,
- crear, clonar y priorizar políticas adicionales y modificar sus ajustes,
- asignar Protection, Device Encryption o ZTNA como software del dispositivo,
- consultar paquetes Recommended, Fixed, LTS y Support disponibles,
- organizar dispositivos mediante tags Key-Value,
- controlar migraciones de Endpoint entre tenants,
- leer resultados de Account Health y ejecutar correcciones compatibles,
- analizar Audit Events, Alerts, XDR Cases y Detections,
- ejecutar consultas guardadas o propias de Live Discover.
No todas las licencias ni todos los roles permiten cada operación. Antes de una automatización con escritura, una llamada Read-Only comprueba que el tenant, los Object IDs, la licencia y el estado actual esperado coincidan.
Algunas APIs tienen límites más restrictivos de lo que su nombre sugiere. La Cases API solo puede crear y modificar actualmente casos self-managed. Sophos indica además un límite flexible de 100 requests por tenant cada 24 horas y 10 requests por usuario y minuto. Al recuperar las detections de un caso, un tamaño de página superior a 50 devuelve 400 Bad Request. La Endpoint Software API solo puede mostrar paquetes para ordenadores y servidores Windows y exige actualmente el rol Service Principal Super Admin. Estos requisitos específicos de cada API se comprueban en su referencia antes de implementarla y no se deducen de roles o límites generales.
Grupos, tags y asignación de software
Los grupos siguen siendo el mecanismo para asignar políticas. Los tags los complementan para el inventario, la búsqueda y los workflows externos. Un tag consta de un Key y un valor opcional. Tanto el Key como el valor pueden tener un máximo de 40 caracteres y no pueden contener dos puntos. Cada Endpoint admite como máximo 15 tags y un mismo Key solo puede tener un valor en un dispositivo.
Una solicitud de tags o software puede contener hasta 1'000 UUID de endpoints. En operaciones Bulk, una respuesta HTTP 200 no significa necesariamente que se haya modificado cada objeto. La aplicación también evalúa los errores parciales de cada dispositivo y no repite ciegamente toda la operación.
En la Device Software API, Protection, Encryption y ZTNA son categorías separadas. All solo asigna la variante con mayor licencia dentro de la categoría indicada; None solo elimina esa categoría. Los Software IDs disponibles se consultan en el Endpoint concreto; distinguen entre mayúsculas y minúsculas y dependen de la licencia y del catálogo del dispositivo.
No tratar las políticas como archivos de texto
La Endpoint Policy API puede leer Base Policies y políticas adicionales. Las políticas adicionales se pueden crear, clonar, actualizar y eliminar. En una Base Policy solo pueden cambiarse los ajustes, no el nombre, la prioridad ni el estado de activación.
Antes de una actualización se guardan el tipo de política, la prioridad actual, las asignaciones y los ajustes existentes. Un PATCH solo contiene las claves modificadas conscientemente. Una automatización no debe sobrescribir ajustes desconocidos o añadidos recientemente por Sophos mediante un objeto completo obsoleto.
Las solicitudes de escritura sobre políticas tienen Rate Limits adicionales por tenant. Una sintaxis correcta tampoco demuestra que el cambio sea operativamente compatible. Igual que en la GUI, se necesitan un grupo piloto, una ventana de cambio, Audit Log y rollback.
Paginación, Rate Limits y reintentos
Las listas deben leerse completamente en todas las páginas. Según la interfaz, las API de Sophos utilizan paginación basada en Offset o en Key. Un script que solo procesa la primera página puede declarar completo un inventario incompleto.
Como valores de referencia o límites, Sophos indica 10 solicitudes por segundo, 100 por minuto, 1'000 por hora y 200'000 por día. Algunas API pueden tener límites más estrictos. Ante 429 Too Many Requests y errores temporales 5xx, se reintenta con backoff exponencial y jitter aleatorio. Una repetición infinita sin cambios es incorrecta para errores de autenticación, autorización o validación.
Cada ejecución registra al menos Tenant ID, operación, número de objetos, IDs correctos y fallidos, momento de la solicitud y un Correlation ID propio. Secrets, Bearer Tokens y contenidos sensibles de la respuesta se eliminan de los registros.
Proceso de implantación seguro
Una automatización nueva comienza en un tenant de prueba o con un pequeño grupo piloto. Primero, el mismo workflow se ejecuta solo en lectura y genera un plan trazable. Después se realiza exactamente un cambio controlado y se verifica tanto mediante la API como en Central, en el dispositivo, en la política efectiva y en Audit Log.
El alcance solo se amplía cuando se han probado los errores parciales, la paginación, los Rate Limits, la caducidad de las credenciales y el rollback. En proyectos puntuales se eliminan las API Credentials al finalizar; las integraciones permanentes reciben un Owner, rotación, Monitoring y un procedimiento documentado de desconexión.
Artículos relacionados
La migración de endpoints entre tenants de Central utiliza un workflow propio de Receiving y Sending. Para grupos de Endpoint e inventario de dispositivos, prioridad de políticas y Live Discover se aplican las mismas reglas técnicas, independientemente de si el cambio se realiza mediante GUI o API.