Register cnspec Using a Credentials File

Most installs register cnspec with a short-lived registration token. For automation that can't paste a token interactively (CI/CD jobs, immutable images, build agents), use a long-lived service account credentials file instead.

Generate a credentials file

1. Log into the Mondoo Console.
2. Navigate to the region, organization, and space the asset should report into.
3. In the left navigation, under Integrations, select Add New Integration.
4. Under Supply Chain, select Generate Long-Lived Credentials.
5. Select GENERATE NEW CREDENTIALS and save the JSON output to a file (for example, mondoo-creds.json).

Use the credentials file

Point cnspec at the credentials file with the --config flag, or copy the file to the default config path so cnspec picks it up automatically.

One-off scan

Pass --config on each invocation:

cnspec scan local --config /path/to/mondoo-creds.json

CI/CD pipelines

Store the JSON as a secret in your CI/CD system, write it to disk during the job, and reference it with --config. For example, in a shell step:

echo "$MONDOO_CREDENTIALS" > mondoo-creds.json
chmod 600 mondoo-creds.json
cnspec scan local --config mondoo-creds.json
rm mondoo-creds.json

Persistent install

For a long-lived install (a server, a baked image), copy the credentials file to the default config path so every cnspec command picks it up:

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

Validate registration

After installing the credentials file, run cnspec status to confirm cnspec is registered and can reach Mondoo Platform. The last lines of the output should read:

→ client is registered
→ client authenticated successfully

For sample status outputs and how to interpret common errors, read Validate registration.