IOC API

This API enables you to manage the indicators of compromise (IOCs) obtained from external sources on the Cytomic Orion platform.

Import and Search for IOCs in the Telemetry Generated by a Client’s Computers

Loads one or more IOCs of the same type onto the platform. You can configure those IOCs for two types of searches:

Retrospective searches (optional): These searches examine, only once, the flow of events generated by the client’s computers over the last year since an IOC is imported. A single indicator is generated in the console for each computer/IOC pair found.
Real-time searches: These searches examine, in real time, the information generated by processes running on the client’s computers. A single indicator is generated in the console for each computer/IOC pair every hour. The search ends when the time indicated in the TTL field expires.

Request

Command	POST
URL	/api/v1/applications/iocs/{iocType}
Required parameters in the URL	iocType: Specifies the type of IOCs you want to import. All the IOCs imported in the same call must be of the same type. Hash: The JSON object with the description of the IOC you want to import must contain the MD5 value of the file that poses a threat. Url: The JSON object with the description of the IOC you want to import must contain the URL accessed by the threat. You must include the protocol in the URL. For example: https://www.google.com/test. IP: The JSON object with the description of the IOC you want to import must contain the source or target IP address of the communication established by the threat. Domain: The JSON object with the description of the IOC you want to import must contain the source or target domain of the communication established by the threat.
Optional querystring parameters in the URL	retrospective: Examines, only once, the flow of events stored by Cytomic and generated by the SOC computers up until the present date.
Required parameters in the HTTP message body	List of JSON objecs with descriptions of the IOCs. You can include only one of these parameters in the JSON object. All of the IOCs must be of the same type. Possible fields in the JSON object: hash: MD5 value of the file that contains the threat. url: URL requested by the threat. ip: Source or target IP address of the communication established by the threat. domain: Source or target domain of the communication established by the threat. additionalData, source, policy, description: Description fields of the IOC. Not used by the platform. daysToExpiration: Number of days the IOCs remain on the platform, after which they are deleted along with any associated searches.
Headers	Accept: application/json Content-Type: application/json-patch+json
Format of the call to import IOCs

Response

JSON object field	Description
success	“true”
message	“n {iocType} added”: Indicates the number of IOCs successfully loaded onto the platform and their type.
error	“null”
PandaAlertId	Internal identifier assigned to the IOC.
Response JSON object when IOCs are successfully loaded

Delete IOCs Imported onto the Platform

Deletes IOCs previously imported onto the platform, interrupting any retrospective or real-time searches that might be in progress.

Request

Command	POST
URL	/api/v1/applications/iocs/{iocType}/eraser/
Required parameters in the URL	iocType: Indicates the type of IOCs you want to delete. All IOCs deleted in the same call must be of the same type. Hash: The JSON object with the description of the IOC you want to delete must contain a file MD5 value. Url: The JSON object with the description of the IOC you want to delete must contain a URL. IP: The JSON object with the description of the IOC you want to delete must contain a communication source or target IP address. Domain: The JSON object with the description of the IOC you want to delete must contain a communication source or target domain.
Required parameters in the HTTP message body	List of JSON objects with descriptions of the IOCs you want to delete. You can include only one of these parameters in the JSON object. All of the IOCs must be of the same type. Possible fields in the JSON object: hash: A file MD5 value. url: URL. ip: A communication source or target IP address. domain: A communication source or target domain. additionalData, source, policy, description: Description fields of the IOC. Not used by the platform.
Headers	Accept: application/json Content-Type: application/json-patch+json
Format of the call to delete IOCs

Response

JSON object field	Description
success	“true”
message	“n {iocType} deleted”: Indicates the number of IOCs successfully deleted from the platform and their type.
error	“null”
PandaAlertId	Internal identifier assigned to the IOC.
Response JSON object when IOCs are successfully deleted

List IOCs Loaded onto the Platform by Attributes

Shows the list of IOCs loaded onto the platform according to their attributes and when they were imported.

Request

Command	POST
URL	/api/v1/applications/iocs/{iocType}/getter/
Required parameters in the URL	iocType: Indicates the type of IOCs you want to list. Hash: The JSON object with the description of the IOC you want to list must contain a file MD5 value. Url: The JSON object with the description of the IOC you want to list must contain a URL. IP: The JSON object with the description of the IOC you want to list must contain a communication source or target IP address. Domain: The JSON object with the description of the IOC you want to list must contain a communication source or target IP domain.
Required parameters in the HTTP message body	List of JSON objects with descriptions of the IOCs you want to list. You can include only one of these parameters in the JSON object. All of the IOCs must be of the same type (specified in the iocType field). Possible fields in the JSON object: hash: A file MD5 value. url: URL. ip: A communication source or target IP address. domain: A communication source or target domain.
Headers	Accept: application/json Content-Type: application/json-patch+json
Format of the call to list IOCs by features

Response

JSON object field	Description
IocType	Indicates the type of the IOCs in the list. Hash: The JSON object with the description of the listed IOC contains a file MD5 value. Url: The JSON object with the description of the listed IOC contains a URL. IP: The JSON object with the description of the listed IOC contains a communication source or target IP address. Domain: The JSON object with the description of the listed IOC contains a communication source or target domain.
KeyValueAsString	IOC value.
IocJson	hash: A file MD5 value. url: URL. ip: A communication source or target IP address. domain: A communication source or target domain. DaysToExpiration: Number of days the IOC remains on the platform. additionalData, source, policy, description: Description fields of the IOC. Not used by the platform.
DeploymentDateUTC	Date the IOC was loaded onto the platform.
ExpirationDateUTC	Date the IOC will be deleted from the platform.
LastRetroScanUTC	Date on which a retrospective search for the IOC was last run.
PandaAlertId	Internal identifier assigned to the IOC.
Response JSON object to a request to list IOCs

List IOCs by Date Loaded onto the Platform

Shows the list of IOCs loaded onto the platform by date of publication.

Request

Command	GET
URL	/api/v1/applications/iocs/{iocType}
Required parameters in the URL	iocType: Indicates the type of IOCs you want to list. Hash: Lists IOCs that specify an MD5.value. Url: Lists IOCs that specify a URL. IP: Lists IOCs that specify a communication source or target IP address. Domain: Lists IOCs that specify a communication source or target IP domain.
Required parameters in the HTTP message body	From:: Unix timestamp in milliseconds with the start date of the interval for which you want to list IOCs. to: Unix timestamp in milliseconds with the end date of the interval for which you want to list IOCs. includeDeleted: Filters the list of IOCs based on whether they belong to a deletion rule. True: The IOC belongs to a deletion rule. False: The IOC does not belong to a deletion rule
Headers	Accept: application/json
Format of the call to list IOCs by date loaded onto the platform

Response

JSON object field	Description
IocType	Indicates the type of the IOCs in the list. Hash: The JSON object with the description of the listed IOC contains a file MD5 value. Url: The JSON object with the description of the listed IOC contains a URL. IP: The JSON object with the description of the listed IOC contains a communication source or target IP address. Domain: The JSON object with the description of the listed IOC contains a communication source or target domain.
KeyValueAsString	IOC value.
IocJson	hash: A file MD5 value. url: URL. ip: A communication source or target IP address. domain: A communication source or target domain. DaysToExpiration: Number of days the IOC remains on the platform. additionalData, source, policy, description: Description fields of the IOC. Not used by the platform.
DeploymentDateUTC	Date the IOC was loaded onto the platform.
ExpirationDateUTC	Date the IOC will be deleted from the platform.
LastRetroScanUTC	Date on which a retrospective search for the IOC was last run.
PandaAlertId	Internal identifier assigned to the IOC.
Response JSON object to the call to list IOCs by date loaded onto the platform

Search for IOCs Retrospectively

Searches for patterns in all events generated so far on the SOC clients’ computers. It returns a list of JSON objects with the IOCs found. The call to this method has a maximum execution time of 90 seconds. It shows all results at the end of the search. If, after the maximum execution time has passed, Cytomic Orion has not been able to retrieve all available threats, the connection terminates without returning any results.

Request

Command	POST
URL	/api/v1/applications/iocs/{iocType}/retrospectivesearcher
Required parameters in the URL	iocType: Indicates the type of IOCs you want to search for. All IOCs in the same call must be of the same type. FileHashIoc: The JSON object with the description of the IOC you want to search for must contain the MD5 value of the file that poses a threat. Url: The JSON object with the description of the IOC you want to search for must contain a URL requested by the threat. IP: The JSON object with the description of the IOC you want to search for must contain the source or target IP address of the communication established by the threat. Domain: The JSON object with the description of the IOC you want to search for must contain the source or target domain of the communication established by the threat.
Required parameters in the HTTP message body	List of JSON objecs with descriptions of the IOCs. You can include only one of these parameters in the JSON object. All of the IOCs must be of the same type. Possible fields in the JSON object: hash: MD5 value of the file that contains the threat. url: URL requested by the threat. ip: Source or target IP address of the communication established by the threat. domain: Source or target domain of the communication established by the threat. additionalData, source, policy, description: Description fields of the IOC. Not used by the platform.
Headers	Accept: application/json Content-Type: application/json-patch+json
Format of the call to run a retrospective search

Response

List of JSON objects with descriptions of the attributes of the IOCs found.

JSON object field	Description
MUID	Computer ID in Cytomic Orion.
clientid	Client ID.
firstSeen	Date the IOC was first seen on the client’s computer.
lastSeen	Date the IOC was last seen on the client’s computer.
ioc	Description of the IOC found. iockey: IOC value. type: IOC type (FileHash, Url, IP, Domain). source, policy, description: Description fields entered when you imported the IOC. .
PandaAlertId	Internal identifier assigned to the IOC.
Response JSON object to a request to run a retrospective search

List of IOCs in the Cytomic Orion Console

To view a list of loaded IOCs in the console, select Settings in the top menu. In the side menu. select IOCs. A list appears that shows information equivalent to that provided in the response to API calls for listing the IOCs loaded onto the platform. See List IOCs Loaded onto the Platform by Attributes or List IOCs by Date Loaded onto the Platform.

Field	Description
IOC type	Type of the data that appears in the IOC value field. It matches the content of the API iocType parameter.
IOC value	Value used in IOC searches. It matches the content of the API KeyValueAsString parameter.
Import date	Date the IOC was created. It matches the content of the API DeploymentDateUTC parameter.
Expiration date	Date the IOC will be deleted from the platform. It matches the content of the API ExpirationDateUTC parameter.
Additional data	It matches the content of the API additionalData parameter.
Source	It matches the content of the API source parameter.
Policy	It matches the content of the API policy parameter.
Description	It matches the content of the API description parameter.
Fields in the IOCs list

Examples of IOC API Calls

This example loads multiple IOCs that identify source and target traffic related to C&C (Command & Control) networks, checks whether they are loaded, runs a retrospective search, and deletes them.

When you load the list of IOCs, Cytomic Orion retrospectively examines, only once, the telemetry stored over the last year and generates indicators if it finds threats that match the loaded IOCs. Additionally, it examines, in real time, the events occurred on computers until the IOC expiration date (10 days).

#IOC type

iocType='IPIoc'

#IOC data

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

#Headers for the API call including the access token

h_request_ioc = {

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

'Accept': 'application/json',

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

}

#Aim: To load three IOCs of type IP (IPIoC) onto the server

#Enable retrospective search

retrospective=True

#Call URL

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

#Returns a JSON object with the number of successfully loaded IOCs

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

ioc_add=r.json()

#Aim: To check the IOCs loaded onto the platform

#Call URL

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)

#Returns a JSON object with a description of the loaded IOCs of the specified type and the

#load date

iocs_list=r.json()

#Aim: To start a retrospective search for a list of IOCs

#Call URL

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)

#Returns a list of JSON objects with the IOCs found on the client’s network

iocs_found=r.json()

#Aim: To delete previously loaded IOCs

#Call URL

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

#Returns a JSON object with the number of successfully deleted IOCs

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

ioc_del=r.json()