Skip to main content

InSpec CLI

Use the InSpec Command Line Interface (CLI) to run tests and audits against targets using local, SSH, WinRM, or Docker connections.

archive

Archive a profile to a tar file (default) or zip file.

Syntax

This subcommand has the following syntax:

inspec archive PATH

Options

This subcommand has the following additional options:

--airgap
--no-airgap
Fallback to using local archives if fetching fails.
--check
--no-check
Before running archive, run inspec check. Default: do not check.
--export
--no-export
Include an inspec.json file in the archive, the results of running inspec export.
--legacy-export
--no-legacy-export
Include an inspec.json file in the archive by utilizing information from the legacy export procedure, the results of running inspec export --legacy-export.
--ignore-errors
--no-ignore-errors
Ignore profile warnings.
-o
--output=OUTPUT
Save the archive to a path.
--overwrite
--no-overwrite
Overwrite existing archive.
--profiles-path=PROFILES_PATH
Folder which contains referenced profiles.
--tar
--no-tar
Generates a tar.gz archive.
--vendor-cache=VENDOR_CACHE
Use the given path for caching dependencies, (default: ~/.inspec/cache).
--zip
--no-zip
Generates a zip archive.

automate

Communicates with Chef Automate.

Syntax

This subcommand has the following syntax:

inspec automate SUBCOMMAND

check

Verify the metadata in the inspec.yml file, verify that control blocks have the correct fields (title, description, impact), and define that all controls have visible tests and the controls are not using deprecated InSpec DSL code.

Syntax

This subcommand has the following syntax:

inspec check PATH

Options

This subcommand has the following additional options:

--format=FORMAT
The output format to use. Valid values: json and doc. Default value: doc.
--profiles-path=PROFILES_PATH
Folder which contains referenced profiles.
--vendor-cache=VENDOR_CACHE
Use the given path for caching dependencies, (default: ~/.inspec/cache).
--with-cookstyle
--no-with-cookstyle
Enable or disable cookstyle checks.
--legacy-check
--no-legacy-check
Run check in legacy mode, which examines the profile in a different way. Default: use newer parser-based method.

detect

Detects the target OS.

Syntax

This subcommand has the following syntax:

inspec detect

Options

This subcommand has the following additional options:

-b
--backend=BACKEND
Choose a backend: local, ssh, winrm, docker.
--bastion-host=BASTION_HOST
Specifies the bastion host if applicable.
--bastion-port=BASTION_PORT
Specifies the bastion port if applicable.
--bastion-user=BASTION_USER
Specifies the bastion user if applicable.
--ca-trust-file=PATH_TO_CA_TRUST_FILE
Specify CA certificate required for SSL authentication (WinRM).
--client-cert=PATH_TO_CLIENT_CERTIFICATE
Specify client certificate required for SSL authentication (WinRM).
--client-key=PATH_TO_CLIENT_KEY
Specify client key required with client certificate for SSL authentication (WinRM).
--client-key-pass=CLIENT_CERT_PASSWORD
Specify client certificate password, if required for SSL authentication (WinRM).
--config=CONFIG
Read configuration from the JSON file (- reads from stdin).
--docker-url
Provides a path to the Docker API endpoint (Docker).
--enable-password=ENABLE_PASSWORD
Password for enable mode on Cisco IOS devices.

--format=FORMAT

--host=HOST
Specify a remote host which is tested.
--insecure
--no-insecure
Disable SSL verification on select targets.
-i
--key-files=one two three
Login key or certificate file for a remote scan.
--password=PASSWORD
Login password for a remote scan, if required.
--path=PATH
Login path to use when connecting to the target (WinRM).
-p
--port=N
Specify the login port for a remote scan.
--podman-url
Provides the path to the Podman API endpoint. Defaults to unix:///run/user/$UID/podman/podman.sock for rootless container, unix:///run/podman/podman.sock for rootful container (for this you need to execute inspec as root user).
--proxy-command=PROXY_COMMAND
Specifies the command to use to connect to the server.
--self-signed
--no-self-signed
Allow remote scans with self-signed certificates (WinRM).
--shell
--no-shell
Run scans in a subshell. Only activates on Unix.
--shell-command=SHELL_COMMAND
Specify a particular shell to use.
--shell-options=SHELL_OPTIONS
Additional shell options.
--ssl
--no-ssl
Use SSL for transport layer encryption (WinRM).
--ssl-peer-fingerprint
Specify SSL peer fingerprint in place of certificates for SSL authentication (WinRM).
--sudo
--no-sudo
Run scans with sudo. Only activates on Unix and non-root user.
--sudo-command=SUDO_COMMAND
Alternate command for sudo.
--sudo-options=SUDO_OPTIONS
Additional sudo options for a remote scan.
--sudo-password=SUDO_PASSWORD
Specify a sudo password, if it is required.
-t
--target=TARGET
Simple targeting option using URIs, e.g. ssh://user:pass@host:port.
--target-id=TARGET_ID
Provide a ID which will be included on reports.
--user=USER
The login user for a remote scan.
--winrm-basic-auth-only
--no-winrm-basic-auth-only
Whether to use basic authentication, defaults to false (WinRM).
--winrm-disable-sspi
--no-winrm-disable-sspi
Whether to use disable sspi authentication, defaults to false (WinRM).
--winrm-transport=WINRM_TRANSPORT
Specify which transport to use, defaults to negotiate (WinRM).
--winrm-shell-type=WINRM_SHELL_TYPE
Specify which shell type to use (powershell, elevated, or cmd), which defaults to powershell (WinRM).

env

Outputs shell-appropriate completion configuration.

Syntax

This subcommand has the following syntax:

inspec env

exec

Run all test files at the specified locations.

The subcommand loads the given profiles, fetches their dependencies if needed, then connects to the target and executes any controls in the profiles. One or more reporters are used to generate the output.

Syntax

This subcommand has the following syntax:

inspec exec LOCATIONS

Options

This subcommand has the following additional options:

--allow-unsigned-profiles
Allow InSpec to execute unsigned profiles if mandatory profile signing is enabled. Defaults to false.

Chef InSpec 6 and greater has an optional setting that requires signed profiles. If you try to execute an unsigned profile with this feature enabled, InSpec won’t execute the profile and returns exit code 6. Use --allow-unsigned-profiles to execute unsigned profiles if mandatory profile signing is enabled.

For more information, see Signed InSpec Profiles.

--attrs=one two three
Legacy name for --input-file - deprecated.
--audit-log-location=AUDIT_LOG_LOCATION
The directory that the audit log saves diagnostic log files to. You must enable audit logging to use this feature. See the Audit Log documentation for details.

Default: ~/.inspec/logs.

InSpec creates log files in the set directory using the following format: inspec-audit-TIMESTAMP-PID.log.

--auto-install-gems
Auto installs gem dependencies of the profile or resource pack.
-b
--backend=BACKEND
Choose a backend: local, ssh, winrm, docker.
--backend-cache
--no-backend-cache
Allow caching for backend command output. (default: true).
--bastion-host=BASTION_HOST
Specifies the bastion host if applicable.
--bastion-port=BASTION_PORT
Specifies the bastion port if applicable.
--bastion-user=BASTION_USER
Specifies the bastion user if applicable.
--ca-trust-file=PATH_TO_CA_TRUST_FILE
Specify CA certificate required for SSL authentication (WinRM).
--client-cert=PATH_TO_CLIENT_CERTIFICATE
Specify client certificate required for SSL authentication (WinRM).
--client-key=PATH_TO_CLIENT_KEY
Specify client key required with client certificate for SSL authentication (WinRM).
--client-key-pass=CLIENT_CERT_PASSWORD
Specify client certificate password, if required for SSL authentication (WinRM).
--command-timeout=SECONDS
Maximum seconds to allow a command to run.
--config=CONFIG
Read configuration from the JSON file (- reads from stdin).
--controls=one two three
A list of control names to run or a list of /regexes/ to match against control names. Ignore all other tests.
--create-lockfile
--no-create-lockfile
Write out a lockfile based on this execution (unless one already exists).
--distinct-exit
--no-distinct-exit
Exit with code 101 if any tests fail and 100 if any are skipped (default). If disabled, exit 0 on skips and 1 for failures.
--docker-url
Provides path to Docker API endpoint (Docker). Defaults to unix:///var/run/docker.sock on Unix systems and tcp://localhost:2375 on Windows.
--enable-password=ENABLE_PASSWORD
Password for enable mode on Cisco IOS devices.
--filter-empty-profiles
--no-filter-empty-profiles
Filter empty profiles (profiles without controls) from the report.
--filter-waived-controls
Do not execute waived controls in InSpec at all. Must use with --waiver-file. Ignores the run setting of the waiver file.
--host=HOST
Specify a remote host which is tested.
--input=name1=value1 name2=value2
Specify one or more inputs directly on the command line, as --input NAME=VALUE. Accepts single-quoted YAML and JSON structures.
--input-file=one two three
Load one or more input files, a YAML file with values for the profile to use.
--insecure
--no-insecure
Disable SSL verification on select targets.
-i
--key-files=one two three
Login key or certificate file for a remote scan.
--password=PASSWORD
Login password for a remote scan, if required.
--path=PATH
Login path to use when connecting to the target (WinRM).
-p
--port=N
Specify the login port for a remote scan.
--podman-url
Provides the path to the Podman API endpoint. Defaults to unix:///run/user/$UID/podman/podman.sock for rootless container, unix:///run/podman/podman.sock for rootful container (for this you need to execute inspec as root user).
--profiles-path=PROFILES_PATH
Folder which contains referenced profiles.
--proxy-command=PROXY_COMMAND
Specifies the command to use to connect to the server.
--reporter=one two:/output/file/path
Enable one or more output reporters: cli, documentation, html2, progress, progress-bar, json, json-min, json-rspec, junit2, yaml.
--reporter-backtrace-inclusion
--no-reporter-backtrace-inclusion
Include a code backtrace in report data (default: true).
--reporter-include-source
Include full source code of controls in the CLI report.
--reporter-message-truncation=REPORTER_MESSAGE_TRUNCATION
Number of characters to truncate failure messages in report data (default: no truncation).
--self-signed
--no-self-signed
Allow remote scans with self-signed certificates (WinRM).
--shell
--no-shell
Run scans in a subshell. Only activates on Unix.
--shell-command=SHELL_COMMAND
Specify a particular shell to use.
--shell-options=SHELL_OPTIONS
Additional shell options.
--show-progress
--no-show-progress
Show progress while executing tests.
--silence-deprecations=all|GROUP GROUP...
Suppress deprecation warnings. See install_dir/etc/deprecations.json for a list of GROUPs or use ‘all’.
--ssh-config-file=one two three
A list of paths to the SSH configuration file, for example: ~/.ssh/config or /etc/ssh/ssh_config.
--ssl
--no-ssl
Use SSL for transport layer encryption (WinRM).
--ssl-peer-fingerprint
Specify SSL peer fingerprint in place of certificates for SSL authentication (WinRM).
--sudo
--no-sudo
Run scans with sudo. Only activates on Unix and non-root user.
--sudo-command=SUDO_COMMAND
Alternate command for sudo.
--sudo-options=SUDO_OPTIONS
Additional sudo options for a remote scan.
--sudo-password=SUDO_PASSWORD
Specify a sudo password, if it is required.
-t
--target=TARGET
Simple targeting option using URIs, e.g. ssh://user:pass@host:port.
--target-id=TARGET_ID
Provide an ID that is included on reports - deprecated.
--tags=one two three
A list of tags or regular expressions that match tags. exec will run controls referenced by the listed or matching tags.
--user=USER
The login user for a remote scan.
--vendor-cache=VENDOR_CACHE
Use the given path for caching dependencies. (default: ~/.inspec/cache).
--waiver-file=one two three
Load one or more waiver files.
--winrm-basic-auth-only
--no-winrm-basic-auth-only
Whether to use basic authentication, defaults to false (WinRM).
--winrm-disable-sspi
--no-winrm-disable-sspi
Whether to use disable sspi authentication, defaults to false (WinRM).
--winrm-transport=WINRM_TRANSPORT
Specify which transport to use, defaults to negotiate (WinRM).
--enhanced-outcomes
Includes enhanced outcome of controls in report data.

Exit codes

0
normal exit, all tests passed
1
usage or general error
2
error in plugin system
3
fatal deprecation encountered
5
invalid profile signature
6
mandatory profile signing mode enabled and no signature found
100
normal exit, at least one test failed
101
normal exit, at least one test skipped but none failed
172
Chef license not accepted

Examples

Below are some examples of using exec with different test locations.

Chef Automate:

inspec automate login
inspec exec compliance://username/linux-baselinem

inspec compliance is a backwards compatible alias for inspec automate and works the same way:

inspec compliance login

Chef Supermarket:

inspec exec supermarket://username/linux-baseline
inspec exec supermarket://username/linux-baseline --supermarket_url="https://privatesupermarket.example.com"

Local profile (executes all tests in controls/):

inspec exec /path/to/profile

Local single test (doesn’t allow inputs or custom resources):

inspec exec /path/to/a_test.rb

Git via SSH:

inspec exec git@github.com:dev-sec/linux-baseline.git

Git via HTTPS (.git suffix is required):

inspec exec https://github.com/dev-sec/linux-baseline.git

Private Git via HTTPS (.git suffix is required):

inspec exec https://api_token@github.com/dev-sec/linux-baseline.git

Private Git via HTTPS and cached credentials (.git suffix is required):

git config credential.helper cache
git ls-remote https://github.com/dev-sec/linux-baseline.git
inspec exec https://github.com/dev-sec/linux-baseline.git

Web-hosted file (also supports .zip):

inspec exec https://webserver/linux-baseline.tar.gz

Web-hosted file with basic authentication (supports .zip):

inspec exec https://username:password@webserver/linux-baseline.tar.gz

Web-hosted signed profile:

inspec exec https://username:password@webserver/linux-baseline.iaf

habitat

Create a Chef Habitat package.

Syntax

This subcommand has the following syntax:

inspec habitat SUBCOMMAND

help

Describe available commands or one specific command.

Syntax

This subcommand has the following syntax:

inspec help [COMMAND]

init

Scaffold a new project.

Syntax

This subcommand has the following syntax:

inspec init TEMPLATE

export

Read the profile in path and generate a summary in the given format.

Syntax

This subcommand has the following syntax:

inspec export PATH

Options

This subcommand has the following additional options:

--what=WHAT
What to export: profile (default), readme, metadata.
--controls=one two three
For –what=profile, a list of controls to include. Other controls are ignored..
--format=FORMAT
The output format to use: json, raw, yaml. If valid format is not provided then it will use the default for the given ‘what’.
--legacy-export
--no-legacy-export
Run with legacy export.
-o
--output=OUTPUT
Save the created output to a path.
--profiles-path=PROFILES_PATH
Folder which contains referenced profiles.
--tags=one two three
For –what=profile, a list of tags to filter controls and include only those. Other controls are ignored.
--vendor-cache=VENDOR_CACHE
Use the given path for caching dependencies, (default: ~/.inspec/cache).

json

Read all tests in the path and generate a json summary.

Syntax

This subcommand has the following syntax:

inspec json PATH

Options

This subcommand has the following additional options:

--allow-unsigned-profiles
Allow InSpec to read unsigned profiles if mandatory profile signing is enabled. Defaults to false.

Chef InSpec 6 and greater has an optional setting that requires signed profiles. If you try to read an unsigned profile with this feature enabled, InSpec won’t read the profile and returns exit code 6. Use --allow-unsigned-profiles to read unsigned profiles if mandatory profile signing is enabled.

For more information, see Signed InSpec Profiles.

--controls=one two three
A list of controls to include. Ignore all other tests.
--legacy-export
--no-legacy-export
Run with legacy export.
-o
--output=OUTPUT
Save the created profile to a path.
--profiles-path=PROFILES_PATH
Folder which contains referenced profiles.
--tags=one two three
A list of tags that reference specific controls. Other controls are ignored.
--vendor-cache=VENDOR_CACHE
Use the given path for caching dependencies. (default: ~/.inspec/cache).

license

Subcommands for interacting with the Chef licensing system.

inspec license supports two subcommands, add and list.

license add

Add a Chef license.

Not applicable for users running a Chef Private Licensing Service.

Syntax

inspec license add

license list

Run license diagnostics and output the details of your current Chef license configuration.

Syntax

inspec license list

nothing

Does nothing.

Syntax

This subcommand has the following syntax:

inspec nothing

plugin

Install and manage Chef InSpec plugins.

Syntax

This subcommand has the following syntax:

inspec plugin SUBCOMMAND

schema

Print the json schema.

Syntax

This subcommand has the following syntax:

inspec schema NAME

Options

This subcommand has the following additional option:

--enhanced-outcomes
Includes enhanced outcome of controls in report data.

shell

Open an interactive debugging shell.

Syntax

This subcommand has the following syntax:

inspec shell

Options

This subcommand has the following additional options:

--audit-log-location=AUDIT_LOG_LOCATION
The directory that the audit log saves diagnostic log files to. You must enable audit logging to use this feature. See the Audit Log documentation for details.

Default: ~/.inspec/logs.

InSpec creates log files in the set directory using the following format: inspec-audit-TIMESTAMP-PID.log.

-b
--backend=BACKEND
Choose a backend: local, ssh, winrm, docker.
--bastion-host=BASTION_HOST
Specifies the bastion host if applicable.
--bastion-port=BASTION_PORT
Specifies the bastion port if applicable.
--bastion-user=BASTION_USER
Specifies the bastion user if applicable.
-c
--command=COMMAND
A single command string to run instead of launching the shell.
--command-timeout=SECONDS
Maximum seconds to allow a command to run.
--ca-trust-file=PATH_TO_CA_TRUST_FILE
Specify CA certificate required for SSL authentication (WinRM).
--client-cert=PATH_TO_CLIENT_CERTIFICATE
Specify client certificate required for SSL authentication (WinRM).
--client-key=PATH_TO_CLIENT_KEY
Specify client key required with client certificate for SSL authentication (WinRM).
--client-key-pass=CLIENT_CERT_PASSWORD
Specify client certificate password, if required for SSL authentication (WinRM).
--config=CONFIG
Read configuration from the JSON file (- reads from stdin).
--depends=one two three
A space-delimited list of local folders containing profiles whose libraries and resources will be loaded into the new shell.
--distinct-exit
--no-distinct-exit
Exit with code 100 if any tests fail and 101 if any are skipped, but none failed (default). If disabled, exit 0 on skips and 1 for failures.
--docker-url
Provides path to Docker API endpoint (Docker). Defaults to unix:///var/run/docker.sock on Unix systems and tcp://localhost:2375 on Windows.
--enable-password=ENABLE_PASSWORD
Password for enable mode on Cisco IOS devices.
--host=HOST
Specify a remote host which is tested.
--insecure
--no-insecure
Disable SSL verification on select targets.
--inspect
--no-inspect
Use verbose/debugging output for resources.
-i
--key-files=one two three
Login key or certificate file for a remote scan.
--password=PASSWORD
Login password for a remote scan, if required.
--path=PATH
Login path to use when connecting to the target (WinRM).
-p
--port=N
Specify the login port for a remote scan.
--podman-url
Provides the path to the Podman API endpoint. Defaults to unix:///run/user/$UID/podman/podman.sock for rootless container, unix:///run/podman/podman.sock for rootful container (for this you need to execute inspec as root user).
--proxy-command=PROXY_COMMAND
Specifies the command to use to connect to the server.
--reporter=one two:/output/file/path
Enable one or more output reporters: cli, documentation, html2, progress, json, json-min, json-rspec, junit2.
--self-signed
--no-self-signed
Allow remote scans with self-signed certificates (WinRM).
--shell
--no-shell
Run scans in a subshell. Only activates on Unix.
--shell-command=SHELL_COMMAND
Specify a particular shell to use.
--shell-options=SHELL_OPTIONS
Additional shell options.
--ssh-config-file=one two three
A list of paths to the SSH configuration file, for example: ~/.ssh/config or /etc/ssh/ssh_config.
--ssl
--no-ssl
Use SSL for transport layer encryption (WinRM).
--ssl-peer-fingerprint=SSL_PEER_FINGERPRINT
Specify SSL peer fingerprint in place of certificates for SSL authentication (WinRM).
--sudo
--no-sudo
Run scans with sudo. Only activates on Unix and non-root user.
--sudo-command=SUDO_COMMAND
Alternate command for sudo.
--sudo-options=SUDO_OPTIONS
Additional sudo options for a remote scan.
--sudo-password=SUDO_PASSWORD
Specify a sudo password, if it is required.
-t
--target=TARGET
Simple targeting option using URIs, e.g. ssh://user:pass@host:port.
--target-id=TARGET_ID
Provide a ID which will be included on reports.
--user=USER
The login user for a remote scan.
--winrm-basic-auth-only
--no-winrm-basic-auth-only
Whether to use basic authentication, defaults to false (WinRM).
--winrm-disable-sspi
--no-winrm-disable-sspi
Whether to use disable sspi authentication, defaults to false (WinRM).
--winrm-transport=WINRM_TRANSPORT
Specify which transport to use, defaults to negotiate (WinRM).
--enhanced-outcomes
Includes enhanced outcome of controls in report data.

supermarket

Supermarket commands.

Syntax

This subcommand has the following syntax:

inspec supermarket SUBCOMMAND ...

Options

This subcommand has additional options:

--supermarket_url
Specify the URL of a private Chef Supermarket.

vendor

Download all dependencies and generate a lockfile in a vendor directory.

Syntax

This subcommand has the following syntax:

inspec vendor PATH

Options

This subcommand has additional options:

--overwrite
--no-overwrite
Overwrite existing vendored dependencies and lockfiles.

version

Prints the version of this tool.

Syntax

This subcommand has the following syntax:

inspec version

Options

This subcommand has the following additional options:

--format=FORMAT

Edit this page on GitHub

Thank you for your feedback!

×









Search Results