> 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/python-development-quick-start-guide/cortex-xsoar-python-development-quick-start-guide/reference.md).

# Reference

### Visual Studio Code Cortex XSOAR Extension

The Cortex XSOAR extension for Visual Studio Code enables you to design and author scripts and integrations for Cortex XSOAR directly from VSCode. The extension adds a set of commands, as a sidebar with Automation and Integration Settings, just like the Settings sidebar in the Cortex XSOAR script editor. When writing code, the plugin provides you with auto-completion of Cortex XSOAR and Python functions. The extension also provides an easy-to-use set of demisto-sdk commands to format your packs, lint, and validate. The extension provides an easy virtual environment setup for Cortex XSOAR integrations and scripts.

These instructions cover configuring Visual Studio Code on Mac OS Big Sur (11.6) and creating a test Cortex XSOAR automation with Python 3.9 with Demisto-SDK 1.5.2 to verify the configuration.

**Prerequisites**

* Visual Studio Code installed on Mac
* GitHub account
* Cortex XSOAR server installed

Review the following Cortex XSOAR development articles:

* [Development Setup](https://xsoar.pan.dev/docs/concepts/dev-setup#bootstrap)
* [Visual Studio Code Extension](https://xsoar.pan.dev/docs/concepts/vscode-extension)
* [Set up Your Dev Environment](https://xsoar.pan.dev/docs/tutorials/tut-setup-dev)
* [Demisto SDK](https://github.com/demisto/demisto-sdk#demisto-sdk)

**Installation and Configuration**

1. In GitHub, create your **content** repository and personal access token.
   1. Fork the public **demisto/content** to your repository, **\<your git user root>/content**.
   2. [Create a personal access token in GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token).
2. In the Mac finder or Terminal shell, create a Python environment.
   1. [Install a Docker desktop on Mac](https://docs.docker.com/desktop/mac/install/) using the downloaded .DMG and verify its installation by running the following command.

      **`docker run --rm hello-world`**
   2. Install Homebrew from a Terminal shell.

      **`/bin/bash -c "$(curl -fsSL`**

      **`https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"`**
   3. Install Python 3.9.7 and Pyenv with Homebrew by running the following commands.

      **`brew update`**

      **`brew install pyenv`**

      **`pyenv install 3.9.7`**
   4. Create a Cortex XSOAR content development directory from a Terminal shell (follow [Set up Your Dev Environment](https://xsoar.pan.dev/docs/tutorials/tut-setup-dev)).
   5. Install virtualenv.

      **`pip3 install virtualenv`**
   6. Create a folder on your Mac (in this example, **xsoarpython**) by running the following commands.

      **`mkdir ../xsoarpython`**

      **`cd xsoarpython`**
3. In the Mac Terminal shell, create a local Cortex XSOAR content repository.
   1. Clone your private GitHub Cortex XSOAR **content** repository to your local system by running the following commands.

      **`git clone https://github.com/<git user>/content.git`**

      **`cd content`**

      **`pyenv local 3.9.7`**
   2. Install the Demisto SDK and update to the latest version by running the following commands.

      **`.hooks/bootstrap`**

      **`source ./venv/bin/activate`**

      **`pip3 install --upgrade demisto-sdk`**
   3. Edit **`.zshrc`** (or whatever shell RC file in use) and add the following lines.

      **`export DEMISTO_BASE_URL=https://<xsoar IP or name>:<port>`**

      **`export DEMISTO_API_KEY<XSOAR API Key>`**

      **`export DEMISTO_SDK_GITHUB_TOKEN<token>`**

      **`eval "$(pyenv init -)"`**
4. On the Mac in Visual Studio Code install extensions and configure them.
   1. Install the Cortex XSOAR and Python extensions.
   2. In the Cortex XSOAR Visual Studio Code extension settings, add the configuration:

      xsoar > Demisto-sdk: Python Path /\<your path>/xsoarpython/content/venv/bin/python
5. Restart Visual Studio Code.
   1. Use the **Select Interpreter** command from the Command Palette and select the **pyenv** version of python (3.9.7) being used with the content repository.
   2. In the Terminal pane at the bottom, verify the configuration.
   3. Run the command **`env`**.
   4. Verify the following values:
      * **`DEMISTO_BASE_URL`**
      * **`DEMISTO_API_KEY`**
      * **`DEMISTO_SDK_GITHUB_TOKEN`**
   5. Execute/debug a simple Python file and verify the pyenv Python version is used in the Terminal pane.
   6. Execute this Cortex XSOAR command from the Demisto SDK in the Terminal pane:

      **`demisto-sdk run --insecure -q 'ip ip="8.8.8.8"'`**
   7. Verify the Demisto SDK command succeeds and provides expected output.

**Create a Test Automation**

1. On the Mac, create a Test Automation pack and script from the terminal shell by running the following commands.

   **`cd xsoarpython/content`**

   **`source ./venv/bin/activate`**

   **`git config --global user.email "<your email name>@<email host>"`**

   **`git config --global user.name "<your user name>"`**

   **`git checkout -b test_automation`**

   **`demisto-sdk init -n TestAutomation`**

   **`demisto-sdk init --script --id "My Test Automation" -n TestAutomation -o Packs/TestAutomation/Scripts`**
2. From the Cortex XSOAR console IDE and Mac Terminal shell:
   1. Copy **`CommonServerPython.py`** from Cortex XSOAR Automations into the Virtual Studio Code workspace (**content/Packs/TestAutomation/Scripts**).
   2. Copy **`CommonServerUserPython.py`** from Cortex XSOAR Automations into the Virtual Studio Code workspace, or create an empty file if not used in Cortex XSOAR.
   3. Copy **`demistomock.py`** into Virtual Studio Code workspace ([content/demistomock.py at master · demisto/content · GitHub](https://github.com/demisto/content/blob/master/Tests/demistomock/demistomock.py)).
3. In Visual Studio Code:
   1. Use Open Folder..." using the **`xsoarpython/content`** folder created.
   2. Edit **`TestAutomation.py`** and create a simple automation.
   3. From the Command Palette, run the the **`XSOAR: Lint`** command.
   4. Once there are no lint errors, commit the automation to GitHub using the **`Git:Commit`** command from the Command Palette or via the **Source Control** icon from the sidebar.
4. In GitHub:
   1. Verify the \*\*`test_automation` \*\*branch was created.
   2. Verify the **`TestAutomation.py`** file is in the branch.

### Development Documentation

The following are links to useful documentation resources.

[Cortex XSOAR Automation Virtual Tour](https://start.paloaltonetworks.com/security-automation-virtual-tour-success.html?sfdcCampaignID=7014u000000eY3UAAU\&languageCode=com\&gtm=Cortex\&acc=granted)

[Cortex XSOAR Training - Write Your First Automation](https://www.youtube.com/watch?v=FaAnSVY6-9g)

[Cortex XSOAR Automations](/xsoar-6-administrator-guide/6.14/customize-cortex-xsoar/customize-and-configure-cortex-xsoar/playbooks/automations.md)

[Cortex XSOAR Demisto Class](https://xsoar.pan.dev/docs/reference/api/demisto-class)

[Cortex XSOAR Common Server Python](https://xsoar.pan.dev/docs/reference/api/common-server-python)

[Cortex XSOAR Common Scripts Content Pack](https://xsoar.pan.dev/marketplace/details/CommonScripts/)

[Demisto Python Client](https://pypi.org/project/demisto-py/2.0.0/)

[Cortex XSOAR Generic Webhook Integration](https://xsoar.pan.dev/docs/reference/integrations/generic-webhook)

[Cortex XSOAR Custom Filters and Transformers Operators](/xsoar-6-administrator-guide/6.14/customize-cortex-xsoar/customize-and-configure-cortex-xsoar/playbooks/filters-and-transformers/filter-operators/create-custom-filter-and-transformer-operators.md)

[Cortex XSOAR Post-Processing Scripts](/xsoar-6-administrator-guide/6.14/customize-cortex-xsoar/customize-and-configure-cortex-xsoar/incidents/post-processing-for-incidents/create-a-post-processing-script.md)

[Add a Script in the Incident Layout](/xsoar-6-administrator-guide/6.14/customize-cortex-xsoar/customize-and-configure-cortex-xsoar/incidents/incident-customization/customize-incident-layouts.md)

[Create a Custom Widget Using an Automation Script](/xsoar-6-administrator-guide/6.14/customize-cortex-xsoar/customize-and-configure-cortex-xsoar/widgets/create-a-custom-widget-using-an-automation-script.md)

[Cortex XSOAR Demisto SDK](https://xsoar.pan.dev/docs/concepts/demisto-sdk)

[Cortex XSOAR IDE](https://xsoar.pan.dev/docs/concepts/xsoar-ide)

[Cortex XSOAR Extension for Visual Studio Code](https://xsoar.pan.dev/docs/concepts/vscode-extension)

[Cortex XSOAR CI/CD](https://xsoar.pan.dev/docs/reference/packs/content-management)

[Cortex XSOAR REST API](/xsoar-6-api/cortex-xsoar-6.x-apis/cortex-xsoar-6-apis-overview.md)

[Cortex XSOAR Logs Overview](/xsoar-6-administrator-guide/6.14/customize-cortex-xsoar/customize-and-configure-cortex-xsoar/logs/logs-overview.md)

[Cortex XSOAR Playbook Debugger](/xsoar-6-administrator-guide/6.14/customize-cortex-xsoar/customize-and-configure-cortex-xsoar/playbooks/playbook-testing/debug-a-playbook.md)

[Cortex XSOAR Troubleshooting](https://xsoar.pan.dev/docs/reference/articles/troubleshooting-guide)

### Third-Party Tools

The following are links to useful tools for developing scripts and troubleshooting specific issues.

[Chrome developer tools for capturing HTTPS request/response traffic](https://developer.chrome.com/docs/devtools/)

[Chrome SAML tracer extension](https://chrome.google.com/webstore/detail/saml-tracer/mpdajninpobndbfcldcmbpnnbhibjmch?hl=en)

[Online SAML decoder](https://www.samltool.com/decode.php)

[Online base 64 decoder and encoder](https://www.base64decode.org/)

[JSON lint](https://jsonlint.com/)

[Markdown preview](https://markdownlivepreview.com/)

[Regex tester](https://regex101.com/)

[YAML lint](http://www.yamllint.com/)

[Postman](https://www.postman.com/)

[Epoch converter](https://www.epochconverter.com/)


---

# 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/python-development-quick-start-guide/cortex-xsoar-python-development-quick-start-guide/reference.md?ask=<question>&goal=<endgoal>
```

`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.