Indicator API

Get Generated Indicators

This API method retrieves the first 30,000 indicators generated in the interval you set. To retrieve all the indicators, run multiple calls consecutively with different shorter intervals. The indicator retrieval interval must not exceed one month. Otherwise, the call returns an error.

This API gets a list of JSON objects with the indicators generated in Cytomic Orion in the specified period. You can also filter the results by type of indicator.

Request

Command

GET

URL

/api/v1/applications/alerts/{from}/{to}

Optional querystring parameters in the URL

  • statuses: Filters the indicators retrieved by whether they have been assigned to an investigation.

    • Pending: The indicator has not been assigned to an investigation yet.

    • InProgress: The indicator has been assigned to an investigation that is still open.

    • Closed: The indicator was assigned to an investigation which is now closed.

  • MUID: Filters the indicators retrieved by the computer MUID.

  • clientid: Filters the indicators retrieved by the client ID.

  • huntingrule: Filters the indicators retrieved by the name of the associated hunting rule.

  • Caseid: Filters the indicators retrieved by the investigation ID.

  • machineName: Filters the indicators retrieved by the computer name.

  • from: Unix timestamp (in milliseconds) with the start date of the interval for which you want to retrieve indicators.

  • to: Unix timestamp (in milliseconds) with the end date of the interval for which you want to retrieve indicators.

  • showExcluded: Filters the indicators retrieved by whether they belong to a deletion rule.

    • True: The indicator belongs to a deletion rule and is in the bin.

    • False: The indicator does not belong to a deletion rule

  • showDetails: Retrieves (or not) the indicator details:

    • true: The indicator details are sent in the Details field.

    • false: The Details field is empty (null).

Headers

  • Accept: application/json

Format of the call to get generated indicators
Response

List of JSON objects with a description of the indicators found.

Field Description

id

Indicator ID.

MUID

Unique identifier of the computer on which the indicator was generated.

timestamp

Date the indicator was generated.

clientid

Unique identifier of the client the computer belongs to.

huntingRule

Name of the hunting rule that generated the indicator.

HuntingRuleId

ID of the hunting rule that generated the indicator.

status

Indicates whether the indicator was assigned to an investigation and the indicator status.

  • 0 (In progress): The indicator is assigned to an investigation and a Tier 2 analyst is investigating it.

  • 1 (Pending): The indicator has not been assigned to an investigation yet.

  • 2 (Closed): The indicator was assigned to an investigation which is now closed.

details

Indicator description. Along with the indicator name, it specifies the types of suspicious events logged so that the Tier 1 team can triage the incident.

alertDateTime

Date the indicator was generated.

lastHourEvidenceCount

Number of times Cytomic Orion generated the same indicator in the last hour.

severity

Severity of the impact of the threat:

  • 0: Undefined

  • 1: Critical

  • 2: High

  • 3: Medium

  • 4: Low

  • 1000: Unknown

mitre

Category of the technique and tactic associated with the hunting rule, mapped to the MITRE matrix.

excluded

Indicates whether Cytomic Orion showed the indicator on the management console or the indicator is excluded.

machineName

Name of the client’s computer where the indicator was detected.

caseId

Unique identifier of the investigation assigned to the indicator, if created.

caseName

Name of the investigation assigned to the indicator, if created.

directLink

URL to access the page that describes the indicator. Used in integration with third-party software.

Format of the JSON object that describes an indicator

Example of API Call to List Indicators

This example provides a list of all the indicators generated in Cytomic Orion from 11/01/2019 to 12/01/2019, which have not been assigned to an investigation yet (status Pending).

#Headers for the API call including the access token.

h_request_alert = {

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

'Accept': 'application/json'}

#start date, end date, and filter criteria

alert_from='1572595090000'

alert_to='1575187090000'

state='Pending'}

#Aim: To get a list of all indicators generated between two dates that have not been assigned to an investigation yet

#call URL

url_alert = f'https://api.orion.cytomic.ai/api/v1/applications/alerts/{alert_from}/{alert_to}?statuses={state}'

r = requests.get(url_alert, headers=h_request_alert, verify=False)

#Returns a list of JSON objects with information about each indicator

alerts=r.json()