> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/cortex-xsoar-8-on-prem/8.14/configure-cortex-xsoar/playbooks/scripts/create-a-script.md). # Create a script 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. Rather than creating a script from scratch, you can edit existing scripts. If the script was installed 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. 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 overridden by the content pack on upgrade. If you want to keep the changes, make a copy before reattaching. {% hint style="info" %} ### 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 ![versionhistory.png](/files/GKmWOBbkuITdiHw3N4H9). {% endhint %} 1. Select **Scripts** → **New Script**. 2. Add an identifying name for the script. 3. 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. | **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 | | 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 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](https://xsoar.pan.dev/docs/integrations/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.

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 23. 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 {% hint style="info" %} ### Note To limit incident access to specific roles, see [Limit access to investigations using access control](/cortex-xsoar-8-on-prem/8.14/investigate-and-respond-to-threats/incidents-and-indicators-investigation/investigate-an-incident/limit-access-to-investigations-using-access-control.md). {% endhint %} | 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. Default is 180. | | Docker image name |

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

Cortex XSOAR supports the following Python versions:

You can change the Docker image.

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

| | 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](https://xsoar.pan.dev/docs/concepts/xsoar-ide#the-script-helper) provides a list of available alphabetically ordered commands and scripts. See this video for an example using Python code to develop a script. [Writing automations](https://www.youtube.com/watch?v=FaAnSVY6-9g)
--- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://cortex-docs.paloaltonetworks.com/cortex-xsoar-8-on-prem/8.14/configure-cortex-xsoar/playbooks/scripts/create-a-script.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.