Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Advanced network configuration

Configure proxy servers, custom CA certificates, and TLS client certificates for the SonarQube CLI in enterprise network environments.

The SonarQube CLI communicates with your SonarQube server and downloads auxiliary components over HTTPS. In enterprise environments that route traffic through a proxy, use a custom certificate authority (CA), or require mutual TLS (mTLS), you configure the CLI's network behavior using environment variables.

The same settings apply when the CLI launches the SonarQube MCP server for agent integrations or sonar run mcp.

Note: Proxy and certificate configuration is not fully supported by secrets detection, Software Composition Analysis, and Sonar Vortex context augmentation features inside the CLI.

Proxy configuration

Set SONAR_HTTPS_PROXY_URL, SONAR_HTTP_PROXY_URL, and SONAR_NO_PROXY as described in Network connectivity.

Proxy URL format

http://proxy.corp.com:3128

For proxies that require basic authentication, include credentials in the URL:

http://username:password@proxy.corp.com:3128

Warning: Don't set credentials inline in terminal commands; they'll be saved to shell history. Instead, add them to your shell profile (for example, ~/.bashrc or ~/.zshrc), or use your CI/CD platform's secrets management.

Bypassing the proxy for specific hosts

Set SONAR_NO_PROXY to a comma-separated list of hosts that the CLI should reach directly, without going through the proxy:

export SONAR_NO_PROXY="sonar.internal.corp.com,localhost,127.0.0.1"

Supported entry formats:

Format
Matches

sonar.internal.corp.com

Exact hostname only

corp.com

The domain itself and all its subdomains

*.corp.com

Subdomains only; does not match the root domain corp.com

sonar.corp.com:9000

That hostname, but only when connecting on port 9000

*

All hosts; bypasses the proxy entirely

Workarounds for unsupported proxy types

The CLI supports only basic-authentication proxies configured via environment variables. If your environment uses a more complex proxy protocol, use a local proxy adapter to bridge the gap.

NTLM and Kerberos proxies

Corporate proxies that require Windows-domain authentication (NTLM or Kerberos) can't be configured directly. Tools like Cntlm and Px Proxy authenticate with the corporate proxy using your domain credentials and expose a simple unauthenticated endpoint on localhost that the CLI can use.

  1. Install and configure Cntlm or Px Proxy with your domain credentials.

  2. Start the local proxy. By default it listens on http://localhost:3128.

  3. Point the CLI to the local proxy:

Your domain credentials stay in the local proxy's configuration file and are never passed to the CLI.

PAC file environments

The CLI doesn't read PAC (Proxy Auto-Config) files. If your organization distributes proxy settings via a PAC file, find the proxy URL that applies to your SonarQube server hostname (or ask your network team) and set it manually:

In many environments a PAC file evaluates to a single proxy for most corporate traffic, so this reduces to one URL to copy.

Custom CA certificates

Use this when your SonarQube server's certificate is signed by an internal CA, or when an SSL-inspecting proxy (such as Zscaler, Bluecoat, or Netskope) re-encrypts HTTPS traffic with a corporate certificate.

Set SONAR_CA_CERT as described in Network connectivity.

Warning: Don't set NODE_TLS_REJECT_UNAUTHORIZED=0 as a workaround for certificate errors. It bypasses NODE_EXTRA_CA_CERTS but not SONAR_CA_CERT, so it won't resolve issues with this CLI and disables certificate validation entirely. Use SONAR_CA_CERT to trust a specific CA instead.

Certificate format

The certificate must be in PEM format: a Base64-encoded text file that begins with -----BEGIN CERTIFICATE-----. If your certificate is in a different format, convert it using openssl before setting the environment variable.

DER (.der, .crt)

PKCS#12 / PFX

P7B / PKCS#7

Export from the system certificate store

macOS

  1. Open Keychain Access and find the CA certificate.

  2. Right-click the certificate and select Export.

  3. Choose Privacy Enhanced Mail (.pem) as the format and save the file.

Windows

  1. Open certmgr.msc.

  2. Expand Trusted Root Certification Authorities > Certificates.

  3. Right-click the CA certificate and select All Tasks > Export.

  4. On the Export File Format page, choose Base-64 encoded X.509 (.CER).

  5. Complete the wizard and choose a file name when prompted.

The exported file is in PEM format and can be used directly with SONAR_CA_CERT.

TLS client certificates

Use this when your SonarQube server requires a client certificate for HTTPS connections (mutual TLS).

Set SONAR_TLS_CLIENT_CERT, and when needed SONAR_TLS_CLIENT_KEY_FILE and SONAR_TLS_CLIENT_PASSPHRASE, as described in Network connectivity.

Required variables

Variable
Description

SONAR_TLS_CLIENT_CERT

Path to your client certificate PEM file, or a PKCS#12 bundle (.p12 or .pfx)

SONAR_TLS_CLIENT_KEY_FILE

Path to the private key PEM file that matches the certificate. Required when SONAR_TLS_CLIENT_CERT is a PEM file, not when it is a PKCS#12 bundle.

SONAR_TLS_CLIENT_PASSPHRASE

Optional passphrase when the private key or PKCS#12 bundle is encrypted

When SONAR_TLS_CLIENT_CERT points to a PEM file, SONAR_TLS_CLIENT_KEY_FILE is required. If a required file is missing or cannot be read, the CLI records a configuration error and reports it in sonar system status.

Certificate and key format

You can configure a client certificate in either of these ways:

PEM files (separate certificate and key)

Both files must be in PEM format. The certificate file begins with -----BEGIN CERTIFICATE-----. The key file begins with -----BEGIN PRIVATE KEY----- or -----BEGIN RSA PRIVATE KEY-----.

PKCS#12 bundle (.p12 or .pfx)

Set SONAR_TLS_CLIENT_CERT to the bundle path. The CLI extracts the certificate and private key from the file, so you don't set SONAR_TLS_CLIENT_KEY_FILE. Set SONAR_TLS_CLIENT_PASSPHRASE when the bundle is password-protected.

You can combine a client certificate with a custom CA certificate (SONAR_CA_CERT) when your server uses an internal CA and also requires a client certificate.

Examples

PEM certificate and key:

PKCS#12 bundle:

Warning: Don't set SONAR_TLS_CLIENT_PASSPHRASE to its value directly in the terminal; it'll be saved to shell history. Instead, add it to your shell profile (for example, ~/.bashrc or ~/.zshrc), or use your CI/CD platform's secrets management.

Run sonar system status to verify the CLI resolved your certificate path (and key path for PEM files). When configuration is invalid, the Network section shows the error and Recommendations suggests how to fix it.

SonarQube MCP server

When the CLI starts the SonarQube MCP server (sonar run mcp or through sonar integrate for supported agents), it passes your resolved network configuration into the MCP container:

Setting
How the CLI applies it

Proxy (SONAR_HTTPS_PROXY_URL, SONAR_HTTP_PROXY_URL, SONAR_NO_PROXY)

Translated to Java proxy system properties in JAVA_OPTS.

Custom CA (SONAR_CA_CERT)

Certificate file mounted read-only into the container; the MCP image updates the system CA bundle at startup.

Client certificate (SONAR_TLS_CLIENT_*)

PKCS#12 keystore mounted for mutual TLS.

When SONAR_TLS_CLIENT_CERT points to PEM files, the CLI converts them to a temporary PKCS#12 file under ~/.sonar/sonarqube-cli/cli-tmp/ and removes it when the MCP server process exits. PKCS#12 bundles (.p12 or .pfx) are mounted directly.

Set the SONAR_* network variables in the environment of your AI agent or terminal session before the MCP server starts. On Windows with WSL, the CLI translates certificate paths so Docker can mount them correctly.

Related pages

PreviousTelemetry and privacyNextCheck system status

Last updated

Was this helpful?