Scan Clients Managed by opsi
Run agentless cnspec fleet scans on the Windows, macOS, and Linux clients that opsi manages.
The opsi integration scans the Windows, macOS, and Linux clients that your opsi config server manages, without installing anything on them yourself. Mondoo calls the config server's JSON-RPC API, which runs a script on the clients of the host group you choose. The script runs cnspec, and cnspec reports the results to Mondoo. To learn how fleet scans work, read Scan Endpoints Through Your Endpoint Management Tool.
Before you begin
You need the Editor or Owner role, or another role with this permission. To see every role, read Roles and permissions.
- An opsi config server whose JSON-RPC API (port 4447 by default) Mondoo Platform can reach over HTTPS
- opsi clients with the opsi client agent installed, organized in opsi host groups. The config server runs the scan on a client through its message bus connection, so a client that isn't connected when the scan starts isn't scanned.
- An opsi user, ideally a dedicated service account, with permission to read host groups and run
hostControl_execute
Add an opsi integration
In the Mondoo App, navigate to the space where you want to add the integration. In the side navigation bar, select Integrations. In the top right, select INSTALL. On the Install Integration page, find the integration you want by browsing a category or searching by name:
-
Under Endpoint Management / UEM, select opsi.
-
In Choose an integration name, enter a name that helps you identify the integration.
-
In Enter the opsi server URL, enter the base URL of your opsi config server, including the JSON-RPC port. For example:
https://opsi.lunalectric.com:4447 -
In Provide opsi service credentials, enter the username and password of the opsi user. Mondoo sends them as HTTP Basic authentication to the JSON-RPC endpoint.

-
Under Options, choose how Mondoo connects and what it adds to the space:
- Skip TLS certificate verification (off by default): Turn this on if your opsi server uses a self-signed certificate. Only turn it on for servers you trust.
- Create assets from opsi inventory (on by default): Add the opsi clients to the space as assets, so they appear even before their first scan reports.
-
Select Create Integration.
Next, choose the host group to scan and a schedule, as described below. To start a scan now for every host group with an active schedule, select Run on the integration's page.
Run and schedule fleet scans
To open the integration, navigate to the space, select Integrations in the side navigation, choose the integration type, then select the integration. Then select the Scan Jobs tab.
In the Run a fleet scan card:
-
Under Target host group, search for the host group to scan and select it. The Devices in this group table lists the group's devices with their OS, last check-in, and readiness. A readiness badge marks a device that probably won't run the scan. Hover over a badge for details. Not every tool reports every badge.
- Stale check-in: The device hasn't checked in with the tool within its normal cadence, or the tool reports it offline.
- Not answering recent scans: The device didn't answer at least two of the group's last three fleet scans and hasn't answered since. Mondoo still includes it in scans.
- Membership pending: The device's record still names the group, but the group's membership no longer includes it, because a dynamic group rule now excludes it or it was removed from the group. The device hasn't checked in since. Fleet scans of the group don't target it.
- Not reporting: An earlier fleet scan of the group targeted the device, but the tool no longer lists it in the group. Fleet scans of the group don't target it.

-
Under Schedule, choose a Cadence. Daily is the default. The cadences offered depend on the tool. Choose Manual only to scan the group once without saving a schedule.
-
For a recurring cadence, set when it runs:
- Day of week (for Weekly) or Day of month (for Monthly, days 1 through 28)
- Time of day (03:00 by default)
- Timezone (your browser's time zone by default)
-
Select Save schedule to save a recurring scan, or Run now if you chose Manual only.

The Saved schedules card lists each schedule with its host group, cadence, time zone, last run, next run, and status. To stop a schedule for a while, select Pause, and select Resume to start it again. To delete it, select Cancel. To change a schedule, save a new one for the same host group: it replaces the old one.
To scan right away without opening the Scan Jobs tab, select RUN at the top of the integration's page. It starts a scan of every host group with an active schedule and leaves the schedules as they are. If the integration has no active schedule, the Mondoo App asks you to turn one on or to start a scan on the Scan Jobs tab. Microsoft Intune integrations have a SYNC button instead of RUN.
Review scan results
The Recent scan jobs card on the Scan Jobs tab lists the scans Mondoo started, with their host group, number of hosts, duration, and status. A scan job's status is Pending, Running, Succeeded, Partial, Failed, Timed out, or Cancelled.
Select a scan job to open its details. The Hosts table shows the outcome on each device, including the reason a device wasn't scanned or its scan failed (for example, the device was offline or didn't check in with the tool in time). If Mondoo retried the hosts a scan couldn't reach in a follow-up scan, the scan detail links to it.
Each device a fleet scan reaches becomes an asset in the space, and its results appear in your inventory like those of any other asset. To open a scanned device's asset page, select Open asset in its row of the Hosts table. If a device's latest fleet scan didn't scan it or failed, the asset page says so and links to the scan.
Check the integration's health
The Diagnosis tab runs preflight checks on the integration: its credentials, permissions, device management policies, and licenses. Each check passes, warns, fails, or lists a setting to verify yourself. The results are advice only: a warning or failure explains why a scan may fail, but never stops a scan. To check again after you fix something, select Re-run.

Set maintenance windows
The Maintenance Windows tab shows the maintenance windows that apply to the integration's devices. A maintenance window says when Mondoo may remediate devices. It never delays a scan. On the tab, you can see the windows imported from the integration or assigned to it, check the effective window for a host group, and, for Microsoft Intune, CrowdStrike Falcon, and opsi, import the windows the tool already defines. To learn more, read Define Maintenance Windows.
Edit or remove the integration
On the integration's page, select the edit (pencil) icon to change its settings, then select Save Changes. To remove the integration, select the trash can icon and confirm.
If the integration authenticates with a stored credential, such as an API client secret or a password, rotate the credential to replace a secret that is expiring or was revoked. In the left navigation, select Settings, then Credentials. Find the credential, open the menu in its Status column, and select Rotate. Every integration that uses the credential switches to the new secret right away. To learn more, read Manage Integration Credentials.
When you edit an opsi integration, you can change its name and these Preferences:
- Create new assets for opsi clients: When a scan discovers an opsi client not found in the space, add it as a new asset.
- Enrich findings with Mondoo: Run Mondoo's vulnerability database against the data opsi clients report, so findings get remediation guidance.
- Skip TLS certificate verification: Turn this on only if you trust the network path to the server.
- Debug mode: Keep the delivered script and cnspec output after a fleet scan instead of cleaning them up, so you can troubleshoot a failing scan. Leave it off for normal operation.
The edit form also lets you change the opsi server URL and Service-account username. Mondoo never shows the stored password, so you must enter the Service-account password again to save any change.
Verify the integration
After you save a schedule or start a scan:
- Check the status. On the Integrations page, the integration's status becomes Active once a scan succeeds. To learn what each status means, read Integration Status and Troubleshooting.
- Follow the scan. On the Scan Jobs tab, Recent scan jobs lists the scan with its status. When it finishes, the status is Succeeded, or Partial if some devices weren't scanned.
- Open a scanned device. Select a scan job, then select Open asset in a device's row of the Hosts table to see the device's first results. To learn more, read Review scan results.
- Find devices that weren't scanned. The Hosts table gives the reason for each device the scan skipped or failed on. The Diagnosis tab checks the integration's credentials, permissions, and licenses. To learn more, read Check the integration's health.
Troubleshoot
For errors that all integrations share, read Integration Status and Troubleshooting. The Diagnosis tab also checks the integration's setup.
A client in the host group isn't scanned
The config server runs the scan on a client through its message bus connection, so a client that isn't connected when the scan starts isn't scanned.
Fix: Make sure the client is connected to the config server, then run the scan again. The Hosts table of the scan job shows why each device wasn't scanned. Read Review scan results.
Next steps
- Inventory your assets: find the scanned devices and the vulnerable software on them.
- Define Maintenance Windows: set when Mondoo may remediate the devices.
- Assess and improve your security: review and prioritize the devices' findings.
Last updated on