Cortex XSOAR can pull events from 3rd party tools and convert them into actionable incidents. There are a few important parts that are necessary to keep in mind while doing so and they are outlined below.
fetch incidents command is the function that Cortex XSOAR calls every minute to import new incidents and is triggered by the "Fetches incidents" parameter in the integration configuration. It is not necessary to configure the
fetch-incidents command in the Integration Settings.
Let's walk through the example below:
First we open up the command called "fetch-incidents". Make sure that the command is also referenced in the execution block as well.
demisto.getLastRun() is the function that retrieves the previous run time. To avoid duplicating incidents, it's important that Cortex XSOAR only fetches events that occurred since the last time the function was run. This helps avoid duplicate incidents.
When an integration runs for the first time, the Last Run time will not be in the integration context. We catch this from failing by using an
if statement. When the last run time is not specified, we use a time that is specified in the integration settings.
It is best practices to allow a customer to specify how far back in time they wish to fetch incidents on the first run. This is a configurable Parameter in the integration settings.
Query and Parameters
Queries and parameters allow for filtering of events to take place. In some cases, a customer may only wish to import certain event types into Cortex XSOAR. In this case, they would need to query the API for only that specific event type. These should be configurable Parameters in the integration settings.
The following example shows how we use both First Run and the Query option:
An important parameter is the
Fetch Limit parameter. Using this parameter the customer can enforce the maximum number of incidents to fetch per fetch command. In order to maintain optimal load on XSOAR we recommend enforcing a limit of 200 incidents per fetch. Notice that should a customer enter a larger number or a blank parameter the
Test button should fail.
Creating an Incident
Incidents are created by building an array of incident objects. These object all must contain the
name of the incident, when the incident
occurred as well as the
rawJSON for the incident.
When fetching incidents, it's important to include the
rawJSON key in the incident field, which enables event mapping. Mapping is how an event gets imported into Cortex XSOAR, since it allows a customer to choose which data from the event to be mapped to their proper fields. An example of this is below:
Setting Last Run
When the last of the events have been retrieved, we need to save the new last run time to the integration context. This timestamp will be used the next time the
fetch-incidents function is run.
When setting the last run object, it's important to know that the values of the dictionary must be of type
We recommend using the time of the most recently created incident as the new last run.
When pulling incidents with fetch-incidents the
setLastRun will not execute if there is an error with fetch-incidents.
Sending the Incidents to Cortex XSOAR
When all of the incidents have been created, we return the array of incidents by using the
demisto.incidents() function. This is similar to the
demisto.results() function, but is used exclusively to handle incident objects.
An example of it's usage is below:
If you do not have any incidents to return then just return an empty list to
For troubleshooting fetch-incident execute
!integration_instance_name-fetch in the Playground, it should return the incidents.