Proxy configuration

cnspec talks to Mondoo Platform over HTTPS: the API, the release service that delivers updates and providers, and the storage that receives scan results. On a network that forces outbound traffic through a forward proxy, such as Squid or Zscaler, cnspec has to send that traffic to the proxy. This page explains where cnspec looks for a proxy, in which order, and how to check which one it uses.

Where cnspec looks for a proxyCopy Anchor Link

cnspec uses the first of these sources that names a proxy:

1. The --api-proxy flag or the MONDOO_API_PROXY environment variable
2. The api_proxy setting in mondoo.yml
3. The HTTPS_PROXY and HTTP_PROXY environment variables, honoring NO_PROXY
4. On Windows, the proxy settings of the operating system
5. No proxy: cnspec connects directly

A proxy in the configuration file overrides both the environment variables and the Windows settings. Set api_proxy when cnspec must use a specific proxy no matter how the host is configured.

Windows proxy settings work out of the boxCopy Anchor Link

Starting with cnspec 14, a Windows host that already has a proxy configured needs no proxy configuration for cnspec. cnspec reads the same settings Windows uses for its own traffic:

• Internet Settings of the account cnspec runs as (Settings > Network & internet > Proxy): a manual proxy with its list of exceptions, a setup script address (PAC), or Automatically detect settings (WPAD).
• The WinHTTP default proxy, set with netsh winhttp set proxy. This is the proxy Windows services use. The cnspec service runs as LocalSystem, an account with no Internet Settings of its own, so this is normally the setting that applies to the service.
• Internet Settings that group policy stores per machine (Make proxy settings per-machine).

cnspec applies these settings the way Windows does. When a setup script or automatic detection is configured and the script runs, its answer decides, including when it asks for a direct connection. Otherwise the manual proxy applies, except for hosts on its exception list. When the account has no proxy of its own, the WinHTTP default proxy applies. Connections to localhost never go through a proxy unless the exception list contains <-loopback>.

The proxy is checked before it is usedCopy Anchor Link

A proxy that comes from the Windows settings is used only after cnspec has confirmed that it carries traffic to the destination. Before the first connection to a host, cnspec connects to the proxy, asks it to tunnel to that host, and completes a TLS handshake through the tunnel using the certificates the machine trusts. If any step fails, cnspec connects to that host directly, which is how versions before cnspec 14 always connected, and logs a warning that names the proxy, the host, and the reason. The result is remembered for five minutes.

This protects hosts that worked before the upgrade. A proxy that requires Windows authentication (NTLM or Kerberos), a proxy that allows browser destinations only, or a proxy address left behind from another network does not take a working installation offline: cnspec keeps connecting directly and tells you why in cnspec status. Only proxies you configure yourself, with api_proxy or HTTPS_PROXY, are used without this check.

The proxy also reaches the providers that scan cloud accounts, so scanning an AWS account or an Azure subscription from a proxied Windows host works as well. cnspec passes the proxy to its providers as the HTTPS_PROXY, HTTP_PROXY, and NO_PROXY environment variables. It never overrides those variables when they are already set.

Use a different proxyCopy Anchor Link

To send Mondoo Platform traffic through a proxy other than the one Windows uses, set api_proxy in C:\ProgramData\Mondoo\mondoo.yml:

api_proxy: http://proxy.example.com:3128

api_proxy applies to Mondoo Platform traffic only. Traffic from providers to cloud APIs keeps following the environment variables and the Windows settings.

Turn the system proxy offCopy Anchor Link

To make cnspec ignore the Windows proxy settings, which is how versions before cnspec 14 behaved, add:

system_proxy: false

The environment variable equivalent is MONDOO_SYSTEM_PROXY=false. Sources 1 to 3 above still apply.

Check which proxy cnspec usesCopy Anchor Link

cnspec status shows the proxy in effect for the Mondoo Platform endpoint and where it came from:

── Mondoo Platform ──────────────────────────────
│  Endpoint   https://us.api.mondoo.com
│  Proxy      http://proxy.example.com:3128  (system)

The source is api_proxy for the flag, the environment variable, or the configuration file, environment for HTTPS_PROXY or HTTP_PROXY, and system for the Windows settings. Without a proxy the row reports a direct connection. When Windows names a proxy that failed the check, the row reports the direct connection together with the reason, for example system proxy http://proxy.example.com:3128 not usable: proxy answered CONNECT us.api.mondoo.com:443 with 407 Proxy Authentication Required. cnspec status -o json returns the same values in the proxy and proxySource fields of the client object, and the cnspec support bundle records them in its manifest.

The first time a run sends traffic through the Windows proxy settings, cnspec logs the proxy it picked and its source at the info level:

using the operating system's proxy settings for outbound connections proxy=http://proxy.example.com:3128 source="WinHTTP default proxy"

TroubleshootingCopy Anchor Link

• cnspec cannot reach Mondoo Platform behind a proxy. Run cnspec status. If the Proxy row reports a direct connection without a reason, cnspec does not see the proxy. The most common cause is a service: it runs as LocalSystem and sees the WinHTTP default proxy, not the Internet Settings of the signed-in user. Set the WinHTTP proxy with netsh winhttp set proxy proxy.example.com:3128, or set api_proxy in the configuration file. If the row reports a direct connection with a reason, the Windows proxy failed the check described above; the reason says why.
• The proxy requires credentials. cnspec cannot authenticate with Windows credentials (NTLM or Kerberos), so such a proxy fails the check and cnspec connects directly. For a proxy that accepts basic authentication, put the credentials in the URL: http://user:password@proxy.example.com:3128. cnspec redacts the password in its logs and in cnspec status.
• Some hosts must not go through the proxy. Add them to NO_PROXY, comma separated, where *.example.com matches subdomains, or to the exception list of the Windows proxy settings.

Learn moreCopy Anchor Link

• Register cnspec
• Run cnspec as a service
• The cnspec configuration file