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.