Query Your Infrastructure

Beyond policy-based scanning, cnspec lets you query any asset directly using MQL (Mondoo Query Language). MQL is a lightweight query language built for searching and filtering infrastructure configuration data. Its data extraction resembles GraphQL, while its scripting approach is similar to JavaScript.

MQL integrates with hundreds of resources to retrieve information about your infrastructure.

cnspec provides two ways to run an MQL query:

cnspec shell opens an interactive shell with auto-complete. It's the fastest way to explore an asset and iterate on a query.
cnspec run executes a single query and prints the result. Use it for one-off checks and for piping output into other tools.

Run queries in the cnspec shell

Open a shell against a target asset:

cnspec shell TARGET

For example, to open a shell against the local system:

cnspec shell local

Or against a remote host over SSH:

cnspec shell ssh user@HOST

Inside the shell:

Type help to list the available resources, or help RESOURCE for details on a specific resource.
Start typing a resource name and press Tab to auto-complete.
Press Ctrl + D or type exit to leave the shell.

Run a single query from the command line

To run one query without opening a shell, use cnspec run with the -c flag:

cnspec run TARGET -c QUERY

For...	Substitute...
`TARGET`	The asset to query, such as `local` or a transport to a remote machine.
`QUERY`	The MQL query that specifies the information you want.

For example, list services and their running status on your local system:

cnspec run local -c "services.list { name running }"

Add -j (or --json) to return results as JSON, which is useful for piping into tools like jq:

cnspec run local -c "services.list { name running }" -j

More query examples

You can run any of the following queries in the cnspec shell or pass them to cnspec run with -c.

Find all AWS EC2 instances with a public IP address:

aws.ec2.instances.where( publicIp != '' ) {
  instanceId
  region
  state
  tags
  publicIp
}

List every available field for all users:

users { * }

Find all container image repositories used in a Kubernetes cluster:

k8s.pods {
  name
  containers.map( containerImage.repository.fullName )
}

.map is a function for arrays that takes a given field and extracts it. Unlike block calls ({ ... }), it returns the field directly instead of wrapping it in an object.

Resources and fields

Resources are the building blocks of every query. They represent things you can retrieve from an asset. Some examples:

asset — Information about the asset, including name, family, release, and more
user — User information, including name, uid, gid, home, shell, and more
packages — Installed packages, including name, version, installed, outdated, and more
k8s.container — Kubernetes container configuration, including imagePullPolicy, workingDir, and more
terraform.block — Terraform block arguments and attributes

Each resource has fields that return specific configuration values. Retrieve multiple fields at once using braces:

asset { platform version arch }

For the full list of resources, type help in the cnspec shell or browse the MQL resource reference.

Learn more

For MQL operators, functions, and language features, read Write Effective MQL.
To run a saved bundle of queries against an asset, read Run a Query Pack.
To scan many assets at once, read Remote Scanning with Inventory Files.