Implementing Custom Web UI Certificates

Products

• Carbon Black EDR (formerly Cb Response)

Issue/Introduction

How to implement a custom certificate for the EDR web interface.

Environment

• EDR Server: 6.x and Higher 

Resolution

If you only want to change the WebUI port, follow these directions: Customizing the web UI port.

Important: These steps should be performed on all Primary and Secondary server nodes. Without this, users will be able to access the UI via port 443 if the secondary server's IP is entered into a browser. It is recommended that secondary servers not be used to access the web console. If possible, use firewall rules to deny outside access on the port for all server nodes except for the primary. All server nodes still need to communicate on the custom port with 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 EDR server version 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

8. 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
9. 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;

9. 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

10. 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
    

11. Restart the server services: EDR: How to restart server services
12. Verify that the UI is accessible: https://<server>:8443

Additional Information

• In some situations it may be necessary to manually type the cert information instead of copying and pasting. 
• 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 secondary servers 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.