The cnspec Configuration File

cnspec stores its settings in a YAML file named mondoo.yml. Registering cnspec creates the file and writes the credentials that connect the host to your Mondoo Platform space. You can then add settings of your own to control logging, proxies, asset metadata, provider updates, and how often the service scans.

Everything in this file is optional except the registration credentials. An unregistered cnspec runs happily without a configuration file, scanning against Mondoo's free, open source policies.

Where cnspec looks for the file

cnspec checks the current user's configuration first, then the system-wide configuration. It uses the first file it finds:

To see which file cnspec loaded, run cnspec status. The output names the file and the source that selected it:

→ loaded configuration from /etc/opt/mondoo/mondoo.yml using source default

Point cnspec at a different file

You can override the search with a flag or an environment variable. When more than one is present, cnspec uses the first match in this order:

1. MONDOO_CONFIG_BASE64: the entire configuration file, base64 encoded. This is the usual choice for CI/CD, where you store the encoded file as a secret and never write it to disk.
2. --config <path>: a path passed on the command line. Every cnspec command accepts it.
3. MONDOO_CONFIG_PATH: a path from the environment, used only when --config is absent.
4. The search paths in the table above.

base64 < mondoo.yml | tr -d '\n'

cnspec can also read the file from AWS Systems Manager Parameter Store. Pass the region and parameter name with the aws-ssm-ps:// prefix, in the form aws-ssm-ps://region/<region>/parameter/<name>:

cnspec scan local --config aws-ssm-ps://region/us-east-1/parameter/mondoo-config

cnspec reads the parameter with the AWS credentials it finds in the environment, the same ones the AWS CLI uses.

How settings are resolved

Three sources feed each setting. Later sources win:

1. The configuration file
2. Environment variables
3. Command line flags

Most settings also have an environment variable equivalent: prefix the key with MONDOO_, uppercase it, and replace hyphens and dots with underscores. So auto_update becomes MONDOO_AUTO_UPDATE and api_endpoint becomes MONDOO_API_ENDPOINT. The log.format and log.color settings are the exception, because cnspec reads them before it applies environment overrides. Set those two in the file.

Platform connection

cnspec login writes these settings. Treat them as generated values: to change spaces or replace credentials, register again rather than editing them by hand.

cnspec resolves the scope from the first of these keys that is set: scope_mrn, then space_mrn, then parent_mrn. Registration writes space_mrn, so that is what you see in most files. parent_mrn is deprecated and remains only so that older files keep working.

Registration can also seed a few of the settings below. cnspec login accepts --annotation, --api-endpoint, --updates-url, --timer, and --splay, and writes each one to the file it creates.

To route traffic through a proxy, add:

api_proxy: http://10.0.0.1:8080

For more on proxies, read Register cnspec.

Asset metadata

These settings control the metadata cnspec attaches to what it scans from this host.

annotations:
  team: research
  owner: cosmo@lunalectric.com

To learn more about annotations and the other ways to set them, read Annotate assets.

Logging

log-level: debug
log.format: json

Updates

auto_update: false

providers_url sets the provider download URL on its own and is deprecated. Use updates_url instead, which covers both cnspec and providers. When you turn off automatic updates, check releases.mondoo.com/providers/ periodically and update providers manually, as described in Manage cnspec providers.

Scheduled scans

When cnspec runs as a service, these settings control the scan schedule:

scan_interval:
  timer: 360
  splay: 30

The cnspec serve --timer and --splay flags override these values for a single run. cnspec login --timer and --splay write them into the file at registration.

The inventory file beside it

When cnspec loads a configuration file, it also looks for an inventory.yml in the same directory. If one is there and you did not pass --inventory-file, cnspec scans the assets that inventory defines:

/etc/opt/mondoo/
├── mondoo.yml
└── inventory.yml

cnspec serve always scans every asset the discovered file defines, on every cycle, with no extra flags. This is how a host running cnspec as a service extends its own scan: list the host itself (type: local) alongside another asset, such as the database service running on it, and each cycle produces a result for both instead of just the host.

To learn what belongs in that file, including a worked example of combining a host scan with a local database scan, read Remote scanning with inventory files.

Advanced

A configuration file with type: external_account tells cnspec to authenticate with Workload Identity Federation rather than a certificate and private key. Such a file carries the federation keys audience, issuerUri, jwtToken, subjectTokenType, scopes, and universeDomain. These files are generated, not hand-authored.

A complete example

# 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
# annotations applied to every asset scanned from this host
annotations:
  team: research
  owner: cosmo@lunalectric.com
# scan every six hours, with up to 30 minutes of jitter
scan_interval:
  timer: 360
  splay: 30

Learn more

• Register cnspec
• Run cnspec as a service
• Manage cnspec providers
• Annotate assets
• Remote scanning with inventory files