Managing the TLS certificates on the client side

A common configuration for all recent scanners

We are aiming to simplify the SSL configuration for all scanners. This is a work in progress and not all scanners are updated, but we recommend always following those generic steps to be future-proof, and then look at each scanner-specific guidelines on top of it.

All scanners should support a PKCS #12 keystore containing the server or CA certificates to trust (a.k.a. the TrustStore). 

• The default location for the TrustStore is $SONAR_USER_HOME/ssl/truststore.p12 (default value for SONAR_USER_HOME is ~/.sonar). This location can be overridden using the scanner property sonar.scanner.truststorePath
• The default password for the TrustStore is changeit. This password can be overridden using the property sonar.scanner.truststorePassword

Please see the Using the SonarScanner for .NET page in Begin step command line parameters for more details about adding these to your .NET project.

SonarScanner for .NET version 10.0 and newer

If you have specified the TrustStore password in the begin step, you must also specify it in the end step. For more details, see the list of Begin step and End step command line parameters.

The SonarScanner for .NET 10.0+ does not support a certificate revocation list (CRL) when the issuing certificate authority is given via the TrustStore file. This means that revoked certificates will still be trusted when the issuing certificate is given via the TrustStore file.

You can still install the Certificate Authority certificate in your system TrustStore to have CRL support:

• On Linux and MacOS:
  1. Copy the self-signed server certificate to /usr/local/share/ca-certificates
  2. Run sudo update-ca-certificates
• On Windows: use certutil. Here is an example:

certutil -addstore -f "ROOT" <path/to/certificate>

If you use the sonarqube-scan-action for your GitHub Action and your SonarQube Server instance has certificates that need to be recognized by the GitHub runner, you'll need to set the SONAR_ROOT_CERT environment variable in GitHub.

To do this, go to your GitHub repository > Settings > Secrets and Variables and add the SONAR_ROOT_CERT environment variable in PEM format. You can also add it at the level of your GitHub organization (recommended).

# Workaround for https://github.com/actions/runner/issues/863

- name: Workaround for containerized environments

  run: echo "SONAR_USER_HOME=$HOME/.sonar" >> $GITHUB_ENV

- name: Run sonar analysis

  uses: SonarSource/sonarqube-scan-action@<action version>

  ...

If you have integrated SonarQube Server with Azure DevOps, define the following environment variable to add the server self-signed certificate:

• Key: NODE_EXTRA_CA_CERTS
• Value: path to the certificate

*Note that the SonarScanner for .NET version 9.2 was deprecated and should not be used.

For scanner versions 9.1 and earlier

Add the self-signed server certificate to the operating system truststore:

• On Linux and MacOS:
  1. Copy the self-signed server certificate to /usr/local/share/ca-certificates
  2. Run sudo update-ca-certificates
• On Windows: use certutil. Here is an example:

certutil -addstore -f "ROOT" <path/to/certificate>

When using certstores, you must disable JRE provisioning and use the SonarScanner for CLI logic. Add the self-signed certificate to the Java TrustStore as explained below in For SonarScanner for Maven, Gradle, CLI < 6.0 , or NPM < 4.0.

For SonarScanners Maven, Gradle, CLI 5.0.1 and earlier, or NPM 3.5 and earlier

These scanners are still relying on the Java VM for the SSL configuration.

You can either:

• Insert your certificate in the default JVM truststore (something like \jre\lib\security\cacerts). To add the self-signed server certificate to the default truststore, use the JVM tool keytool. The instructions depend on your operating system and you will find many resources online, such as this one for Linux.
  
  See also: Self Signed certificate of DevOps platforms
• Provide a custom Java truststore by using the following properties:
  • javax.net.ssl.trustStore: path to the truststore file (pkcs12 format is recommended)
  • javax.net.ssl.trustStorePassword: password of the truststore.

There is no Docker image for the SonarScanner for .NET therefore, this section does not apply.

If you need to configure a self-signed certificate for the scanner to communicate with your SonarQube Server instance, the preferred way is to mount a folder containing a PKCS #12 file named truststore.p12 (default password changeit) under /opt/sonar-scanner/.sonar/ssl. 

If you have a PEM or DER certificate, you can use OpenSSL or Keytool to generate the PKCS #12 keystore:

• With OpenSSL:

openssl pkcs12 -export -caname sonar -out "truststore.p12" -in "server.pem" -passout pass:"<a password>" -nokeys

• With Keytool 

keytool -import -storetype PKCS12 -alias sonar -keystore truststore.p12 -file server.pem -storepass "<a password>"

If running the scanner in Docker: use a mounted volume

By default, the scanner expects the TrustStore password to be changeit. If you need to use a different password, inform the scanner using the -Dsonar.scanner.truststorePassword=<YOUR PASSWORD> property.

docker pull sonarsource/sonar-scanner-cli
docker run \
    --rm \
    -v ${DIR_WITH_TRUSTSTORE_DOT_P12}:/opt/sonar-scanner/.sonar/ssl \
    -v ${YOUR_CACHE_DIR}:/opt/sonar-scanner/.sonar/cache \
    -v ${YOUR_REPO}:/usr/src \
    -e SONAR_HOST_URL="http://${SONARQUBE_URL}" \
    sonarsource/sonar-scanner-cli \
    -Dsonar.scanner.truststorePassword=<a password> // Not needed if the default password is used

Store the client certificate and CA certificate chain in a keystore file and define the access to this file through the following properties:

• javax.net.ssl.keyStore or (for SonarScanner CLI from version 6.0 and SonarScanner for NPM from version 4.0) sonar.scanner.keystorePath: path to the keystore file.
• javax.net.ssl.keyStorePassword or (for SonarScanner CLI from version 6.0 and SonarScanner for NPM from version 4.0) sonar.scanner.keystorePassword: password of the keystore file.

1. Store the client certificate and CA certificate chain in a keystore file and define the access to this file through the following properties:
   • sonar.clientcert.path : path to the keystore file, must be set in the begin step.
   • sonar.clientcert.password: password of the keystore file, must be set in both the begin and end steps.
2. In addition, set the following options before the end step (for the SonarScanner CLI invocation):
   • javax.net.ssl.keyStore: same value as sonar.clientcert.path
   • javax.net.ssl.keyStorePassword: same value as sonar.clientcert.password