Install private CA certificates

If your organization uses an internal Certificate Authority (CA) to sign certificates on servers hosting your internal services, you need to install a private CA certificate on your orchestrator’s virtual machine. This allows Rapid7 plugins to connect to your organization’s secure internal sites.

CA certificates are mapped from the host machine into running plugin containers. An interval timer proactively clones the host's CA certificate directory and bind mounts it directly into the plugin container. Certificates are converted to .crt format.

Convert certificate to PEM (base64) format

In order to import a CA certificate or a CA certificate chain into an orchestrator, you will need to convert the file to PEM .pem (base64) format.

To convert a .p7b file to .pem, run the following command: $ openssl pkcs7 -print_certs -in certificate.p7b -out certificate.pem

To convert a .der (binary) file to .pem, run the following command: $ openssl x509 -inform der -in certificate.cer -out certificate.pem

Install a private CA certificate

You will need root access on your orchestrator’s virtual machine to install your CA certificate.

To install a private CA certificate:

1. Open a terminal window.
2. Check the hash sum of the main CA bundle. This returns the hashsum and address of the main CA bundle. You will check the updated hash against this value later.
   • For RHEL, run md5sum /etc/pki/tls/certs/ca-bundle.crt
   • For Ubuntu, run md5sum /etc/ssl/certs/ca-certificates.crt
3. Rename the certificate file to use the .crt extension if the file is currently in .pem format. To do this, run mv myCAroot.pem myCAroot.crt.
4. Copy your CA root certificate.
   • For RHEL, run cp myCAroot.crt /etc/pki/ca-trust/source/anchors
   • For Ubuntu, run cp myCAroot.crt /usr/local/share/ca-certificates
5. Update the trust chain.
   • For RHEL, run sudo update-ca-trust
   • For Ubuntu, run sudo update-ca-certificates
6. Verify the main CA bundled was updated. If the bundle updated successfully, it will return a different hash than the value in the first md5sum command.
   • For RHEL, run md5sum /etc/pki/tls/certs/ca-bundle.crt
   • For Ubuntu, run md5sum /etc/ssl/certs/ca-certificates.crt

Enable CA bundle mirroring in your orchestrator configuration file

After installing your private CA certificates, enable CA bundle mirroring for your orchestrator:

1. Connect to your orchestrator via SSH or virtual console and run orch-config. This opens the configuration file in the vim text editor.
2. Enter edit mode by typing i. Remove the hash # marks at the beginning of the KOMAND_CA_CERT_MIRROR_DIR=/opt/rapid7/orchestrator/ca-cert-mirror and KOMAND_CA_CERT_MIRROR_ENABLED=true lines. Save the changes by pressing the esc button, then typing :wq!.
3. Stop the orchestrator by running the command orch-stop.
4. Clear out any old plugin containers by running sudo docker ps -aq | xargs sudo docker rm -f
5. Restart the orchestrator with the command orch-start.