Automatizar de forma segura la API de Sophos Fusion Endpoint

La API de Sophos Fusion Endpoint es la API de tenant para recursos Endpoint y de servidor. Permite inventariar dispositivos y, según el endpoint y los permisos, gestionar escaneos, aislamiento, grupos, políticas, exclusiones, tags y asignaciones de software. La escritura afecta a la protección; para un inventario basta una identidad Read-Only.

El camino rápido y seguro consiste en usar una API Credential con el rol mínimo, obtener un token mediante OAuth2 Client Credentials Flow, descubrir el Tenant ID y el host regional, probar primero GET /endpoint/v1/endpoints y procesar todas las páginas y errores.

Límite con Sophos Fusion Admin y otras APIs

Crear, guardar, rotar y eliminar Service Principals es una tarea común de Sophos Fusion Admin. El proceso completo se explica en Gestionar de forma segura las credenciales de la API de Sophos Fusion, en lugar de duplicarlo aquí.

Las listas de tenants de Partner y Organization, Alerts, Audit Events, Account Health, Cases y Live Discover tampoco pertenecen automáticamente a la Endpoint API. Sophos Fusion (antes Sophos Central) ofrece APIs separadas con sus propios roles y límites. Este artículo solo trata solicitudes bajo la ruta regional /endpoint/v1.

Autenticación y contexto de la solicitud

El artículo Owner enlazado define exclusivamente el contrato Request/Response del token, whoami, las listas Partner/Enterprise, la validación del host y el tratamiento de secretos. Se reutilizan sin cambios SOPHOS_ACCESS_TOKEN, SOPHOS_TENANT_ID y SOPHOS_API_HOST. scope=token no sustituye la autorización: también se aplican rol de Service Principal, acceso al tenant, licencia y permiso Endpoint; Partner Assistance o Enterprise Admin Management debe permitir el tenant objetivo.

Realizar una lectura inocua

Este ejemplo no inventa tokens ni datos. Espera tres valores de su propio proceso de credenciales y descubrimiento y guarda la primera página en un archivo local:

: "${SOPHOS_ACCESS_TOKEN:?Bearer token is missing}"
: "${SOPHOS_TENANT_ID:?Tenant ID is missing}"
: "${SOPHOS_API_HOST:?Regional API host is missing}"
umask 077

curl --fail-with-body --silent --show-error --get \
  "${SOPHOS_API_HOST}/endpoint/v1/endpoints" \
  --header "X-Tenant-ID: ${SOPHOS_TENANT_ID}" \
  --data-urlencode "pageSize=50" \
  --output endpoints-page.json \
  --config - <<EOF
header = "Authorization: Bearer ${SOPHOS_ACCESS_TOKEN}"
EOF

Use SOPHOS_API_HOST sin modificar desde whoami o la lista de tenants. El token debe llegar al proceso desde un Secret Store, no desde el script, el historial de Shell, los argumentos de la línea de comandos, tickets o Debug Logs. La configuración por la entrada estándar evita que el Bearer Header expandido aparezca en la lista de argumentos de curl; umask 077 limita los permisos del nuevo archivo de salida. --fail-with-body hace visible un error HTTP, pero el archivo sigue siendo inventario potencialmente sensible.

Un HTTP Status correcto solo confirma la solicitud. Después hay que comprobar que el archivo contiene JSON válido, se consultó el tenant esperado y aparecen los dispositivos necesarios. No se muestra una respuesta ficticia que pueda confundirse con una respuesta observada.

Elegir conscientemente las rutas Endpoint

Endpoint v1 incluye estas rutas:

• GET /endpoint/v1/endpoints y GET /endpoint/v1/endpoints/{endpointId} para inventario y detalles;
• POST /endpoint/v1/endpoints/{endpointId}/scans para solicitar un escaneo;
• /endpoint/v1/endpoint-groups para grupos de ordenadores y servidores;
• /endpoint/v1/policies para políticas de Endpoint, Server y Device Encryption;
• POST /endpoint/v1/tags/assignment para asignar tags;
• endpoints para aislamiento, elementos permitidos o bloqueados, exclusiones, Web Control, paquetes de software y migraciones de Endpoint.

Utilice el método HTTP y la ruta completa indicados arriba; no los sustituya por rutas antiguas de nombre parecido. Antes de escribir, compruebe esquema, rol y permiso necesarios, límites de plataforma y licencia, Status Codes y Rate Limit específico de la operación.

Grupos, tags, software y políticas

Los grupos controlan la asignación de políticas y permanecen dentro de la jerarquía del tenant. Los tags complementan inventario y búsqueda. Un Key tiene 1–40 caracteres y un valor 0–40, sin dos puntos. Un Endpoint admite como máximo 15 tags y un Key solo un valor. Una solicitud acepta hasta 1.000 UUID y puede devolver errores parciales por Endpoint; el cliente debe evaluar cada estado de Endpoint devuelto.

En Device Software, Protection, Encryption y ZTNA son categorías separadas. Los ordenadores admiten las tres; los servidores, solo Protection en este flujo. Cada bloque computer o server acepta hasta 1.000 IDs. Los Software IDs válidos dependen del Endpoint, catálogo y licencia. Utilice solo IDs devueltos por una lectura previa de ese Endpoint exacto; no aplique All, None ni IDs supuestos sin validarlos.

Antes de modificar políticas, conserve tipo, ajustes, asignaciones y prioridad. Las Base Policies y políticas adicionales no admiten las mismas operaciones. Modifique solo los campos que el objeto actual del tenant muestre como editables y no bloqueados. Un PATCH contiene solo Keys revisados; un objeto completo antiguo no debe sobrescribir ajustes añadidos posteriormente.

Paginación, límites y errores

Las listas de Endpoints usan paginación por Key: la primera página sin pageFromKey y las siguientes con pages.nextKey de la respuesta anterior. Otros recursos usan paginación por página. El máximo de pageSize depende de la operación: 50 por defecto para Endpoints y 500 como máximo para Endpoint Groups. Siga el esquema concreto y termine solo cuando no haya Key ni página siguiente.

Límites globales de las APIs de Sophos Fusion:

• 10 llamadas por segundo: recomendado;
• 100 por minuto: aplicado, con ráfagas breves de hasta 300;
• 1.000 por hora: recomendado;
• 200.000 por día: aplicado.

Prevalecen límites específicos más estrictos. Sophos aplica los tres primeros por separado a credenciales, cuenta e IP de origen; la cuota diaria se aplica a cuenta y credenciales, no a IP. No use múltiples credenciales o IPs para eludirlos.

Reintente 429 Too Many Requests y 5xx un número limitado de veces con backoff exponencial y jitter aleatorio. Para 400, 401, 403, 404 y 409, corrija antes solicitud, token, rol, ID o estado. Los Bulk Endpoints pueden incluir errores pese a HTTP 200; evalúe cada objeto y reintente solo las partes fallidas que sea seguro repetir.

Introducir escrituras de forma segura

1. Verifique tenant, host regional, paginación y filtros con una credencial Read-Only.
2. Elija el rol y permiso documentados más pequeños para la operación exacta.
3. Lea y conserve el estado actual y los IDs como evidencia del cambio.
4. Realice exactamente un cambio en un grupo piloto o dispositivo de prueba.
5. Evalúe toda la respuesta y verifique el efecto en el dispositivo o Central.
6. Amplíe después; prepare rollback, caducidad, 429 y errores parciales.

Siguen vigentes las reglas de grupos de Endpoint e inventario, orden de políticas y Live Discover. El proceso admitido para mover Endpoints ya protegidos a otro tenant se explica aparte y no debe deducirse de un ejemplo API genérico.

Preguntas frecuentes