Scan in Debug Mode to Troubleshoot

If a cnspec scan isn't behaving as expected, you can run it in debug mode to capture detailed information about what happened. Debug mode creates files that you can share with Mondoo support to help diagnose the problem.

Collect a support bundle

The quickest way to gather everything Mondoo support needs is the --collect-support-bundle flag:

cnspec scan local --collect-support-bundle

cnspec runs the scan with debug logging, then packs the debug log, the asset bundle, the inventory, the resolved policy, the report, and the installed provider versions into a single archive in the current directory. It prints the archive's path when it finishes:

support bundle written to: /home/lunalectric/cnspec-support-bundle-20260924T173422Z.tar.gz

To write the bundle somewhere else, add --support-bundle-dir:

cnspec scan aws --collect-support-bundle --support-bundle-dir /tmp/cnspec-support

Run a debug scan

To scan in debug mode without building a bundle, set the DEBUG=1 environment variable before the cnspec scan command:

DEBUG=1 cnspec scan

You can use debug mode with any scan target. For example, to debug an AWS scan:

DEBUG=1 cnspec scan aws --region us-east-1

Or an Oracle Cloud Infrastructure scan:

DEBUG=1 cnspec scan oci

To learn more about scan targets, read the cnspec scan CLI reference.

Debug output files

With DEBUG=1, cnspec writes its debug data to a timestamped directory, such as cnspec-debug-20260924T173406Z, inside the directory from which you run the scan. The directory holds files for the whole run, such as report.json, assets-resolved.json, and mondoo-debug-inventory-unresolved.json, plus one subdirectory per scanned asset with that asset's resolved policy and filters.

cnspec sbom, cnspec vuln, and cnspec aibom also honor DEBUG=1. They write to cnspec-sbom-debug-*, cnspec-vuln-debug-*, and cnspec-aibom-debug-* directories.

Control log output

To raise the log level without writing debug files, use the --log-level flag. It accepts error, warn, info (the default), debug, and trace:

cnspec scan local --log-level debug

Environment variables override the flag. MONDOO_LOG_LEVEL accepts any of those levels, and DEBUG=1 and TRACE=1 set debug and trace.

For full control over where and how cnspec logs, point --logging-config at a YAML or JSON file. It selects the log writer, the level, and options for that writer. For example, to write JSON log lines at the warn level:

writer: cli
level: warn
options:
  format: json

cnspec scan local --logging-config logging.yml

A logging configuration file takes precedence over --log-level. The MONDOO_LOG_LEVEL, DEBUG, and TRACE environment variables still override the level it sets.

Share debug files with Mondoo

To get troubleshooting help, send the support bundle archive, or the whole cnspec-debug-* directory, to Mondoo support.

Learn more

• To learn about scanning, read cnspec scan.

• To report scan results, read Report Results.