Configuring SSL between CxManager and CxEngine (v9.4.0 and up)

CxSAST supports secure communication between CxManager and CxEngine based on SSL certificates. These instructions take Windows and Linux support for CxEngine into consideration.

The Cx Engine is working on a WCF service that is not managed via the IIS console. The steps below explain how to configure the secure connection on both the CxManager and the CxEngine servers.

The secure connection is established between two servers only, it can be configured with Self Signed Certificates or real CA`s certificates.

Windows

This section explains how to establish a secure connection when running CxEngine under Windows.

CxEngine Host

  • It is recommended to use the PowerShell command New-SelfSignedCertificate as explained for self-signed certificates.

  • The certificate must have the following key usages: DigitalSignature, KeyEncipherment
    The command’s syntax differs between PowerShell versions.

  1. Create a certificate (Certificate Authority-CA or self-signed).

  2. Place the certificate in the store under Local Machine\Personal\Certificates.

  3. Make the private key available to the service. To do so, go to Local Machine\Personal\Certificates and then to Manage Private Keys on the certificate.

  4. Add “Network Service” to the list of authorized users. Read permissions are sufficient.

  5. Copy the certificate to Local Machine\Trusted Root Certification Authority\Certificates.

  6. Set these environment variables on the host (machine) level as explained below.

 

To set the environment variables:

Before setting the environment variables, you have to know the Certificate-Subject.

  1. To obtain the pfx certificate subject name, open the PowerShell and run
    Get-PfxCertificate –FilePath <full path of the PFX file>, for example
    Get-PfxCertificate -FilePath "C:\Users\Administrator\Desktop\myCert.pfx".

  2. Enter your certificate’s password when prompted. The Certificate-Subject appears as illustrated below.

     

  3. Set the following environment variables as follows which includes entering the certificate subject that you just obtained:
    SETX CX_ENGINE_TLS_ENABLE true /m
    SETX CX_ENGINE_CERTIFICATE_SUBJECT_NAME Certificate-Subject /m, for example
    SETX CX_ENGINE_CERTIFICATE_SUBJECT_NAME CN=cx_example.com /m

  4. Restart the CxEngineService.

Manager Host

  • Place the certificate in the Local Machine\Trusted Root CA store.

public only .cer/.crt is sufficient.

Linux

  • Use a pfx (pkcs12) certificate.

Engine Host

The CxEngine server package consists of the components listed below. Additional information is available in the installation instructions for Linux.

  • cx-engine-server.tar (CxEngine image)

  • readme.md

  • run.sh

  • server.env

To establish a secure connection:

1. Copy the certificate to the location of your certificates, for example, /usr/my/certificates

2. Update the following environment variables in the server.env file:

CX_ENGINE_TLS_ENABLE=true
CX_ENGINE_CERTIFICATE_SUBJECT_NAME=Certificate-Subject
CX_ENGINE_CERTIFICATE_PATH=certificat_full_path
CX_ENGINE_CERTIFICATE_PASSWORD=certificat_password

Example:
CX_ENGINE_TLS_ENABLE=true
CX_ENGINE_CERTIFICATE_SUBJECT_NAME=CN=www.myhost.com
CX_ENGINE_CERTIFICATE_PATH=/app/certificate/mycert.pfx
CX_ENGINE_CERTIFICATE_PASSWORD=12345

The CX_ENGINE_CERTIFICATE_PATH must be relative to the location of your certificate inside the container

 

  1. Copy the AMQ broker certificate to the location of your certificates, for example, /usr/my/certificates/<broker_cert>

  2. Modify server.env file with the following:
    CX_ES_MESSAGE_QUEUE_URL=ssl://<Active_MQ_host_address>:<MQ_PORT>?transport.BrokerCertFilename=%2Fusr%2Fmy%2Fcertificates%2F<broker_cert>

  3. If the same certificate used for both engine communication and MQ broker simply modify server.env file as following:
    CX_ES_MESSAGE_QUEUE_URL=ssl://<Active_MQ_host_address>:<MQ_PORT>

3. Add the location of the certificate to the container as illustrated in the example below.

run.sh script

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 #!/bin/bash CX_SERVER_TAR=./cx-engine-server.tar CX_SERVER_ENV=./server.env docker_run_args=( ##Run container in background -d ##Restart policy --restart=always ##Automatically remove the container when it exits #--rm ##Environment variable file --env-file $CX_SERVER_ENV ##Publish a container's port to the host -p 0.0.0.0:8088:8088 ##Volume checkmarx logs directory -v /var/checkmarx:/var/checkmarx ##Volume certificates directory (use when TLS enabled) -v /var/certs:/app/certificate/ ##Checkmarx engine server image cx-engine-server ##[Optional] Certificate parameters #--cert_filepath /certificates_file_path/cert.pfx #--cert_password password #--mng_cert_filepath manager_locally_signed_certificate.crt ) echo loading checkmarx engine server image docker load < $CX_SERVER_TAR echo deploying checkmarx engine server container docker run "${docker_run_args[@]}"

Manager Host

  • Place the certificate in the Local Machine\Trusted Root CA store.

public only .cer/.crt is sufficient.