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

The selected Docker image is configured in the script or integration YAML file under the

dockerimage

key.

Docker Images

Cortex XSOAR maintains a repository of Docker images, all of which are available in the Docker hub under the demisto 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.

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:

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 licenses and types, see comparison of free and open source software licenses.

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.