Skip to main content

Run cnspec as a service

This document covers how to run cnspec as a service on hosts in your environment.

Configure cnspec to run as a service

When configured as a service, cnspec continuously assesses hosts by running policies configured in Mondoo Platform. By default, every 60 minutes, cnspec service:

  1. Connects to your account in the platform

  2. Retrieves and validates the latest policies enabled for it.

  3. Scans the host.

  4. Reports scan results back to the platform.

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

info

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

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.

info

cnspec serve leverages the default configuration of the host if already registered.

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 configuration is stored on the host at this location:

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

Common cnspec service configuration options:

NameDescription
agent_mrnAgent Mondoo resource name, identifies the client
api_endpointThe URL of Mondoo Platform (https://us.api.mondoo.com is the default)
certificateClient's public certificate
loglevelService log level: error, warn, info, debug, trace (default is info)
mrnService Account Mondoo resource name, which identifies the service account
private_keyClient's private key used to sign requests sent to Mondoo Platform
space_mrnSpace Mondoo resource name, identifies the space that the client belongs to
annotationsAnnotations that display in the Mondoo Console condole.mondoo.com
# service account mrn
mrn: //agents.api.mondoo.app/spaces/spacex/serviceaccounts/1utIs5XUQ8XayfB6yiQNTLOqPlD
# agent mrn
agent_mrn: //agents.api.mondoo.app/spaces/spacex/agents/1utIqsjg3YSAF8hMMIhg8tBsTPP
# space mrn
space_mrn: //captain.api.mondoo.app/spaces/spacex
# 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
loglevel: info
# tags
annotations:
- key1: value1
- key2: value2

cnspec inventory

cnspec inventory configuration defines a list of targets for cnspec to scan. This example contains an ssh-based scan with annotations:

apiVersion: v1
kind: Inventory
metadata:
name: cnspec-ssh-inventory
labels:
environment: production
spec:
assets:
# linux with password authentication
- id: linux-ssh-with-password
connections:
- host: 192.168.5.89
type: ssh
credentials:
- type: password
user: mondoo
password: mondoo
annotations:
key: value

This example scans the local machine and all running containers:

apiVersion: v1
kind: Inventory
metadata:
name: mondoo-inventory
labels:
environment: production
spec:
assets:
- id: docker-container
connections:
- type: local
discover:
targets:
- "container"

This example scans the local machine and all container images:

apiVersion: v1
kind: Inventory
metadata:
name: mondoo-inventory
labels:
environment: production
spec:
assets:
- id: docker-container
connections:
- type: local
discover:
targets:
- "container-images"

This example scans the vSphere environment with embedded credentials:

apiVersion: v1
kind: Inventory
metadata:
name: mondoo-inventory
labels:
environment: production
spec:
assets:
- name: vsphere
connections:
- type: vsphere
host: 192.168.5.24
credentials:
- type: password
user: mondoo-read@vsphere.local
password: test
discover:
targets:
- host-machines

This example scans the vSphere environment with extracted credentials and reference:

apiVersion: v1
kind: Inventory
metadata:
name: mondoo-inventory
labels:
environment: production
spec:
assets:
- name: vsphere
connections:
- type: vsphere
host: 192.168.5.24
credentials:
- secret_id: my-secret
discover:
targets:
- host-machines
credentials:
my-secret:
type: password
user: mondoo-read@vsphere.local
password: test

This example scans the vSphere environment with credentials from HashiCorp Vault:

apiVersion: v1
kind: Inventory
metadata:
name: mondoo-inventory
labels:
environment: production
spec:
assets:
- name:
connections:
- type: vsphere
host: 192.168.5.24
insecure: true
credentials:
- secret_id: vcenter/mondoo-read
discover:
targets:
- auto
annotations:
Owner: patrick@mondoo.com
vault:
name: cnspec-hashivault
type: hashicorp-vault
options:
url: http://127.0.0.1:8200
token: XXXXXXXX

Example to scan a Microsoft 365 account:

apiVersion: v1
kind: Inventory
metadata:
name: mondoo-inventory
labels:
environment: production
spec:
assets:
- connections:
- type: ms365
credentials:
- type: pkcs12
private_key_path: "/Users/atomic111/Projects/presales/m365-scanning/certificate.combo.pem"
options:
client-id: c4b89770-5ed2-4367-b4f6-ff05ffcb3406
organization: ""
sharepoint-url: ""
tenant-id: d9abc6fc-fd88-4480-a931-2f7939adbac2
discover:
targets:
- auto

Example to scan an Azure tenant including all subscriptions:

apiVersion: v1
kind: Inventory
metadata:
name: mondoo-inventory
labels:
environment: production
spec:
assets:
- connections:
- type: azure
credentials:
- type: pkcs12
private_key_path: "</Users/user/tmpjddt4b_y5.pem>"
options:
client-id: 9f51cb-66c3-4gg9-b525-fbd717384d96
lun: "0"
tenant-id: f115cf8c-a2d4-51ef-1234-56f7ed7e18ec
discover:
targets:
- auto

Example to scan a Google Workspace account:

apiVersion: v1
kind: Inventory
metadata:
name: mondoo-inventory
labels:
environment: production
spec:
assets:
- connections:
- type: google-workspace
credentials:
- type: json
secret: <base64 encoded secret>
options:
customer-id: D34dr1r
impersonated-user-email: user@lunalectric.com

To execute cnspec with the inventory file, run this command:

cnquery scan --inventory-file ./inventory.yml

cnspec inventory template

cnspec inventory files are useful for a CI/CD pipeline. Inventory templates are useful for scanning different assets for different environments. They allow you to reuse the same template with a custom variable. This example uses the getenv function to include an environment variable (the asset name):

spec:
assets:
- name: {{ getenv "ASSET_NAME" }}
connections:
- type: local
discover:
targets:
- auto

You can use this example inventory template by providing the ASSET_NAME and variable with the cnspec scan command and specifying the template:

ASSET_NAME="my_asset" cnspec scan --inventory-template template.yaml