API de acceso a OSQuery

La API de OSQuery requiere el envío de dos peticiones distintas en un orden determinado:

  1. Envío de la sentencia OSQuery a los equipos para que el agente Cytomic EPDR prepare la información almacenada en la base de datos del equipo y la envíe a la plataforma Cytomic. Hay disponibles dos llamadas a la API (/api/v1/osQuery/client y /api/v1/osQuery/machine) dependiendo de si se quiere recuperar información de todos los equipos de uno o varios clientes, o de una lista de equipos concreta. Como resultado se obtiene un identificador de operación por cada cliente que reporta datos de sus equipos.

  2. Envío de cada identificador de operación para obtener la URL de descarga del fichero, con la información de los equipos de cada cliente, o para obtener el estado de la petición.

  3. Descarga de un fichero por cada cliente, que consolida toda la información recolectada de sus equipos. Este recurso es accesible a través de la URL obtenida en el paso 2 que, por motivos de seguridad, permanecerá activa durante un máximo de 5 minutos; una vez transcurridos es necesario volver al paso 2 para obtener una nueva URL de descarga.

Debido a que puede haber equipos apagados o inaccesibles, las sentencias OSQuery pueden extenderse indefinidamente en el tiempo. Por esta razón es necesario determinar un TTL o tiempo de vida máximo, pasado el cual Cytomic Orion dará por concluida la operación.

Enviar una petición para obtener información de uno o varios equipos

Ejecuta una sentencia SQL compatible con OSQuery en los equipos indicados que pertenecen a la infraestructura IT de uno o varios clientes.

Petición

Comando

POST

URL

/api/v1/osQuery/machine

Parámetros requeridos en el cuerpo del mensaje HTTP

JSON con la petición OSQuery y una lista de MUIDs.

  • query: sentencia SQL compatible con OSQuery.

  • ttl: máximo tiempo de espera en minutos para recibir los resultados. 0 para 24 horas.

  • MUIDs: lista de los identificadores de equipos donde se ejecutará la sentencia.

Cabeceras

  • Accept: application/json

  • Content-Type: application/json-patch+json

Formato de la llamada para obtener información de uno o varios equipos
Respuesta

Lista de JSONs, cada uno de ellos con el identificador de la operación de un cliente.

Campo del JSON Descripción

pandaID

Identificador del cliente al que pertenecen los equipos que devolvieron datos.

operationId

Identificador de la operación realizada, necesario para consultar la URL con los resultados de la petición OSQuery. ConsultaObtener el resultado de una petición OSQuery.

MUIDs

Lista de identificadores de equipos del cliente que devolvieron resultados de la petición.

JSON con la información de uno o varios equipos

Enviar una petición para obtener información de todos los equipos de uno o varios clientes

Ejecuta una sentencia SQL compatible con OSQuery en todos los equipos que pertenecen a la infraestructura IT de los clientes indicados.

Petición

Comando

POST

URL

/api/v1/osQuery/client

Parámetros requeridos en el cuerpo del mensaje HTTP

JSON con la petición OSQuery y una lista de identificadores de clientes.

  • query: sentencia SQL compatible con OSQuery.

  • ttl: máximo tiempo de espera en minutos para recibir los resultados. 0 para 24 horas.

  • pandaIDs: lista de los identificadores de los clientes donde se ejecutará la sentencia.

Cabeceras

  • Accept: application/json

  • Content-Type: application/json-patch+json

Formato de la llamada para obtener información de los equipos de uno o más clientes
Respuesta

Lista de JSONs, cada uno de ellos con información de un cliente.

Campo del JSON Descripción

pandaID

Identificador del cliente al que pertenecen los equipos que devolvieron datos.

operationId

Identificador de la operación realizada, necesario para consultar la URL con los resultados de la petición OSQuery. ConsultaObtener el resultado de una petición OSQuery.

MUIDs

Lista de identificadores de equipos del cliente que devolvieron resultados de la petición.

JSON con la información de todos los equipos de un cliente

Obtener el resultado de una petición OSQuery

Obtiene la URL que apunta al fichero con los datos de los equipos solicitados.

Petición

Comando

POST

URL

/api/v1/osQuery/state

Parámetros requeridos en el cuerpo del mensaje HTTP

Lista de JSONs, cada uno de ellos con el identificador de la operación cuyos datos se quieren recuperar.

  • pandaId: identificador del cliente al que pertenecen los equipos que devolvieron datos.

  • operationId: identificador de la operación ejecutada.

Cabeceras

  • Accept: application/json

  • Content-Type: application/json-patch+json

Formato de la llamada para obtener el resultado de una petición OSQuery
Respuesta

Lista de JSONs, uno por cliente, con información sobre el resultado de la petición.

Campo del JSON Descripción

pandaId

Identificador del cliente al que pertenecen los equipos que devolvieron datos.

operationId

Identificador de la operación ejecutada.

url

Enlace de descarga del fichero con la información recogida de los equipos. Este enlace es válido durante 5 minutos. Consulta Formato del fichero de descarga para obtener información sobre el formato del fichero.

counters

JSON con las estadísticas de la ejecución:

  • totalOperationElements: número de equipos a los que se envió la petición para recuperar la información.

  • totalSuccess: número de equipos que devolvieron información de forma correcta.

  • totalPartiallySucceeded: número de equipos que devolvieron información pero hubo algún problema a la hora de interpretar los resultados.

  • totalError: número de equipos que devolvieron un código de error.

  • errors: lista de JSON con los distintos errores recibidos de los equipos. ConsultaTipos de error implementados

    • errorCode: código de error.

    • errorDescription: descripción del error.

    • occurrences: número de equipos afectados por el error.

JSON de respuesta con la URL y el resultado de la operación
Control de los equipos apagados, inaccesibles o con retraso en la respuesta

totalOperationElements es igual a la suma de totalSuccess + totalPartiallySucceeded + totalError en el caso de que todos los equipos respondan, bien con información o con un error. Como las sentencias OSQuery pueden tardar un tiempo indeterminado en ejecutarse, si totalOperationElements no es igual a la suma de totalSuccess + totalPartiallySucceeded + totalError quiere decir que todavía hay equipos en el cliente que no han respondido. En tal caso será necesario enviar el operationId sucesivas veces hasta que la suma coincida o hasta que el tiempo establecido en el campo ttl pase.

Formato del fichero de descarga

El fichero que contiene los datos de los equipos del cliente tiene las características siguientes:

  • Nombre: “osquery_” + identificador de la operación.

  • Formato: texto.

  • Cabecera: campos del fichero separados por el carácter “;”.

  • Cuerpo: lineas con el contenido de los campos extraídos por OSQuery de la base de datos del equipo.

Tipos de error implementados
Nombre Código Descripción Observaciones

ErrorExecutingOsQuery

201

near "name": syntax error

OSQuery es compatible con el esquema de datos 4.2.0. Consulta Requisitos de OSQuery y revisa la sintaxis de la sentencia OSQuery.

ErrorOsNotSupported

202

Error operating system not supported

OSQuery es compatible con sistemas Windows. Consulta Requisitos de OSQuery

ErrorOsQueryNotInstalled

203

Error OsQuery not installed

OSQuery está disponible a partir de la versión 3.71 de Cytomic EDR. Consulta Requisitos de OSQuery

Códigos de error implementados y su significado

Obtener el estado de una petición OSQuery

Obtiene una lista de JSONs que indican el estado de las operaciones en curso o finalizadas.

Petición

Comando

POST

URL

/api/v1/osQuery/info

Parámetros requeridos en el cuerpo del mensaje HTTP

Lista de JSONs, cada uno de ellos con el identificador de la operación cuyo estado se quieren recuperar.

  • pandaId: identificador del cliente al que pertenecen los equipos que devolvieron datos.

  • operationId: identificador de la operación ejecutada.

Parámetros opcionales en el cuerpo del mensaje HTTP

  • trackingStateType: devuelve únicamente las operaciones que tienen el estado indicado:

  • Pending (0): operaciones en curso.

  • Success (1): operaciones completadas con éxito.

  • PartiallySucceeded (2): operaciones que recibieron resultados de algunos equipos.

  • Error (3): operaciones no se pudieron ejecutar.

  • Cancelled (4): operaciones canceladas por haber expiado el tiempo máximo definido sin haber sido completadas.

Cabeceras

  • Accept: application/json

  • Content-Type: application/json-patch+json

Formato de la llamada para obtener el estado de una lista de peticiones OSQuery
Respuesta

Lista de JSONs, uno por cliente, con información sobre el resultado de las peticiones.

Campo del JSON Descripción

pandaId

Identificador del cliente al que pertenece la operación.

operationId

Identificador de la operación ejecutada.

info

Lista de JSONs, uno por cada operación del cliente, con su estado:

  • pandaId: identificador del cliente al que afecta la operación.

  • hostname: nombre del equipo al que afecta la operación.

  • deviceId: identificador del equipo al que afecta la operación.

  • trackingStateType: estado de la operación.

    • Pending (0): operación en curso.

    • Success (1): operación completada con éxito.

    • PartiallySucceeded (2): operación que recibió resultados de algunos equipos.

    • Error (3): la operación no se pudo ejecutar. ConsultaTipos de error implementados .

    • Cancelled (4): operación cancelada por haber expiado el tiempo máximo definido sin haber terminado.

  • date: fecha en la que la operación cambió de estado por última vez.

  • errorCode: código de error.

  • errorDescription: descripción del error.

JSON de respuesta con estado de la operación
Tipos de error implementados
Nombre Código Descripción Observaciones

ErrorExecutingOsQuery

201

near "name": syntax error

OSQuery es compatible con el esquema de datos 4.2.0. Consulta Requisitos de OSQuery y revisa la sintaxis de la sentencia OSQuery.

ErrorOsNotSupported

202

Error operating system not supported

OSQuery es compatible con sistemas Windows. Consulta Requisitos de OSQuery

ErrorOsQueryNotInstalled

203

Error OSQuery not installed

OSQuery está disponible a partir de la versión 3.71 de Cytomic EDR. Consulta Requisitos de OSQuery

Códigos de error implementados y su significado