Configure Python Docker Integrations to Trust Custom Certificates
Configure CA signed and custom certificates for Docker. Trust custom certificates for python integrations in Cortex XSOAR.
Python integrations running in Docker contain a built-in set of CA-Signed certificates, to which you can add custom trusted certificates when needed. For example, if you work with a proxy that performs SSL traffic inspection or use a service that has a self-signed certificate. You can also configure the server and integrations to trust custom certificates.
Only PEM format certificates are supported.
This procedure assumes that the Cortex XSOAR
lib diris configured to the default location
/var/lib/demisto. If you have moved the
lib dirfile to a different location use the new location instead of the default.
- Configure the custom certificates.
- Create a certificates 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 server machine (requires openssl client):openssl s_client -servername <host_name> -host <host_name> -port 443 -showcerts < /dev/nullFor example,openssl s_client -servername api.github.com -host api.github.com -port 443 -showcerts < /dev/nullThis prints certificate information including the PEM representation of the certificates. After examining the output, if you seeVerification 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 acerts.pemfile 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 thecerts.pemhas all needed certificates as part of the certificate chain, run the following command:openssl verify certs.pem
- After saving thecerts.pemfile, 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/CentOS only) 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 containers access to the/var/lib/demisto/python-ssl-certs.pemfile, 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 thecontainer_file_t SELinuxtype 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, 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.This example adds theproxy-ca.pemfile (custom certificate) to thecacert.permfile (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
- Configure the Cortex XSOAR server settings.
- Go to.SettingsAboutTroubleshooting
- In theServer Configurationsection clickAdd Server Configuration.
(Multi-tenant) In a multi-tenant deployment, the server configuration must be added to each tenant.
- Save the server configuration.
- Restart the Cortex XSOAR server to verify that all existing Docker images are relaunched.
- (Optional)Add the certificate files to engines.
- Configure each engine to use the/var/lib/demisto/python-ssl-certs.pemfile.
- Ensure that you have the following directory on the engine host./var/lib/demisto
- Copy thepython-ssl-certs.pemfile to the/var/lib/demisto directory.
- Add the following configuration to either the engine configuration file (UI) or to thed1.conffile."python.docker.use_custom_certs": true
- Restart the engine.
- Verify that the configuration was added successfully.If you use an SSL inspection proxy (MiTM) and want to verify that the certificates are properly set, run the following command, which fetches from www.google.com using HTTPS, and prints the response headers:!py script="import requests; print(requests.get('https://google.com').headers)"
After you save the server configuration, Docker images that are launched by the Cortex XSOAR server contain the certificates file mounted in the following path:
Additionally, the following environment variables are set with the value of the certificates file path, which enables standard Python HTTP libraries to automatically trust the certificates (without code modifications):
If you develop your own integration (BYOI) and using non-standard HTTP libraries, you may need to include specific code that will trust the passed certificates file when the
environment variable is set. In these cases, 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...
The Python SSL library checks the
SSL_CERT_FILEenvironment variable only when using OpenSSL. If you are using a Docker image that uses
SSL_CERT_FILEenvironment variable will be ignored.
For further troubleshooting, see https://xsoar.pan.dev/docs/reference/articles/troubleshooting-guide#tlsssl-troubleshooting.
Recommended For You
Recommended videos not found.