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 fileCopy Anchor Link

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 fileCopy Anchor Link

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 resolvedCopy Anchor Link

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 connectionCopy Anchor Link

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

On Windows, cnspec uses the proxy configured in the operating system when this setting is empty. For the order in which cnspec considers each proxy source, and how to turn the Windows behavior off, read Proxy configuration.

Asset metadataCopy Anchor Link

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.

LoggingCopy Anchor Link

log-level: debug
log.format: json

UpdatesCopy Anchor Link

auto_update: false

Two environment variables act as a hard off switch that even an explicit cnspec update respects: MONDOO_AUTO_UPDATE=false stops both cnspec and provider updates, and MONDOO_AUTO_UPDATE_ENGINE=false stops only the cnspec binary from updating itself.

When updates_url is unset, cnspec reads its release manifest from https://install.mondoo.com and downloads providers from https://releases.mondoo.com/providers. When you set it, cnspec reads the manifest from <updates_url>/package/cnspec/latest.json and downloads providers from <updates_url>/providers, so a mirror must serve both.

providers_url is the deprecated predecessor of updates_url. cnspec 14 still honors it for provider downloads, takes it over updates_url when both are set, and logs a deprecation warning. To move a configuration file over, run cnspec migrate: when providers_url ends in /providers and updates_url isn't set, it adds the matching updates_url and leaves providers_url in place so that older cnspec versions still find it. Because updates_url also sets where cnspec looks for binary updates, the mirror must serve the release manifest as well as /providers once updates_url is in the file.

When you turn off automatic updates, check releases.mondoo.com/providers/ periodically and update providers manually, as described in Manage cnspec providers.

ScanningCopy Anchor Link

Scheduled scansCopy Anchor Link

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 itCopy Anchor Link

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.

Starting with cnspec 14, cnspec serve reloads the inventory and rediscovers its assets before every scan cycle, so an inventory.yml you add, edit, or remove next to a running service takes effect on the next cycle without a restart. If the file is momentarily invalid, for example halfway through an edit, the service logs an error and scans with the last inventory it could read. Two cases still need a restart: an inventory piped in on stdin (--inventory-file -), which can only be read once, and changes to mondoo.yml itself, such as the scan interval.

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.

AdvancedCopy Anchor Link

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 exampleCopy Anchor Link

# 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 moreCopy Anchor Link

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