cnspec scan

Use cnspec scan to check whether your assets comply with security policies. It evaluates an asset against one or more policies and reports which checks pass and fail, giving you a clear picture of your security posture. By default, cnspec scans the local system with the default policies built specifically for the platform. If you register cnspec with Mondoo, this command scans using the applicable enabled policies.

To learn more, read Get Started with cnspec.

cnspec scan local

You can also specify a local policy and run it without storing results in Mondoo Platform:

cnspec scan local --policy-bundle POLICYFILE.yaml --incognito

In addition, cnspec can scan assets remotely using SSH. By default, cnspec uses the operating system's SSH agent and SSH config to retrieve the credentials:

cnspec scan ssh ec2-user@52.51.185.215

cnspec scan ssh ec2-user@52.51.185.215:2222

Examples: cloud

Scan AWS

cnspec scan aws --region us-east-1

To learn more, read Secure Amazon Web Services (AWS) with cnspec.

Scan Azure

cnspec scan azure --subscription SUBSCRIPTION_ID

To learn more, read Secure an Azure Subscription.

Scan Google Cloud (GCP)

cnspec scan gcp project PROJECT_ID

To learn more, read Secure a Google Cloud Project.

Scan Kubernetes

cnspec scan k8s

cnspec scan k8s MANIFEST_FILE

To learn more, read Secure a Kubernetes Cluster.

Scan Oracle Cloud Infrastructure (OCI)

cnspec scan oci

To learn more, read Secure an OCI Tenancy.

Examples: identity

Scan Active Directory

cnspec scan activedirectory --dc dc01.lunalectric.com --user admin@lunalectric.com --password YOUR_PASSWORD

To learn more, read Assess Active Directory Security with cnspec.

Scan Okta

cnspec scan okta --organization your_org.okta.com --token API_TOKEN

To learn more, read Assess Okta Security with cnspec.

Examples: SaaS

Scan GitHub

export GITHUB_TOKEN=YOUR_PERSONAL_ACCESS_TOKEN
cnspec scan github repo ORG/REPO

To learn more, read Assess GitHub Security with cnspec.

Scan GitLab

cnspec scan gitlab --group YOUR_GROUP_NAME --token YOUR_TOKEN

Scan Google Workspace

export GOOGLEWORKSPACE_CLOUD_KEYFILE_JSON=/home/user/my-project-6646123456789.json
cnspec scan google-workspace --customer-id 5amp13iD --impersonated-user-email admin@domain.com

To learn more, read Assess Google Workspace Security with cnspec.

Scan Jira

cnspec scan atlassian jira --host HOST_URL --user USER@DOMAIN --user-token YOUR_TOKEN

Scan Microsoft 365 (M365)

cnspec scan ms365 --certificate-path certificate.combo.pem --tenant-id YOUR_TENANT_ID --client-id YOUR_CLIENT_ID

To learn more, read Assess Microsoft 365 Security with cnspec.

Scan Slack

cnspec scan slack --token API_TOKEN

To learn more, read Assess Slack Security with cnspec.

Examples: supply chain and containers

cnspec supports local containers and images as well as images in Docker registries.

Scan Docker

cnspec scan docker container b62b276baab6

cnspec scan docker image ubuntu:latest

Scan Harbor

cnspec scan container registry harbor.lunalectric.com

Scan ECR

cnspec scan container registry 123456789.dkr.ecr.us-east-1.amazonaws.com/repository

Scan GCR

cnspec scan gcp gcr PROJECT_ID

Scan Vagrant

cnspec scan vagrant HOST

Scan an inventory file

cnspec scan --inventory-file FILENAME

By default, cnspec scans the assets in an inventory in parallel. It uses the smallest parallelism declared by the providers behind your assets, capped at half the CPUs available on the machine. If any of those providers doesn't declare a value, cnspec scans one asset at a time. To set the number yourself, use --parallelism or the MONDOO_PARALLELISM environment variable. An explicit value isn't capped by the CPU count, and 1 scans sequentially. If you're registered with Mondoo Platform, your space can set a lower ceiling that applies on top of either value.

Scan four assets at a time:

cnspec scan --inventory-file FILENAME --parallelism 4

Examples: infrastructure as code

Scan OpenTofu

cnspec scan opentofu ./infrastructure

The opentofu connector (alias tofu) scans OpenTofu HCL configurations, plan files, and state files.

Scan Terraform

cnspec scan terraform ./infrastructure

Examples: output formats

Use --output (-o) to choose the report format. To write the report to a file or directory instead of the terminal, add --output-target.

Write OCSF events for a security data lake such as Amazon Security Lake:

cnspec scan aws -o ocsf-parquet --output-target ./events/

The ocsf-json and ocsf-parquet formats report each check as an OCSF Compliance Finding and emit OCSF 1.3.0 by default. Append options with commas to report Detection Findings instead, or to emit OCSF 1.9.0:

cnspec scan aws -o ocsf-json,ocsf-findings=detection,ocsf-version=1.9.0 --output-target ./events/

Write InSpec exec-json (OHDF) for Heimdall and other MITRE Security Automation Framework tools. When --output-target is a directory, cnspec writes one file per asset:

cnspec scan --inventory-file FILENAME -o hdf --output-target ./hdf/

Write the results as CSV:

cnspec scan local -o csv --output-target results.csv

MQL strict mode

Use --strict to run policies in MQL strict mode, where every link in an MQL access chain must resolve. The flag sets the default for policies that don't declare strict mode themselves:

cnspec scan local --strict

Options

      --annotation stringToString     Add an annotation to the asset in the form KEY=VALUE (default [])
      --asset-name string             Override the asset name
      --collect-support-bundle        Collect a support bundle (debug logs, asset bundle, inventory, resolved policy, report, provider versions) for sharing with Mondoo support. By default writes to a timestamped directory in the current working dir; override with --support-bundle-dir.
      --detect-cicd                   Try to detect CI/CD environments. If detected, set the asset category to 'cicd' (default true)
      --discover strings              Enable the discovery of nested assets. Supports: all, auto, container, container-images, mcp-servers
  -h, --help                          help for scan
      --incognito                     Run in incognito mode. Do not report scan results to Mondoo Platform
      --inventory-file string         Set the path to the inventory file
      --inventory-format-ansible      Set the inventory format to Ansible
      --inventory-format-domainlist   Set the inventory format to domain list
  -j, --json                          Run the query and return the object in a JSON structure
  -o, --output string                 Set the output format: compact, csv, full, hdf, json, json-v1, json-v2, junit, ocsf-json, ocsf-parquet, report, sarif, summary, yaml, yaml-v1, yaml-v2 (default "compact")
      --output-target string          Set the output target for the asset report: an AWS SQS topic URL, a local file, or a local directory (with -o hdf, one OHDF file per asset; with the OCSF formats, one file per event class)
      --parallelism int               Set the number of assets to scan in parallel. Defaults to a per-provider value capped by the CPUs available on this machine. Use 1 for sequential
      --platform-id string            Select a specific target asset by providing its platform ID
      --policy strings                Specify policies to execute. This requires --policy-bundle. You can pass multiple policies using --policy POLICY
  -f, --policy-bundle strings         Set the path to a policy file. Supports local paths, s3:// URIs, and http(s):// URLs
      --props stringToString          Set custom values for properties (default [])
      --record string                 Record all resource calls and use resources in the recording
      --risk-threshold int            Set the risk threshold. Exit with status 1 if any risk meets or exceeds this value (default 101)
      --sudo                          Elevate privileges with sudo
      --support-bundle-dir string     Directory to write the support bundle into. Only used when --collect-support-bundle is set. Defaults to ./cnspec-support-bundle-<timestamp>/.
      --trace-id string               Set a trace identifier
      --use-recording string          Use a recording to inject resource data (read-only)

Options inherited from parent commands

      --api-proxy string        Set the proxy for communications with Mondoo Platform API
      --auto-update             Enable automatic provider installation and update (default true)
      --config string           Set config file path (default $HOME/.config/mondoo/mondoo.yml)
      --log-level string        Set the log level: error, warn, info, debug, trace (default "info")
      --logging-config string   Path to a logging configuration file (YAML or JSON) that selects the log writer, level, and writer-specific options
      --strict                  Default MQL strict mode for policies that do not declare one: every link in an MQL chain must resolve
  -v, --verbose                 Enable verbose output