Context and outputs
Cortex XSIAM context maps and outputs for integrations and playbooks.
The context is a map (dictionary) / JSON object that is created for each incident and is used to store structured results from integration commands and automation scripts. Context keys are strings and the values can be strings, numbers, objects, and arrays/lists.
The main use of the context is to pass data between playbook tasks. One task stores its output in the context and another task reads that output from the context and uses it.
For example, the ThreatStream integration includes the threatstream-analysis-report command, which returns the report of a file or URL that was submitted to the sandbox.
Cortex XSIAM integration context and outputs
REST API response example
{
"Category": "File",
"Duration": 68,
"Network": [
{
"UdpDestination": "8.8.8.8",
"UdpPort": 53,
"UdpSource": "192.168.2.4"
},
{
"UdpDestination": "192.168.2.4",
"UdpPort": 65324,
"UdpSource": "8.8.8.8"
},
{
"UdpDestination": "192.168.2.4",
"UdpPort": 54896,
"UdpSource": "8.8.8.8"
}
],
"ReportID": "413336",
"Started": "2019-05-30 14:05:25",
"Verdict": "Benign"
}Integration YAML command outputs
In the integration YAML file, the command outputs are defined BrandName.Object.PropertyName.
For each output entry, there are three fields:
Context Path - Dot notation representation of the path to access the context.
Description - Short description of what this context entry represents.
Type - The type of value that is located at the path. Enables Cortex XSIAM to format the data correctly.
YAML output definitions
outputs:
- contextPath: ThreatStream.Analysis.ReportID
description: The ID of the report submitted to the sandbox.
type: String
- contextPath: ThreatStream.Analysis.Category
description: The report category.
type: String
- contextPath: ThreatStream.Analysis.Started
description: Detonation start time.
type: String
- contextPath: ThreatStream.Analysis.Duration
description: Duration of the detonation (in seconds).
type: Number
- contextPath: ThreatStream.Analysis.Network.UdpSource
description: The source of UDP.
type: String
- contextPath: ThreatStream.Analysis.Network.UdpDestination
description: The destination of UDP.
type: String
- contextPath: ThreatStream.Analysis.Network.UdpPort
description: The port of the UDP.
type: String
- contextPath: ThreatStream.Analysis.Verdict
description: The verdict of the sandbox detonation.
type: StringReturn command outputs in code
report_id = '413336'
response_from_api = {
"Category": "File",
"Duration": 68,
"Network": [
{
"UdpDestination": "8.8.8.8",
"UdpPort": 53,
"UdpSource": "192.168.2.4"
},
{
"UdpDestination": "192.168.2.4",
"UdpPort": 65324,
"UdpSource": "8.8.8.8"
},
{
"UdpDestination": "192.168.2.4",
"UdpPort": 54896,
"UdpSource": "8.8.8.8"
}
],
"ReportID": "413336",
"Started": "2019-05-30 14:05:25",
"Verdict": "Benign"
} # assume that we get this response from the service
command_results = CommandResults(
outputs_prefix='ThreatStream.Analysis',
outputs_key_field='ReportID',
outputs=response_from_api
)
return_results(command_result)Note
The code must match the context path outputs specified in the YAML file.
You can output the API response as is to the context as a raw value, under the brand name key. You do not need to modify the API response and map it to human-readable keys.
Avoid using dot and space characters in the context path keys.
Integration context output use cases
Important
When setting integration_name with the vendor value, it must match the name of the integration as defined in the YAML file.
Return integration command data
alerts = [
{
'id': 100,
'name': 'alert1'
},
{
'id': 200,
'name': 'alert2'
}
]
results = CommandResults(
outputs_prefix='PrismaCompute.Alert',
outputs_key_field='id',
outputs=alerts
)
return_results(results)Return data with multiple unique identifier fields
Note
Key fields are used to determine whether the data is updated or added as new.
Return a potentially malicious file
Note
Potentially malicious file - e.g. email attachment
YAML definition
Return IP reputation results
For an integration usage example of how the code implements the indicator reputation command, see AutofocusV2 integration.
Context data - as stored in the incident context data:
YAML definition:
Markdown
Results
12345
95
5.5.5.5
Return domain reputation results
For an integration usage example of how the code implements the indicator reputation command, see AutofocusV2 integration.
YAML definition
Context data - as stored in the incident context data:
Return URL reputation results
For an integration usage example of how the code implements the indicator reputation command, see AutofocusV2 integration.
YAML definition
Context data - as stored in the incident context data:
Return file hash reputation results
For an integration usage example of how the code implements the indicator reputation command, see AutoFocus v2 integration or Crowd Strike Malquery.
YAML definition
Context data - as stored in the incident context data:
Return CVE reputation results
For an integration usage example of how the code implements the indicator reputation command, see CVE Search v2.
YAML definition
Context data - as stored in the incident context data:
Return custom indicator results
For more information, see CustomIndicatorDemo. For a usage example of the CustomIndicator helper class, see CustomIndicatorDemo;.
Context data - as stored in the incident context data:
YAML definition
Return multiple indicator results
For an integration usage example of how the code implements the indicator reputation command, see MispV3. In case you need to return multiple indicators (i.e. IPs) in the same call, you should return a list of CommandResults, as shown in the following example.
Context data - as stored in the incident context data:
YAML definition
Markdown
Results
12345
95
5.5.5.5
54321
73
4.4.4.4
DT (Cortex XSOAR Transform Language)
In the above example, we observe the entry context using (val.ReportID == obj.ReportID). This works to tie together related entry context objects. In this instance, we are using the value of the ReportID key as the unique identifier to search through the existing context and link related objects. This prevents data from being overwritten as well as further enriches an existing entry with more information. Learn more about linking context.
Last updated
Was this helpful?