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:

Connects to your space in Mondoo Platform.
Pulls the latest enabled policies.
Scans the host.
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

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

Tail cnspec service logs

sudo journalctl -u cnspec -f

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

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

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:

Name	Description
`scan_interval.timer`	Minutes between scans (default is 60)
`scan_interval.splay`	Maximum random delay in minutes added to each scan, so a fleet doesn't scan in lockstep (default is 60)
`log-level`	Service log level: error, warn, info, debug, trace (default is info)
`annotations`	Annotations that display on assets in the Mondoo Console
`api_proxy`	Proxy URL for all traffic to Mondoo Platform

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
# 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

Run cnspec as a service

On this page