How to run CxSAST 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.
Copy the following files to a directory of your choice.
- container-up.sh
- container-down.sh
- docker-compose-activemq.yml
If you are running Docker on a Linux host, ‘sh’ scripts have been 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”

Notice

For internal artifactory users

Please follow https://checkmarx.atlassian.net/wiki/pages/createpage.action?spaceKey=SAST&title=Docker%20daemon to add the internal artifactory as an allowed insecure registry.

Configuration:

Before launching the container, configurations need to be set to reflect the specific environment with which it is intended 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 that are used by Engine Service. The environment variables in the shell ‘sh’ files are used only for the setup. This means that 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 ';' 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

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

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

Unless a fine tuned environment is needed or result files need to stay in the Engine container’s volume, it is suggested to use the values above.

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 as described in the Shell example as the values for the key-value pairs under the “environment:” tag

Required Prerequisites for Installing CxEngine

Linux host, equipped with either an x64 or ARM64 processor.
Docker engine, available from https://docs.docker.com/engine/install/
For Amazon Linux images: Increased limit of file descriptors as explained below.

In the console, enter the following:

Run: ulimit
Verify that there is no limit to the max number of files
Run: docker ps
Find the process number of dotnet (proc#).
Note: The docker ps command only shows running containers by default. To see all containers (both running and stopped), use the -a (or --all) flag.
Run: cat /proc/proc#/limits
Check the Max open files (soft/hard) - it should be 4096/65535 at least
If the current limit is below the expected values, edit /etc/security/limits.conf,
Add these lines:
1 * soft nofile 4096
2 * hard nofile 65535
Restart the machine for the changes to take effect
Repeat steps 1-3 and verify the limits have changed.
If the problem persists - edit run.shrun.sh
Add this parameter to the docker run command:
--ulimit nofile=4096:65535
1 docker run --ulimit nofile=4096:65535

Package Content

The CxEngine package for Linux contains the following files:

cx-engine-server.tar (CxEngine image)
readme.md
run.sh
server.env

The package is provided with the following directory structure:

Installation and Configuration

These instructions assume that the prerequisites are in place and you downloaded the installation package.

Installing CxEngine

Create a new directory.
Copy the three installation files into the new directory:
cx-engine-server.tar
server.env
run.sh
Retrieve the AMQ Password and the URL. The AMQ is usually deployed as part of the CxManager component.
- To retrieve the AMQ password, connect to the CxSAST database, and execute the following SQL query:
  1 SELECT TOP (1000) [Id]
  2 ,[Key]
  3 ,[Value]
  4 ,[Description]
  5 FROM [CxDB].[dbo].[CxComponentConfiguration]
  6 WHERE [Key] = 'MessageQueuePassword'
- To retrieve the AMQ URL, connect to the CxSAST database and execute the following SQL query:
  1 SELECT TOP (1000) [Id]
  2 ,[Key]
  3 ,[Value]
  4 ,[Description]
  5 FROM [CxDB].[dbo].[CxComponentConfiguration]
  6 WHERE [Key] = 'ActiveMessageQueueURL'
Open server.env and update the following environment variables with the required data as follows:
ES_MESSAGE_QUEUE_PASSWORD={retrieve from database}
ES_MESSAGE_QUEUE_URL=tcp://{client host address as explained below}:{port}
CX_ES_ACCESS_CONTROL_URL=http://{client host address}/CxRestAPI/auth
CX_ES_END_POINT={cx-engine-server host address - example - http://x.x.x.x:8088}
If a proxy is used, add the following proxy environment variables:
HTTP_PROXY=http://<ip>:<port>
HTTPS_PROXY=https://<ip>:<port>
Enter sh run.sh to install CxEngine. The image (cx-engine-server.tar) is extracted and loaded. The container is established.

Notice

run.sh uses port 8088 by default, which must be entered in the server.env variables as relevant. To use a different port, follow the instructions below and use that new port where entering the port is required.

Warning

Unlike Windows services, the CxSAST Linux container does not restart automatically by default. Therefore, you have to configure the CxSAST Linux Engine containers to restart automatically. To do so, open run.sh with your text editor and, in the “docker_run_args=” section, add or uncomment “—restart=always”.

Changing the Port for the Command run.sh

It is recommended to use the default port (port 8088). If you have to use a different port, for example, port 8090, change the port as follows:

Run the “docker run” command 0.0.0.0:{exposed port}:8090
Save the new setting.

Verifying that the Server with CxEngine is Running

The syntax below assumes that you use the default port (port 8088).

Run the “docker ps” command. The following is returned, if the container is running:
1 * IMAGE: cx-engine-server
2 * PORTS: 0.0.0.0:8088->8088/tcp
Run the command "docker logs -f {container ID}”. The following is returned if the server is running.
1 * Now listening on: <http://[::]:8088> |Application started

Connecting the CxEngine to the Application

In the web portal, go to Settings > Application Settings > Engine Management and connect to the new engine as explained under Engine Management.

Centos 8 Installation Notes

This note addresses users who use Centos 8 and did not set up a Docker engine yet.

RHEL switched from iptables to nftables, which means that there are no more iptables running on the Centos 8 level and all the firewall functionality is provided by nftables.

The migration from iptables to nftables requires one of the following:

Configuring firewalld to use iptable configurations.
Enabling masquerading.

Configuring Firewalld to use Iptable Configurations

This section explains how to provide an interface to firewalld to add iptables. To do so, do the following:

At the prompt, enter - sudo vi /etc/firewalld/firewalld.conf
Change - FirewallBackend=nftables to - FirewallBackend=iptables
Save the change and reload firewalld. To do so, enter - sudo systemctl restart firewalld.service at the prompt.

Enabling Masquerading

Check what interface docker is using (default is 'docker0').
ip link show
Check available firewalld zones, e.g., 'public'.
- sudo firewall-cmd --get-active-zones
Check what zone the docker interface it bound to, most likely 'no zone' yet.
- sudo firewall-cmd --get-zone-of-interface=docker0
Add the 'docker0' interface to the 'public' zone. Changes take effect once firewalld is reloaded.
- sudo nmcli connection modify docker0 connection.zone public
Add masquerading. It allows for docker ingress and egress.
- sudo firewall-cmd --zone=public --add-masquerade –permanent
Optionally open required incoming ports (optional).
- sudo firewall-cmd --zone=public --add-port=443/tcp
Reload firewalld.
- sudo firewall-cmd –reload
Reload dockerd.
- sudo systemctl restart docker

Best Practices to Maintain Docker Security

This document provides tips for best practice on the optimal security measures to be taken 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:

How to run CxSAST Engine with Docker

Prerequisites:

How to:

Notice

Configuration:

Required Prerequisites for Installing CxEngine

Package Content

Installation and Configuration

Installing CxEngine

Notice

Warning

Changing the Port for the Command run.sh

Verifying that the Server with CxEngine is Running

Connecting the CxEngine to the Application

Centos 8 Installation Notes

Configuring Firewalld to use Iptable Configurations

Enabling Masquerading

Best Practices to Maintain Docker Security

Docker Image

Docker Orchestrators

Search results