Upgrade the Python version to 3.11

Both the certified and customized code in the Marketplace integrations run on Python. To help improve both security and performance, certain Python versions are being deprecated in a phased approach and the platform is moving to Python version 3.11.

If you have custom code written in a Python 2 integration (certified or custom), you need to update the integration code manually. You can use the IDE staging mode to update the integration code without impacting production.

A new community integration that is named Py2to3 helps you refactor the custom code to Python 3.11. You can download integrations directly into the IDE page where you can test your code in staging to make sure the integration works before pushing it into production.

Before you begin

Make sure that you have All Environments selected in your permission group. For more information, refer to Work with permission groups.

Upgrade integrations

Go to Response > IDE.
Pay attention to the banner which lets you know if there integrations that are running outdated versions of Python. This banner also appears on the Marketplace and Playbooks page.
Click View Integration to see a list of these integrations.
Click Close.
Select the required integration on the integrations list.
Click more_vert three dots > Push to staging. This step creates a copy of the integration that you can test and run new code changes in before pushing it live to production.
Click the toggle from Production to Staging in order to enter the Staging mode.
On the same integration, click more_vert three dots > Configure instance. For information on how to configure instances, read Configure instances. Note that this instance is a specific staging instance and won't appear in the integration configuration page. Only a single staging instance is supported for each integration.
Continue to one of the following procedures.

Upgrade certified integrations to Python 3.11

On the required integration, click more_vert three dots > Upgrade Integration. This upgrades the integration and its dependencies to Python version 3.11. Click Save.
If this integration includes custom items, make sure to update the code. You can use the Py2to3 helper if needed.
In the Testing area, add in the parameters as required, including the staging instance that you configured earlier.
After making sure there are no errors in the Debug Output, on the same integration click more_vert three dots > Push to production. Move the toggle back to production mode if required.

Upgrade custom integrations to Python 3.11

Follow this procedure to update the Script Dependencies in custom integrations.

Click more_vert three dots > Configure custom integration.
In the dialog, in the Running on Python field, change to Python 3.11.
Make a note of each of the dependency names under Script Dependencies and save them on your desktop.
Delete these dependencies from the list.
Click Save.
Copy each of the dependency names (without the version or target OS) from your file to the Libraries field and click Add. For example, change requests-2.27.1-none-any.whl to requests and then add it to the Libraries field.
The platform downloads each dependency with Python 3.11 already configured.
After you finish reloading each dependency, click Save.

Use Py2to3 helper to update items in integrations

The Py2to3 helper uses the Python lib2to3 package which is included in the Python standard library, to refactor the Python version 2 code syntax to Python version 3.11. Only use this package on custom integration items. To read more about this library and the changes it can refactor, see Python lib2to3. There are two ways to use the Py2to3 helper: You can use it directly as a community integration in the IDE or you can use it as a tool from your local CLI.

Update custom items in commercial or custom integrations using the Py2to3 integration

Go to Marketplace.
Locate and download the Py2to3 integration.
Go to Response > IDE.
Review the integrations to see which ones have custom items that need updating and make a list of them.
Click more_vert three dots > Push to staging on each integration that needs updating.
Under the Py2to3 integration in the list, select the Refactor Integration job and go to the Testing section.
In the Staging Integration Name field, type the name of the integration whose items need updating.
Repeat as needed for each integration.
Click Play Item. This step updates the code in the staging instances of the integrations.
Go to the Debug Output section to check that the upgrade was successful in the Results area.
Move the toggle button over to the Staging mode.
On the same integration, click more_vert three dots > Configure instance. Make sure to test each integration's code.
For each integration that you updated and tested, click more_vert three dots > Push to production.

Upgrade integration items using the Py2to3 CLI script

You can use the Py2to3.py Manager as a Python CLI script to run locally using an API key.

Verify the following:

Python installation. Ensure that the Python version is greater than 3.7 and before 3.13.
Ensure you have an API key with the Admin permission group and with the Admin SOC role. For information on how to create an API key, see Working with API keys.

To use the Py2to3 CLI script, use the following procedure:

Go to Marketplace.
Locate and download the Py2to3 integration.
Go to Response > IDE.
From the more_vert three dots, select Export.
In the dialog, enter Py2to3 in the Integration name field, select All items, and click Export.
Go to the exported zip package and extract the contents.
In your CLI, navigate to the root directory of the extracted integration:
```
 cd ./Py2to3 
```
Create a virtual environment:
```
 python3 -m venv venv
```
Activate the virtual environment:
In Linux, run
```
source venv/bin/activate
```
In Windows
```
venv\Scripts\activate.bat
```
Install the tool's dependencies:
```
 pip install requests 
```
If you need to install the tool using local dependencies (for Debian), run this prompt instead:
```
pip install Dependencies/requests-2.31.0-py3-none-any.whl --find-links ./Dependencies/
```
To update the custom items in the staged integration to Python 3.11, edit the following command and run it:
```
python ./Managers/Py2to3.py -r https://.backstory.chronicle.security/ {name of integration}
```
At the prompt, enter the API key that you created for this scenario.
After the helper has finished running, go to the platform and refresh the IDE page to see all changes. Google recommends testing the integrations in the staging environment before pushing the integrations to production.

When you finish testing, click the three dots next to the integration name, and select Push to production to apply all changes to production.

Available CLI commands

Command format:

Py2to3.py [-h] -r API_ROOT [-k API_KEY] [-n,--no-verify] [-v] [-d] integration_name

-h, --help: Shows available command-line options.
integration_name: Name of the staging integration:
-r, --api-root URL of the SecOps instance (https://[nameofcustomer].backstory.chronicle.security/)
-k, --api-key API key as a parameter. If provided, the API key prompt is skipped.
-n, --no-verify Disable certificate verification for debug purposes.
-d, --dry-run Prevents the helper from saving the changes to the IDE. Recommended to use with the `-v` flag.
-v, --verbose Logs all the changes made to the code in `diff` format

Remote agents

If you are working with Remote Agents, you need to update both the agent and the integrations running on them as follows:

Go to SOAR Settings > Advanced > Remote Agents.
Click the Update Available button.
Upgrade the agent according to the instructions. If you use Docker, read Perform a major upgrade of a Docker image. If you are upgrading using the installer for Red Hat, see Perform a major upgrade using installer for RHEL. If you are upgrading using the installer for CentOS, see Perform a major upgrade using installer for CentOS.
Upgrade the integrations as described in this document.