API de IOCs

Gestiona en la plataforma Cytomic Orion los identificadores de compromiso (IOCs) obtenidos de fuentes externas.

Importar y buscar IOCs en la telemetría generada por los equipos del cliente

Carga uno o más IOCs de un mismo tipo en la plataforma, los cuales podrán configurarse para realizar dos tipos de búsquedas:

Búsqueda retrospectiva (opcional): busca una única vez el IOC en el flujo de eventos generado por los equipos del cliente y acumulado durante el último año desde el momento de la importación. Esta búsqueda genera un único indicio en la consola por cada equipo / IOC encontrado.
Búsqueda en streaming: busca el IOC desde el momento de la carga del IOC en la plataforma, generando un indicio en la consola por cada equipo / IOC / hora. La búsqueda terminará cuando se cumpla el tiempo indicado en el campo TTL. Este tipo de búsqueda se realiza sobre la información generada por los procesos en ejecución de los equipos del cliente.

Petición

Comando	POST
URL	/api/v1/applications/iocs/{iocType}
Parámetros requeridos en la URL	iocType: indica el tipo de los IOCs a importar. Todos los IOCs importados en una misma llamada tienen que ser del mismo tipo. Hash: el JSON con la descripción del IOC a importar contiene un md5 del fichero que representa una amenaza. Url: el JSON con la descripción del IOC a importar contiene la URL a la que accede la amenaza. Es necesario incluir el protocolo en la URL, por ejemplo: https://www.google.com/test. IP: el JSON con la descripción del IOC a importar contiene la dirección IP (origen o destino) de la comunicación establecida por la amenaza. Domain: el JSON con la descripción del IOC a importar contiene el dominio (origen o destino) de la comunicación establecida por la amenaza.
Parámetros opcionales en la URL por querystring	retrospective: ejecuta una única búsqueda sobre todos los eventos almacenados por Cytomic y generados por los equipos del SOC hasta la fecha.
Parámetros requeridos en el cuerpo del mensaje HTTP	Lista de JSONs con la descripción de los IOCs. Solo se puede incluir en el JSON uno de los parámetros mostrados a continuación. Todos los IOCs tienen que ser del mismo tipo. Los campos posibles del JSON son: hash: md5 del fichero que contiene la amenaza. url: URL solicitada por la amenaza. ip: dirección IP (origen o destino) de la comunicación establecida por la amenaza. domain: dominio (origen o destino) de la comunicación establecida por la amenaza. additionalData, source, policy, description: campos descriptivos del IOC. No utilizados por la plataforma. daysToExpiration: número de días que permanecerán los IOCs en la plataforma, pasados los cuales serán eliminados junto a sus búsquedas asociadas.
Cabeceras	Accept: application/json Content-Type: application/json-patch+json
Formato de la llamada para importar IOCs

Respuesta

Campo del JSON	Descripción
success	“true”
message	“n {iocType} added”: indica el número de IOCs cargados con éxito en la plataforma y su tipo.
error	“null”
PandaAlertId	Identificador interno asignado al IOC.
JSON de respuesta a la carga de IOCs con éxito

Borrar IOCs importados en la plataforma

Elimina los IOCs previamente importados en la plataforma, interrumpiendo a su vez las búsquedas en streaming y retrospectivas en curso.

Petición

Comando	POST
URL	/api/v1/applications/iocs/{iocType}/eraser/
Parámetros requeridos en la URL	iocType: indica el tipo de los IOCs a borrar. Todos los IOCs borrados en una misma llamada tienen que ser del mismo tipo. Hash: el JSON con la descripción del IOC a borrar contiene un md5 del fichero. Url: el JSON con la descripción del IOC a borrar contiene una URL. IP: el JSON con la descripción del IOC a borrar contiene la dirección IP (origen o destino) de una comunicación. Domain: el JSON con la descripción del IOC a borrar contiene el dominio (origen o destino) de una comunicación establecida.
Parámetros requeridos en el cuerpo del mensaje HTTP	Lista de JSONs con la descripción de los IOCs a borrar. Solo se puede incluir en el JSON uno de los parámetros mostrados a continuación. Todos los JSONs tienen que ser del mismo tipo. Los campos posibles del JSON son: hash: md5 un fichero. url: URL . ip: dirección IP (origen o destino) de una comunicación. domain: dominio (origen o destino) de una comunicación. additionalData, source, policy, description: campos descriptivos del IOC. No utilizados por la plataforma.
Cabeceras	Accept: application/json Content-Type: application/json-patch+json
Formato de la llamada para borrar IOCs

Respuesta

Campo del JSON	Descripción
success	“true”
message	“n {iocType} deleted”: indica el número de IOCs borrados con éxito en la plataforma y su tipo.
error	“null”
PandaAlertId	Identificador interno asignado al IOC.
JSON de respuesta al borrado IOCs con éxito

Listar IOCs por atributos cargados en la plataforma

Muestra la lista de IOCs cargada en la plataforma según sus atributos y cuándo fueron importados.

Petición

Comando	POST
URL	/api/v1/applications/iocs/{iocType}/getter/
Parámetros requeridos en la URL	iocType: indica el tipo de los IOCs a listar. Hash: el JSON con la descripción del IOC a listar contiene un md5 del fichero. Url: el JSON con la descripción del IOC a listar contiene una URL. IP: el JSON con la descripción del IOC a listar contiene la dirección IP (origen o destino) de una comunicación. Domain: el JSON con la descripción del IOC a listar contiene el dominio (origen o destino) de una comunicación establecida.
Parámetros requeridos en el cuerpo del mensaje HTTP	Colección de JSONs con la descripción de los IOCs a listar. Solo se puede incluir en el JSON uno de los parámetros mostrados a continuación. Todos los JSONs tienen que ser del mismo tipo especificado en el campo iocType. Los campos posibles del JSON son: hash: md5 un fichero. url: URL . ip: dirección IP (origen o destino) de una comunicación. domain: dominio (origen o destino) de una comunicación.
Cabeceras	Accept: application/json Content-Type: application/json-patch+json
Formato de la llamada para listar IOCs por característica

Respuesta

Campo del JSON	Descripción
IocType	Indica el tipo de los IOCs listados. Hash: el JSON con la descripción del IOC listado contiene un md5 del fichero. Url: el JSON con la descripción del IOC listado contiene una URL. IP: el JSON con la descripción del IOC listado contiene la dirección IP (origen o destino) de una comunicación. Domain: el JSON con la descripción del IOC listado contiene el dominio (origen o destino) de una comunicación establecida.
KeyValueAsString	Valor del IOC.
IocJson	hash: md5 un fichero. url: URL . ip: dirección IP (origen o destino) de una comunicación. domain: dominio (origen o destino) de una comunicación. DaysToExpiration: número de días que el IOC permanecerá en la plataforma. additionalData, source, policy, description: campos descriptivos del IOC. No utilizados por la plataforma.
DeploymentDateUTC	Fecha en la que el IOC se cargó en la plataforma.
ExpirationDateUTC	Fecha en la que el IOC será borrado por la plataforma.
LastRetroScanUTC	Fecha en la que es inició una búsqueda retrospectiva por ultima vez con el IOC.
PandaAlertId	Identificador interno asignado al IOC.
JSON de respuesta a la llamada para listar IOCs

Listar IOCs por fecha de carga en la plataforma

Muestra la lista de IOCs cargados en la plataforma según su fecha de publicación.

Petición

Comando	GET
URL	/api/v1/applications/iocs/{iocType}
Parámetros requeridos en la URL	iocType: indica el tipo de los IOCs a listar. Hash: lista IOCs que especifican un md5. Url: lista IOCs que especifican una URL. IP: lista IOCs que especifican un dirección IP (origen o destino) de una comunicación. Domain: lista IOCs que especifican un dominio (origen o destino) de una comunicación establecida.
Parámetros requeridos en el cuerpo del mensaje HTTP	from: timestamp Unix en milisegundos con la fecha inferior del intervalo de IOCs a listar. to: timestamp Unix en milisegundos con la fecha superior del intervalo de IOCs a listar. includeDeleted: filtra el listado de IOCs según su pertenencia o no a una regla de eliminación. True: el IOC pertenece a una regla de eliminación. el IOC no pertenece a una regla de eliminación.
Cabeceras	Accept: application/json
Formato de la llamada para listar IOCs por fecha de carga en la plataforma

Respuesta

Campo del JSON	Descripción
IocType	Indica el tipo de los IOCs listados. Hash: el JSON con la descripción del IOC listado contiene un md5 del fichero. Url: el JSON con la descripción del IOC listado contiene una URL. IP: el JSON con la descripción del IOC listado contiene la dirección IP (origen o destino) de una comunicación. Domain: el JSON con la descripción del IOC listado contiene el dominio (origen o destino) de una comunicación establecida.
KeyValueAsString	Valor del IOC.
IocJson	hash: md5 un fichero. url: URL . ip: dirección IP (origen o destino) de una comunicación. domain: dominio (origen o destino) de una comunicación. DaysToExpiration: número de días que el IOC permanecerá en la plataforma. additionalData, source, policy, description: campos descriptivos del IOC. No utilizados por la plataforma.
DeploymentDateUTC	Fecha en la que el IOC se cargó en la plataforma.
ExpirationDateUTC	Fecha en la que el IOC será borrado por la plataforma.
LastRetroScanUTC	Fecha en la que es inició una búsqueda retrospectiva por ultima vez con el IOC.
PandaAlertId	Identificador interno asignado al IOC.
JSON de respuesta a la llamada para listar IOCs por fecha de carga en la plataforma

Búsqueda retrospectiva de un IOC

Busca patrones en los eventos generados hasta la fecha por los equipos de los clientes del SOC, y devuelve una lista de JSONs con los IOCs encontrados. La llamada a este método tiene un tiempo de ejecución máximo de 90 segundos y mostrará todos los resultados encontrados al final de la búsqueda. Si transcurrido el tiempo máximo, Cytomic Orion no ha podido recuperar todas la amenazas disponibles, la conexión se interrumpirá sin devolver ningún resultado.

Petición

Comando	POST
URL	/api/v1/applications/iocs/{iocType}/retrospectivesearcher
Parámetros requeridos en la URL	iocType: indica el tipo de los IOCs a buscar. Todos los IOCs en una misma llamada tienen que ser del mismo tipo. FileHash: el JSON con la descripción del IOC a buscar contiene un md5 del fichero que representa una amenaza. Url: el JSON con la descripción del IOC a buscar contiene una URL pedida por la amenaza. IP: el JSON con la descripción del IOC a buscar contiene la dirección IP (origen o destino) de la comunicación establecida por la amenaza. Domain: el JSON con la descripción del IOC a buscar contiene el dominio (origen o destino) de la comunicación establecida por la amenaza.
Parámetros requeridos en el cuerpo del mensaje HTTP	Lista de JSONs con la descripción de los IOCs. Solo se puede incluir en el JSON uno de los parámetros mostrados a continuación. Todos los JSONs tienen que ser del mismo tipo. Los campos posibles del JSON son: hash: md5 del fichero que contiene la amenaza. url: URL solicitada por la amenaza. ip: dirección IP (origen o destino) de la comunicación establecida por la amenaza. domain: dominio (origen o destino) de la comunicación establecida por la amenaza. additionalData, source, policy, description: campos descriptivos del IOC. No utilizados por la plataforma.
Cabeceras	Accept: application/json Content-Type: application/json-patch+json
Formato de la llamada para ejecutar una búsqueda retrospectiva

Respuesta

Lista de JSONs con la descripción de los atributos de los IOCs encontrados

Campo del JSON	Descripción
MUID	Identificador del equipo dentro de Cytomic Orion.
clientid	Identificador del cliente.
firstSeen	Fecha de la primera aparición del IOC en el equipo del cliente.
lastSeen	Fecha de la ultima aparición del IOC en el equipo del cliente.
ioc	Descripción del IOC encontrado. iockey: valor del IOC. type: tipo del IOC (FileHash, Url, IP, Domain). source, policy, description: campos descriptivos introducidos en la importanción del IOC.
PandaAlertId	Identificador interno asignado al IOC.
JSON de respuesta a la ejecución de una búsqueda retrospectiva

Listado de IOCs en la consola de Cytomic Orion

Para mostrar en la consola los IOCs cargados haz clic en el menú superior Configuración, panel lateral IOCs. Se mostrará un listado con información equivalente a la ofrecida en la respuesta de las llamadas a la API para listar los IOCs cargados en la plataforma. Consulta Listar IOCs por atributos cargados en la plataforma o Listar IOCs por fecha de carga en la plataforma.

Campo	Descripción
Tipo IOC	Tipo del dato indicado en el campo Valor IOC. Coincide con el contenido del parámetro iocType de la API.
Valor IOC	Valor utilizado en la búsqueda del IOC. Coincide con el contenido del parámetro KeyValueAsString de la API.
Fecha de importación	Fecha en la que se creó el IOC. Coincide con el contenido del parámetro DeploymentDateUTC de la API.
Fecha de exploración	Fecha en la que se borrará el IOC de la plataforma. Coincide con el contenido del parámetro ExpirationDateUTC.
Datos adicionales	Coincide con el contenido del parámetro additionalData de la API.
Fuente	Coincide con el contenido del parámetro source de la API.
Política	Coincide con el contenido del parámetro policy de la API.
Descripción	Coincide con el contenido del parámetro description de la API.
Campos del listado IOCs

Ejemplos de llamadas a la API de IOCs

El siguiente ejemplo carga varios IOCs que identifican el tráfico origen o destino de redes C2C (Command & Control), comprueba que están cargados, ejecuta una búsqueda retrospectiva y los borra.

Al cargar la lista de IOCs, Cytomic Orion ejecutará una única búsqueda retrospectiva en la telemetría almacenada durante último año y generará indicios en caso de encontrar amenazas que coincidan con los IOCs cargados. Además, continuará buscando en el stream de eventos producidos hasta que se cumpla la fecha de caducidad del IOC (10 días).

#tipo de IOC

iocType='IPIoc'

#datos de los IOCs

ioc_data=[{'ip':'192.168.0.1'},{'ip':'192.168.0.2'},{'ip':'192.168.0.3'}]

#cabeceras para la llamada a la API incluyendo el token de acceso

h_request_ioc = {

'Authorization': f'Bearer {token_access}',

'Accept': 'application/json',

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

}

#Objetivo: cargar en el servidor 3 IOCS de tipo IP (IPIoC)

#activar búsqueda retrospectiva

retrospective=True

#URL de la llamada

url_ioc_add = f'https://api.orion.cytomic.ai/api/v1/applications/iocs/{iocType}?retrospective={retrospective}'

#devuelve un JSON con el número de IOC cargados con éxito

r = requests.post(url_ioc_add, headers=h_request_ioc, json=ioc_data, verify=False)

ioc_add=r.json()

#Objetivo: comprobar los IOCs cargados en la plataforma

#URL de la llamada

url_ioc_list = f'https://api.orion.cytomic.ai/api/v1/applications/iocs/{iocType}/getter/'

r = requests.post(url_ioc_list, headers=h_request_ioc, json=ioc_data, verify=False)

#devuelve un JSON con la definición de los IOCs cargados del tipo indicado y su

#fecha de carga

iocs_list=r.json()

#Objetivo: inicia una búsqueda retrospectiva de una lista de IOCs

#URL de la llamada

url_ioc_search = f'https://api.orion.cytomic.ai/api/v1/applications/iocs/{iocType}/retrospectivesearcher/'

r = requests.post(url_ioc_search, headers=h_request_ioc, json=ioc_data, verify=False)

#devuelve una lista de JSONs con los IOCs encontrados en el parque del cliente

iocs_found=r.json()

#Objetivo: borra los IOCs previamente cargados

#URL de la llamada

url_ioc_del = f'https://api.orion.cytomic.ai/api/v1/applications/iocs/{iocType}/eraser/'

#devuelve un JSON con el número de IOCs borrados con éxito

r = requests.post(url_ioc_del, headers=h_request_ioc, json=ioc_data, verify=False)

ioc_del=r.json()