Skip to Content
Installation

Run cnspec as a service

Configure cnspec to run as a system service that automatically scans hosts and reports results to Mondoo Platform.

Run cnspec as a system service to assess a host on a recurring schedule and stream the results back to Mondoo Platform without anyone running a command.

How the service works

Once enabled, the cnspec service runs in serve mode. By default, every 60 minutes it:

  1. Connects to your space in Mondoo Platform.
  2. Pulls the latest enabled policies.
  3. Scans the host.
  4. Reports the results back to the platform.

You can change the interval, the configuration path, and the log level. See cnspec configuration options below.

Configure cnspec to run as a service

The installation places a systemd unit file at /etc/systemd/system/cnspec.service. However, it does not register or enable the service.

Before starting cnspec as a service, you should have already registered the host with your Mondoo Platform account.

Enable and start cnspec as a service

1. Reload systemd daemon and load the cnspec.service unit file
sudo systemctl daemon-reload
2. Enable cnspec to run during startup
sudo systemctl enable cnspec
3. Start cnspec service
sudo systemctl start cnspec
4. Check the status of cnspec
sudo systemctl status cnspec

cnspec service logging

By default, the cnspec service writes log events to the system journal. You can use this command to tail cnspec service logs on Linux hosts:

Tail cnspec service logs
sudo journalctl -u cnspec -f

On many distributions, rsyslog copies journal messages into /var/log/messages or /var/log/syslog. If your hosts alert on those files, routine cnspec errors such as a failed scan or a timed out upload can raise incidents. To keep cnspec logs out of the system logs, set log_file in /etc/opt/mondoo/mondoo.yml and restart the service:

mondoo.yml
log_file: /var/log/cnspec/cnspec.log
Restart the cnspec service
sudo systemctl restart cnspec

The service then writes all of its output to that file, including output from providers and crash reports, and nothing to the journal. A few messages still go to the journal: anything logged before cnspec reads its configuration (such as an error about an unreadable configuration file) and systemd's own start and stop messages. cnspec creates the file and its directory if they don't exist, readable only by root and the root group. If cnspec can't open the file, it logs the error and keeps logging to the journal.

To tail the log file instead of the journal:

Tail the cnspec log file
sudo tail -f /var/log/cnspec/cnspec.log

The cnspec packages install a logrotate rule, /etc/logrotate.d/cnspec, that rotates /var/log/cnspec/*.log weekly, or sooner once a file reaches 100 MB, and keeps four rotated files. If you set log_file to a path outside /var/log/cnspec, add your own logrotate rule for it.

The default log level is info, but can be configured with log-level as defined in cnspec configuration options below.

cnspec serve

In addition to leveraging the platform service management system, cnspec includes the cnspec serve command, which you can use on any supported platform (Linux, Windows, macOS) to continuously run assessments of hosts.

If the host is already registered, cnspec serve uses the existing configuration.

Set a custom scan interval

Use the --timer flag to set a scan interval in minutes. The default is 60. For example, this runs a scan with cnspec serve every 15 minutes:

cnspec serve --timer 15

To spread scans across a fleet, --splay adds a random delay of up to the given number of minutes to each scan (default 60). To anchor the schedule to a time of day, pass --start-time in HH:MM local time. cnspec then scans every --timer minutes from that time and restarts the schedule at it each day. For example, this scans once a day at 2:00:

cnspec serve --start-time 02:00 --timer 1440

cnspec configuration options

cnspec reads its settings from mondoo.yml:

  • Linux: /etc/opt/mondoo/mondoo.yml
  • macOS: /Library/Mondoo/etc/mondoo.yml
  • Windows: C:\ProgramData\Mondoo\mondoo.yml

These are the settings that matter most when cnspec runs as a service:

NameDescription
scan_interval.timerMinutes between scans (default is 60)
scan_interval.splayMaximum random delay in minutes added to each scan, so a fleet doesn't scan in lockstep (default is 60)
scan_interval.start_timeLocal time of day (HH:MM) of the first scan. Scans then run every timer minutes and the schedule restarts at this time each day (not set by default)
log-levelService log level: error, warn, info, debug, trace (default is info)
log_fileLinux only: write service logs to this file instead of the system journal (not set by default)
annotationsAnnotations that display on assets in the Mondoo Console
api_proxyProxy URL for all traffic to Mondoo Platform. Overrides the environment and the Windows proxy settings
system_proxyWhether to use the Windows proxy settings when api_proxy and HTTPS_PROXY are unset (default is true)

Registration writes the credentials in the same file: mrn, agent_mrn, space_mrn, certificate, private_key, and api_endpoint.

mondoo.yml
# service account mrn
mrn: //agents.api.mondoo.app/spaces/lunalectric/serviceaccounts/1utIs5XUQ8XayfB6yiQNTLOqPlD
# agent mrn
agent_mrn: //agents.api.mondoo.app/spaces/lunalectric/agents/1utIqsjg3YSAF8hMMIhg8tBsTPP
# space mrn
space_mrn: //captain.api.mondoo.app/spaces/lunalectric
# api endpoint
api_endpoint: https://us.api.mondoo.com
# pem-encoded certificate
certificate: |
  -----BEGIN CERTIFICATE-----
  ...
  -----END CERTIFICATE-----
# pem-encoded private key
private_key: |
  -----BEGIN PRIVATE KEY-----
  ...
  -----END PRIVATE KEY-----
# log level: error, warn, info, debug, trace
log-level: info
# Linux only: write service logs to a file instead of the system journal
log_file: /var/log/cnspec/cnspec.log
# scan every six hours, with up to 30 minutes of jitter
scan_interval:
  timer: 360
  splay: 30
# tags
annotations:
  key1: value1
  key2: value2

For every setting the file accepts, read The cnspec configuration file.

cnspec inventory

You can define multiple scan targets, credentials, and discovery options in an inventory file. To learn more, read Remote scanning with inventory files.

To execute cnspec with an inventory file:

cnspec scan --inventory-file ./inventory.yml

Last updated on

On this page