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.

Certificate Format

If your file is already in PEM format; skip this section and begin installing your CA certificate.

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 CentOS 7/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 CentOS 7/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 CentOS 7/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 CentOS 7/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 certificate(s), then 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. Uncomment KOMAND_CA_CERT_MIRROR_DIR=/opt/rapid7/orchestrator/ca-cert-mirror line and KOMAND_CA_CERT_MIRROR_ENABLED=true by removing the hash # marks at the beginning of these 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.