Create a script

Create scripts in Cortex XSOAR 8 SaaS.

Developing scripts in Cortex XSOAR helps to automate repetitive tasks, streamline security operations, and make incident response more efficient. Customizing scripts can improve threat detection, mitigation, and remediation processes specific to your organization's needs.

1. Select Scripts → New Script.
2. Add an identifying name for the script.
3. Save the script.
4. Configure the script settings and add the code you want for 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.

Tags

Script tags enable you to use the script in a specific area in Cortex XSOAR. For example, a script can be tagged to 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 a filter or conditional operator in a playbook task
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 a 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	Hides the argument from being displayed in the UI and in logs.
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	Script permissions are determined by the Run as and Role fields. Run as: Defines the permissions with which the script runs. By default, most scripts run as a Limited user with restricted access and can only perform specific operations allowed by that role. If you select the DBotRole, user roles can execute with full permission. Users with lower permissions can also view the results. To address this, assign Run as according to the user roles you want to give access to the information the script can extract. Note When a script runs automatically (such as from a playbook running on fetched incidents, a display script, a trigger script, or a pre-processing rule) the Run as permission defines who can view the playbook results. Role: Determines which user roles can execute the script. 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 21. Script Permissions

In this example, you created a script that searches for all incidents in the system. The following scenarios show how the system behaves using the Run as and Role configurations.

You restrict the following roles to your incidents:

• Incident 1: Instance administrators
• Incident 2: No role assigned
• Incident 3: Analysts

Note

To limit incident access to specific roles, see Limit access to investigations using access control.

Scenario	How the system behaves	Results
Run as: Analyst Role: Analyst	Only users with at least the analyst role can execute the script. The script is executed with the permissions and access levels associated with the analyst role. The script has the same permission level as an analyst user, allowing you to perform actions based on the assigned role.	The script returns incidents 2 and 3.
Run as: Analyst Role: Not set	All users can execute the script, but only incidents that are viewable by the analyst role are returned.	The script returns incidents 2 and 3.
Run as: Limited User Role: Analyst	The analyst role can execute the script. The script is executed with restricted permissions and access levels. The limited user role defines the specific operations the script can perform, restricting it from executing unauthorized actions or accessing sensitive information within Cortex XSOAR. This provides a more restricted execution environment with a narrower scope of capabilities.	The script returns 2 and 3.
Run as: DBotRole Role: Not set	All users can execute the script, whether they are Analysts or Instance Administrators, and they have access to all incidents that are returned.	All incidents
Run as: DBotRole Role: Analyst	Any user with at least analyst permissions can execute the script. All other users can't run the script in playbook tasks, 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.	All incidents

Advanced

Parameter	Description
Timeout (seconds)	Time (in seconds) before the script times out. The 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.

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