Skip to main content

Configuring SSL between CxManager and CxEngine

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

The CxEngine is working on a WCF (Windows Communication Foundation) 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 CA certificates.

Windows

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

CxEngine Host

Notice

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

6436182609.png

To set the environment variables:

Notice

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.

    6436182612.png

  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.

Notice

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

    Notice

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

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

    run.sh script

    #!/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
)

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.

Notice

public only .cer/.crt is sufficient.

In this section: