Fetching Incidents
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
The The 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.
Last Run
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.
First Run
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:
Fetch Limit
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.
rawJSON
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 string
.
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 demisto.incidents()
function.
Troubleshooting
For troubleshooting fetch-incident execute !integration_instance_name-fetch
in the Playground, it should return the incidents.
