inspec 1.0.0 → 1.35.1

data/docs/resources/os_env.md.erb

@@ -6,7 +6,7 @@ title: About the os_env Resource
 
 Use the `os_env` InSpec audit resource to test the environment variables for the platform on which the system is running.
 
-# Syntax
+## Syntax
 
 A `os_env` resource block declares an environment variable, and then declares its value:
 
@@ -20,37 +20,37 @@ where
 * `matcher` is a valid matcher for this resource
 
 
-# Matchers
+## Matchers
 
 This InSpec audit resource has the following matchers:
 
-## be
+### be
 
 <%= partial "/shared/matcher_be" %>
 
-## cmp
+### cmp
 
 <%= partial "/shared/matcher_cmp" %>
 
-## content
+### content
 
 The `content` matcher return the value of the environment variable:
 
     its('content') { should eq '/usr/local/bin:/usr/local/sbin:/usr/sbin:/usr/bin:/sbin' }
 
-## eq
+### eq
 
 <%= partial "/shared/matcher_eq" %>
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-## split
+### split
 
 The `split` splits the content with the `:` deliminator:
 
@@ -64,18 +64,18 @@ Use `-1` to test for cases where there is a trailing colon (`:`), such as `dir1:
 
     its('split') { should include ('-1') }
 
-# Examples
+## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-## Test the PATH environment variable
+### Test the PATH environment variable
 
     describe os_env('PATH') do
       its('split') { should_not include('') }
       its('split') { should_not include('.') }
     end
 
-## Test Habitat environment variables
+### Test Habitat environment variables
 
 Habitat uses the `os_env` resource to test environment variables. The environment variables are first defined in a whitespace array, after which each environment variable is tested:
 

data/docs/resources/package.md.erb

@@ -7,7 +7,7 @@ title: About the package Resource
 Use the `package` InSpec audit resource to test if the named package and/or package version is installed on the system.
 
 
-# Syntax
+## Syntax
 
 A `package` resource block declares a package and (optionally) a package version:
 
@@ -20,60 +20,67 @@ where
 * `('name')` must specify the name of a package, such as `'nginx'`
 * `be_installed` is a valid matcher for this resource
 
-# Matchers
+## Matchers
 
 This InSpec audit resource has the following matchers:
 
-## be
+### be
 
 <%= partial "/shared/matcher_be" %>
 
-## be_installed
+### be_held
+
+The `be_held` matcher tests if the named package is "held". On dpkg platforms, a "held" package
+will not be upgraded to a later version.
+
+    it { should be_held }
+
+### be_installed
 
 The `be_installed` matcher tests if the named package is installed on the system:
 
     it { should be_installed }
 
-## cmp
+### cmp
 
 <%= partial "/shared/matcher_cmp" %>
 
-## eq
+### eq
 
 <%= partial "/shared/matcher_eq" %>
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-## version
+### version
 
 The `version` matcher tests if the named package version is on the system:
 
     its('version') { should eq '1.2.3' }
 
-# Examples
+## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-## Test if nginx version 1.9.5 is installed
+### Test if nginx version 1.9.5 is installed
 
     describe package('nginx') do
       it { should be_installed }
-      its('version') { should eq 1.9.5 }
+      its('version') { should eq '1.9.5' }
     end
 
-## Test that a package is not installed
+### Test that a package is not installed
 
     describe package('some_package') do
       it { should_not be_installed }
     end
 
-## Test if telnet is installed
+### Test if telnet is installed
 
     describe package('telnetd') do
       it { should_not be_installed }
@@ -83,7 +90,7 @@ The following examples show how to use this InSpec audit resource.
       its('telnet') { should eq nil }
     end
 
-## Test if ClamAV (an antivirus engine) is installed and running
+### Test if ClamAV (an antivirus engine) is installed and running
 
     describe package('clamav') do
       it { should be_installed }
@@ -96,7 +103,13 @@ The following examples show how to use this InSpec audit resource.
       it { should_not be_running }
     end
 
-## Verify if Memcached is installed, enabled, and running
+### Verify if some_package is installed according to my_rpmdb
+
+   describe package('some_package', rpm_dbpath: '/var/lib/my_rpmdb') do
+     it { should be_installed }
+   end
+
+### Verify if Memcached is installed, enabled, and running
 
 Memcached is an in-memory key-value store that helps improve the performance of database-driven websites and can be installed, maintained, and tested using the `memcached` cookbook (maintained by Chef). The following example is from the `memcached` cookbook and shows how to use a combination of the `package`, `service`, and `port` InSpec audit resources to test if Memcached is installed, enabled, and running:
 

data/docs/resources/parse_config.md.erb

@@ -6,7 +6,7 @@ title: About the parse_config Resource
 
 Use the `parse_config` InSpec audit resource to test arbitrary configuration files.
 
-# Syntax
+## Syntax
 
 A `parse_config` resource block declares the location of the configuration setting to be tested, and then what value is to be tested. Because this resource relies on arbitrary configuration files, the test itself is often arbitrary and relies on custom Ruby code:
 
@@ -20,7 +20,7 @@ or:
 
     audit = command('/sbin/auditctl -l').stdout
       options = {
-        assignment_re: /^\s*([^:]*?)\s*:\s*(.*?)\s*$/,
+        assignment_regex: /^\s*([^:]*?)\s*:\s*(.*?)\s*$/,
         multiple_values: true
       }
 
@@ -35,57 +35,57 @@ where each test
 * May run a command to `stdout`, and then run the test against that output
 * May use options to define how configuration data is to be parsed
 
-# Matchers
+## Matchers
 
 This InSpec audit resource has the following matchers:
 
-## assignment_re
+### assignment_regex
 
-Use `assignment_re` to test a key value using a regular expression:
+Use `assignment_regex` to test a key value using a regular expression:
 
     'key = value'
 
 may be tested using the following regular expression, which determines assignment from key to value:
 
-    assignment_re: /^\s*([^=]*?)\s*=\s*(.*?)\s*$/
+    assignment_regex: /^\s*([^=]*?)\s*=\s*(.*?)\s*$/
 
-## be
+### be
 
 <%= partial "/shared/matcher_be" %>
 
-## cmp
+### cmp
 
 <%= partial "/shared/matcher_cmp" %>
 
-## comment_char
+### comment_char
 
 Use `comment_char` to test for comments in a configuration file:
 
     comment_char: '#'
 
-## eq
+### eq
 
 <%= partial "/shared/matcher_eq" %>
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## key_vals
+### key_values
 
-Use `key_vals` to test how many values a key contains:
+Use `key_values` to test how many values a key contains:
 
     key = a b c
 
 contains three values. To test that value to ensure it only contains one, use:
 
-    key_vals: 1
+    key_values: 1
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-## multiple_values
+### multiple_values
 
 Use `multiple_values` if the source file uses the same key multiple times. All values will be aggregated in an array:
 
@@ -105,7 +105,7 @@ To use plain key value mapping, use `multiple_values: false`:
     params['key'] = 'b'
     params['key2'] = 'c'
 
-## standalone_comments
+### standalone_comments
 
 Use `standalone_comments` to parse comments as a line, otherwise inline comments are allowed:
 
@@ -117,6 +117,6 @@ Use `standalone_comments: false`, to parse the following:
     'key = value # comment'
     params['key'] = 'value'
 
-# Examples
+## Examples
 
 None.

data/docs/resources/parse_config_file.md.erb

@@ -2,11 +2,11 @@
 title: About the parse_config_file Resource
 ---
 
-# parse_config_file
+# parse\_config\_file
 
 Use the `parse_config_file` InSpec audit resource to test arbitrary configuration files. It works in the same way as `parse_config`. Instead of using a command output, this resource works with files.
 
-# Syntax
+## Syntax
 
 A `parse_config_file` InSpec audit resource block declares the location of the configuration file to be tested, and then which settings in that file are to be tested.
 
@@ -17,7 +17,7 @@ A `parse_config_file` InSpec audit resource block declares the location of the c
 or:
 
     options = {
-      assignment_re: /^\s*([^:]*?)\s*:\s*(.*?)\s*$/,
+      assignment_regex: /^\s*([^:]*?)\s*:\s*(.*?)\s*$/,
       multiple_values: true
     }
 
@@ -32,69 +32,69 @@ where each test
 * May run a command to `stdout`, and then run the test against that output
 * May use options to define how configuration data is to be parsed
 
-# Options
+## Options
 
 This resource supports the following options for parsing configuration data. Use them in an `options` block stated outside of (and immediately before) the actual test:
 
     options = {
-        assignment_re: /^\s*([^:]*?)\s*:\s*(.*?)\s*$/,
+        assignment_regex: /^\s*([^:]*?)\s*:\s*(.*?)\s*$/,
         multiple_values: true
       }
     describe parse_config_file('path/to/file',  options) do
       its('setting') { should eq 1 }
     end
 
-# Matchers
+## Matchers
 
 This InSpec audit resource has the following matchers:
 
-## assignment_re
+### assignment_regex
 
-Use `assignment_re` to test a key value using a regular expression:
+Use `assignment_regex` to test a key value using a regular expression:
 
     'key = value'
 
 may be tested using the following regular expression, which determines assignment from key to value:
 
-    assignment_re: /^\s*([^=]*?)\s*=\s*(.*?)\s*$/
+    assignment_regex: /^\s*([^=]*?)\s*=\s*(.*?)\s*$/
 
-## be
+### be
 
 <%= partial "/shared/matcher_be" %>
 
-## cmp
+### cmp
 
 <%= partial "/shared/matcher_cmp" %>
 
-## comment_char
+### comment_char
 
 Use `comment_char` to test for comments in a configuration file:
 
     comment_char: '#'
 
-## eq
+### eq
 
 <%= partial "/shared/matcher_eq" %>
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## key_vals
+### key_values
 
-Use `key_vals` to test how many values a key contains:
+Use `key_values` to test how many values a key contains:
 
     key = a b c
 
 contains three values. To test that value to ensure it only contains one, use:
 
-    key_vals: 1
+    key_values: 1
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-## multiple_values
+### multiple_values
 
 Use `multiple_values` if the source file uses the same key multiple times. All values will be aggregated in an array:
 
@@ -114,7 +114,7 @@ To use plain key value mapping, use `multiple_values: false`:
     params['key'] = 'b'
     params['key2'] = 'c'
 
-## standalone_comments
+### standalone_comments
 
 Use `standalone_comments` to parse comments as a line, otherwise inline comments are allowed:
 
@@ -126,18 +126,24 @@ Use `standalone_comments: false`, to parse the following:
     'key = value # comment'
     params['key'] = 'value'
 
-# Examples
+## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-## Test a configuration setting
+### Test a configuration setting
 
     describe parse_config_file('/path/to/file.conf') do
      its('PARAM_X') { should eq 'Y' }
     end
 
-## Use options, and then test a configuration setting
+### Use options, and then test a configuration setting
 
     describe parse_config_file('/path/to/file.conf', { multiple_values: true }) do
      its('PARAM_X') { should include 'Y' }
     end
+
+## Test a file with an ini-like structure (such as a yum.conf)
+
+    describe parse_config_file('/path/to/yum.conf') do
+     its('main') { should include('gpgcheck' => '1') }
+    end

data/docs/resources/{etc_passwd.md.erb → passwd.md.erb}

@@ -18,7 +18,7 @@ These entries are defined as a colon-delimited row in the file, one row per user
 
     root:x:1234:5678:additional_info:/home/dir/:/bin/bash
 
-# Syntax
+## Syntax
 
 A `passwd` resource block declares one (or more) users and associated user information to be tested:
 
@@ -38,40 +38,40 @@ where
 * `filter` may take any of the following arguments: `count` (retrieves the number of entries), `lines` (provides raw `passwd` lines), and `params` (returns an array of maps for all entries)
 
 
-# Matchers
+## Matchers
 
 This InSpec audit resource has the following matchers:
 
-## be
+### be
 
 <%= partial "/shared/matcher_be" %>
 
-## cmp
+### cmp
 
 <%= partial "/shared/matcher_cmp" %>
 
-## eq
+### eq
 
 <%= partial "/shared/matcher_eq" %>
 
-## gids
+### gids
 
 The `gids` matcher tests if the group indentifiers in the test match group identifiers in `/etc/passwd`:
 
     its('gids') { should include 1234 }
     its('gids') { should cmp 0 }
 
-## homes
+### homes
 
 The `homes` matcher tests the absolute path to a user's home directory:
 
     its('home') { should eq '/' }
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## length
+### length
 
 The `length` matcher tests the length of a password that appears in `/etc/passwd`:
 
@@ -83,11 +83,11 @@ This matcher is best used in conjunction with filters. For example:
        its('length') { should_not be < 16 }
     end
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-## passwords
+### passwords
 
 The `passwords` matcher tests if passwords are
 
@@ -100,7 +100,7 @@ For example:
     its('passwords') { should eq ['x'] }
     its('passwords') { should cmp '*' }
 
-## shells
+### shells
 
 The `shells` matcher tests the absolute path of a shell (or command) to which a user has access:
 
@@ -112,7 +112,7 @@ or to find all users with the nologin shell:
       its('users') { should_not include 'my_login_user' }
     end
 
-## uids
+### uids
 
 The `uids` matcher tests if the user indentifiers in the test match user identifiers in `/etc/passwd`:
 
@@ -125,24 +125,24 @@ or:
       its('count') { should eq 1 }
     end
 
-## users
+### users
 
 The `users` matcher tests if the user names in the test match user names in `/etc/passwd`:
 
     its('users') { should eq ['root', 'www-data'] }
 
-# Examples
+## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-## Test usernames and UIDs
+### Test usernames and UIDs
 
     describe passwd do
       its('users') { should eq ['root', 'www-data'] }
       its('uids') { should eq [0, 33] }
     end
 
-## Select one user and test for multiple occurrences
+### Select one user and test for multiple occurrences
 
     describe passwd.uids(0) do
       its('users') { should cmp 'root' }

data/docs/resources/pip.md.erb

@@ -6,67 +6,67 @@ title: About the pip Resource
 
 Use the `pip` InSpec audit resource to test packages that are installed using the Python PIP installer.
 
-# Syntax
+## Syntax
 
 A `pip` resource block declares a package and (optionally) a package version:
 
-    describe pip('Jinja2') do
+    describe pip('package_name') do
       it { should be_installed }
     end
 
 where
 
-* `'Jinja2'` is the name of the package
-* `be_installed` tests to see if the `Jinja2` package is installed
+* `'package_name'` is the name of the package, such as `'Jinja2'`
+* `be_installed` tests to see if the package described above is installed
 
 
-# Matchers
+## Matchers
 
 This InSpec audit resource has the following matchers:
 
-## be
+### be
 
 <%= partial "/shared/matcher_be" %>
 
-## be_installed
+### be_installed
 
 The `be_installed` matcher tests if the named package is installed on the system:
 
     it { should be_installed }
 
-## cmp
+### cmp
 
 <%= partial "/shared/matcher_cmp" %>
 
-## eq
+### eq
 
 <%= partial "/shared/matcher_eq" %>
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-## version
+### version
 
 The `version` matcher tests if the named package version is on the system:
 
     its('version') { should eq '1.2.3' }
 
-# Examples
+## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-## Test if Jinja2 is installed on the system
+### Test if Jinja2 is installed on the system
 
     describe pip('Jinja2') do
       it { should be_installed }
     end
 
-## Test if Jinja2 2.8 is installed on the system
+### Test if Jinja2 2.8 is installed on the system
 
     describe pip('Jinja2') do
       it { should be_installed }