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 de referencia enlazado define exclusivamente el formato de solicitud y respuesta 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

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 almacén de secretos, no desde el script, el historial del intérprete de comandos, los argumentos de la línea de comandos, tickets o registros de depuración. La configuración por la entrada estándar evita que la cabecera de autorización Bearer expandida 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 código de estado HTTP de éxito 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;
• POST /endpoint/v1/endpoints/tamper-protection para cambios selectivos de Tamper Protection en hasta 200 dispositivos;
• POST /endpoint/v1/endpoints/reset-health para restablecer el estado de salud y las alertas en hasta 500 dispositivos compatibles;
• /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, códigos de estado y límite de solicitudes específico de la operación.

Cambiar Tamper Protection y el estado de salud de forma selectiva mediante solicitudes masivas

Las dos operaciones masivas complementan las llamadas existentes de Endpoint v1; no obligan a realizar una migración. Ambas utilizan el host regional identificado, el token Bearer, X-Tenant-ID del tenant de destino y Content-Type: application/json. El permiso requerido para ambas es endpoint-state:update. Una identidad de solo lectura no basta; compruebe primero que el rol del Service Principal incluya este permiso en el tenant de destino.

Tamper Protection: El cuerpo JSON de POST /endpoint/v1/endpoints/tamper-protection contiene ids con 1–200 UUID de endpoint únicos y al menos uno de los campos booleanos enabled o regeneratePassword. enabled: true solicita la activación; enabled: false, la desactivación. regeneratePassword: true solicita nuevas contraseñas de dispositivo. El esquema utiliza anyOf, no oneOf: también permite enviar ambos campos juntos. No obstante, para que los cambios de mantenimiento sean trazables, planifique por separado los cambios de estado y la regeneración de contraseñas y envíe solo los campos previstos. La regeneración de contraseñas no es un override local de cuatro horas ni una contraseña compartida por todos los dispositivos.

Antes de desactivar la protección: Utilice únicamente el conjunto de ID autorizado y registre para cada dispositivo el estado inicial, el final del mantenimiento y la persona responsable. La desactivación por API no tiene documentada una reactivación automática tras cuatro horas. Después del mantenimiento, solicite la activación exactamente de los dispositivos desactivados y compruebe su efecto. Los métodos de mantenimiento locales y por dispositivo suelen seguir siendo la mejor opción para dispositivos individuales.

Consulte primero GET /endpoint/v1/endpoints/{endpointId}?view=full e incluya solo dispositivos con tamperProtectionSupported: true confirmado; la ausencia del valor no constituye una autorización. El alcance Windows/Linux del restablecimiento de salud no demuestra compatibilidad de esas plataformas con Tamper Protection. Compruebe el interruptor global con GET /endpoint/v1/settings/tamper-protection: si está desactivado, activar dispositivos individuales no restablece la protección. GET /endpoint/v1/endpoints/{endpointId}/tamper-protection devuelve el estado previsto enabled, pero también password y, cuando corresponda, previousPasswords. No registre esta respuesta íntegramente. Las contraseñas no deben figurar en tickets ni en registros de depuración; una rotación no se puede deshacer volviendo a escribir la contraseña anterior.

Reset Health: POST /endpoint/v1/endpoints/reset-health espera un cuerpo JSON con el campo obligatorio ids: 1–500 UUID de endpoint únicos. Se admiten ordenadores Windows, servidores Windows y Linux, pero no macOS.

Antes del restablecimiento: La operación pone el estado de salud en verde y elimina todas las alertas de los endpoints afectados. Guarde previamente los hallazgos relevantes, los detalles de las alertas y las pruebas de auditoría fuera de la vista que se vaciará, y obtenga autorización expresa para eliminarlas. El restablecimiento no elimina malware ni repara un servicio de protección averiado. Un estado verde tras esta intervención no demuestra que se haya resuelto la causa; el contrato de la operación no ofrece una función para deshacerla y recuperar las alertas eliminadas.

Tras una solicitud piloto autorizada, vuelva a consultar los detalles de los dispositivos, compruebe el estado de salud y las alertas en Sophos Fusion y verifique por separado el funcionamiento real de la protección. Investigue las nuevas alertas en lugar de ocultarlas con restablecimientos repetidos.

Aceptada no significa ejecutada

Para ambas operaciones masivas, HTTP 202 solo significa que la solicitud se ha procesado y se ha evaluado su aceptación por ID. items contiene las solicitudes aceptadas con id, status: requested y requestedAt; errors contiene las rechazadas con id, errorCode y errorMessage. requestedAt no es una marca de tiempo de finalización. Coteje cada ID enviado con estos resultados; las correspondencias ausentes o contradictorias siguen sin resolverse aunque el estado HTTP indique éxito.

Los códigos de error son notFound, notSupported, conflict, permissionDenied e internalError. Para los cuatro primeros, corrija antes el ID/tenant, la compatibilidad del dispositivo, el estado o el permiso, según corresponda. Ni siquiera internalError autoriza a reenviar todo el lote. Ante errores HTTP, evalúe la respuesta de error; un 202 puede contener simultáneamente ID aceptados y rechazados.

Confirme después el efecto por separado: tras un contacto correcto del dispositivo, consulte los detalles del endpoint con view=full y, para Tamper Protection, también los ajustes, y compruebe la protección localmente. Evalúe lastSeenAt, tamperProtectionEnabled o, según corresponda, health.overall, health.threats y health.services. La mera lectura del estado previsto no confirma su aplicación en un dispositivo offline. Defina un intervalo de comprobación acotado y un tiempo máximo total; si no llega la confirmación, documente la ejecución como pendiente e investigue la conectividad del dispositivo o los errores.

Tras un timeout o una interrupción de conexión, una solicitud de escritura puede haberse aceptado ya. No la repita a ciegas: coteje primero el estado y las pruebas disponibles por ID. De lo contrario, otra rotación de contraseñas o un nuevo restablecimiento de alertas podría alterar estados surgidos entretanto. Autorice nuevos intentos solo para subconjuntos cuyo rechazo esté demostrado y que sea seguro repetir tras corregir el problema; reserve los ID sin resolver para revisión manual.

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. Una clave tiene 1–40 caracteres y un valor 0–40, sin dos puntos. Un Endpoint admite como máximo 15 tags y una clave 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 claves revisadas; 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 clave de continuación: 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 clave de continuación 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.

Para las lecturas que sea seguro repetir, gestione 429 Too Many Requests y 5xx con un número limitado de reintentos, backoff exponencial y jitter aleatorio. Esto no se aplica de forma general a las escrituras: si la aceptación es incierta, compruebe primero el efecto por objeto. Para 400, 401, 403, 404 y 409, corrija antes solicitud, token, rol, ID o estado. Los endpoints masivos pueden devolver listas de errores pese a HTTP 200 o 202; evalúe los éxitos y errores por objeto y reenvíe 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