How to Run the Checkmarx SAST Engine with Docker

Prerequisites:

Docker engine installation (Linux) or Docker Desktop (Windows or Mac). Docker documentation
Docker-Compose appropriate for the host OS. Docker-Compose documentation

How to:

Verify that your environment has an installation of Docker and Docker-Compose specific to your host’s OS.
Create the following files in a directory of your choice and set their contents to the sample contents given below, then update them according to the instructions in the Configuration section below.
- container-up.sh
- container-down.sh
- docker-compose-activemq.yml
If you run Docker on a Linux host, ‘sh’ scripts are provided for easy configuration. Otherwise, you’ll only need the ‘yml’ file with minor configurations.

#!/bin/bash
export MESSAGE_QUEUE_DISABLE= # 1 if no message queue is needed. Leave blank otherwise
# region for <Message queue NOT disabled>
export MQ_PASSWORD= # Message queue encrypted password
export MQ_URL_WITH_PORT= # Message queue url with port. Ex: tcp://10.31.100.252:61616
export ACCESS_CONTROL_URL= # Access Control Url. Ex: http://10.31.100.252
export ENGINE_SERVICE_API_URL_WITH_PORT= # Url of Engine Service's exposed endpoint with port. Usually it's the hosting machine's ip and port
# End <Message queue NOT disabled>

export ENGINE_VERSION=9.2.0 # Version of Engine Agent
export PUBLISHING_METHOD="MessageQueue"       # FileSystem and/or MessageQueue ';' seperated
                                                                                # Use FileSystem if message queue is disabled

export ENABLED_QUEUES="ResultQueue;StatusQueue;IncrementalFilesQueue;MethodsMappingQueue" # None or more of [ResultQueue, StatusQueue, IncrementalFilesQueue, MethodsMappingQueue] ';' seperated
                                                                                                                                                                                # Recommending all when using with application
                                                                                                                                                                                # Empty if message queue is disabled
docker-compose -f docker-compose-activemq.yml up -d

version: '3'
services:
###############################################################################################################
    cx-engine-agent:
        image: cx-artifactory:8081/sast-engine-docker/linux_x64/staging/cx-engine-agent-9.2.0:latest        
        container_name: cx-engine-agent
        volumes:
            - engineagentvol:/app
        networks:
            - "prod"       
###############################################################################################################
    cx-engine-service:
        image: cx-artifactory:8081/sast-engine-docker/linux_x64/staging/cx-engine-service-9.2.0:latest
        #build:
        #    context: .
        #    dockerfile: Dockerfile
        container_name: cx-engine-service
        restart: always
        depends_on: 
            - cx-engine-agent
        volumes:
            - engineagentvol:/app/EngineServer 
        ports:
            - "8088:8088"
        environment:
            - ES_MESSAGE_QUEUE_USERNAME=cxuser
            - ES_MESSAGE_QUEUE_PASSWORD=${MQ_PASSWORD}                                   # Encrypted MessageQueue Password
            - ES_MESSAGE_QUEUE_URL=${MQ_URL_WITH_PORT}                             # Url with port of Message Queue. Ex: tcp://10.0.0.138:61616
            - ACCESS_CONTROL_URL=${ACCESS_CONTROL_URL}/CxRestAPI/auth             # Url of Access Control
            - ENGINE_SERVICE_END_POINT=${ENGINE_SERVICE_API_URL_WITH_PORT}       # Url of Engine Service's exposed endpoint with port. Usually it's the hosting machine's ip
            - CX_VERSION=${ENGINE_VERSION}                                               # Version of Engine Agent
            - EA_PUBLISHING_METHOD=${PUBLISHING_METHOD}
            - EA_ENABLED_QUEUES=${ENABLED_QUEUES}
            - CxLogsPath=/etc/checkmarx/Logs/EngineService
            - ENGINE_WORKER_PATH=/app/EngineServer
            - ENGINE_TLS_ENABLE=false
        networks:
            - "prod" 
###############################################################################################################
networks:
    prod:
volumes:
    engineagentvol:

Edit and insert environment-specific configuration to “container-up.sh” (Linux host only) or
“docker-compose-activemq.yml” (any host OS). Configuration is further detailed in the appropriate section below.
Launch the container using ./container-up.sh (Linux host only) or
“docker-compose -f docker-compose-activemq.yml up -d“ (any host OS)
Note: If you are using the shell script, make sure it has execute permissions (chmod +x container-up.sh)
When the container is up and running successfully in “detached” mode, it is possible to go into the running container with an interactive shell using: “docker exec -it cx-engine-service bash“
To shut the container down, use ./container-down.sh or
”docker-compose -f docker-compose-activemq.yml down”

Configuration:

Before launching the container, configurations must be set to reflect the specific environment it intends to communicate. Currently, this is done manually by editing either “container-up.sh“ (recommended for Linux hosts) or “docker-compose-activemq.yml.“

Important: only the environment variables listed in the ‘yml’ file are those used by Engine Service. The environment variables in the shell ‘sh’ files are used only for the setup. If you wish to change the environment variables on a running container, look for them by name using the link above or by looking up their keys in the ‘yml’ file.

#!/bin/bash
export MESSAGE_QUEUE_DISABLE= # 1 if no message queue is needed. Leave blank otherwise
# region for <Message queue NOT disabled>
export MQ_PASSWORD= # Message queue encrypted password
export MQ_URL_WITH_PORT= # Message queue url with port. Ex: tcp://10.31.100.252:61616
export ACCESS_CONTROL_URL= # Access Control Url. Ex: http://10.31.100.252
export ENGINE_SERVICE_API_URL_WITH_PORT= # Url of Engine Service's exposed endpoint with port. Usually it's the hosting machine's ip and port
# End <Message queue NOT disabled>

export ENGINE_VERSION=9.2.0 # Version of Engine Agent
export PUBLISHING_METHOD="MessageQueue"	# FileSystem and/or MessageQueue ';' separated
										# Use FileSystem if message queue is disabled

export ENABLED_QUEUES="ResultQueue;StatusQueue;IncrementalFilesQueue;MethodsMappingQueue" # None or more of [ResultQueue, StatusQueue, IncrementalFilesQueue, MethodsMappingQueue] ';' seperated
																						# Recommending all when using with application
																						# Empty if message queue is disabled
docker-compose -f docker-compose-activemq.yml up -d

#!/bin/bash
export MESSAGE_QUEUE_DISABLE= 
export MQ_PASSWORD=091141104077175018047185115193151162082025146108
export MQ_URL_WITH_PORT=tcp://10.31.100.252:61616
export ACCESS_CONTROL_URL=http://10.31.100.252
export ENGINE_SERVICE_API_URL_WITH_PORT=http://10.32.2.61:8088

export ENGINE_VERSION=9.2.0
export PUBLISHING_METHOD="MessageQueue"
export ENABLED_QUEUES="ResultQueue;StatusQueue;IncrementalFilesQueue;MethodsMappingQueue"							
docker-compose -f docker-compose-activemq.yml up -d

Breakdown of the values in the example above:

The environment contains an All-In-One installation on a laptop Windows machine with IP 10.31.100.252
A CentOS Linux VM, which will be the host of the dockerized Engine Service with IP 10.32.2.61

This instance of Engine Service will use the message queue, so MESSAGE_QUEUE_DISABLE key is empty.
MQ_PASSWORD is the encrypted password for the ActiveMQ instance installed on a remote machine
MQ_URL_WITH_PORT is the IP and port of the installed ActiveMQ used by the entire solution
Access_Control_URL is the IP where Access Control is installed. It will be used for authorization and authentication.
ENGINE_SERVICE_API_URL_WITH_PORT is the IP of the Linux VM and the exposed port, which is bridged to the running container’s Engine Service port
ENGINE_VERSION is used for informational and display purposes in the New Queue Management flow
PUBLISHING_METHOD was configured to send results to the MQ just like an All-In-One default engine
ENABLED_QUEUES was configured to use all queue options

The values above are suggested to be used unless a fine-tuned environment is needed or the result files must stay in the engine container’s volume.

version: '3'
services:
###############################################################################################################
    cx-engine-agent:
        image: cx-artifactory:8081/sast-engine-docker/linux_x64/staging/cx-engine-agent-9.2.0:latest        
        container_name: cx-engine-agent
        volumes:
            - engineagentvol:/app
        networks:
            - "prod"       
###############################################################################################################
    cx-engine-service:
        image: cx-artifactory:8081/sast-engine-docker/linux_x64/staging/cx-engine-service-9.2.0:latest
        #build:
        #    context: .
        #    dockerfile: Dockerfile
        container_name: cx-engine-service
        restart: always
        depends_on: 
            - cx-engine-agent
        volumes:
            - engineagentvol:/app/EngineServer 
        ports:
            - "8088:8088"
        environment:
            - ES_MESSAGE_QUEUE_USERNAME=cxuser
            - ES_MESSAGE_QUEUE_PASSWORD=${MQ_PASSWORD}                                   # Encrypted MessageQueue Password
            - ES_MESSAGE_QUEUE_URL=${MQ_URL_WITH_PORT}                             # Url with port of Message Queue. Ex: tcp://10.0.0.138:61616
            - ACCESS_CONTROL_URL=${ACCESS_CONTROL_URL}/CxRestAPI/auth             # Url of Access Control
            - ENGINE_SERVICE_END_POINT=${ENGINE_SERVICE_API_URL_WITH_PORT}       # Url of Engine Service's exposed endpoint with port. Usually it's the hosting machine's ip
            - CX_VERSION=${ENGINE_VERSION}                                               # Version of Engine Agent
            - EA_PUBLISHING_METHOD=${PUBLISHING_METHOD}
            - EA_ENABLED_QUEUES=${ENABLED_QUEUES}
            - CxLogsPath=/etc/checkmarx/Logs/EngineService
            - ENGINE_WORKER_PATH=/app/EngineServer
            - ENGINE_TLS_ENABLE=false
        networks:
            - "prod" 
###############################################################################################################
networks:
    prod:
volumes:
    engineagentvol:

In a Windows or Mac hosting environment, edit the ‘yml’ file directly rather than the Linux-specific Shell script. Use the same values described in the Shell example for the key-value pairs under the “environment:” tag.

Best Practices to Maintain Docker Security

This document provides best practices for optimal security measures when running the Engine on Linux Docker.

Docker Image

The provided docker image uses the following protection:

Uses a limited Linux version (.NET Core 2.1 and .NET Core 3.1 alpine).
Creates a dedicated user (not root) to operate the respective docker.

Docker Orchestrators

When working with multiple docker orchestrators, each of them provides a default set of capabilities.

To optimize security, the customer can remove all capabilities. The Engine doesn’t require any special permission or capability in order to run.

To drop all capabilities when using Docker Compose, you can use the following command:

cap_drop:

-all

In this section: