Create a script - Administrator Guide - 8 - Cortex XSOAR - Cortex

Create a script - Administrator Guide - 8 - Cortex XSOAR - Cortex - Security Operations

Cortex XSOAR Cloud Documentation

Product

Cortex XSOAR

Version

Creation date

2024-03-07

Last date published

2025-01-15

Note

You can enable/disable a script in the Settings, without having to detach or duplicate the script.
You can view recently modified or deleted scripts by clicking version history for all scripts .

Select Scripts → New Script.
Add an identifying name for the script.
Save the script.

Basic script settings

Define the relevant Basic script parameters.

Parameter	Description
Name	An identifying name for the script.
Language type	Select the script language type.
Description	A meaningful description of the script.
Tags	Predefined script identifiers. For example, if a script is intended for phishing, tagging it with the phishing tag helps organize, classify, and manage the script among other scripts. Organizations can also implement policies or restrictions based on tags associated with scripts. For example, they may restrict certain users from accessing or executing a script tagged for phishing.
Enabled	Whether the script is available for playbook tasks and indicator types, or to run in the CLI.

Special script tags

Special script tags enable you to use the script in a specific area of Cortex XSOAR. For example, a script can be tagged for use in post-processing, indicator formatting, field display, and indicator enhancement. The following table includes the commonly used tags:

Tag Value	Description
Condition	Conditional script in a playbook task Note All custom scripts are available for conditional tasks, including scripts without the condition tag. System scripts are only available for use in conditional tasks if they have the condition tag.
dynamic-indicator-section	General purpose dynamic section script for indicator layout
dynamic-section	General purpose dynamic section script for incident layout
enhancement	Indicator enhancement script
field-change-triggered	Script to run on incident field change
field-display	Field display script
filter	Script used as filter or conditional operator in a playbook task
general-dynamic-section	General purpose dynamic section script for object layouts (excluding incidents and indicator layouts)
incident-action-button	Incident layout action button script
indicator-action-button	Indicator layout action button script
indicator-format	Indicator formatting script
post-processing	Incident post-processing script
preProcessing	Pre-process rule script
reputation	Indicator reputation script
sla	SLA breach script
threatIntelReport-action-button	Threat Intel Report layout action button script
transformer	Script used as transformer in a playbook task
widget	Script that can be used to generate a dashboard/report widget

Arguments

You can create, edit, or delete arguments as required.

Parameter	Description
Argument	An identifying name.
Mandatory	Makes the argument mandatory.
Default	Makes the argument the default.
Sensitive	Makes the argument case-sensitive.
Description	A meaningful description of the argument.
Default	The default value for the argument.
Is array	Specifies that the argument is an array.
Type	Select Unknown (default), Key-Value, or Text Area.
List options	A comma-separated list of argument values.

You can create, edit, or delete outputs as required. Define the outputs according to types such as string, number, date, and boolean. For more information, see Context and Outputs.

Parameter	Description
Context Path	A dot-notation representation of the path to access the Context. For example, `ThreatStream.Analysis.ReportID`.
Description	A short description of what the context path represents. For example, the ID of the report submitted to the sandbox.
Type	The value type of the context path, such as string, number, and date Enables Cortex XSOAR to format the data correctly.

Script permissions

Define the script permissions to set who can view and execute the script.

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 Roles	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 Content packs typically use scripts, and the scripts can have dependencies on each other, so it is important to assign the Run as and Role parameters consistently to ensure scripts run properly. If you change permissions for a script, the new permissions do not affect playbooks that are already using the script. The playbooks continue using the previous permissions until the next run, even when the playbook is triggered manually.

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

Roles

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

Content packs typically use scripts, and the scripts can have dependencies on each other, so it is important to assign the Run as and Role parameters consistently to ensure scripts run properly.

If you change permissions for a script, the new permissions do not affect playbooks that are already using the script. The playbooks continue using the previous permissions until the next run, even when the playbook is triggered manually.

Example 18. Script Permissions

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 `DBotRole` 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 `DBotRole` Role set to `Analyst`	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 `Analyst` 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 `Analyst` Role set to `Analyst`	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.

Advanced

Parameter	Description
Timeout (seconds)	Time (in seconds) before the script times out. Default is 180.
Docker image name	For Python scripts, this is the name of the Docker image to use for the script. Cortex XSOAR supports the following Python versions: 2.7 3.0 and later You can change the Docker image. The default Docker image that Cortex XSOAR uses is `demisto/python3`, but you can use other Docker images or images from a private image registry. For more information, see Change the Docker image in an integration or script.
Run on a separate container	Runs the script on a separate container.

Parameter

Description

Timeout (seconds)

Time (in seconds) before the script times out. Default is 180.

Docker image name

For Python scripts, this is the name of the Docker image to use for the script.

Cortex XSOAR supports the following Python versions:

2.7
3.0 and later

You can change the Docker image.

The default Docker image that Cortex XSOAR uses is demisto/python3, but you can use other Docker images or images from a private image registry. For more information, see Change the Docker image in an integration or script.

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.

Edit existing code or create new code

Modify parameters, logic, or integrations within a script to adapt it to specific use cases, optimize performance, and address evolving security needs without starting from scratch.

The Script Helper provides a list of available alphabetically ordered commands and scripts.

Example 19.

See this video for an example using Python code to develop a script.