> For the complete documentation index, see [llms.txt](https://docs.sonarsource.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.sonarsource.com/sonarqube-cli/administration/advanced-network-configuration.md).

# 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), configure the CLI's network behavior with environment variables or stored `sonar config` keys.

The same resolved settings apply when the CLI launches the [SonarQube MCP server](https://github.com/SonarSource/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 [Vortex context](/agent-centric-development-cycle/inside-your-agent-the-agentic-loop/sonar-vortex-context.md) features inside the CLI.

## Configuration sources

The CLI checks sources in this order:

1. The matching `SONAR_*` environment variable. See [Environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md#network-connectivity).
2. The matching stored `sonar config` key. Store it with [`sonar config set`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-set), print one key with [`sonar config get`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-get), print every key with [`sonar config list`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-list), and remove it with [`sonar config unset`](/sonarqube-cli/using-sonarqube-cli/commands.md#sonar-config-unset).
3. A generic environment variable, for proxy and custom CA settings only.

The custom CA certificate and each client certificate setting use the first source that has a value. Generic proxy names also match `https_proxy`, `http_proxy`, and `no_proxy`.

| Setting                     | `SONAR_*` variable            | Stored key                     | Generic variable      |
| --------------------------- | ----------------------------- | ------------------------------ | --------------------- |
| HTTPS proxy                 | `SONAR_HTTPS_PROXY_URL`       | `network.proxy.https`          | `HTTPS_PROXY`         |
| HTTP proxy                  | `SONAR_HTTP_PROXY_URL`        | `network.proxy.http`           | `HTTP_PROXY`          |
| Hosts that bypass the proxy | `SONAR_NO_PROXY`              | `network.proxy.noProxy`        | `NO_PROXY`            |
| Custom CA certificate       | `SONAR_CA_CERT`               | `network.tls.caCert`           | `NODE_EXTRA_CA_CERTS` |
| Client certificate          | `SONAR_TLS_CLIENT_CERT`       | `network.tls.clientCert`       | None                  |
| Client key                  | `SONAR_TLS_CLIENT_KEY_FILE`   | `network.tls.clientKey`        | None                  |
| Client passphrase           | `SONAR_TLS_CLIENT_PASSPHRASE` | `network.tls.clientPassphrase` | None                  |

The HTTPS proxy URL, HTTP proxy URL, and no-proxy list are one group. The highest-priority source that sets either proxy URL supplies all three. A no-proxy value alone does not select that source.

Client certificate path, key file, and passphrase are separate. A `SONAR_*` variable overrides only that setting's stored key. Client certificates have no generic fallback.

Sensitive stored keys (`network.proxy.https`, `network.proxy.http`, and `network.tls.clientPassphrase`) live in the OS keychain. If the CLI cannot read a stored key, it treats that key as unset. See [State and storage](/sonarqube-cli/administration/state-and-storage.md).

Run `sonar system status` to see which source the CLI resolved.

## Proxy configuration

Set `SONAR_HTTPS_PROXY_URL`, `SONAR_HTTP_PROXY_URL`, and `SONAR_NO_PROXY` as described in [Environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md#network-connectivity). The matching stored keys are `network.proxy.https`, `network.proxy.http`, and `network.proxy.noProxy`.

### 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:** Do not set credentials inline in terminal commands; they'll be saved to shell history. To store a proxy URL that includes a password, run `sonar config set network.proxy.https` or `sonar config set network.proxy.http` and type the URL at the masked prompt. The value is saved in the OS keychain. You can also add the URL 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:

```bash
export SONAR_NO_PROXY="sonar.internal.corp.com,localhost,127.0.0.1,::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       |
| `::1`                     | Exact IPv6 address, unbracketed                            |
| `[::1]`                   | Exact IPv6 address, bracketed                              |
| `[::1]:9000`              | That IPv6 address, but only when connecting on port 9000   |
| `*`                       | All hosts; bypasses the proxy entirely                     |

For an IPv6 address with a port, use `[IPv6]:port`. The CLI cannot treat an unbracketed value such as `::1:9000` as a host-and-port entry.

## Workarounds for unsupported proxy types

The CLI supports only basic-authentication proxies. 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) cannot be configured directly. Tools like [Cntlm](http://cntlm.sourceforge.net/) and [Px Proxy](https://github.com/genotrance/px) 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:

```bash
export SONAR_HTTPS_PROXY_URL="http://localhost:3128"
```

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

### PAC file environments

The CLI does not 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:

```bash
export SONAR_HTTPS_PROXY_URL="http://proxy.corp.com:3128"
```

In many environments, a PAC file evaluates to a single proxy for most corporate traffic, which 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 [Environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md#network-connectivity). The matching stored key is `network.tls.caCert`.

> **Warning:** Do not set `NODE_TLS_REJECT_UNAUTHORIZED=0` as a workaround for certificate errors. It bypasses `NODE_EXTRA_CA_CERTS` but not `SONAR_CA_CERT`. As a result, it will not resolve issues with this CLI, and it disables certificate validation. 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)

```bash
openssl x509 -inform DER -in corp-ca.der -out corp-ca.pem
```

#### PKCS#12 / PFX

```bash
openssl pkcs12 -in bundle.pfx -nokeys -cacerts -out corp-ca.pem
```

#### P7B / PKCS#7

```bash
openssl pkcs7 -print_certs -in corp-ca.p7b -out corp-ca.pem
```

### 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 [Environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md#network-connectivity). The matching stored keys are `network.tls.clientCert`, `network.tls.clientKey`, and `network.tls.clientPassphrase`.

### 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 for a PEM certificate unless `network.tls.clientKey` is set. Not used for a PKCS#12 bundle. |
| `SONAR_TLS_CLIENT_PASSPHRASE` | Optional passphrase when the private key (PKCS#8) or PKCS#12 bundle is encrypted                                                                                    |

When the client certificate is a PEM file, a key file is required (`SONAR_TLS_CLIENT_KEY_FILE` or `network.tls.clientKey`). 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

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 one of these lines:

* `-----BEGIN PRIVATE KEY-----` or `-----BEGIN RSA PRIVATE KEY-----` for an unencrypted key
* `-----BEGIN ENCRYPTED PRIVATE KEY-----` for an encrypted key (PKCS#8). Set `SONAR_TLS_CLIENT_PASSPHRASE` to its passphrase, or store it as `network.tls.clientPassphrase`.

Encrypted keys in the legacy OpenSSL format, which contain `Proc-Type: 4,ENCRYPTED` and `DEK-Info` header lines, are not supported. Convert such a key to the supported encrypted format with OpenSSL:

```bash
openssl pkcs8 -topk8 -in legacy-key.pem -out client-key.pem
```

OpenSSL prompts for the current passphrase, then for the passphrase that protects the new file. You can reuse the same passphrase.

**PKCS#12 bundle (`.p12` or `.pfx`)**

Set the certificate path to the bundle (`SONAR_TLS_CLIENT_CERT` or `network.tls.clientCert`). The CLI extracts the certificate and private key from the file, so you do not set a key file. When the bundle is password-protected, set the passphrase (`SONAR_TLS_CLIENT_PASSPHRASE` or `network.tls.clientPassphrase`).

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:

```bash
export SONAR_TLS_CLIENT_CERT=/etc/ssl/client-cert.pem
export SONAR_TLS_CLIENT_KEY_FILE=/etc/ssl/client-key.pem
export SONAR_TLS_CLIENT_PASSPHRASE=my-secret   # only when the key is encrypted
sonar list issues -p <YourProjectKey>
```

PKCS#12 bundle:

```bash
export SONAR_TLS_CLIENT_CERT=/etc/ssl/client-cert.p12
export SONAR_TLS_CLIENT_PASSPHRASE=my-secret   # only when the bundle is encrypted
sonar list issues -p <YourProjectKey>
```

> **Warning:** Do not set `SONAR_TLS_CLIENT_PASSPHRASE` to its value directly in the terminal; it'll be saved to shell history. To store the passphrase, run `sonar config set network.tls.clientPassphrase` and type it at the masked prompt. You can also 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. Stored `sonar config` keys are included in that same resolved configuration. On Windows with WSL, the CLI translates certificate paths so Docker can mount them correctly.

## Troubleshooting TLS errors

### Certificate not trusted

If the CLI reports an error like "unable to get local issuer certificate" or "self-signed certificate in certificate chain", the server's certificate is signed by a CA that's not in your system trust store. This is common with internal CAs and SSL-inspecting proxies such as Zscaler or Bluecoat.

Set `SONAR_CA_CERT` to the path of a PEM file containing the CA certificate. See [Custom CA certificates](#custom-ca-certificates).

### Java TLS exceptions

If you see `SSLHandshakeException: PKIX path building failed` or similar Java TLS errors, run `sonar system status` to identify which component is failing. The SonarQube CLI manages underlying Java binaries (such as secrets detection and SCA) that can surface these errors. If none of those components is failing but you're still seeing Java TLS errors, you may be running `sonar-scanner` (SonarScanner CLI) rather than `sonar` (SonarQube CLI). See the SonarScanner CLI docs for [SonarQube Server](https://docs.sonarsource.com/sonarqube-server/analyzing-source-code/scanners/sonarscanner/) or [SonarQube Cloud](/sonarqube-cloud/analyzing-source-code/scanners/sonarscanner-cli.md) for how to configure its truststore.

### Skipping SSL verification

The SonarQube CLI does not have an option to skip certificate validation. Use `SONAR_CA_CERT` to trust a specific CA instead.

## Related pages

* [Check system status](/sonarqube-cli/administration/system-status.md)
* [Environment variables](/sonarqube-cli/using-sonarqube-cli/environment-variables.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.sonarsource.com/sonarqube-cli/administration/advanced-network-configuration.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.