inspec 1.31.0 → 1.45.9

data/docs/resources/os.md.erb

@@ -6,45 +6,53 @@ title: About the os Resource
 
 Use the `os` InSpec audit resource to test the platform on which the system is running.
 
+<br>
+
 ## Syntax
 
 An `os` resource block declares the platform to be tested. The platform may specified via matcher or control block name. For example, using a matcher:
 
     describe os[:family] do
-      it { should eq 'platform_name' }
+      it { should eq 'platform_family_name' }
     end
 
-or using the block name:
-
-    describe os[:family_name] do
-      ...
-    end
+* `'platform_family_name'` (a string) is one of `aix`, `bsd`, `darwin`, `debian`, `hpux`, `linux`, `redhat`, `solaris`, `suse`,  `unix`, or `windows`
 
-* `'platform_name'` (a string) or `:family_name` (a symbol) is one of `aix`, `bsd`, `darwin`, `debian`, `hpux`, `linux`, `redhat`, `solaris`, `suse`,  `unix`, or `windows`
+The parameters available to `os` are:
 
-## Matchers
+* `:name` - the operating system name, such as `centos`
+* `:family` - the operating system family, such as `redhat`
+* `:release` - the version of the operating system, such as `7.3.1611`
+* `:arch` - the architecture of the operating system, such as `x86_64`
+<br>
 
-This InSpec audit resource has the following matchers:
+## Examples
 
-### be
+The following examples show how to use this InSpec audit resource.
 
-<%= partial "/shared/matcher_be" %>
+### Test for RedHat
 
-### cmp
+    describe os[:family] do
+      it { should eq 'redhat' }
+    end
 
-<%= partial "/shared/matcher_cmp" %>
+### Test for Ubuntu
 
-### eq
+    describe os[:family] do
+      it { should eq 'debian' }
+    end
 
-<%= partial "/shared/matcher_eq" %>
+### Test for Microsoft Windows
 
-### include
+    describe os[:family] do
+      it { should eq 'windows' }
+    end
 
-<%= partial "/shared/matcher_include" %>
+<br>
 
-### match
+## Matchers
 
-<%= partial "/shared/matcher_match" %>
+This InSpec audit resource has the following matchers. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
 
 ## os.family? Helpers
 
@@ -121,34 +129,12 @@ For example, both of the following tests should have the same result:
       end
     end
 
-    if os[:debian]
+    if os.debian?
       describe port(69) do
         its('processes') { should include 'in.tftpd' }
       end
-    elsif os[:redhat]
+    elsif os.redhat?
       describe port(69) do
         its('processes') { should include 'xinetd' }
       end
     end
-
-## Examples
-
-The following examples show how to use this InSpec audit resource.
-
-### Test for RedHat
-
-    describe os[:family] do
-      it { should eq 'redhat' }
-    end
-
-### Test for Ubuntu
-
-    describe os[:family] do
-      it { should eq 'debian' }
-    end
-
-### Test for Microsoft Windows
-
-    describe os[:family] do
-      it { should eq 'windows' }
-    end

data/docs/resources/os_env.md.erb

@@ -6,6 +6,8 @@ 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.
 
+<br>
+
 ## Syntax
 
 A `os_env` resource block declares an environment variable, and then declares its value:
@@ -19,50 +21,7 @@ where
 * `('VARIABLE')` must specify an environment variable, such as `PATH`
 * `matcher` is a valid matcher for this resource
 
-
-## Matchers
-
-This InSpec audit resource has the following matchers:
-
-### be
-
-<%= partial "/shared/matcher_be" %>
-
-### cmp
-
-<%= partial "/shared/matcher_cmp" %>
-
-### 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
-
-<%= partial "/shared/matcher_eq" %>
-
-### include
-
-<%= partial "/shared/matcher_include" %>
-
-### match
-
-<%= partial "/shared/matcher_match" %>
-
-### split
-
-The `split` splits the content with the `:` deliminator:
-
-    its('split') { should include (':') }
-
-or:
-
-    its('split') { should_not include ('.') }
-
-Use `-1` to test for cases where there is a trailing colon (`:`), such as `dir1::dir2:`:
-
-    its('split') { should include ('-1') }
+<br>
 
 ## Examples
 
@@ -96,3 +55,23 @@ Habitat uses the `os_env` resource to test environment variables. The environmen
         its('content') { should eq nil }
       end
     end
+
+<br>
+
+## Matchers
+
+This InSpec audit resource has the following matchers. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### 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' }
+
+### split
+
+The `split` matcher splits the value of the environment variable with the `:` deliminator (use the `;` deliminator if Windows):
+
+    its('split') { should include ('/usr/bin') }
+
+Note: the `split` matcher returns an array including `""` for cases where there is a trailing colon (`:`), such as `dir1::dir2:`

data/docs/resources/package.md.erb

@@ -6,6 +6,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.
 
+<br>
 
 ## Syntax
 
@@ -20,47 +21,13 @@ where
 * `('name')` must specify the name of a package, such as `'nginx'`
 * `be_installed` is a valid matcher for this resource
 
-## Matchers
-
-This InSpec audit resource has the following matchers:
-
-### be
-
-<%= partial "/shared/matcher_be" %>
-
-### be_installed
-
-The `be_installed` matcher tests if the named package is installed on the system:
-
-    it { should be_installed }
-
-### cmp
-
-<%= partial "/shared/matcher_cmp" %>
-
-### eq
-
-<%= partial "/shared/matcher_eq" %>
-
-### include
-
-<%= partial "/shared/matcher_include" %>
-
-### match
-
-<%= partial "/shared/matcher_match" %>
-
-### version
-
-The `version` matcher tests if the named package version is on the system:
-
-    its('version') { should eq '1.2.3' }
+<br>
 
 ## 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 }
@@ -119,3 +86,34 @@ Memcached is an in-memory key-value store that helps improve the performance of
     describe port(11_211) do
       it { should be_listening }
     end
+
+<br>
+
+## Matchers
+
+This InSpec audit resource has the following matchers. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### 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 }
+
+### version
+
+The `version` matcher tests if the named package version is on the system:
+
+    its('version') { should eq '1.2.3' }
+
+You can also use the `cmp OPERATOR` matcher to perform comparisions using the version attribute:
+
+    its('version') { should cmp >= '7.35.0-1ubuntu3.10' }
+
+`cmp` understands version numbers using Gem::Version, and can use the operators `==, <, <=, >=, and >`.  It will compare versions by each segment, not as a string - so '7.4' is smaller than '7.30', for example.  

data/docs/resources/parse_config.md.erb

@@ -6,6 +6,8 @@ title: About the parse_config Resource
 
 Use the `parse_config` InSpec audit resource to test arbitrary configuration files.
 
+<br>
+
 ## 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:
@@ -35,9 +37,11 @@ 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
 
+<br>
+
 ## Matchers
 
-This InSpec audit resource has the following matchers:
+This InSpec audit resource has the following matchers. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
 
 ### assignment_regex
 
@@ -49,28 +53,12 @@ may be tested using the following regular expression, which determines assignmen
 
     assignment_regex: /^\s*([^=]*?)\s*=\s*(.*?)\s*$/
 
-### be
-
-<%= partial "/shared/matcher_be" %>
-
-### cmp
-
-<%= partial "/shared/matcher_cmp" %>
-
 ### comment_char
 
 Use `comment_char` to test for comments in a configuration file:
 
     comment_char: '#'
 
-### eq
-
-<%= partial "/shared/matcher_eq" %>
-
-### include
-
-<%= partial "/shared/matcher_include" %>
-
 ### key_values
 
 Use `key_values` to test how many values a key contains:
@@ -81,10 +69,6 @@ contains three values. To test that value to ensure it only contains one, use:
 
     key_values: 1
 
-### match
-
-<%= partial "/shared/matcher_match" %>
-
 ### multiple_values
 
 Use `multiple_values` if the source file uses the same key multiple times. All values will be aggregated in an array:
@@ -116,7 +100,3 @@ Use `standalone_comments: false`, to parse the following:
 
     'key = value # comment'
     params['key'] = 'value'
-
-## Examples
-
-None.

data/docs/resources/parse_config_file.md.erb

@@ -6,6 +6,8 @@ title: About the parse_config_file Resource
 
 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.
 
+<br>
+
 ## 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.
@@ -32,6 +34,8 @@ 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
 
+<br>
+
 ## 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:
@@ -44,9 +48,35 @@ This resource supports the following options for parsing configuration data. Use
       its('setting') { should eq 1 }
     end
 
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### 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
+
+    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
+
+<br>
+
 ## Matchers
 
-This InSpec audit resource has the following matchers:
+This InSpec audit resource has the following matchers. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
 
 ### assignment_regex
 
@@ -58,28 +88,12 @@ may be tested using the following regular expression, which determines assignmen
 
     assignment_regex: /^\s*([^=]*?)\s*=\s*(.*?)\s*$/
 
-### be
-
-<%= partial "/shared/matcher_be" %>
-
-### cmp
-
-<%= partial "/shared/matcher_cmp" %>
-
 ### comment_char
 
 Use `comment_char` to test for comments in a configuration file:
 
     comment_char: '#'
 
-### eq
-
-<%= partial "/shared/matcher_eq" %>
-
-### include
-
-<%= partial "/shared/matcher_include" %>
-
 ### key_values
 
 Use `key_values` to test how many values a key contains:
@@ -90,10 +104,6 @@ contains three values. To test that value to ensure it only contains one, use:
 
     key_values: 1
 
-### match
-
-<%= partial "/shared/matcher_match" %>
-
 ### multiple_values
 
 Use `multiple_values` if the source file uses the same key multiple times. All values will be aggregated in an array:
@@ -125,25 +135,3 @@ Use `standalone_comments: false`, to parse the following:
 
     'key = value # comment'
     params['key'] = 'value'
-
-## Examples
-
-The following examples show how to use this InSpec audit resource.
-
-### 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
-
-    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,6 +18,8 @@ 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
 
+<br>
+
 ## Syntax
 
 A `passwd` resource block declares one (or more) users and associated user information to be tested:
@@ -37,22 +39,36 @@ where
 * `filter` one (or more) arguments, for example: `passwd.users(/name/)` used to define filtering
 * `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)
 
+<br>
 
-## Matchers
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test usernames and UIDs
 
-This InSpec audit resource has the following matchers:
+    describe passwd do
+      its('users') { should eq ['root', 'www-data'] }
+      its('uids') { should eq [0, 33] }
+    end
 
-### be
+### Select one user and test for multiple occurrences
 
-<%= partial "/shared/matcher_be" %>
+    describe passwd.uids(0) do
+      its('users') { should cmp 'root' }
+      its('count') { should eq 1 }
+    end
 
-### cmp
+    describe passwd.filter(user: 'www-data') do
+      its('uids') { should cmp 33 }
+      its('count') { should eq 1 }
+    end
 
-<%= partial "/shared/matcher_cmp" %>
+<br>
 
-### eq
+## Matchers
 
-<%= partial "/shared/matcher_eq" %>
+This InSpec audit resource has the following matchers. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
 
 ### gids
 
@@ -67,10 +83,6 @@ The `homes` matcher tests the absolute path to a user's home directory:
 
     its('home') { should eq '/' }
 
-### include
-
-<%= partial "/shared/matcher_include" %>
-
 ### length
 
 The `length` matcher tests the length of a password that appears in `/etc/passwd`:
@@ -83,10 +95,6 @@ This matcher is best used in conjunction with filters. For example:
        its('length') { should_not be < 16 }
     end
 
-### match
-
-<%= partial "/shared/matcher_match" %>
-
 ### passwords
 
 The `passwords` matcher tests if passwords are
@@ -130,26 +138,3 @@ or:
 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
-
-The following examples show how to use this InSpec audit resource.
-
-### 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
-
-    describe passwd.uids(0) do
-      its('users') { should cmp 'root' }
-      its('count') { should eq 1 }
-    end
-
-    describe passwd.filter(user: 'www-data') do
-      its('uids') { should cmp 33 }
-      its('count') { should eq 1 }
-    end

data/docs/resources/pip.md.erb

@@ -6,6 +6,8 @@ title: About the pip Resource
 
 Use the `pip` InSpec audit resource to test packages that are installed using the Python PIP installer.
 
+<br>
+
 ## Syntax
 
 A `pip` resource block declares a package and (optionally) a package version:
@@ -19,56 +21,39 @@ where
 * `'package_name'` is the name of the package, such as `'Jinja2'`
 * `be_installed` tests to see if the package described above is installed
 
+<br>
 
-## Matchers
-
-This InSpec audit resource has the following matchers:
-
-### be
-
-<%= partial "/shared/matcher_be" %>
+## Examples
 
-### be_installed
+The following examples show how to use this InSpec audit resource.
 
-The `be_installed` matcher tests if the named package is installed on the system:
+### Test if Jinja2 is installed on the system
 
-    it { should be_installed }
+    describe pip('Jinja2') do
+      it { should be_installed }
+    end
 
-### cmp
+### Test if Jinja2 2.8 is installed on the system
 
-<%= partial "/shared/matcher_cmp" %>
+    describe pip('Jinja2') do
+      it { should be_installed }
+      its('version') { should eq '2.8' }
+    end
 
-### eq
+<br>
 
-<%= partial "/shared/matcher_eq" %>
+## Matchers
 
-### include
+This InSpec audit resource has the following matchers. For a full list of available matchers please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
 
-<%= partial "/shared/matcher_include" %>
+### be_installed
 
-### match
+The `be_installed` matcher tests if the named package is installed on the system:
 
-<%= partial "/shared/matcher_match" %>
+    it { should be_installed }
 
 ### version
 
 The `version` matcher tests if the named package version is on the system:
 
     its('version') { should eq '1.2.3' }
-
-## Examples
-
-The following examples show how to use this InSpec audit resource.
-
-### 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
-
-    describe pip('Jinja2') do
-      it { should be_installed }
-      its('version') { should eq '2.8' }
-    end