Cortex XSOAR Tips & Tricks – Tagging War Room Entries

Introduction

The war room in Cortex XSOAR incidents allows a SOC analyst to do additional investigations by using any command available as an automation or integration command. It also contains the output of all tasks used in playbooks (if not in Quiet mode). In this blogpost we will show you how to format output of automations to the war room using the CommandResults class in CommonServerPython, how to add tags to this output and what you can do with these tags.

To support creating tagged war room entries in automations, we have created our own nitro_return_tagged_command_results function which is available on the NVISO Github:

https://github.com/NVISOsecurity/blogposts/blob/master/CortexXSOAR/nitro_return_tagged_command_results.py

CommandResults

The CommonServerPython automation in Cortex XSOAR contains common Python functions and classes created by Palo Alto that are used in multiple built-in automations. They are appended to the code of each integration/automation before being executed.

One of these classes is CommandResults. Together with the return_results function, it can be used to return (formatted) output from an automation to the war room or context data:

results = [
    {
        'FileName': 'malware.exe',
        'FilePath': 'c:\\temp',
        'DetectionStatus': 'Detected'
    },
    {
        'FileName': 'evil.exe',
        'FilePath': 'c:\\temp',
        'DetectionStatus': 'Prevented'
    }
]
title = "Malware Mitigation Status"

command_result = CommandResults(readable_output=tableToMarkdown(title, results, None, removeNull=True),
        outputs_prefix=title,
        outputs=results
    )

return_results(command_result)

By using the outputs_prefix and outputs attributes of the CommandResult class, the following data is created in the Context Data:

By using the readable_output attributes of the CommandResult class, the following entry to the war room is created:

By using the actions menu of the war room entry, you can manually add tags:

nitro_return_tagged_command_results()

The functionality to add tags to war room entries is not available in the return_results function in CommonServerPython, so we created a nitro_return_tagged_command_result function which supports adding tags:

def nitro_return_tagged_command_results(command_result: CommandResults, tags: list):
    """
    Return tagged CommandResults

    :type command_result: ``CommandResults``
    :param command_result: CommandResults object to output with tags
    :type tags: ``list``
    :param tags: List of tags to add to war room entry

    """
    result = command_result.to_context()
    result['Tags'] = tags

    demisto.results(result)

This function allow you to provide tags which will be automatically added to the war room entry:

results = [
    {
        'FileName': 'malware.exe',
        'FilePath': 'c:\\temp',
        'DetectionStatus': 'Detected'
    },
    {
        'FileName': 'evil.exe',
        'FilePath': 'c:\\temp',
        'DetectionStatus': 'Prevented'
    }
]
tags_to_add = ['evidence', 'malware']
title = "Malware Mitigation Status"

command_result = CommandResults(
        readable_output=tableToMarkdown(title, results, None, removeNull=True),
    )

nitro_return_tagged_command_results(command_result=command_result, tags=tags_to_add)

We have added this custom function to the CommonServerUserPython automation. This automation is created for user-defined code that is merged into each script and integration during execution. It will allow you to use nitro_return_tagged_command_results in all your custom automations.

Using Entry Tags

Now that you have created tagged war room entries from an automation, what can you do with this?

We use these tagged war room entries to automatically add output from automations as evidence to the incident Evidence Board. The Evidence board can be used by the analyst to store key artifacts for current and future analysis.

First we use the getEntries command to search the war room for the entries with the “evidence” tag.

results = nitro_execute_command(command='getEntries', args={'filter': {'tags': ['evidence']}})

Then we get the entry IDs from the results of getEntries:

entry_ids = [result.get('ID') for result in results]

Finally we loop through all entry IDs of the tagged war room entries and use the AddEvidence command to add them to the evidence board:

for entry_id in entry_ids:
    nitro_execute_command(command='AddEvidence', args={'entryIDs': entry_id, 'desc': 'Example Evidence'})

The tagged war room entry will now be added to the Evidence Board of the incident:

References

https://docs.paloaltonetworks.com/cortex/cortex-xsoar/6-1/cortex-xsoar-admin/incidents/incident-management/war-room-overview.html

https://xsoar.pan.dev/docs/playbooks/playbook-settings

https://xsoar.pan.dev/docs/reference/api/common-server-python

https://xsoar.pan.dev/docs/integrations/code-conventions#commandresults

https://xsoar.pan.dev/docs/integrations/code-conventions#return_results

https://xsoar.pan.dev/docs/reference/scripts/common-server-user-python

About the author

Wouter is an expert in the SOAR engineering team in the NVISO SOC. As the SOAR engineering team lead, he is responsible for the development and deployment of automated workflows in Palo Alto Cortex XSOAR which enable the NVISO SOC analysts to faster detect attackers in customers environments. With his experience in cloud and DevOps, he has enabled the SOAR engineering team to automate the development lifecycle and increase operational stability of the SOAR platform.

You can contact Wouter via his LinkedIn page.

Want to learn more about SOAR? Sign- up here and we will inform you about new content and invite you to our SOAR For Fun and Profit webcast.
https://forms.office.com/r/dpuep3PL5W