Cortex XSOAR Tips & Tricks – Execute Command Function

Introduction

When developing the automated SOC workflows for the NVISO Managed SOC and the additional NITRO services on Cortex XSOAR, we have started to make use of automations to do complex tasks instead of playbooks. Automations have much better performances and, if your team has a decent level of Python skills, developing complex tasks in automations can be much easier than playbooks.

When using automations in Cortex XSOAR, the command you will call most often is demisto.executeCommand. This is used to execute available commands from integrations and to call other automations.

To add additional functionality to this command, we have created our own nitro_execute_command wrapper function which is available on the NVISO Github:

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

nitro_execute_command()

When  using demisto.executeCommand to run commands in an automation, the first issue you will come across is that it does not return an error when the command execution was unsuccessful. The execution status of the command that has run can be find in the Type key of the returned result of demisto.executeCommand:

[
    {
        'ModuleName': 'CustomScripts', 
        'Brand': 'Scripts', 
        'Category': 'automation', 
        'ID': '', 
        'Version': 0, 
        'Type': 1, 
        'Contents': None
    }
]

In our nitro_execute_command function, we loop through all returned results from demisto.executeCommand and check the Type key value. If the value is Error (4), we raise an exception with the error message:

raise Exception(f"Error when executing command: {command} with arguments:{args}: {error_result.get('Contents')}")

Because in certain use cases, you might not want your automation to halt whenever a command was unable to run successfully, we have added a fail_on_error boolean parameter to nitro_execute_command:

nitro_execute_command(command='setIncident', args={'name': 'incident name'}, fail_on_error=False)

To improve the resiliency of our set of automations, we have additionally added retry logic when the execution of a command returns an error. In case of an error, the nitro_execute_command function retries by default 3 times before raising an exception and halting the automation. This can be configured with the retry parameter of nitro_execute_command:

nitro_execute_command(command='setIncident', args={'name': 'incident name'}, retry=5)

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_execute_command in all your custom automations.

References

https://xsoar.pan.dev/docs/reference/api/demisto-class#executecommand

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