Skip to main content

Install cnspec on Linux


Before you install cnspec or integrate Linux systems with Mondoo, you must:

  • Confirm access to the internet using the terminal

  • Confirm access to Mondoo systems using the terminal

  • Synchronize your system clock


If you install cnspec on machines that can't download and install updates (because they're air-gapped or don't give cnspec write access), you must deploy cnspec providers. To learn more, read Manage cnspec Providers.

Confirm access to the internet using the terminal

Check internet connectivity from the terminal:

curl -I

If you get the status 200 OK and the website’s headers, you internet connection is working.

If you have a proxy setting in your environment, you might need to configure it in the terminal:

export http_proxy='http://proxyServerAddress:proxyPort'
export https_proxy='https://proxyServerAddress:proxyPort'

To make this configuration permanent, you can set the proxy in system-wide configuration files or user-based files like /etc/bashrc, /etc/profile/, and /etc/profile.d/ based on your distribution.

Confirm Mondoo systems access using the terminal

Be sure you have access to these systems from the terminal:                Port 443/https Port 443/https Port 443/https Port 443/https Port 443/https

If your organization's region (in the Mondoo Console) is US, you must be able to access If your region is EU, you must be able to access

To check the connectivity, follow the approach in the previous section using the curl command.

Synchronize your system clock

Make sure your system clock is in sync with your NTP or internet time:

ntpq -p

Install cnspec on Linux

There are two ways of installing Mondoo on Linux:

Option A: Install using the automated install script

The environment variable MONDOO_REGISTRATION_TOKEN allows you to pass a registration token to the installation package. If you provide this value, the agent automatically registers during the installation and creates mondoo.yml, the configuration file for Mondoo.

We recommend that you create an integration and retrieve a token from Mondoo:

  1. Log into the Mondoo Console.

  2. Create a new integration for your Linux machine:

    • If this is your first time logging in, select the BROWSE INTEGRATIONS button.

    • If you've accessed the console before, in the side navigation bar, under INTEGRATIONS, select Add New Integration. Under Server and Endpoint Security, select your operating system.


  4. In your terminal, enter:

  1. In your terminal, enter:
Automated installation script
bash -c "$(curl -sSL"

You can also register and create a configuration file after installation using this command:

Automated installation script
cnspec login --token $MONDOO_REGISTRATION_TOKEN --config /etc/opt/mondoo/mondoo.yml

Option B: Install manually using a package manager

Add the YUM repository
curl --silent --location | tee /etc/yum.repos.d/mondoo.repo
Install mondoo package with yum
yum install -y mondoo

Understand the installation: binaries and files

When you complete the installation, you should have these three binaries on the machine:

  • cnspec
  • cnquery

To learn the location, run one of these commands:

which cnspec
which cnquery

Depending on your Linux distribution, the files can be in different locations, such as/usr/bin/ in Debian/Ubuntu or /bin/ in Red Hat/Fedora.

Note the location of the cnspec binary.

The installation also creates mondoo.yml, a configuration file that contains important data about the certificate, private key, API endpoint, and space address. These values come from the token (a JSON web token or JWT). You can check the content of the JWT using this command:

jq -R 'split(".") | .[1] | @base64d | fromjson' <<<  "<Token-Here>"

By default, the installation creates the mondoo.yml file here:


It is important to check the cnspec status, configuration file, and registration status by running:

cnspec status

In new Linux distributions, the installation creates a systemd cnspec service, which you can see in:


If you encounter an issue with the token, you can re-register cnspec with the new token:

cnspec login --token $MONDOO_REGISTRATION_TOKEN --config /etc/opt/mondoo/mondoo.yml


cnspec register --token $MONDOO_REGISTRATION_TOKEN --config /etc/opt/mondoo/mondoo.yml

Enable and start cnspec as a service:

systemctl enable cnspec.service
systemctl start cnspec.service
systemctl daemon-reload

Each time the service starts, it runs a local scan based on the selected policies and sends the results to this machine's space in Mondoo Platform. You can then view the results in the Mondoo Console.

To force cnspec to continuously scan the machine, the binary runs with a option called serve, which runs cnspec as a daemon every hour. See this in the cnspec.service:

Description=cnspec Service

ExecStart=/usr/bin/cnspec --config /etc/opt/mondoo/mondoo.yml serve


To run the scan yourself and see the results as well, you can use this command:

cnspec scan local

During the scan, if cnspec finds a configuration file (mondoo.yml), it loads the policies enabled for this machine's space in Mondoo Platform. If cnspec doesn't find a configuration file, it scans based on Mondoo's free, open source policies. cnspec loads the policies into memory and runs the scan.

Proxy configuration in cnspec

You can also set the proxy settings from within cnspec during registration or add them to the mondoo.yml configuration file.

During the registration:

Set Proxy via cnspec command
cnspec login --token 'YOUR_TOKEN_HERE' --api-proxy '' --config '/etc/opt/mondoo/mondoo.yml'

Add to the mondoo.yml file:

  1. Navigate to the cnspec configuration file located at /etc/opt/mondoo/mondoo.yml.
  2. Add this line:
Set Proxy via cnspec configuration file

Learn more