inspec-core 2.1.67

data/docs/resources/packages.md.erb

@@ -0,0 +1,67 @@
+---
+title: About the packages Resource
+platform: linux
+---
+
+# packages
+
+Use the `packages` InSpec audit resource to test the properties of multiple packages on the system.
+
+<br>
+
+## Syntax
+
+A `packages` resource block declares a regular expression search to select packages
+
+    describe packages(/name/) do
+      its('statuses') { should cmp 'installed' }
+    end
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Verify that no `xserver` packages are installed
+
+    describe package(/xserver/) do
+      its('statuses') { should_not cmp 'installed' }
+    end
+
+### Verify all `openssl` packages match a certain version
+
+    describe package(/openssl/) do
+      its('versions') { should cmp '1.0.1e-42.el7' }
+    end
+
+### Verify that both the `i686` and `x86_64` versions of `libgcc` are installed
+
+    describe package(/libgcc/) do
+      its('architectures') { should include 'x86_64' }
+      its('architectures') { should include 'i686' }
+    end
+
+<br>
+
+## Matchers
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### statuses
+
+The `statuses` matcher tests if packages are installed on the system
+
+    its('statuses') { should cmp 'installed' }
+
+### versions
+
+The `versions` matcher tests the versions of the packages installed on the system
+
+    its('versions') { should cmp '3.4.0.2-4.el7' }
+
+### architectures
+
+The `architectures` matcher tests the architecture of packages installed on the system
+
+    its('architectures') { should include 'i686' }

data/docs/resources/parse_config.md.erb

@@ -0,0 +1,103 @@
+---
+title: About the parse_config Resource
+platform: os
+---
+
+# parse_config
+
+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:
+
+    output = command('some-command').stdout
+
+    describe parse_config(output, { data_config_option: value } ) do
+      its('setting') { should eq 1 }
+    end
+
+or:
+
+    audit = command('/sbin/auditctl -l').stdout
+      options = {
+        assignment_regex: /^\s*([^:]*?)\s*:\s*(.*?)\s*$/,
+        multiple_values: true
+      }
+
+    describe parse_config(audit, options) do
+      its('setting') { should eq 1 }
+    end
+
+where each test
+
+* Must declare the location of the configuration file to be tested
+* Must declare one (or more) settings to be tested
+* 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
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### assignment_regex
+
+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_regex: /^\s*([^=]*?)\s*=\s*(.*?)\s*$/
+
+### comment_char
+
+Use `comment_char` to test for comments in a configuration file:
+
+    comment_char: '#'
+
+### key_values
+
+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_values: 1
+
+### multiple_values
+
+Use `multiple_values` if the source file uses the same key multiple times. All values will be aggregated in an array:
+
+    # # file structure:
+    # key = a
+    # key = b
+    # key2 = c
+    params['key'] = ['a', 'b']
+    params['key2'] = ['c']
+
+To use plain key value mapping, use `multiple_values: false`:
+
+    # # file structure:
+    # key = a
+    # key = b
+    # key2 = c
+    params['key'] = 'b'
+    params['key2'] = 'c'
+
+### standalone_comments
+
+Use `standalone_comments` to parse comments as a line, otherwise inline comments are allowed:
+
+    'key = value # comment'
+    params['key'] = 'value # comment'
+
+Use `standalone_comments: false`, to parse the following:
+
+    'key = value # comment'
+    params['key'] = 'value'

data/docs/resources/parse_config_file.md.erb

@@ -0,0 +1,138 @@
+---
+title: About the parse_config_file Resource
+platform: os
+---
+
+# 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.
+
+<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.
+
+    describe parse_config_file('/path/to/file', { data_config_option: value } ) do
+      its('setting') { should eq 1 }
+    end
+
+or:
+
+    options = {
+      assignment_regex: /^\s*([^:]*?)\s*:\s*(.*?)\s*$/,
+      multiple_values: true
+    }
+
+    describe parse_config_file('path/to/file', options) do
+      its('setting') { should eq 1 }
+    end
+
+where each test
+
+* Must declare the location of the configuration file to be tested
+* Must declare one (or more) settings to be tested
+* 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:
+
+    options = {
+        assignment_regex: /^\s*([^:]*?)\s*:\s*(.*?)\s*$/,
+        multiple_values: true
+      }
+    describe parse_config_file('path/to/file',  options) do
+      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
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### assignment_regex
+
+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_regex: /^\s*([^=]*?)\s*=\s*(.*?)\s*$/
+
+### comment_char
+
+Use `comment_char` to test for comments in a configuration file:
+
+    comment_char: '#'
+
+### key_values
+
+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_values: 1
+
+### multiple_values
+
+Use `multiple_values` if the source file uses the same key multiple times. All values will be aggregated in an array:
+
+    # # file structure:
+    # key = a
+    # key = b
+    # key2 = c
+    params['key'] = ['a', 'b']
+    params['key2'] = ['c']
+
+To use plain key value mapping, use `multiple_values: false`:
+
+    # # file structure:
+    # key = a
+    # key = b
+    # key2 = c
+    params['key'] = 'b'
+    params['key2'] = 'c'
+
+### standalone_comments
+
+Use `standalone_comments` to parse comments as a line, otherwise inline comments are allowed:
+
+    'key = value # comment'
+    params['key'] = 'value # comment'
+
+Use `standalone_comments: false`, to parse the following:
+
+    'key = value # comment'
+    params['key'] = 'value'

data/docs/resources/passwd.md.erb

@@ -0,0 +1,141 @@
+---
+title: About the passwd Resource
+platform: linux
+---
+
+# passwd
+
+Use the `passwd` InSpec audit resource to test the contents of `/etc/passwd`, which contains the following information for users that may log into the system and/or as users that own running processes. The format for `/etc/passwd` includes:
+
+* A username
+* The password for that user (on newer systems passwords should be stored in `/etc/shadow` )
+* The user identifier (UID) assigned to that user
+* The group identifier (GID) assigned to that user
+* Additional information about that user
+* That user's home directory
+* That user's default command shell
+
+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:
+
+    describe passwd do
+      its('users') { should_not include 'forbidden_user' }
+    end
+
+    describe passwd.uid(filter) do
+      its('users') { should cmp 'root' }
+      its('count') { should eq 1 }
+    end
+
+where
+
+* `homes`, `gids`, `passwords`, `shells`, `uids`, and `users` are valid accessors for `passwd`
+* `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>
+
+## 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.where { user == 'www-data' } do
+      its('uids') { should cmp 33 }
+      its('count') { should eq 1 }
+    end
+
+<br>
+
+## Matchers
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### 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
+
+The `homes` matcher tests the absolute path to a user's home directory:
+
+    its('home') { should eq '/' }
+
+### length
+
+The `length` matcher tests the length of a password that appears in `/etc/passwd`:
+
+    its('length') { should be <= 32 }
+
+This matcher is best used in conjunction with filters. For example:
+
+    describe passwd.users('highlander') do
+       its('length') { should_not be < 16 }
+    end
+
+### passwords
+
+The `passwords` matcher tests if passwords are
+
+* Encrypted
+* Have direct logins disabled, as indicated by an asterisk (`*`)
+* In the `/etc/shadow` file, as indicated by the letter x (`x`)
+
+For example:
+
+    its('passwords') { should eq ['x'] }
+    its('passwords') { should cmp '*' }
+
+### shells
+
+The `shells` matcher tests the absolute path of a shell (or command) to which a user has access:
+
+    its('shells') { should_not include 'user' }
+
+or to find all users with the nologin shell:
+
+    describe passwd.shells(/nologin/) do
+      its('users') { should_not include 'my_login_user' }
+    end
+
+### uids
+
+The `uids` matcher tests if the user indentifiers in the test match user identifiers in `/etc/passwd`:
+
+    its('uids') { should eq ['1234', '1235'] }
+
+or:
+
+    describe passwd.uids(0) do
+      its('users') { should cmp 'root' }
+      its('count') { should eq 1 }
+    end
+
+### 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'] }