Project: Chef InSpec (Provisioning / Security & Compliance)
File: command.md

+++ title = "command resource" draft = false gh_repo = "inspec" platform = "os" [menu] [menu.inspec] title = "command" identifier = "inspec/resources/os/command.md command resource" parent = "inspec/resources/os" +++ Use the `command` Chef InSpec audit resource to test an arbitrary command that is run on the system. {{< readfile file="content/inspec/reusable/md/inspec_installation.md" >}} This resource first became available in v1.0.0 of InSpec. A `command` resource block declares a command to be run, one (or more) expected values, and the location to which that output is sent: describe command('command') do it { should exist } its('property') { should eq 'value' } end where `'command'` must specify a command to be run `'property'` is one of `exit_status`, `stderr`, or `stdout` `'output'` tests the output of the command run on the system versus the output value stated in the test The following examples show how to use this Chef InSpec audit resource. The `exit_status` property tests the exit status for the command: its('exit_status') { should eq 123 } The `stderr` property tests results of the command as returned in standard error (stderr): its('stderr') { should eq 'error' } The `stdout` property tests results of the command as returned in standard output (stdout). The following example shows matching output using a regular expression: describe command('echo 1') do its('stdout') { should match (/[0-9]/) } end describe command('echo hello') do its('stdout') { should eq "hello\n" } its('stderr') { should eq '' } its('exit_status') { should eq 0 } end describe command('>&2 echo error') do its('stdout') { should eq '' } its('stderr') { should eq "error\n" } its('exit_status') { should eq 0 } end describe command('exit 123') do its('stdout') { should eq '' } its('stderr') { should eq '' } its('exit_status') { should eq 123 } end describe command('/bin/sh').exist? do it { should eq true } end describe command('this is not existing').exist? do it { should eq false } end describe command('psql -V') do its('stdout') { should eq '/RC/' } its('stdout') { should_not eq '/DEVEL/' } its('stdout') { should_not eq '/BETA/' } end The following example shows how to use the `file` audit resource to verify if the `ntp.conf` and `leap-seconds` files are present, and then the `command` resource to verify if NTP is installed and running: describe file('/etc/ntp.conf') do it { should be_file } end describe

do it { should be_file } end describe command('pgrep ntp') do its('exit_status') { should eq 0 } end Wix includes several tools -- such as `candle` (preprocesses and compiles source files into object files), `light` (links and binds object files to an installer database), and `heat` (harvests files from various input formats). The following example uses a whitespace array and the `file` audit resource to verify if these three tools are present: %w( candle.exe heat.exe light.exe ).each do |utility| describe file("C:/wix/##{utility}") do it { should be_file } end end On target platforms that support the feature, the command resource takes an optional `timeout:` parameter which specifies how long the command may run in seconds before erroring out and failing the control. ```ruby describe command("find / -owner badguy", timeout: 300) do its("stdout") { should be_empty } end ``` This example would run the `find` command for up to 300 seconds, then give up and fail the control if it exceeded that time. Aside from setting the value on a per-resource basis, you may also use the `--command-timeout` CLI option to globally set a command timeout. The CLI option takes precedence over any per-resource `timeout:` options. Currently supported target platforms include: Local Unix-like OSes, including macOS SSH targets Windows targets via WinRM Any target platforms not listed are not supported at this time. On unsupported platforms, the timeout value is ignored and the command will run indefinitely. By default the command that is ran is shown in the Chef InSpec output. This can be problematic if the command contains sensitive arguments such as a password. These sensitive parts can be redacted by passing in `redact_regex` and a regular expression to redact. Optionally, you can use 2 capture groups to fine tune what is redacted. The following examples show how to use `redact_regex`: describe command('myapp -p secretpassword -d noredact', redact_regex: /-p .* -d/) do its('exit_status') { should cmp 0 } end Command: `myapp REDACTED no_redact` exit_status should cmp == 0 describe command('myapp -p secretpassword -d noredact', redact_regex: /(-p ).*( -d)/) do its('exit_status') { should cmp 0 } end Command: `myapp -p REDACTED -d no_redact` exit_status should cmp == 0 For more info/help on regular expressions, we recommend {{< readfile file="content/inspec/reusable/md/inspecmatcherslink.md" >}} This resource has the following special matchers. The `exist` matcher tests if a command may be run on the system: it { should exist }