Create and edit a scrip in Cortex XSOAR, including detach and attach, script settings, etc.
Scripts perform specific actions and are comprised of commands, which are used in playbook tasks and when running commands in the War Room.
In the Scripts page, you can view, edit, and create scripts in JavaScript, Python, or PowerShell. When creating a script, you can access all Cortex XSOAR APIs, including access to incidents, investigations, share data to the War Room, etc. Scripts can receive and access arguments, and can be password protected.
You can use the Script Helper when creating a script, which provides a list of available commands and scripts, ordered alphabetically. For more information about the scripts used in Cortex XSOAR, see the List of Scripts.
Script Permissions
Permissions for scripts in Cortex XSOAR are determined by the Run as and Role fields.
Run as defines the specific role the script is executed with. Role determines who can manually execute the script.
By default, most scripts in Cortex XSOAR are run as a limited user with restricted access. However, some scripts require higher permissions and are delivered out-of-the-box with Run as set to DBotRole, which means the script executes with elevated permissions.
When a user runs a script manually, the Run as permissions are added to the permissions of the user running the script. For example, if user runs a script with Run as set to elevated permissions, its results can be viewed even by users with lower permissions. To mitigate this, you should assign Run as aligned with the users to whom you want to expose the information the script can extract.
When a script runs automatically, for example from a playbook running on fetched incidents, a display script, a trigger script or a pre-processing rule, the Run as permissions define who can view the playbook results.
Note
As content packs may use a number of these scripts, and the scripts could 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 scripts can run properly.
When you change permissions for a script, those permissions do not affect playbooks that are already using the script. The playbooks continue using the previous permissions even when the playbook is triggered manually.
For a script that searches for all incidents in the system, the following scenarios show how the system behaves given the various Run as and Role configurations.
If you implement the following roles on your incidents:
Incident 1: Viewable to Administrators
Incident 2: No role assigned
Incident 3: Viewable by Analysts
Incident 4: Viewable by nested Analyst (custom role)
Scenario | How the system behaves | What a nested Analyst (custom role) sees for each incident when running the script to search for incidents |
|---|---|---|
Run as set to Role not set | All users can execute the script, whether they are an analyst or administrator, and they have access to all incidents that are returned. | Incidents 1 - 4 |
Run as set to Role set to | Any user with at least analyst permissions will have access to execute the script. All other users are not able to implement the script in playbook tasks. They cannot run the script manually from the command line or in a playbook. All users can see the results of the execution in the War Room. | Nested Analyst cannot execute the script, but if a playbook runs the script, nested Analyst sees incidents 1 through 4. |
Run as set to Role not set | All users can execute the script, but only incidents that are viewable by the analyst role and by the executing user's role are returned. | Incidents 2 - 4 |
Run as set to Role set to | Only users with at least the analyst role are able to execute the script. Only incidents that are viewable by the analyst role and by the executing user's role are returned. | Nested Analyst cannot execute the script, but if a playbook runs the script, nested Analyst sees incidents 2 and 4. |
Detach and Attach Scripts
When installing a script from a content pack, by default, the script is attached, which means that it is not editable. To edit the script, you need to either make a copy or detach it.
Note
You can make some changes to the script settings, such as Propagation Labels, Run as, Roles, etc., without having to detach or duplicate the script.
While the script is detached, it is not updated by the content pack. This may be useful when you want to update the script without breaking customization. If you want to update the script through content pack updates, you need to reattach it, but any changes are overwritten by the content pack on upgrade. If you want to keep the changes, make a copy before reattaching.
Script Settings
In Script settings you can define the following information:
Basic
Parameter | Description |
|---|---|
Name | An identifying name for the script. |
Language type | Select the script language. |
Version | The script language version. |
Description | A meaningful description for the script. |
Predefined script identifiers that determine where the script is available. For example, to use this script as a pre-processing script, it must be tagged with the pre-processing tag. | |
Run on | The Cortex XSOAR tenant, single engine, or a load-balancing group. NoteYou need to create an engine for the engine field to appear. |
Propagation Labels | (Multi-tenant) Select the propagation labels for the script. |
Enabled | Whether the script is available for playbook tasks, indicator types, incident types and fields. |
Content Pack | The content pack to which the script belongs, if applicable. |
Arguments
Click ADD ARGUMENT to add new arguments as required.
Parameter | Description |
|---|---|
Argument | An identifying name. |
Mandatory | Makes the argument mandatory. |
Default | Makes this argument the default argument for the script. |
Sensitive | Hides the argument from being displayed in the UI and in logs. |
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. |
Outputs
Click ADD OUTPUT to add the outputs according to string, number, date, boolean, etc. For more information, see Context and Outputs.
Parameter | Description |
|---|---|
Context Path | A dot notation representation of the path to access the Context. For example, |
Description | A short description of what the context path represents. For example, |
Type | The value type of the context path, such as string, number, etc. Enables Cortex XSOAR to format the data correctly. |
Permissions
Parameter | Description |
|---|---|
Password Protect | Enables you to add a password for the script, which will be required when running the script from the CLI. |
Run as | Determines which role the script runs as. Select the role from the dropdown list. |
Roles | The assigned roles determine who can run the script. |
Advanced
Parameter | Description |
|---|---|
Timeout (seconds) | Time (in seconds) before the script times out. Default is 180. |
Docker image name | For Python scripts, the name of the Docker image to use to run this script. For more information, see Change the Docker Image for Scripts and Integrations. |
Run on a separate container | Runs the script on a separate container. |
Depends on Commands
You can set the commands that the script depends on directly from these settings. You still have the option to set the dependencies in the script yaml file.