This role installs cnquery and cnspec on Linux and Windows servers.
It does:
- Installs the signed
cnqueryandcnspecbinaries - Registers
cnqueryandcnspecwith Mondoo Platform - Enables the
cnspecservice on Linux and Windows
It supports:
- Amazon Linux
- Debian
- Red Hat Enterprise Linux and derivatives (CentOS/AlmaLinux/Rocky Linux)
- SUSE & openSUSE
- Ubuntu
- Windows 10, 11, 2019, 2022, 2025
The role is published at Ansible Galaxy: Mondoo/Client role.
- Ansible > 2.5
| Name | Default Value | Description |
|---|---|---|
registration_token_retrieval |
manual |
manual requires to set ``registration_token` |
registration_token |
n/a | manually set the Mondoo Platform Registration Token that is used to register cnquery and cnspec |
force_registration |
false | forces re-registration for each run |
This role requires community.general to be installed for several tasks.
This playbook demonstrates how to use the Mondoo Package role to install cnquery and cnspec on many instances:
- Create a new
hostsinventory. Add your host to the group.
[linux_hosts]
54.172.7.243 ansible_user=ec2-user- Create a
playbook.ymland change theregistration_token:
---
- hosts: linux_hosts
become: yes
roles:
- role: ansible-mondoo # if used from galaxy: mondoo.client
vars:
registration_token: "changeme"In addition we support the following variables:
| variable | description |
|---|---|
force_registration: true |
set to true if you want to re-register cnquery and cnspec |
ensure_managed_client: true |
ensures the configured clients are configured as managed Client in Mondoo |
proxy_env['https_proxy'] |
set the proxy for the cnspec client |
annotations |
set annotations/ tags for the node |
update_linux_enabled |
set to true if you want to enable the update task for linux via cron job |
update_linux_cron_day |
define the update interval in days for the cnspec update, example */3 for every 3 days |
update_linux_cron_hour |
define the hour at which the task is to be carried out |
update_linux_cron_minute |
define the minute at which the task is to be carried out |
update_windows_enabled |
set to true if you want to enable the update task for windows via scheduled task |
update_windows_interval |
define the update interval in days for the cnspec update |
update_windows_time |
define the time at which the task is to be carried out |
timer |
define the timer to set a scan interval in minutes. The default is 60. |
splay |
define the delay in the scan timing |
mondoo_subscription_manager_repo_id |
ID of the RPM repository shown by subscription-manager command (when defined, mondoo_rpm_* variables will be ignored) |
mondoo_rpm_repo |
URL of the RPM repository (defaults to "https://releases.mondoo.com/rpm/$basearch/") |
mondoo_rpm_gpgkey |
GPG of the RPM repository (defaults to "https://releases.mondoo.com/rpm/pubkey.gpg") |
mondoo_releases_base_url |
Advanced: Base URL for Mondoo releases (defaults to "https://releases.mondoo.com") - only set if custom URL required |
mondoo_providers_url |
Advanced: URL for provider downloads (defaults to "https://releases.mondoo.com/providers") - only set if custom URL required |
---
- hosts: linux_hosts
become: yes
roles:
- role: ansible-mondoo # if used from galaxy: mondoo.client
vars:
registration_token: "changeme"
force_registration: true
ensure_managed_client: true
annotations: "owner=hello@mondoo.com,env=production"If you want to use cnspec behind a proxy
---
- hosts: linux_hosts
become: yes
vars:
proxy_env:
http_proxy: "http://192.168.56.1:3128"
https_proxy: "http://192.168.56.1:3128"
roles:
- role: ansible-mondoo # if used from galaxy: mondoo.client
vars:
registration_token: "changeme"
force_registration: true
ensure_managed_client: true
environment: "{{proxy_env}}"If you want to use the Windows update task
---
- hosts: windows_hosts
become: yes
roles:
- role: ansible-mondoo # if used from galaxy: mondoo.client
vars:
registration_token: "changeme"
force_registration: true
ensure_managed_client: true
update_windows_enabled: true
update_windows_interval: "1"
update_windows_time: "15:04"If you want to use the Linux update task
---
- hosts: linux_hosts
become: yes
roles:
- role: ansible-mondoo # if used from galaxy: mondoo.client
vars:
registration_token: "changeme"
force_registration: true
ensure_managed_client: true
update_linux_enabled: true
update_linux_cron_day: "*"
update_linux_cron_hour: "11"
update_linux_cron_minute: "40"- Run the playbook with the local hosts file
# download mondoo role from github
ansible-galaxy role install git+https://github.com/mondoohq/ansible-mondoo.git
# (alternative) download mondoo role from ansible galaxy
ansible-galaxy install mondoo.client
# apply the playbook
ansible-playbook -i hosts playbook.yml- Log into the Mondoo Console to view the scan results
If you are using Windows, please read the ansible documentation about WinRM setup or the SSH setup.
- Create a new
hostsinventory. Add your host to the group.
[windows_hosts]
123.123.247.76 ansible_port=5986 ansible_connection=winrm ansible_user=Administrator ansible_password=changeme ansible_shell_type=powershell ansible_winrm_server_cert_validation=ignoreor if you are going to use ssh:
3.235.247.76 ansible_port=22 ansible_connection=ssh ansible_user=admin ansible_shell_type=cmd- Create a
playbook.ymland change theregistration_token:
If you are targeting windows, the configuration is slightly different since become needs to be deactivated:
- hosts: windows_hosts
roles:
- role: ansible-mondoo # if used from galaxy: mondoo.client
vars:
registration_token: "changeme"
force_registration: false- Run the playbook with the local hosts file
# download mondoo role from github
ansible-galaxy role install git+https://github.com/mondoohq/ansible-mondoo.git
# (alternative) download mondoo role from ansible galaxy
ansible-galaxy install mondoo.client
# apply the playbook
ansible-playbook -i hosts playbook.ymlThis role uses molecule for testing with a Makefile-based workflow that ensures you test your local changes instead of any installed Galaxy role.
Before starting, you need to install uv (Python package manager):
macOS/Linux:
curl -LsSf https://astral.sh/uv/install.sh | shOr via Homebrew:
brew install uvOr via pip:
pip install uvFor other installation methods, see: https://docs.astral.sh/uv/getting-started/installation/
Step 1: Setup Python Environment Install all testing tools (molecule, ansible-lint, etc.) in an isolated environment:
make setup/envmake setup/env
Environment not found, creating it first...
Creating virtual environment at: molecule-env
Activate with: source molecule-env/bin/activate
Installing molecule dependencies...
uv pip install --python molecule-env/bin/python ansible-core==2.18.12 molecule==6.0.3 molecule-docker==2.1.0 ansible-lint jmespath
Using Python 3.11.14 environment at: molecule-env
Resolved 47 packages in 20ms
Installed 47 packages in 49ms
+ ansible-compat==25.12.0
+ ansible-core==2.18.12
+ ansible-lint==26.1.1
...
+ urllib3==2.6.3
+ yamllint==1.38.0
Ansible testing environment ready!
IMPORTANT: Run 'source molecule-env/bin/activate' before testing
Then you can use: make molecule/debian/12Step 2: Configure Local Development Configure molecule to test your repository code instead of any installed role from your home directory:
make setup/devmake setup/dev
Configuring molecule for local development testing...
Molecule configured to test local repository code!
Tests will now use your current changes, not installed Galaxy roleStep 3: Activate Environment Before running any tests, activate the Python environment:
source molecule-env/bin/activateTest Specific Distributions:
make molecule/debian/12 # Test Debian 12
make molecule/ubuntu/2404 # Test Ubuntu 24.04
make molecule/rhel/rocky9 # Test Rocky Linux 9
make molecule/suse/opensuse # Test openSUSETest Multiple Distributions:
make molecule/test/debian # Test all Debian-based systems
make molecule/test/rhel # Test all RHEL-based systems
make molecule/test/all # Test all supported distributionsMolecule Lifecycle Commands:
make molecule/create # Create test containers
make molecule/converge # Apply the role
make molecule/verify # Run verification tests
make molecule/destroy # Clean up containers
make molecule/login # Login to test container for debuggingRun ansible-lint to check code quality:
make lintClean development configuration only:
make setup/cleanReset everything (including Python environment):
make setup/resetThis Makefile-based approach solves a common problem: ensuring molecule tests use your local repository code instead of any role you may have installed in your home directory from Ansible Galaxy. Without this setup, you might accidentally test an older installed version rather than your current changes.
The make setup/dev command creates local symlinks that force molecule to use your repository code, while make setup/env provides all the testing tools in an isolated environment.
Mondoo, Inc
Error 'module' object has no attribute 'HTTPSHandler'
TASK [mondoo : Download Mondoo RPM key] ********************************
fatal: [suse]: FAILED! => {"changed": false, "module_stderr": "Shared connection to 127.0.0.1 closed.\r\n", "module_stdout": "Traceback (most recent call last):\r\n File \"/home/vagrant/.ansible/tmp/ansible-tmp-1562450830.52-85510064926638/AnsiballZ_get_url.py\", line 113, in <module>\r\n _ansiballz_main()\r\n File \"/home/vagrant/.ansible/tmp/ansible-tmp-1562450830.52-85510064926638/AnsiballZ_get_url.py\", line 105, in _ansiballz_main\r\n invoke_module(zipped_mod, temp_path, ANSIBALLZ_PARAMS)\r\n File \"/home/vagrant/.ansible/tmp/ansible-tmp-1562450830.52-85510064926638/AnsiballZ_get_url.py\", line 48, in invoke_module\r\n imp.load_module('__main__', mod, module, MOD_DESC)\r\n File \"/tmp/ansible_get_url_payload_103dVU/__main__.py\", line 308, in <module>\r\n File \"/tmp/ansible_get_url_payload_103dVU/ansible_get_url_payload.zip/ansible/module_utils/urls.py\", line 346, in <module>\r\nAttributeError: 'module' object has no attribute 'HTTPSHandler'\r\n", "msg": "MODULE FAILURE\nSee stdout/stderr for the exact error", "rc": 1}
sudo zypper install python python2-urllib3 python3 python3-urllib3
Error ansible.legacy.setup on Windows with SSH
fatal: [123.123.247.76]: FAILED! => {"ansible_facts": {}, "changed": false, "failed_modules": {"ansible.legacy.setup": {"failed": true, "module_stderr": "Parameter format not correct - ;\r\n", "module_stdout": "", "msg": "MODULE FAILURE\nSee stdout/stderr for the exact error", "rc": 1}}, "msg": "The following modules failed to execute: ansible.legacy.setup\n"}
Ansible in combination with Win32-OpenSSH versions older than v7.9.0.0p1-Beta do not work when powershell is the shell type, set the shell type to cmd
Error: You need to install 'jmespath' prior to running json_query filter"
Make sure jmespath is installed in the same python environment as ansible:
pip install jmespathI want to test it with an unsupported OS
Add the following to main.yml and print the ansible_facts to see what is used and adjust the when conditions:
- name: Print all available facts
ansible.builtin.debug:
var: ansible_factsI can't see my changes taking affect when testing with molecule?
Double check that you are using the local role as opposed to the role you might have installed within your home profile, especially if you already have answerable installed on your machine. Within the molecule output, double check the task paths that are being loaded within the converge runs.
It should for example look like this, ie paths that match this repo. The official role is mondoo.client as opposed to this repo which is called ansible-mondoo.
TASK [Gathering Facts] *********************************************************
ok: [instance]
TASK [ansible-mondoo : Linux] **************************************************
included: /Users/********/git-repo/ansible-mondoo/tasks/linux.yml for instance
TASK [ansible-mondoo : Install mondoo package on Debian] ***********************
included: /Users/********/git-repo/ansible-mondoo/tasks/pkg_debian.yml for instanceRun the make setup/dev task to create the symlinks and ansible.cfg file to force molecule to use the local code.
Join the Mondoo Community GitHub Discussions to collaborate on policy as code and security automation.