Resolve SSL Certificate Path errors

Introduction

This document outlines troubleshooting steps for Mend Integrations encountering a "PKIX Path Building error" during secure communication (HTTPS) with external servers. This error arises when the Java runtime environment cannot validate the authenticity of the server's SSL certificate due to an incomplete certificate chain or a missing trusted Certificate Authority (CA) certificate. Resolving this issue ensures secure data exchange between Mend Repository Integrations and other servers.

Steps

Configure docker host system with custom CA certs
1. Confirm that the certificate is valid by using curl --cacert /path/to/cacert-file <url-to-scm-system>
Export certs on docker host:
1. RPM-Based distros (CentOS, RHEL, Amazon, etc):
  1. Add your certificate to the /etc/pki/ca-trust/source/anchors
  2. Run the command update-ca-trust extract https://www.linux.org/docs/man8/update-ca-trust.html
2. Debian-based distros (Ubuntu, etc.):
  1. Add your certificate to the /usr/local/share/ca-certificates directory.
  2. Run the command update-ca-certificates (for the system)
  3. Run the CLI utility update-java-ca-certificates - Download from: https://github.com/mend-toolkit/mend-examples/tree/main/Repo-Integration/Binaries
Add certificate volume mappings and environment variables to docker-compose.yaml or helm charts.

Container Mappings

RPM-Based Systems

After exporting custom CA certificates on the host, add the following volume mappings to the Mend containers:

Example docker-compose.yaml:

YAML

app:
  # ...
  volumes:
    # handles certificates for most system utilities and git
    - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem:/etc/ssl/certs/ca-certificates.crt
    # containerbase java install symlinks /opt/containerbase/ssl/cacerts into the jre security volder
    - /etc/pki/ca-trust/extracted/java/cacerts:/opt/containerbase/ssl/cacerts
  # ...
  
scanner:
  # ...
  volumes:
    # handles certs for most system utilities and git
    - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem:/etc/ssl/certs/ca-certificates.crt
    # containerbase java install symlinks /opt/containerbase/ssl/cacerts into all jdk installs
    - /etc/pki/ca-trust/extracted/java/cacerts:/opt/containerbase/ssl/cacerts
  # ...
  
remediate:
  # ...
  volumes:
    # handles certs for most system utilities and git
    - /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem:/etc/ssl/certs/ca-certificates.crt
    # containerbase java install symlinks /opt/containerbase/ssl/cacerts into the jre security folder
    - /etc/pki/ca-trust/extracted/java/cacerts:/opt/containerbase/ssl/cacerts
  environment:
    # configures Node to use custom certs exported from host
    - NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt
    # ...

Debian-Based Systems

After exporting custom CA certificates on the host, add the following volume mappings to the Mend containers:

Example docker-compose.yaml:

YAML

app:
  # ...
  volumes:
    # handles certificates for most system utilities and git
    - /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt
    # containerbase java install symlinks /opt/containerbase/ssl/cacerts into the jre security volder
    - /etc/ssl/java/cacerts:/opt/containerbase/ssl/cacerts
  # ...
  
scanner:
  # ...
  volumes:
    # handles certs for most system utilities and git
    - /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt
    # containerbase java install symlinks /opt/containerbase/ssl/cacerts into all jdk installs
    - /etc/ssl/java/cacerts:/opt/containerbase/ssl/cacerts
  # ...
  
remediate:
  # ...
  volumes:
    # handles certs for most system utilities and git
    - /etc/ssl/certs/ca-certificates.crt:/etc/ssl/certs/ca-certificates.crt
    # containerbase java install symlinks /opt/containerbase/ssl/cacerts into the jre security folder
    - /etc/ssl/java/cacerts:/opt/containerbase/ssl/cacerts
  environment:
    # configures Node to use custom certs exported from host
    - NODE_EXTRA_CA_CERTS=/etc/ssl/certs/ca-certificates.crt
    # ...