Configure CA signed and custom certificates for Docker. Trust custom certificates for python integrations in Cortex XSOAR.
Python, Javascript, and native integrations running in Docker use an engine's built-in set of CA-signed certificates to validate TLS communication. If you need to change the certificate bundle of the operating system you are working on, for Javascript and native integrations you need to add custom trusted certificates to the engine built-in set, and for Python Docker integrations you need to create a certificate file that includes the custom certificates and add it to the engine. This is relevant for example if you work with a proxy that performs SSL traffic inspection or use a service that has a self-signed certificate.
Add the certificate to the machine’s trusted root CA bundle. The location of the CA bundle depends on the operating system version and the operating configuration.
Examples of bundle paths:
"/etc/ssl/certs/ca-certificates.crt", // Debian/Ubuntu/Gentoo etc.
"/etc/pki/tls/certs/ca-bundle.crt", // Fedora/RHEL 6
"/etc/ssl/ca-bundle.pem", // OpenSUSE
"/etc/pki/tls/cacert.pem", // OpenELEC
"/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem", //RHEL 7
"/etc/ssl/cert.pem", // Alpine Linux
Examples of certificate bundle directories:
"/etc/ssl/certs", // SLES10/SLES11, https://golang.org/issue/12139
"/etc/pki/tls/certs", // Fedora/RHEL
Restart the engine.
This procedure assumes that the Cortex XSOAR lib dir
is configured to the default location /var/lib/demisto
.
Note
Only PEM format for certificates is supported.
/var/lib/demisto
requires root access. This is relevant for Docker and Podman.
Configure the custom certificates for the engine.
Create a certificate PEM file that includes all of the required custom certificates.
To examine the certificate chain used by a specific endpoint, run the following command on the engine machine (requires openssl client):
openssl s_client -servername <host_name> -host <host_name> -port 443 -showcerts < /dev/null
For example,
openssl s_client -servername api.github.com -host api.github.com -port 443 -showcerts < /dev/null
This prints certificate information including the PEM representation of the certificates. After examining the output, if you see
Verification error: unable to get issuer certificate
, one or more certificates in the certificate chain is not available and you need to obtain these certificates from your IT administrator.To save the certificates to a
certs.pem
file run the following command:openssl s_client -servername api.github.com -host api.github.com -port 443 -showcerts < /dev/null 2>/dev/null | sed -n '/^-----BEGIN CERT/,/^-----END CERT/p' > certs.pem
To verify that the
certs.pem
has all needed certificates as part of the certificate chain, runopenssl verify -CAfile certs.pem site.pem
, wheresite.pem
contains the certificate of a specific site you want to trust. To get the cert of a site, runopenssl s_client -servername <site_host> -host <site_host> -port 443
and copy the base content including-----BEGIN CERTIFICATE-----
and-----END CERTIFICATE-----
.After saving the
certs.pem
file, add its content to/var/lib/demisto/python-ssl-certs.pem
, by running the following command:cat certs.pem >> /var/lib/demisto/python-ssl-certs.pem
(RedHat) Set the required SELinux permissions.
By default, when SELinux is in enforcing mode, directories under
/var/lib/
cannot be accessed by Docker containers. To allow container access to the/var/lib/demisto/python-ssl-certs.pem
file, you need to set the correct SELinux policy type, by typing the following command:chcon -t svirt_sandbox_file_t /var/lib/demisto/python-ssl-certs.pem
(Optional) Verify that the file has the
container_file_t SELinux
type attached by running the following command:ls -d -Z /var/lib/demisto/python-ssl-certs.pem
(Optional) If you require the standard set of certificates trusted by browsers, you can append the CA certificates provided by your operating system. For example, on Ubuntu, these certificates are located at the following path:
/etc/ssl/certs/ca-certificates.crt
. Alternatively, you can download the PEM certificates file provided by the Certifi Project and add your custom certificates to the file that contains the standard set of certificates. For more details, see the cacert.pem file.This example adds the
proxy-ca.pem
file (custom certificate) to thecacert.pem
file (standard certificates):cat proxy-ca.pem >> cacert.pem
Copy the certificates PEM file to the following path.
/var/lib/demisto/python-ssl-certs.pem
(Multi-tenant) In a multi-tenant deployment, the certificate is copied to the following path on the host machine:
/var/lib/demisto/tenants/acc_
TENANT
/python-ssl-certs.pem
Add the certificate file to your engines.
Configure each engine to use the
/var/lib/demisto/python-ssl-certs.pem
file.Verify you have the following directory on the engine host.
/var/lib/demisto
Set the demisto user as the directory owner with 0700 permissions.
Copy the
python-ssl-certs.pem
file to the/var/lib/demisto directory
.Add the following configuration to either the engine configuration file (in the UI) or to the
d1.conf
file."python.docker.use_custom_certs": true
Restart the engine.
After saving the
python.docker.use_custom_certs
configuration on your engine, Docker images that are launched by the engine will contain the certificates file mounted in the following path:/etc/custom-python-ssl/certs.pem
Additionally, the following environment variables will be set with the value of the certificates file path, which enables standard Python HTTP libraries to automatically trust the certificates (without code modifications):
REQUESTS_CA_BUNDLE
SSL_CERT_FILE
The Python SSL library checks the
SSL_CERT_FILE
environment variable only when using OpenSSL. If you use a Docker image that usesLibreSSL
, theSSL_CERT_FILE
environment variable will be ignored. For more details, see LibreSSL support.
Note
If you are developing your own integration (BYOI) and using non-standard HTTP libraries, you might need to include specific code that will trust the passed certificates file when the environment variable SSL_CERT_FILE is set. In this case, always use the value in the environment variable as the path for the certificates file, and do not hard code the mounted path specified above. For example:
certs_file = os.environ.get('SSL_CERT_FILE') if certs_file: # perform custom logic to trust certificates...
Check the integration runs correctly on your engine.
For more information about troubleshooting, see TLS/SSL troubleshooting.