Automations

Create and edit an automation in Cortex XSOAR, including detach and attach, automation settings, etc.
Automations perform specific actions and are comprised of commands, which are used in playbook tasks and when running commands in the War Room.
In the
Automation
page, you can view, edit, and create automations in JavaScript, Python, or Powershell. When creating an automation, you can access all Cortex XSOAR APIs, including access to incidents, investigations, share data to the War Room, etc. Automations can receive and access arguments, and can be password protected.
You can use the Script Helper when creating an automation, which provides a list of available commands and scripts, ordered alphabetically. For more information about the automations used in Cortex XSOAR, see the List of Automations.

Automation Permissions

Permissions for automations in Cortex XSOAR are determined by the
Run as
and
Role
fields.
Run as
determines the permissions with which the automation runs.
Role
determines who the automation can be seen and executed by.
By default, most automations in Cortex XSOAR are run as the limited user. However, some automations require higher permissions and are delivered, out-of-the-box with
Run as
set to
DbotRole
, which means the automation executes with elevated permissions. When an automation runs with elevated permissions, its results can be viewed even by users with lower permissions. To mitigate this, you should assign a role to the automation that is aligned with the users to whom you want to expose the information the automation can extract.
As Content Packs might use a number of these automations, and the automations might have some dependency on each another, it is important that you assign the
Run as
and
Role
parameters consistently to ensure that all of the automations can run properly.
For example, you have an automation that searches for all incidents in the system. The following scenarios show how the system behaves given the various configurations.
Scenario 1
Set the automation with
Run as
, defined as
DBotRole
and do not set the
Role
parameter.
Anyone can run the automation, whether they are an analyst or administrator, and they have access to all incidents that are returned.
Scenario 2
Set the
Run as
parameter to
DBotRole
, and set the
Role
parameter to
Analyst
. Any user with at least analyst permissions will have access to execute the automation. All other users are not able to implement the automation in playbook tasks. They cannot run the automation manually, neither from the command line nor in a playbook.
All users can see the results of the execution in the War Room.
Scenario 3
Set the
Run as
parameter to
Analyst
and do not set a role. Everyone can run the automation, but only incidents that are viewable by the analyst role are returned.
Scenario 4
You set the
Run as
as parameter to
Analyst
and define the
Role
parameter as
Analyst
. Only users with at least the analyst role are able to execute the automation. Only incidents that are viewable by the analyst role are returned.
For example, you implemented the following roles on your incidents:
  • Incident 1 viewable to Administrators
  • Incident 2 without any role assigned
  • Incident 3 viewable by Analysts
  • Incident 4 viewable by nested Analyst (custom role)
As a nested analyst, you run the automation to search for the incidents in your system.
  • In scenario 1, you will see incidents 1 through 4.
  • In scenario 2, you will not be able to execute the automation, but if a playbook runs the automation, you will see incidents 1 through 4.
  • In scenario 3, you will be able to see incidents 2 through 4.
  • In scenario 4, you will not be able to execute the automation, however, if a playbook runs the automation, you will see incidents 2 and 4.
To change the permissions for out-of-the-box automations:
  1. Detach the automation.
    Note that detached automations no longer receive content updates.
  2. Change the permissions.
You can re-attach the automation, however, the changes you made will be overwritten the next time the content is updated.
When you change permissions for an automation, those permissions do not affect playbooks that are already using the automation. The playbooks continue using the previous permissions even when the playbook is triggered manually.
For more information, see Role-based Permission Levels.

Detach and Attach Automations

When installing an automation from a Content Pack, by default, the automation is attached, which means that it is not editable. To edit the automation, you need to either make a copy or detach it.
While the automation is detached, it is not updated by the Content Pack. This may be useful when you want to update the automation without breaking customization. If you want to update the automation type through Content Pack updates, you need to reattach it, but any changes are overridden by the Content Pack on upgrade. If you want to keep the changes, make a copy before reattaching.

Automation Settings

In
Script settings
you can define the following information:
Basic Settings
Parameter
Description
Name
An identifying name for the automation.
Type
Select the automation language.
Description
A meaningful description for the automation.
Tags
Predefined script identifiers that determine where the automation is available. For example, to use this automation as a pre-processing automation, it must be tagged with the pre-processing tag.
Enabled
Whether the automation is available for playbook tasks, indicator types, incident types and fields.
Content Pack
The Content Pack for which the automation belongs.
Arguments
Parameter
Description
Argument
An identifying name.
Mandatory
Makes the argument mandatory.
Default
Makes this argument the default argument for the automation.
Sensitive
Makes the argument case sensitive.
Description
A meaningful description for the argument.
Initial value
The initial default value for the argument.
Is array
Specifies that the argument is an array.
List options
CSV list of argument values.
You can define the outputs according to string, number, date, boolean, etc. For more information, see Context and Outputs. The Important field is for backwards compatibility only for previous Cortex XSOAR versions.
Permissions
Parameter
Description
Password Protect
Enables you to add a password for the automation, which will be required when running the script from the CLI
Run as
Determines which role the automation runs as. Select the role from the dropdown list.
Roles
The assigned roles determine who can run the automation.
Advanced
Parameter
Description
Timeout (seconds)
Time (in seconds) before the automation times out. Default is 180.
Run on
The Cortex XSOAR server or D2 agent.
Docker image name
For Python automation, the name of the Docker image to use to run this automation.
Run on a separate container
Runs the automation on a separate container.
You can set the commands that the automation depends on directly from these settings. You still have the option to set the dependencies in the automation yaml file.

Recommended For You