Ir al contenido
Avanet
Mi cuenta
Mi cuenta

Cargando …

Consultar el Data Lake de Sophos Fusion con la Search GraphQL API

La Search GraphQL API v1 permite buscar en el Data Lake histórico de Sophos Fusion (anteriormente Sophos Central) desde una aplicación propia con QL. El proceso es asíncrono: iniciar la búsqueda, conservar su Search-URN, comprobar la finalización y el resultado de la ejecución y después leer todas las páginas de resultados. COMPLETE por sí solo no significa que todas las partes de la búsqueda hayan tenido éxito.

La API está publicada desde el 12 de octubre de 2026. Complementa las API existentes y no exige una transición inmediata desde la XDR Query API, que sigue disponible. Tampoco sustituye a Live Endpoint Search (LES): LES consulta endpoints conectados con SQL de tipo osquery. La distinción entre Classic Live Discover, Data Lake Search y LES ayuda a elegir la vía de datos correcta.

Antes de la primera solicitud

Se necesitan un tenant con los datos históricos buscados, API Credentials adecuadas, el UUID único del tenant y un cliente HTTP que pueda enviar solicitudes POST JSON y guardar las respuestas completas. Para el ejemplo, el tenant debe contener eventos de procesos. Sin esos datos, una búsqueda técnicamente correcta puede quedar vacía.

Gestionar las credenciales API de forma segura explica la identidad de máquina, el flujo OAuth con client_credentials, la asignación al tenant y la rotación. Un identificador de partner u organización no es un UUID de tenant. Si hay varios tenants, seleccionar el destino mediante una correspondencia aprobada e inequívoca, no solo por su nombre visible.

El rol mínimo exacto y los derechos de acceso necesarios para el cliente Search concreto deben aclararse antes de autorizarlo en producción. El nombre de un rol genérico de entidad de servicio no confirma permisos de Search. Si se deniega el acceso, no asignar Super Admin por precaución.

Antes de empezar, definir la pregunta de investigación, el intervalo temporal y los campos necesarios. Los datos de procesos pueden incluir nombres de usuario, rutas y líneas de comandos confidenciales. Consultas y exportaciones deben permanecer en un entorno aprobado con permisos de acceso y conservación regulados. Ni los tokens ni el Client Secret deben aparecer en registros de solicitudes, tickets o archivos de ejemplo guardados. Tampoco registrar sin control las filas completas de resultados.

Usar el host de destino específico de la API

Las operaciones siguientes comparten el mismo contrato de solicitud:

POST https://api.taegis.sophos.com/graphql
Authorization: Bearer <access-token>
X-Tenant-ID: <tenant-uuid>
X-GraphQL-Schema: default
Content-Type: application/json

En el cliente HTTP, sustituir <access-token> por el token de acceso OAuth actual y <tenant-uuid> por el UUID verificado. La URL y las cabeceras son las mismas para cada cuerpo JSON siguiente. Las plantillas siguientes preparan solicitudes; validar la respuesta real y los campos devueltos antes de utilizarlos en una automatización.

El host REST regional de apiHosts.dataRegion no es el host de destino de este contrato Search. A la inversa, no cambiar globalmente los clientes REST existentes al host GraphQL. Este nombre de host tampoco garantiza la ubicación de almacenamiento ni la residencia de los datos; aclarar esos requisitos según las disposiciones contractuales y del tenant aplicables.

Iniciar y seguir una búsqueda de forma inequívoca

Crear una nueva ejecución con createSearch

La plantilla siguiente busca eventos de procesos de la última hora y limita los campos de evento seleccionados. -1h es una ventana relativa para una primera comprobación funcional; para comparar después con otro cliente, definir límites temporales explícitos idénticos.

{
  "operationName": "CreateSearch",
  "query": "mutation CreateSearch($input: CreateSearchInput) { createSearch(input: $input) { urn status } }",
  "variables": {
    "input": {
      "text": "from process where earliest = -1h | fields host_id, commandline, image_path"
    }
  }
}

Antes del envío, comprobar tenant, intervalo temporal y alcance de los datos. createSearch crea e inicia una nueva ejecución de búsqueda, pero no modifica la configuración de protección de los endpoints. La ejecución puede generar trabajo en el servicio y resultados sensibles. Por tanto, un error del cliente no debe iniciar automáticamente una serie ilimitada de búsquedas nuevas.

Tras la solicitud, evaluar primero el estado HTTP y el array GraphQL errors de nivel superior. HTTP 200 también puede contener errores GraphQL. Guardar data.createSearch.urn solo después de esta comprobación. Utilizar la URN devuelta sin cambios para consultar estado y resultados; no descomponer ni reconstruir su formato. El estado inicial puede variar.

Para cada ejecución, el cliente registra como mínimo el UUID del tenant, el texto de la consulta, la referencia temporal, la Search-URN y la hora de inicio. Una Search-URN identifica toda la ejecución. Una Partition-URN identifica una subtarea, mientras que un Event Resource Name identifica un evento individual. Estos identificadores no son intercambiables.

Reutilizar búsquedas existentes de forma deliberada

Si se permite utilizar una búsqueda adecuada ya en curso o finalizada, getOrCreateSearch es una alternativa:

{
  "operationName": "GetOrCreateSearch",
  "query": "mutation GetOrCreateSearch($input: CreateSearchInput) { getOrCreateSearch(input: $input) { urn status } }",
  "variables": {
    "input": {
      "text": "from process where earliest = -1h | fields host_id, commandline, image_path"
    }
  }
}

Aquí se toma la URN de data.getOrCreateSearch.urn. La correspondencia considera los datos de entrada y compara consultas mediante su representación estructurada canónica, no solo por un texto idéntico. La reutilización no garantiza resultados recientes y el cliente no debe presentarla como una ejecución nueva. Si la tarea requiere una nueva ejecución, utilizar deliberadamente createSearch.

Si un timeout provoca la pérdida de la respuesta tras createSearch, la búsqueda podría seguir ejecutándose. Repetir a ciegas puede crear otra ejecución. Registrar este estado como «creación incierta» y decidir la reanudación según los requisitos de reutilización y actualidad definidos previamente. getOrCreateSearch no demuestra a posteriori que se haya encontrado precisamente la ejecución perdida.

Comprobar finalización, fallos parciales y caducidad

Consultar el estado con la Search-URN guardada. Sustituir <search-urn> exclusivamente por el valor realmente devuelto:

{
  "operationName": "SearchDiagnostics",
  "query": "query SearchDiagnostics($urn: URN!) { search(urn: $urn) { urn status errors expireTime outcome { success errors { urn errors } } searchPartitions { urn schemaType status errors } } }",
  "variables": {
    "urn": "<search-urn>"
  }
}

Mientras status sea QUEUED o IN_PROGRESS, el cliente espera entre consultas. outcome.success: UNKNOWN es esperable antes de finalizar. Un intervalo de sondeo de, por ejemplo, cinco segundos es una posible decisión del cliente, no un límite garantizado del servicio. Cada solicitud necesita además un timeout y el proceso completo un plazo acorde con la carga. Superado ese plazo, la ejecución sigue sin resolverse; detener el sondeo local no cancela la búsqueda en el servidor.

Con status: COMPLETE, evaluar outcome.success por separado:

ValorSignificado
ALLTodas las particiones tuvieron éxito.
PARTIALSolo algunas particiones tuvieron éxito.
NONENinguna partición tuvo éxito.

Para PARTIAL, definir antes del uso en producción si se admiten resultados parciales y para qué fines. Un informe de investigación completo no debe presentarlos tácitamente como hallazgos globales. Con NONE, no hay un alcance de búsqueda correcto en el que basar una declaración de ausencia de amenazas. outcome.errors asocia los mensajes a las particiones; searchPartitions proporciona su esquema, estado y errores. Incluso con una ejecución correcta, errors puede contener advertencias de búsqueda o partición.

Usar también expireTime para comprobar el plan de recuperación: leer los resultados necesarios antes de esa fecha y guardarlos en un sistema propio aprobado si se necesitan durante más tiempo. Guardar una URN o un cursor no prolonga su disponibilidad. Aquí no se deduce una TTL fija a partir de un único ejemplo.

Leer todas las páginas de resultados

Una vez finalizada la ejecución y evaluado su resultado, solicitar la primera página sin cursor en las variables:

{
  "operationName": "SearchResults",
  "query": "query SearchResults($urn: URN!, $limit: Int, $cursor: String) { searchResults(urn: $urn, limit: $limit, cursor: $cursor) { fields { name baseType originSchemaTypes } values totals { total { value } subtotals { schemaType value } } nextCursor } }",
  "variables": {
    "urn": "<search-urn>",
    "limit": 2
  }
}

limit: 2 facilita verificar la secuencia de páginas durante el piloto. Limita las filas por página, no el número total de coincidencias. En producción, elegir un tamaño de página adecuado al procesamiento, sin deducir de él un máximo documentado ni un límite del resultado completo.

Tras cada recuperación, comprobar el estado HTTP, los errors GraphQL y la ruta de respuesta esperada. Procesar la página solo después. Incluso tras COMPLETE, la recuperación puede requerir tiempo; un timeout de lectura no demuestra un fallo de búsqueda. Reintentar los errores de lectura transitorios con backoff limitado, usando la misma Search-URN y el mismo cursor. El consumidor debe impedir que una página releída se añada dos veces a la exportación.

Si data.searchResults.nextCursor contiene un valor, copiarlo sin cambios en las variables de la misma solicitud SearchResults:

{
  "urn": "<search-urn>",
  "limit": 2,
  "cursor": "<next-cursor>"
}

Esto solo sustituye la sección variables, no es un cuerpo GraphQL completo. <next-cursor> procede de la página inmediatamente anterior procesada con éxito. Cada cursor permanece vinculado a la Search-URN que lo proporcionó. No interpretarlo, modificarlo ni transferirlo a otra ejecución. Continuar hasta que nextCursor sea null o no exista. Tratar un cursor repetido o el vencimiento del plazo del cliente como un error de recuperación, no como una finalización correcta.

Distinguir valores, metadatos y totales

values contiene objetos JSON de fila, no una lista de columnas SQL ni una cadena additionalColumns codificada en JSON como en el formato de resultados LES. Las entradas pueden contener objetos y listas anidados. fields describe los nombres y tipos de campos disponibles; una entrada de metadatos no garantiza un valor cumplimentado en cada fila. Gestionar tanto campos ausentes como valores null explícitos, sin equipararlos de forma general a una cadena vacía o a cero coincidencias.

baseType sirve para interpretar los valores. Por ejemplo, TIMESTAMP_SECONDS distingue los segundos de TIMESTAMP_MILLISECONDS y TIMESTAMP_MICROSECONDS; TIMESTAMP_ISO_8601 indica una cadena ISO-8601. Procesar los tipos lista y mapa como colecciones, no como un único escalar. expireTime también es una marca de tiempo ISO-8601. Los metadatos pueden nombrar campos anidados con notación de puntos, como process_file_hash.md5. Por ello, el analizador no debe suponer que cada nombre así sea una clave plana del objeto de fila.

Los datos opcionales totals.total y totals.subtotals se refieren al conjunto completo de resultados y a sus esquemas, respectivamente, no a la longitud de la lista values actual. Para una recuperación completa, procesar todas las páginas y contrastar las filas recopiladas con los totales disponibles. La ausencia de totales no justifica inventar un número; siguen siendo necesarios el final de los cursores y la documentación del alcance recuperado. Ni siquiera una paginación completa convierte un resultado PARTIAL en un éxito completo.

Conservar la proyección QL y el enriquecimiento

En el ejemplo, | fields host_id, commandline, image_path limita los campos de evento de la consulta QL. El conjunto de selección GraphQL determina, en cambio, si se incluyen secciones como fields, totals o nextCursor. values es un escalar JSON: sus campos de fila individuales no pueden seleccionarse mediante un conjunto de selección GraphQL anidado.

El enriquecimiento añade información derivada. hostname y enrichSummary no deben aparecer directamente en | fields. Conservar host_id para resolver el nombre de host. Aun así, no se garantiza un nombre resoluble. Los campos de entrada para enrichSummary dependen del evento; una proyección más estrecha puede acortar el resumen. Antes de reducirla, comparar eventos representativos con los enriquecimientos necesarios para el consumidor.

Una proyección puede reducir la respuesta. No demuestra menores costes de escaneo ni una ejecución más rápida. Omitir las secciones de respuesta innecesarias no debe implicar, en particular, perder nextCursor y con ello la posibilidad de recuperar todos los resultados.

Comparar de forma controlada un cliente XDR Query existente

Pasar de SQL histórico a Search-QL no consiste en sustituir una URL ni en traducir SQL mecánicamente. Primero inventariar las consultas existentes, los campos requeridos y los informes posteriores. La distinción general entre API XDR sigue siendo pertinente por separado para Cases, Detections y otros flujos.

Para cada consulta histórica, comparar en este orden:

  1. Registrar la pregunta funcional y las fuentes necesarias. Las tablas SQL no justifican una correspondencia directa con esquemas QL del mismo nombre; comprobar cada esquema y nombre de campo.
  2. Definir límites explícitos earliest y latest idénticos para ambas búsquedas y documentar la referencia temporal. Dos consultas consecutivas de «última hora» no constituyen una comparación rigurosa de igualdad.
  3. Comprobar comparaciones de cadenas, sensibilidad a mayúsculas y expresiones regulares. QL no admite joins SQL; los joins y las columnas derivadas necesitan un flujo funcional rediseñado. No cambiar sin aclarar la equivalencia.
  4. Verificar primero la consulta QL de forma interactiva en Security Operations > Data Lake Search. Después ejecutar la búsqueda API con las mismas condiciones funcionales.
  5. Comparar registros representativos, campos obligatorios, tipos, marcas de tiempo y enriquecimiento, no solo cantidades de coincidencias. Ambos clientes deben leer completamente sus respectivos resultados.
  6. Adaptar el nuevo consumidor a values/fields, Search-URN y cursores. No asignar a ciegas los antiguos estados REST finished y succeeded a un único campo de estado GraphQL: COMPLETE y outcome.success siguen siendo comprobaciones separadas.

Antes del cambio definitivo deben funcionar también la política de fallos parciales, los reintentos limitados, la creación incierta, la caducidad y la conservación de exportaciones. El piloto de tenant aprobado registra consulta, ventana temporal, campos requeridos y todas las páginas, pero ningún secreto. Una búsqueda vacía solo se interpreta después de comprobar fuente, periodo, filtros, resultado de ejecución y resultados leídos íntegramente; no es una declaración general de ausencia de amenazas.

Hasta la aceptación, el cliente XDR Query existente sigue siendo la vía operativa acordada. Si el nuevo proceso falla, detener la transición o devolver la aplicación al cliente conservado previamente. Esto no elimina datos ya exportados ni subsana lagunas de evidencia producidas. Una búsqueda nueva posterior puede diferir de la primera por referencias temporales distintas o datos ya no disponibles.

Acotar los errores de forma dirigida

  • Solicitud rechazada: Comprobar URL, X-GraphQL-Schema: default, cuerpo JSON, token Bearer válido y UUID del tenant correcto. Aclarar por separado autenticación y autorización específica de la operación; no buscar una región por ensayo y error. Excluir secretos de los diagnósticos.
  • HTTP 200, pero sin data utilizable: Leer los errors de nivel superior. Comprobar consulta, tipos de variables y campos solicitados antes de procesar datos posteriores.
  • COMPLETE con PARTIAL o NONE: Evaluar outcome.errors, errores de búsqueda y searchPartitions afectadas. Tratar la exportación como incompleta o retenerla conforme a la regla de resultados parciales aprobada previamente; no confundir con cero coincidencias.
  • Sin nombre de host o resumen más corto: Comprobar proyección y tipo de evento. Conservar host_id para resolver el nombre de host; no sustituir las entradas de enriquecimiento ausentes por hostname o enrichSummary en | fields.
  • La recuperación se bloquea o termina demasiado pronto: Comprobar timeout de solicitud, plazo global, URN sin cambios, última página procesada con éxito y correspondencia del cursor. Un limit pequeño no es un límite global de resultados.
  • Una URN guardada ya no devuelve resultados más adelante: Comprobar expireTime y los datos ya guardados. Ni URN ni cursor son un archivo permanente. Si hace falta otra ejecución, documentarla como nueva, no como restauración del resultado original.

La API sigue evolucionando. Limitar el cliente a las operaciones documentadas createSearch, getOrCreateSearch, search y searchResults y a los campos admitidos. Los campos adicionales de introspección no constituyen una autorización automática de implementación.