Docker Images in Cortex XSOAR

Use Docker to run Python scripts and integrations in a controlled environment.
Docker is a tool used by developers to package dependencies into a single container (or image). This means that when creating an integration in Cortex XSOAR you are not required to “pip install” all required packages. The dependencies are part of a container that “docks” to the server and contains all libraries needed to run the integration. For more information see Docker documentation.
Why use Docker?
Docker is used to run Python scripts and integrations in a controlled environment. Integrations are run isolated from the server, which prevents accidental damage to the server. By packaging libraries and dependencies together, unknown issues can be prevented from occurring since the environments remain the same.
Script and Integration Configuration
Specifying which Docker image to use is done in the Cortex XSOAR IDE (Open:
Settings
Docker image name
). If an image is not specified, a default Docker image using Python 2.7 is used. New scripts and integrations use Python 3, unless there is a specific reason not to use it. For example, a need to use a library which is not available for Python 3.
You can specify in the Cortex XSOAR IDE the Python version (2.7 or 3.x). If 3.x is chosen, the latest Cortex XSOAR Python 3 Docker image is selected automatically.
The selected Docker image is configured in the script or integration YAML file under the
dockerimage
key.
Update a Docker Image
From Cortex XSOAR v5.0 and above, you can update a Docker image of a script or integration.
Cortex XSOAR (Demisto) 4.5 and lower does not support updating the Docker image without creating a new script or integration (v2). You can add an additional configuration to the script or integration that updates the Docker image for Cortex XSOAR 5.0 and above and still generate a 4.5 version with the original 4.5 Docker image. This is accomplished in the YAML file with the
dockerimage45
key. This key should contain the Docker image to use by Cortex XSOAR (Demisto) 4.5 and lower.
When the key is present, the content creator script generates two unified YAML files: one for Cortex XSOAR (Demisto) 4.5 and lower and one for 5.0 and higher. For an example see the Kafa v2 integration.
Docker Images
Cortex XSOAR maintains a repository of Docker images, all of which are available in the Docker hub under the Cortex XSOAR organization. The Docker image creation process is managed in the open-source project demisto/dockerfiles. A search of the repository-info branch should be done prior to creating a new image. The repository is updated nightly with all image metadata and os/python packages used in the images.
For security, images that are not part of the Cortex XSOAR organization in Docker hub cannot be accepted.
When an engine needs a Docker image it pulls it either from Docker Hub or from a custom registry, if defined in the server configuration:
python.docker.registry
.
From version 5.0, the engine can fetch Docker images directly from the Cortex XSOAR server. If the engine fails to fetch the Docker image from the registry it tries to fetch it from the Cortex XSOAR server. The server packages the image when running
docker save
, and sends it to the engine, which enables the engine to obtain the required images, even if it does not have network access to the Docker Hub. The engine can only obtain images that are available from the server.
If an existing image cannot be found, you can create a Docker image.
Package Requirements
Consider some of the following:
  • Does the package have known security issues?
  • Is the package licensed?
  • What type of license is used?
Licensing
The Cortex XSOAR Content repository is only compatible with packages that use the MIT license. As a general rule, only use
permissive
licenses. For a complete list of licences and types, see comparison of free and open source software licenses.
Other licenses might be permitted with specific approval.
Security Concerns
Due diligence needs to be done on all approved packages. Including verifying the package name is correct. In 2018 a scan of PyPI resulted in the detection of 11 “typo-squatted” packages which were found to be malicious. See Detecting Cyber Attacks in the Python Package Index (PyPI).
Create a Docker Image in Cortex XSOAR
After due diligence has been completed and licenses checked, you can Create a Docker Image In Cortex XSOAR.
Docker Files (Required for Production)
If the integration is for public release, the integration pushes Docker files into the dockerfiles repository. Pushing into the repository will add an image (after the approval process) to the Docker hub Cortex XSOAR organization. For more information, see Cortex XSOAR’s Dockerfiles and Image Build Management.
When modifying an existing Docker image, ensure the change does not disrupt other integrations that may use the same package. All Docker images are created with unique version tags, for which overriding is blocked.

Recommended For You