Configure Engines

Configure Cortex Xpanse engines to use custom certificates and notify users if engine disconnects

You can Edit the Engine Configuration File either by modifying the d1.conf file on the engine or when managing engines. You can only configure an engine in if you have installed the engine using the shell installer.

You can configure the server and engine to do the following:

• Docker Hardening Guide
• Configure an Engine to Use Custom Certificates
• Configure the Engine to Use a Web Proxy
• Configure the Engine to Call the Server Without Using a Proxy
• Use NGINX as a Reverse Proxy to the Engine

Edit the Engine Configuration File

You can edit the engine configuration by either modifying the d1.conf file on the engine, or in Cortex Xpanse by modifying specific properties in the JSON formatted configuration dialog box (Shell installations only).

1. Modify the d1.conf file.

   1. On the machine on which you installed the engine, navigate to the d1.conf file:

      Installation Type	Location
      RPM, DEB, Shell	/usr/local/demisto If using multiple engines, the location is /usr/local/demisto/name of the engine>. For example, /usr/local/demisto/d1_e1
      ZIP	Same folder as the binary.

   2. Modify the file as required. See Common Properties When Editing an Engine Configuration.

      You can also Configure the Engine to Use a Web Proxy.
2. Modify the configuration in Cortex Xpanse.

   Ensure that the data is in JSON format. The properties that you specify override the values defined in the d1.conf file. A use case for modifying the engine configuration is if you want to generate engine logs for a specific log level.

   1. From the engines table, select the engine for which you want to modify the configuration.
   2. Click Edit Configuration.
   3. In the JSON formatted configuration dialog box, modify the properties as required. For more information, see Common Properties When Editing an Engine Configuration.

      

      json-config.png

Common Properties When Editing an Engine Configuration

The following table describes the common properties when editing an engine configuration using the d1.conf file (located by default at /usr/local/demisto/) or in the JSON formatted configuration dialog box in Cortex Xpanse.

Property	Type	Values	Edit
http_proxy	String	The IP address of the HTTP proxy through which the engine communicates.	The engine d1.conf file.
https_proxy	String	The IP address of the HTTP/s proxy through which the engine communicates.	The engine d1.conf file.
LogLevel	String	debug info warning	The engine d1.conf file or in the JSON formatted configuration dialog box.
BindAddress	String	The port on which the engine listens for agent connection requests and communication task responses.	The engine d1.conf file.
EngineURLs	String array	An array of tenant addresses to which the engine tries to connect. If you change the tenant URL, you need to update this parameter.	The engine d1.conf file.
LogFile	String	Path to the d1.log file. If you change the name or location of the d1.log file, you need to update this parameter.	The engine d1.conf file.
engine.allow.data.collection	String	Disables the option to send communication task forms through the engine. false	The engine d1.conf file.

Configure the Engine to Use a Web Proxy

The engine uses a web proxy if the following environment variables are set:

• http_proxy
• https_proxy

If the environment variables are not set, or you wish to use a different settings than those specified in the environment variables, set the configuration with your specific proxy details in the d1.conf file. For example:

{"http_proxy": "http://proxy.host.local:8080",
"https_proxy": "https://proxy.host.local:8443"}

Configure the Engine to Call the Server Without Using a Proxy

In some cases, due to specific environment architecture, you may need to configure the engine to use a proxy when working with integrations, but not use a proxy when calling the Cortex Xpanse tenant.

1. On the computer where you have installed the engine, go to the directory for d1.conf file.

   For RPM, DEB, Shell go to /usr/local/demisto.
2. Add the following configuration:

   Key	Value
   engine.to.server.proxy	false (default is true)

Use NGINX as a Reverse Proxy to the Engine

NGINX can act as a reverse proxy that sits between internal applications and external clients, forwarding client requests to the appropriate application. Using NGINX as a reverse proxy in front of the engine enables you to provide network segmentation where the proxy can be put on a public subnet (DMZ) while the engine can be on a private subnet, only accepting traffic from the proxy. Additionally, NGINX provides a number of advanced load balancing and acceleration features that you can utilize.

The following topics describe how to install NGINX, how to use a Self-Signed Certificate for non-production environments, and how to configure NGINX.

• Install NGINX on the Engine
• Generate a Certificate for NGINX
• Configure NGINX on an Engine

Use Engines Through the NGINX Reverse Proxy

If you want to use an engine (d1) through the reverse proxy, you need to modify EngineURLs in the d1.conf file to point to the host and port the NGINX server is listening on.

Install NGINX on the Engine

You can install NGINX on the Red Hat/Amazon (yum) and Ubuntu Linux distributions. For full instructions and available distributions, see NGINX documentation.

1. On the engine machine, run one of the following commands according to your Linux system:

   • RedHat/Amazon: sudo yum install nginx
   • Ubuntu: sudo apt-get install nginx
2. (Optional) Verify the NGINX installation by running the following command:

   sudo nginx -v

Generate a Certificate for NGINX

You should not use self-signed certificates for production systems. It is recommended to use a properly signed certificate for production systems. These instructions are intended only for non-production setups.

1. To use OpenSSL to generate a self-signed certificate, on the engine machine run the following command:

   sudo openssl req -x509 -nodes -days 3650 -newkey rsa:2048 -keyout /etc/nginx/cert.key -out /etc/nginx/cert.crt
2. When prompted, complete the on-screen instructions to complete the required fields.

Configure NGINX on an Engine

Follow these instructions to configure NGINX on an engine.

1. Open the following NGINX configuration file with your preferred editor:

   /etc/nginx/conf.d/demisto.conf
2. Use the following configuration template:

   Replace DEMISTO_ENGINE with the appropriate hostname.

   # Replace DEMISTO_ENGINE with the appropriate hostname. If needed, change port 443 to the port on which the engine is listening.
   
   upstream demisto {
       server DEMISTO_ENGINE:443;
   }
   
   # Uncomment to redirect http to https (optional)
   # server {
   #     listen 80;
   #     return 301 https://$host$request_uri;
   # }
   
   server {
      # Change the port if you want NGINX to listen on a different port
       listen 443;
       
       ssl_certificate           /etc/nginx/cert.crt;
       ssl_certificate_key       /etc/nginx/cert.key;
   
       ssl on;
       ssl_session_cache  builtin:1000  shared:SSL:10m;
       ssl_protocols  TLSv1 TLSv1.1 TLSv1.2;
       ssl_ciphers HIGH:!aNULL:!eNULL:!EXPORT:!CAMELLIA:!DES:!MD5:!PSK:!RC4;
       ssl_prefer_server_ciphers on;
   
       access_log            /var/log/nginx/demisto.access.log;
   
       location / {
   
         proxy_set_header        Host $host;
         proxy_set_header        X-Real-IP $remote_addr;
         proxy_set_header        X-Forwarded-For $proxy_add_x_forwarded_for;
         proxy_set_header        X-Forwarded-Proto $scheme;
   
         proxy_pass          https://demisto;
         proxy_read_timeout  90;
       }
   
       location ~ ^/(websocket|d1ws|d2ws) {
           proxy_pass https://demisto;
           proxy_http_version 1.1;
           proxy_set_header Upgrade $http_upgrade;
           proxy_set_header Connection "upgrade";
           proxy_set_header Host $host;
           proxy_set_header Origin "";
           proxy_set_header X-Real-IP $remote_addr;
           proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
           proxy_set_header X-Forwarded-Proto $scheme;
       }
   }

   Note

   For multi-tenant deployments, replace location ~ ^/(websocket|d1ws|d2ws) { with location ~ ^/(acc_\S+/)?(websocket|d1ws|d2ws)
3. Restart the NGINX server, by typing the following command:

   sudo service nginx restart
4. Verify you can access the engine by browsing to the NGINX server host.

Configure an Engine to Use Custom Certificates

For communication tasks that go through an engine, you can replace the default self-signed certificate for the engine with your own certificate.

1. Find the two files created by the engine. The default location is /usr/local/demisto.

   d1.key.pem

   d1.cert.pem
2. Replace the contents of these files with your own certificates.
3. Change file owner to demisto:

   chown -R demisto:demisto d1.key.pem

   chown -R demisto:demisto d1.cert.pem
4. Set the file permissions:

   chmod 600 d1.key.pem

   chmod 644 d1.cert.pem
5. (Optional) If you are using a key passphrase for your custom certificate, add the passphrase to your engine configuration:

   1. Go to Settings → Configurations → Engines.
   2. Create New Engine and provide an engine name or select an existing engine and Edit Configuration.
   3. Select Use a passphrase for the engine certificate private key.
   4. Click Save.