Skip to main content

Mondoo Quick Start


This page covers creating an account on Mondoo Platform, installing Mondoo Client on a workstation and registering it with Mondoo Platform, and running your first scan with Mondoo Policies.

  • Sign up for a free account on Mondoo Platform
  • Install the Mondoo Client on a workstation (macOS, Windows, Linux)
  • Run a Mondoo security policy and evaluate the results

After completing this quick start you will have your account setup on Mondoo Platform, understand how clients are installed hosts and how they are configured to connect to Mondoo Platform, and how to run scans and understand scan results.

info

If you encounter any issues during this quick start, don't hesitate to reach out to us in the Mondoo Community Discord channel. We are here to help!

Step 1: Create a Mondoo Platform Account


Mondoo Platform has a free usage tier. If you don’t already have an account, follow these steps to sign up for a free Mondoo account:

  1. Open a browser and go to https://console.mondoo.app.
  2. At the top right of the page, click on JOIN.
  3. Create an account using single sign-on (SSO) via Google, Github, and Microsoft 365, or email/password.
  4. Log in to your account.
info

For larger organizations we support SAML authentication with Microsoft Active Directory.

Getting Started with Mondoo Platform

Mondoo Platform provides a hierarchical structure of Organizations and Spaces. Each new account starts with one Organization and one Space.

  • An Organization provides the top-level structure to manage team members, and create additional Spaces.
  • A Space provides a grouping mechanism and isolation boundary for your assets. Every Space has its own POLICY HUB containing a collection of security policies that can be deployed and customized for the assets connecting to that Space. Additionally, you can develop your own policies and upload them to any, or all of the Spaces that you create.
  • Assets are the business-critical infrastructure that you integrate with Mondoo. Assets can only belong to one Space at at time.

When you first log in to your default Space, you will be greeted with a landing page to help you start integrating assets. The options are to try Mondoo locally, setup a cloud integration, or to manually setup Mondoo.

Landing Page

For the purposes of this quick start guide, we are going to be following the Try it locally path, but be sure to explore our documentation on integrating other assets into Mondoo Platform

Step 2: Install and Register Mondoo Client on a Workstation


Mondoo Client is a cross-platform binary that provides a number of capabilities including:

  • Security Scanning - Use Mondoo to scan local hosts and remote targets such as VMs, containers, container registries, Kubernetes clusters, CI/CD pipelines, and even entire cloud environments.
  • Continuous Security Assessments - Mondoo can be configured to run as a background service on hosts to run continuous security assessments on assets.
  • Infrastructure Development Environment - Start a Mondoo Shell and query your assets using the Mondoo Query Language (MQL).
  • Administer Mondoo Platform - Use Mondoo as a command-line interface (CLI) to administer your account on Mondoo Platform.

First things first, you will need to install Mondoo Client on your workstation and register it with Mondoo Platform.

Install and Register Mondoo Client

Click on the platform for your local workstation, and follow the steps to install and register Mondoo on your system.

Install and register Mondoo on macOS

Mondoo provides an open source shell script for *nix systems that detects the platform, and installs the latest version of Mondoo on the target host.

For macOS, the install script checks to see if Homebrew is installed, and will install Mondoo using the Mondoo Tap if it is.

By setting the MONDOO_REGISTRATION_TOKEN environment variable before installation, Mondoo will automatically register with your account on the Mondoo Platform..

  1. Click on Try it locally.

  2. Click on the Apple icon to generate a temporary registration token, and an command that sets the MONDOO_REGISTRATION_TOKEN environment variable and executes the Mondoo installer in the shell.

  3. Click the Copy to clipboard button to copy the token and install command to your clipboard.

  4. On your workstation, open a Terminal and paste the contents of your clipboard into the shell and hit ENTER

  5. Once Mondoo finishes installing and registering, you can run mondoo status to validate it is installed and authenticating with Mondoo Platform. If registration was successful, mondoo status will output:

    β†’ agent is registered
    β†’ agent authenticated successfully
info

Mondoo registration tokens generated in the Getting Started page expire every 600 seconds. Longer-lived tokens can be generated from the INTEGRATIONS/Managed Agents page within Mondoo Platform

Viewing Managed Clients on Mondoo Platform

Managed Clients are clients that have registered with Mondoo Platform. Managed clients can be viewed in Mondoo Platform by navigating to INTEGRATIONS, then Managed Clients.

Managed Clients in Mondoo Platform

Here you can view all of your clients along with metadata including hostname, IP Address, platform information, last check-in time, Mondoo Client version, and the current status.

info

Managed Clients that have not checked in in the last 24 hours will be marked as Missing

At this point your workstation has registered with the platform, but has not run any security policies yet. We will take care of that in the next step.

Step 3: Run a Security Scan


The Mondoo Platform POLICY HUB comes stocked with an ever-increasing collection of certified security policies and benchmarks designed to assess your critical business assets for security vulnerabilities and misconfigurations. These policies are production-ready, simple to deploy and manage, and provide actionable insights for your business.

Mondoo policies describe a prescriptive set of security and compliance rules used to test and validate consistent standards are met across every infrastructure environment from build-time, to runtime. Mondoo continuously assesses your business-critical systems according to the policies you enable in Mondoo Platform, and reports any deviation from those policies so that you can take immediate action.

Policies are ENABLED and DISABLED in Mondoo Platform, and clients will automatically run any policies that are designed for the type of asset they are. Every new Space has a default set of policies enabled including the Mondoo Security Baselines for macOS, Windows, and Linux, which are a collection of security controls based off the CIS Benchmarks for those platforms.

Mondoo Security Baselines

Run Mondoo Scan

After a client is registered with Mondoo Platform, running policies is effortless. Simply open a terminal (bash, zsh, PowerShell, CMD) and run:

Run mondoo scan
mondoo scan

When scan is initiated, Mondoo Client authenticates with the Mondoo Platform API and requests it's policies. Policies are verified for integrity before executing, and run completely in memory. Policies are not written to the host.

info

Mondoo Client can be configured to run continuously as a background service on Linux and Windows servers. More information can be found in the Running Mondoo as a Service documentation.

Step 4: Understanding Security Scan Results


Mondoo Policy scans provide detailed information about the queries executed on assets. Let's take a look at the results from the scan we just ran in the last section.

Asset Scan Results in the Terminal

After executing mondoo scan the results of the policies executed are returned to the terminal. A score is generated for the asset along with detailed information for each failed query.

Scan macOS

This information can be useful for development of policies, investigations, and remediation. As we deal with larger and more complex environments, we need a way to view reporting across all of our assets.

Next, let's take a look at the reports generated from scans in Mondoo Platform.

Asset Scan Results in Mondoo Platform

In addition to returning the results of a scan to the shell, Managed Clients send the results of scans to Mondoo Platform where a report is generated. Asset reports can be viewed by navigating to FLEET section in the console.

Mondoo Platform Fleet View

The top level view provides the latest information for all assets checking into your Space. From there you can click on any asset to view detailed information about the policies associated with it, and results from the last scan.

Individual Asset Reports

As assets can run many policies at once (more on how this is done later), after clicking selecting an asset from the FLEET page, are shown an aggregated score for that asset at the top based off of all of the policies it has executed, but can drill down into each individual policy for detailed information.

If not already there, log in to Mondoo Platform, navigate to the FLEET section, locate your workstation, and click on it to view details about the scan we ran.

Click on the platform you installed Mondoo Client on and let's explore the findings:

Once you've located your workstation in the FLEET and clicked on it to view more details, locate the report for the Mondoo macOS Security Baseline and click it to view the results.

Selecting an individual policy allows you to see all of the queries associated with it, and the results when executed on the asset you are looking at.

Additionally, policies can provide descriptions, rationale, and remediation steps. Here you will find the query that was executed using the Mondoo Query Language (MQL).

Let's take a look at one query titled "Disable Remote Login".

  1. In the Filter queries... search box,, search for Disable Remote Login.
  2. Click the drop-down arrow on the right for detailed information.

From this view we can see the information about what this query is testing, and the rationale for it.

Additionally, the policy provides steps to remediate the issue on the host.

It is here in the details that we also get our first look at MQL:

MQL query for Disable Remote Login
macos.systemsetup.remoteLogin == "Off"

We are going to dive into MQL just yet, but know that at any point you can explore how MQL queries are constructed by click on any policy in the POLICY HUB, and expanding individual queries.

Conclusion

If you followed along then you should now have your account setup on Mondoo Platform and have at least one asset reporting in after running a scan of a policy.

In the next section we'll dive deeper and introduce to the real power behind Mondoo...the Mondoo Query Language (MQL), and how you can start leveraging it right away using Mondoo Shell.