Context Data Management - Administrator Guide - Cortex XSIAM - Cortex - Security Operations

Cortex XSIAM Administrator Guide

Product
Cortex XSIAM
Creation date
2024-02-26
Last date published
2024-04-16
Category
Administrator Guide
Abstract

Learn about incident context data, how it is stored in Cortex XSIAM, and how to access it.

Context data is a map (dictionary) that stores structured results from data such as commands, playbooks, correlation rules, and scripts. Context data includes keys (strings) and values (numbers, maps, arrays, and strings).

You can use context data to pass data between playbook tasks and capture important structured data. Context data acts as an incident data dump from which you can map data into alerts/incident fields using a script. When an alert is generated in Cortex XSIAM and a playbook or analyst begins investigating it, context data will be written to the alert. You can add context data to a parent incident to assist with the investigation and remediation process.

Alert Context Data

When an automation is executed on an alert (command, script, or playbook execution) the results are entered into the alert context, along with all alert fields. Although an alert can access incident data (context and fields), it cannot access data related to other alerts' context and the incident context may be empty, unless you add alert context to incident context data.

All alert data which is stored in alert fields is also stored in the context data. In most cases, not all context data is stored in alert fields. Alert fields represent a subset of the total alert data.

To view context data, when investigating an alert, on the right-hand side of an alert click context-data.png. When viewing the alert context data, you can see both the alert and parent's incident context data.

Note

When an alert is created, the alert data is stored in the context data, under the alert key. When an investigation is opened and commands are run, the data returned from those commands is also stored as context data, outside of the main alert key.

Incident Context Data

As a general rule, when an alert is generated in Cortex XSIAM, context data is written to the alert and not to the incident. You can add data to the incident context and Update Incident Fields From an Alert, By adding incident context data, it enables you to:

  • Add context for remediation: If you have multiple alerts in an incident, you can avoid running duplicate actions, by using the parent incident context in a playbook. You can add the alert context results to the incident context, such as the status, action, or ID and allow other playbooks to use the parent incident context to see if action has occurred.

  • Incident Assignment: You may want to know if an analyst has been assigned to the incident or other alerts.

  • Insights at the incident level: As an automation engineer, you may want to set responses based on characteristics in the incident.

To view context data on the right-hand side of an incident, click context-data.png.

Add Context Data to the Alert and Incident Using the CLI

To add context data to an alert or an incident, you can run the following commands in the CLI in the Alert or Incident War Room:

  • Run the Set command to add data to incident or alert context. The Set command enables you to set a value in context under a specific key. For example, !Set key=hello value=world adds the key and value hello:world to the incident or alert context.

    Note

    If you use the Set command in the Incident War Room, context is added to the Incident context. If running in the Alert War Room, it is added to the Alert context.

  • Run the !setParentIncidentContext in the Alert or Incident War Room to add context to the parent incident. It is useful to add it in the alert war room, so you can easily view the alert context and see what you want to add to the incident. For example, run !setParentIncidentContext key="hello" value="world". In the incident context, you can see the owner of the alert.

    If you run this command in the Incident War Room, the data is added to incident context data dialog box (click the Incident Context Data button to view the added data). If running in the Alert War Room, you can see it both in the incident data dialog box and in the alert context data dialog box (incident tab).

To delete the context in the parent Incident, run the !deleteParentIncidentContext command in the Alert or Incident War Room. You can delete a specific key or delete all the context.

Add Context Data Using a Playbook

In a playbook, context data can be used as follows:

  • When configuring playbook tasks, use information stored in the alert context as task inputs and outputs. You can apply filters and transformers to context data before using the data in playbook tasks.

  • While running a playbook using the debugger. As context data may be updated during a playbook run, you can set a breakpoint to view the context data after a specific task, which can be useful for designing and troubleshooting playbooks.

To see how to use context data in the playbook, see Use Context Data in a Jira Ticketing System.

When running a playbook, the data is written to the alert context data. You can also write the data to incident context data by using the setParentIncidentContext script in a standard task. When you add data to the incident context, if you run playbooks in other alerts, those playbooks can use the incident context data.

Caution

Users with Trigger Playbook permissions on a given alert may still be able to modify the parent incident via commands and scripts, even without full access to the incident.

By default, context data for sub-playbooks is stored in a separate context key. When a task in a main playbook accesses context data, it does not have direct access to sub-playbook data. When a task in a sub-playbook accesses context data, it does not have direct access to the main playbook data. If the sub-playbook has been configured to share globally, the sub-playbook context data is available to the main playbook and vice versa.

Note

Generic polling does not work if a playbook’s context data is shared globally.

Add Context Data using a Script

In any script that runs in an alert, the data is written to the alert context. If you want to add the data to the incident context, in the JSon file, add the setParentIncidentContext to the demisto.executeCommand key. For example, demisto.executeCommand("setParentIncidentContext", {"key":"<key>", "value":"<value>"}).

For example, to add the close reason with the value to the incident context, add demisto.executeCommand("setParentIncidentContext", {"key":"hello", "value":"world"}) to the Json file.

Note

Ensure that you have the required RBAC permission to write scripts.

Search Context Data

To view context data from within an alert or incident, on the right-hand side click context-data.png. In the Context Data pane, you can use Query to search within the JSON for specific items and expand nested keys.

Search examples:

  • ${c} finds the value of the object c.

  • ${HelloWorld.Domain(val.domain == 'example.com')} shows the full object for the example.com domain, as stored in the context data by the domain command that is part of the HelloWorld integration.

  • ${HelloWorld.Domain(val.domain == 'example.com').registrar} shows the registrar for the example.com domain, as stored in the context data by the domain command that is part of the HelloWorld integration.

  • ${HelloWorld.Alert(val.alert_status === "ACTIVE").alert_id} fetches the HelloWorld.Alert.alert_id of all ACTIVE alerts.