v0.12.0: Templates for control outputs, two new formats →

Running Benchmarks

Steampipe controls and benchmarks provide a generic mechanism for defining and running control frameworks such as CIS, NIST, HIPAA, etc, as well as your own customized groups of controls.

There are many control frameworks in existence today, and though they are all implemented with their own specific syntax and structure, they are generally organized in a defined, hierarchical structure, with a pass/fail type of status for each item. The control and benchmark resources allow Steampipe to provide simplified, consistent mechanisms for defining, running, and returning output from these disparate frameworks.

You can run controls and benchmarks with the steampipe check command.

steampipe check all

The console will show progress as its runs, and will print the results to the screen when it is complete:

You can find controls and benchmarks in the Steampipe Mods section of the Steampipe Hub, or by searching Github directly.

You can also create your own controls and benchmarks, and optionally package them into a mod.

You can run all controls in the workspace:

steampipe check all

Or only run a specific benchmark:

steampipe check benchmark.cis_v130

Or run only specific controls:

steampipe check control.cis_v130_1_4 control.cis_v130_2_1_1

Or only run controls with specific tags. For example, to run the controls that have tags cis_level=1 and benchmark=cis:

steampipe check all --tag cis_level=1 --tag cis=true

Usually, steampipe mods use unqualified queries to "target" whichever connection is first in the search path, but you can specify a different path or prefix if you want:

steampipe check all --search-path-prefix aws_connection_2

You can filter the controls to run using a where clause on the steampipe_control reflection table. You may want to preview with --dry-run:

steampipe check all --where "severity in ('critical', 'high')" --dry-run

Before you run:

steampipe check all --where "severity in ('critical', 'high')"

By default, the console output uses 'dark mode' colors, but you can use 'light mode' if you prefer:

steampipe check benchmark.cis_v130 --theme=light

If you run steampipe from a CI tool or batch scheduler, you may want to use non-colorized output and disable the progress bar:

steampipe check all --theme=plain --progress=false

Some benchmarks are quite verbose. To show only the items that are in alarm or error, use brief output:

steampipe check all --output=brief

You can also export the full output to JSON:

steampipe check all --export=json


steampipe check all --export=csv

Or markdown:

steampipe check all --export=md

Or html:

steampipe check all --export=html

Or multiple formats:

steampipe check all --export=csv --export=json --export=html

You can export to a filename of your choosing - steampipe will infer the output type by the file extension:

steampipe check all --export=output.csv --export=output.json --export=output.md

You can also send JSON output to stdout, if you want to redirect it to a file or pipe it to another program:

steampipe check all --progress=false --output=json | jq