Installing and Configuring CxEngine under Linux
Starting with CxSAST 9.3, CxEngine supports both Windows and Linux, thus becoming a cross-platform. These pages explain how to install CxEngine under Linux, transition to Linux and establish a secure connection between CxEngine and CxManager.
Notice
Before you start installing CxEngine, refer to Preparing the System for Cross-Platform Query Support for additional information.
Starting with CxSAST 9.3, CxEngine is supported by the following common Linux distributions:
CentOS
RHEL (Red Hat Enterprise Linux)
Ubuntu
Amazon Linux
Notice
Some Amazon Linux images are pre-configured with a limited number of file-descriptors, which might render the EngineService unstable. In these cases, the following message is returned: No file descriptors available
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.
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.
Preparing the System for Cross-Platform Query Support
There are differences between Windows and Linux with respect to file names and new line characters. Therefore, CxSAST queries have been adjusted to run run on Windows and Linux. User custom queries must follow the same adaptations to support both platforms as explained below.
Required Adjustments
There are two differences between Linux and Windows:
File names:
Windows –
*\temp\config.xml
Linux –
*/temp/config.xml
New Line characters:
Windows -
\r\n
Linux -
\n
Solution
Already starting with CxSAST 9.2, an additional CxQL API has been introduced, the cxEnv. By using this API variable, queries can be written in a cross-platform format in order to support both operating systems.
There are 6 properties to be used in cxEnv:
cxEnv.Path.DirectorySeparatorChar
cxEnv.Path.AltDirectorySeparatorChar
cxEnvPath.InvalidPathChars
cxEnv.Path.PathSeparator
cxEnv.Path.VolumeSeparatorChar
cxEnv.NewLine
For a full description of each variable, refer to the latest CxQL API guide.
All custom queries must use the above-listed variables rather than the actual values to run on both platforms and all their flavors.
Examples
The following section illustrates two examples.
Directory Separator
This string:
string[] path = fileName.Split('\\');
Must be replaced with the following:
string[] path = fileName.Split(cxEnv.Path.DirectorySeparatorChar);
New Line in Regex
This string:
elseIfs.FindByRegex(@"[\W]if[^;\{]*{[^\}]*}[(\s)(\r\n)]*else[(\s)(\r\n)]*{[^\}]*?[(/\*)(//)]");
Must be replaced with the following:
elseIfs.FindByRegex(@"[\W]if[^;\{]*{[^\}]*}[(\s)(" + cxEnv.NewLine + @")]*else[(\s)(" + cxEnv.NewLine + @")]*{[^\}]*?[(/\*)(//)]");
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
Configuring TLS (SSL) between CxManager and CxEngine
CxSAST supports a secure communication between CxManager and CxEngine based on TLS (SSL) certificates. These instructions take Windows and Linux support for CxEngine into consideration.
The Cx Engine is working on a Rest 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. For additional information and instructions, refer to Configuring TLS (SSL) between CxManager and CxEngine (v9.3.0 and up).
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
Linux Bare Metal Deployment
Description
A standalone Engine can be deployed and used in the following ways:
Docker container
Bare metal deployment (described in this section)
Prerequisites
.NET 3.1 ASP.NET Core Runtime appropriate to the specific Linux OS installed on the machine.
Follow the instruction in the official documentation.
Extract the Engine Service tarball to a directory of your choice.
How to run the CxSAST Engine on demand
The distributed Engine Service package contains an executable script: run.sh
Edit environment variables in the script so that they are appropriate for the deployment environment.
The variables are explained in the Configuration section.
After editing the file, execute run.sh
When the Engine Service starts successfully, it displays the following lines:
Now listening on: http://[::]:8088
Application started. Press Ctrl+C to shut down.
How to run the CxSAST Engine as a system service
The CxSAST Engine can configured to run as a system service so that it runs automatically any time the system is restarted.
The distributed Engine Service package contains the following files that are required for registering the service in systemctl:
cxengine.service - Used for configuration and service parameters.
install.sh - Deploys and starts the service.
Edit the environment variables in the cxengine.service configuration file so that they are appropriate for the deployment environment.
Change the environment variables in the file. The variables are explained in the Configuration section.
After editing the configuration file, execute install.sh
To verify the service is running, use the following command: sudo systemctl status cxengine
Configuration
Edit the following the environment variables in the configuration files to match the deployment environment of the product:
CX_ES_ACCESS_CONTROL_URL - The URL pointing to the Access Control installation instance used.
CX_ES_END_POINT - the endpoint address of the current machine, where this instance of Engine Service is being installed. This address must be the outward-facing IP address that external machines can use to reach the current one. Usually, using the ifconfig command is sufficient to find the IP address. If the machine is behind a router or switch, you can find this value by running the following command locally:
wget -qO- http//ifconfig.me/ip
CX_ENGINE_TLS_ENABLE - Set to ‘true’ to optionally set SSL/TLS communication on.
If an SSL setup is desired, edit the following values as well:
CX_ENGINE_CERTIFICATE_SUBJECT_NAME - Full subject name (ex. CN=dev.corp.com)
CX_ENGINE_CERTIFICATE_PATH - Location of the certificate file
CX_ENGINE_CERTIFICATE_PASSWORD - Password for the certificate’s private key
Message queue details:
CX_ES_MESSAGE_QUEUE_USERNAME
CX_ES_MESSAGE_QUEUE_PASSWORD
CX_ES_MESSAGE_QUEUE_URL
Match these variables to the installed ActiveMQ configuration of user, password, and URL respectively. If unsure, these values can be obtained from the database using the following query: