Use Docker to run Python scripts and integrations in a controlled environment.
Docker is a tool used by developers to package together dependencies into an image. Therefore, you are not required to run pip install to install all the required packages to use your integration. They are part of a image and the image contains all of the libraries you need. See the Docker site for more information.
Script/integration configuration
When creating a script within the Cortex XSIAM IDE, you can specify the Docker image to use, within the script settings. If you don't specify a docker image, a default docker image using Python 3.9 is used.
The selected Docker image is configured in the script/integration yaml file under the dockerimage key. See Integration metadata YAML file
Updating Docker images automatically via pull request
Every integration/script that utilizes either demisto/python or demisto/python3 Docker images Is updated automatically whenever a newer tag is available. This happens via an automatic recurring job that updates the Docker image of the content item by a pull request in the content Git repository. The pack is then distributed in Marketplace.
Enabling/disabling Docker image automatic update
If your integration/script is not using either demisto/python or demisto/python3 Docker images, you can still have it updated automatically by adding the autoUpdateDockerImagekey to the YAML file. For example, the following will update the integration MyIntegration docker image:
commonfields: id: MyIntegration version: -1 name: MyIntegration display: MyIntegration script: dockerimage: demisto/oauthlib:1.0.0.16907 autoUpdateDockerImage: true
If your integration/script uses either demisto/python or demisto/python3 Docker images and you don't want to have it automatically updated, you can set the autoUpdateDockerImage field to false. For example, adding the following will not update your Docker image automatically.
autoUpdateDockerImage: false
Docker images
Palo Alto Networks maintains a large repository of Docker images. All Docker images are available via DockerHub under the Demisto organization. The Docker image creation process is managed via Dockerfiles repository. Before trying to create a new Docker image, check if there is one available already. You can search https://github.com/demisto/dockerfiles-info/blob/master/used_packages.csv which is updated nightly with image metadata and the os/python packages used in the images. To create a custom Docker image to use in your integration or script, follow the Contributing section.
Important
For security reasons, we cannot accept images which are not part of the Docker hub Palo Alto Networks organization.
Package requirements
Considerations when choosing a package to be used in an integration:
Does the package have known security issues?
Is the package licensed? If so, what type of license is being used?
You must perform due diligence on packages you choose to use. This includes verifying the package name is correct. For example, in the past, scans of PyPI resulted in the detection of 11 "typo-squatted" packages which were found to be malicious.
Licensing
The Cortex XSIAM content repository is produced with an MIT (Massachusetts Institute of Technology) license, which means that we use only packages that have a license compatible with the MIT license. As a rule, we only use permissive licenses. For a complete list of OSS licenses and their types see: https://en.wikipedia.org/wiki/Comparison_of_free_and_open-source_software_licenses.
Note
Other licenses may be permitted with specific approval.
Add files to dockerfiles repository
In most cases, if your integration is for public release, you need to push Docker files into the dockerfiles repository located here. Pushing into this repository adds the image (after an approval process) to the Docker hub Palo Alto Networks organization. See the README.md for details.
Server - container communication (advanced)
The Cortex XSIAM launches a Docker container by running a Python loop script. The server communicates with the Python loop script over stdout and stdin. The server passes the relevant integration/script code to the loop script. The script receives the code, executes it and returns a completed response to the server. While the integration/script code is executing, communication is performed over stdout/stdin. The server may then reuse the container to execute additional integrations/scripts that utilize the same Docker container. An simplified example loop script is available for review and testing here.
For example, to use the example loop script to simulate running a simple script which sends a log entry to the server via calling demisto.log(...) run the following:
echo '{"script": "demisto.log(\"this is an example entry log\")", "integration": false, "native": false}' | \
docker run --rm -i -v `pwd`:/work -w /work demisto/python3:3.8.6.12176 python Utils/_script_docker_python_loop_example.py