Mondoo
Docs
Installation

Register cnspec

This page provides details on registering cnspec with Mondoo Platform.

If you install cnspec on an asset using a system package instead of Mondoo's automated installation script, you must register the asset manually.

  1. Navigate to the region, organization, and space where you want to see the new asset's scan results.

  2. In the left navigation, under Integrations, select Add New Integration.

  3. Select your operating system and copy the registration token.

  4. Open a terminal and run this command:

    Register cnspec
    cnspec login --token "<PASTE_YOUR_TOKEN_HERE>"

    This command uses the token to create a service account that lets cnspec report results to Mondoo Platform.

  • Windows: cnspec login --token "<PASTE_YOUR_TOKEN_HERE>" --config "C:\ProgramData\Mondoo\mondoo.yml"
  • Linux: cnspec login --token "<PASTE_YOUR_TOKEN_HERE>" --config "/etc/opt/mondoo/mondoo.yml" Communication with Mondoo Platform is encrypted using HTTPS. The payload is signed to ensure it has not been tampered with.

Validate registration

The cnspec status command validates cnspec registration and ensures that communication with Mondoo Platform is successful.

Unregistered cnspec
cnspec status
→ loaded configuration from /Users/stella/.config/mondoo/mondoo.yml using source default
→ Platform:		macos
→ Version:		26.1
→ Hostname:		stella.home
→ IP:			172.16.1.94
→ Time:			2025-11-25T17:55:43-08:00
→ Version:		12.11.0 (API Version: 12)
→ Latest Version:	12.11.0
→ Providers URL:	https://releases.mondoo.com/providers
→ Installed Providers:	core | os | mock
→ API ConnectionConfig:	https://us.api.mondoo.com
→ API Status:		SERVING
→ API Time:		2025-11-26T01:55:43Z
→ API Version:		12
x client is not registered
Correctly registered client
cnspec status
→ loaded configuration from /Users/mwezi/.config/mondoo/mondoo.yml using source default
→ Platform:		macos
→ Version:		26.1
→ Hostname:		mwezi.home
→ IP:			192.168.254.21
→ Time:			2025-11-25T17:58:10-08:00
→ Version:		12.11.0 (API Version: 12)
→ Latest Version:	12.11.0
→ Providers URL:	https://releases.mondoo.com/providers
→ Installed Providers:	core | os | mock
→ API ConnectionConfig:	https://us.api.mondoo.com
→ API Status:		SERVING
→ API Time:		2025-11-26T01:58:10Z
→ API Version:		12
→ Owner:		//captain.api.mondoo.app/spaces/lunalectric-team-workstations
→ Client:		//agents.api.mondoo.app/spaces/lunalectric-team-workstations/agents/2SARlZgQnFLAzj7jfiS1Fx2HBz8
→ Service Account:      //agents.api.mondoo.app/spaces/lunalectric-team-workstations/serviceaccounts/2bMtksUk9EjrI5MC3tTf6UmhNC2
→ client is registered
→ client authenticated successfully
Invalid cnspec registration
cnspec status
→ loaded configuration from /Users/cosmo/.config/mondoo/mondoo.yml using source default
→ Platform:		macos
→ Version:		26.1
→ Hostname:		cosmo.home
→ IP:			192.168.254.21
→ Time:			2025-11-25T17:58:10-08:00
→ Version:		12.11.0 (API Version: 12)
→ Latest Version:	12.11.0
→ Providers URL:	https://releases.mondoo.com/providers
→ Installed Providers:	 core | mock | os
→ API ConnectionConfig:	https://api.edge.mondoo.com
→ API Status:		SERVING
→ API Time:		2025-11-26T01:58:10Z
→ API Version:		12
→ Owner:		//captain.api.mondoo.app/spaces/lunalectric-team-workstations
→ Client:		//agents.api.mondoo.app/spaces/lunalectric-team-workstations/agents/2SARlZgQnFLAzj7jfiS1Fx2HBz8
→ Service Account:      //agents.api.mondoo.app/spaces/lunalectric-team-workstations/serviceaccounts/2bMtksUk9EjrI5MC3tTf6UmhNC2
→ client is registered
x could not connect to mondoo platform error="rpc error: code = Unauthenticated desc = request permission unauthenticated"permission unauthenticated"
No current system time (clock skew detected)
cnspec status
→ loaded configuration from /Users/cosmo/.config/mondoo/mondoo.yml using source default
→ Platform:		macos
→ Version:		26.1
→ Hostname:		tsuki.home
→ IP:			192.168.254.21
→ Time:			2025-11-23T12:07:41-08:00
→ Version:		12.11.0 (API Version: 12)
→ Latest Version:	12.11.0
→ Providers URL:	https://releases.mondoo.com/providers
→ Installed Providers:	 core | mock | os
→ API ConnectionConfig:	https://api.edge.mondoo.com
→ API Status:		SERVING
→ API Time:		2025-11-23T20:07:42Z
→ API Version:		12
→ Owner:		//captain.api.mondoo.app/spaces/lunalectric-team-workstations
→ Client:		//agents.api.mondoo.app/spaces/lunalectric-team-workstations/agents/2SARlZgQnFLAzj7jfiS1Fx2HBz8
→ Service Account:      //agents.api.mondoo.app/spaces/lunalectric-team-workstations/serviceaccounts/2bMtksUk9EjrI5MC3tTf6UmhNC2
→ client is registered
→ client authenticated successfully
! possible clock skew detected: 72h0m6.277868s

Specify a proxy server for communication with Mondoo

You can specify a proxy server for communication between cnspec and Mondoo Platform. This is useful if your default system proxy restricts communication, or if you need to monitor different types of traffic.

  1. Find the Mondoo configuration file: /etc/opt/mondoo/mondoo.yml.

  2. Add this line to mondoo.yml:

    api_proxy: https://1.1.1.1:8080

Manage cnspec Providers

Learn about cnspec providers and special considerations for containers and air-gapped or limited access assets

Register cnspec Using a Credentials File

This page provides details on registering cnspec with Mondoo Platform using a credentials file.

On this page

Validate registrationSpecify a proxy server for communication with Mondoo