Just Published! Threat Report: Exposing Malware in Linux-Based Multi-Cloud Environments | Download Now

EDR: How to Implement Custom Web UI Certificates

EDR: How to Implement Custom Web UI Certificates

Environment

  • EDR Server: 6.x and Higher 

Objective

To use a custom certificate for the VMware Carbon Black EDR web interface.

Resolution

If you only want to change the WebUI port, follow these directions: EDR: How to customize the web UI port

Important: These steps should be performed on Primary and Minion nodes. Without this, users will be able to access the UI via port 443 if the Minion IP is entered. It is recommended that minions not be used to access the web console and use the firewall to deny outside access on the port for the minions. They will still need to communicate on the custom port within each other. 
  1. Upload the custom .crt and .key files to the EDR server backend. (If the certificate files are password-protected, see this article
  2. Place the files in /etc/cb/certs/
  3. Rename the nginx cb.conf file with mv to back it up:
    mv /etc/cb/nginx/conf.d/cb.conf /etc/cb/nginx/conf.d/cb.conf.default
  4. Copy and rename multi-home template configuration file:
    cp /etc/cb/nginx/conf.d/cb.multihome.conf.example /etc/cb/nginx/conf.d/cb.multihome.conf
  5. Backup the nginx http.conf file:
    cp /etc/cb/nginx/conf.d/http.conf /etc/cb/nginx/conf.d/http.conf.default
  6. Edit /etc/cb/nginx/conf.d/cb.multihome.conf.
    • Modify the line in blue under the WebUI section to the desired port (8443 is the common choice), Note: There are two port areas, the first one is for Sensors. Make sure to edit the end one per the example here.
    • Comment out the two lines nginx.runtime.ssl_certificate.* lines in orange. This disables the use of the self signed cert to allow your custom cert to be used
    • Add the two "ssl_certificate" lines in green,updating to your filename. DO NOT copy and paste as it can sometimes introduce hidden characters, and make sure to include the semicolon ; at the end to terminate the line. 
    • On 7.5.0+ comment out the cb.server.error line in red    
      server
      {
      # This server configuration is used for communications between the sensors
      # and the server.
      
      # IMPORTANT: If this configuration file is used, NginxSensor#### parameters in
      # /etc/cb/cb.conf MUST be updated to match this file.
      # Port 80 is defined in the http.conf. By default it redirects all trafic
      # to the https://$host$request_uri; If this behaviour needs to change update http.conf
      listen [::]:443 ssl ipv6only=off;
      
      include /etc/cb/nginx/conf.d/includes/cb.server.body;
      include /etc/cb/nginx/conf.d/includes/cb.server.sensor;
      
      # Include content of custom server configuration file
      include /etc/cb/nginx/conf.d/includes/cb.server.custom;
      }
      
      server
      {
      # This server configuration is used for VMware Carbon Black EDR Server's Web UI
      
      # IMPORTANT: If this configuration file is used, NginxWebApi#### parameters in
      # /etc/cb/cb.conf MUST be updated to match this file.
      # Port 80 is defined in the http.conf. By default it redirects all trafic
      # to the https://$host$request_uri; If this behaviour needs to change update http.conf
      listen [::]:8443 ssl ipv6only=off;
      
      #include /var/cb/nginx/props/nginx.runtime.ssl_certificate.prop;
      #include /var/cb/nginx/props/nginx.runtime.ssl_certificate_key.prop;
      
      ssl_certificate /etc/cb/certs/mycertfile.crt;
      ssl_certificate_key /etc/cb/certs/mycertfile.key;
      
      include /etc/cb/nginx/conf.d/includes/cb.server.body;
      include /etc/cb/nginx/conf.d/includes/cb.server.api;
      #include /etc/cb/nginx/conf.d/includes/cb.server.error;
      
      # Include content of custom server configuration file
      include /etc/cb/nginx/conf.d/includes/cb.server.custom;
      }
  7. Edit /etc/cb/cb.conf:
       NginxWebApiHttpPort=443
    Change to…
       NginxWebApiHttpPort=8443
    
    And if minion port was also changed (recommended, see additional notes)
       MinionApiPort=443
    change to...
       MinionApiPort=8443
    
also modify the SSLUICertFile and SSLUIKeyFile line entries to point to the new .crt and .key files:
SSLUICertFile=/etc/cb/certs/<file name>.crt
SSLUIKeyFile=/etc/cb/certs/<file name>.key
  1. Port 80 redirection is optional
    • To keep port 80 redirection when typing http://<servername>, open /etc/cb/nginx/conf.d/http.conf and edit this line
         return         301 https://$host$request_uri;
      Change to...
         return         301 https://$host:8443$request_uri;
    • To remove port 80 redirection, open /etc/cb/nginx/conf.d/http.conf and comment out this line
      #listen [::]80 ipv6only=off;
    • Note: You cannot forward from port 443 to 8443 due to sensors communicating over port 443
  2. Update Nginx to forward the custom port in the header for CSRF:
    • Open /etc/cb/nginx/conf.d/includes/headers.includes
    • Find the following line:
proxy_set_header       Host               $host;
  • Edit to:
proxy_set_header       Host               $host:$server_port;
  1. Update the firewall to include 8443
    • If using Iptables on CentOS 6
iptables -I INPUT 5 -p tcp -m state --state NEW -m tcp --dport 8443 -j ACCEPT
service iptables save
service iptables reload
  • If using firewalld on CentOS 7
firewall-cmd --permanent --add-port=8443/tcp
firewall-cmd --reload
  1. Note: There should only be one cb*.conf file. Nginx will fail to start if there are two. Confirm there is only one ending in .conf by running: ls -lh /etc/cb/nginx/conf.d | grep 'cb\.'
    cb.conf.default
    cb.multihome.conf
    
  2. Restart the server services: EDR: How to restart server services
  3. Verify that the UI is accessible: https://<server>:8443

Additional Notes

  • Older server versions may store the multihome configuration in a file such as cb-multihome.conf.example instead of cb.multihome.conf.example. The steps above will still apply, but the file name in step 4 will be different.
  • Custom WebUI certificates require a custom port. The port should not be the same as the sensor listening port. Nginx does not allow duplicate listening ports and will fail to start if not adjusted. Both sensor and webui would be using separate certificates with this adjustment
  • It's recommended to follow the same instructions on the minions for clustered environments. Without this, the console will be accessible over 443 by minion IP and will not use the custom certificates. 
  • Common causes of Nginx not starting after making this change. Always check /var/log/cb/nginx/startup.log
    • Port was not changed to differ from Sensor port, causing a duplicate listen error
    • Line is missing a semicolon at the end to terminate the call
    • Copy/Pasting the lines causes a hidden line feed character
  • It is safe to copy the cb.multihome.conf and http.conf over to the other nodes. Do not copy the /etc/cb/cb.conf as it contains node specific information that could cause services not to startup correctly. 

Related Content


Labels (1)
Tags (2)
Was this article helpful? Yes No
50% helpful (1/2)
Article Information
Author:
Creation Date:
‎01-24-2019
Views:
5569
Contributors