Skip to main content

Policy Authoring Guide | Limit Target Assets with Filters

Filters can specify what target assets a policy, group, check, or query can run against. A filter is simply a condition, written in MQL, that must be met. Any fields you can query about any resources can be the basis for a filter.

The most common basis for filters is platform information. For example, you can add a filter that tells cnspec to run a policy only on AWS EKS clusters. Or you can add a filter that tells cnspec to run a check only on certain versions of an operating system.

info

Filters are an essential part of creating variants. To learn about variants, read Make Policies Flexible with Variants.

Apply a filter to a check or query​

Add filters information to a check or query to apply a filter to it.

This is an example of a check with a filter:

- uid: ssh-root-login-is-disabled
  title: Ensure SSH root login is disabled
  filters: package('openssh-server').installed
  impact: 90
  mql: sshd.config.params["PermitRootLogin"] == "no"

The filter in the ssh-root-login-is-disabled check tells cnspec to run the check only on assets that have the SSH Server package installed. When scanning an asset without SSH Server, cnspec skips this check.

Apply a filter to a chapter or group​

Add filters information to a group to apply a filter to it.

This is an example of a chapter type of group with two filters:

groups:
  - title: AWS Compute Services
    type: chapter
    filters: |
      asset.name == "aws"
      asset.kind == "api"
    checks:

    ...

Unless the asset is an AWS compute service, cnspec skips all the checks and queries in this group when scanning the asset.

Apply a filter to a policy​

The policy in this bundle has a filter:

policies:
  - uid: ssh-with-filter
    name: SSH policy that uses a filter

...

    groups:
      - title: my-group
        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

        filters:
          - mql: asset.family.contains('unix')

This bundle contains only one policy, ssh-with-filter. The section beginning on line 24 defines filters for the policy. In this case, cnspec uses the policy to scan only assets that are based on UNIX (Linux distributions and macOS).

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.

More examples of filters​

This filter limits scans to only GCP projects:

asset.platform == "gcp-project"

This filter limits scans to only kubelets:

asset.family.contains('linux')
processes.where( executable == /kubelet/ ).list != []

To learn how to write your own filters, read Write Effective MQL and the MQL Reference.

Next steps​

  • To learn an efficient way to define the ideal values that policies check against, read Define Properties.

  • You can find many examples of policy bundles in Mondoo's cnspec-policies GitHub repo.

  • To learn how to set up, validate, and store policy bundles, read Manage Policies.