Skip to main content

Policy Authoring Guide | Write Custom Policies

Policies are the specifications that cnspec uses when it scans an asset. cnspec compares your asset's configuration against the standards set in policies, and calculates a score based on the comparison.

Mondoo provides dozens of free policy bundles (collections of policies) with cnspec that cover the most common types of assets—and Mondoo Platform has even more. If your organization has unique needs that these policy bundles don't meet, you can create custom policy bundles.

A very simple policy bundle​

All cnspec policies are stored in YAML files. These files are called bundles because they bundle policies together. Their filename ends in .mql.yaml. To learn more about policies and policy bundles, read About Policies.

Here's a very simple example of a policy bundle. It contains only one policy, Simple example policy 1:

policies:
  - uid: simple-example1
    name: Simple example policy 1
    version: "1.0.0"
    scoring_system: highest impact
    authors:
      - name: Lunalectric
        email: security@lunalectric.com
    docs:
      desc: |-
        Descriptive documentation about this policy
    groups:
      - title: group1
        checks:
          - uid: sshd-01
            title: Ensure the port is set to 22
            mql: sshd.config.params["Port"] == 22
            impact: 30

          - uid: sshd-02
            title: Prevent weaker CBC ciphers from being used
            mql: sshd.config.ciphers.none( /cbc/ )
            impact: 60

        queries:
          - uid: sshd-d-1
            title: Gather SSH config params
            mql: sshd.config.params

We'll use this simple policy bundle example to explore how to write a policy.

Basic policy attributes​

The attribute...On line...Defines...
uid2A unique identifier for the policy
name3A descriptive name for the policy
version4The current version of the policy.
We recommend using semantic versioning to keep track of major and minor policy changes.
scoring_system5How Mondoo calculates the score for an asset: average or highest impact. To learn more, read Score Policies.
authors6-7The person or entity to credit for writing the policy, and email where they can be reached.
docs9-11Optional documentation section for describing the policy's purpose and makeup.

The groups section of the policy defines the checks and queries that define how to assess and report on asset security. To learn more, read Break up a Policy into Groups / Chapters.

Queries​

A query is an MQL inquiry that requests information about an asset. For example, a query can ask what version of an OS is running on a container or request the UIDs, names, and statuses are of all users in an application.

Queries in a policy add helpful insights to scan report output. (They're also the bases for checks, which are described below.)

The simple example policy bundle above contains one query (on lines 26-28). It requests the configuration values of the SSH server scanned. This information is included in the scan report output.

The attribute...On line...Defines...
uid26A unique identifier for the query
title27A descriptive name for the query
mql28The MQL query that requests information, such as the number of root accounts or the state of a port

To learn how to create MQL queries, read Write Effective MQL.

Checks​

An MQL query that also makes an assertion and produces a score is called a check. Checks retrieve a value just like any query. For example, a check can ask What OS version is running? How they differ from other queries is that they compare the retrieved value to a desired value and create a score based on that comparison. For example, a check can assert that the value should be 8.3.1 or higher. All checks return a Boolean true or false. In our example, if the current OS version on the scanned asset is 8.2, the check returns false. If the current OS version is 8.3.1 or 8.3.5, the check returns true.

Checks are the building blocks of policies. A typical policy identifies a number of desired configurations (such as MFA is enabled and no ports are publicly accessible) and instructs Mondoo to compare that to the actual configuration on the scan target. This is a collection of checks.

The simple example policy bundle above contains two checks:

  • The check defined in lines 15-18 ensures the SSH port is set to 22.

  • The check defined in lines 20-23 ensures that SSH uses a strong cipher.

Each check has its own attributes:

The attribute...On lines...Defines...
uid15 & 20A unique identifier for the check
title16 & 21A descriptive name for the check that's useful in report output
mql17 & 22The MQL assertion that identifies the desired condition or configuration, such as logging is enabled or encryption is required
impact18 & 23How important (on a scale from 0 to 100) the check is in the scope of the entire policy. The impact and result of each check determine the asset's score on the policy. To learn more, read Score Policies.

To learn how to create MQL queries and checks, read Write Effective MQL.

tip

To check for errors in the policy bundles you write, run cnspec bundle lint BUNDLE-NAME.mql.yaml. For BUNDLE-NAME, substitute the name of your file.

Next steps​

  • To learn how scoring works in Mondoo policies, read Score Policies.

  • If you're ready to create your own policy: To learn how to set up, validate, and store policy bundles, read Manage Policies.