inspec 1.0.0.beta2 → 1.0.0.beta3

data/docs/resources/csv.md.erb

@@ -0,0 +1,62 @@
+---
+title: About the csv Resource
+---
+
+# csv
+
+Use the `csv` InSpec audit resource to test configuration data in a CSV file.
+
+# Syntax
+
+A `csv` resource block declares the configuration data to be tested:
+
+    describe csv('file') do
+      its('name') { should eq 'foo' }
+    end
+
+where
+
+* `'file'` is the path to a CSV file
+* `name` is a configuration setting in a CSV file
+* `should eq 'foo'` tests a value of `name` as read from a CSV file versus the value declared in the test
+
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+## name
+
+The `name` matcher tests the value of `name` as read from a CSV file versus the value declared in the test:
+
+    its('name') { should eq 'foo' }
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test a CSV file
+
+    describe csv('some_file.csv') do
+      its('setting') { should eq 1 }
+    end

data/docs/resources/directory.md.erb

@@ -0,0 +1,43 @@
+---
+title: About the directory Resource
+---
+
+# directory
+
+Use the `directory` InSpec audit resource to test if the file type is a directory. This is equivalent to using the `file` resource and the `be_directory` matcher, but provides a simpler and more direct way to test directories. All of the matchers available to `file` may be used with `directory`.
+
+# Syntax
+
+A `directory` resource block declares the location of the directory to be tested, and then one (or more) matchers:
+
+    describe directory('path') do
+      it { should MATCHER 'value' }
+    end
+
+# Matchers
+
+This resource may use any of the matchers available to the `file` resource that may be useful when testing a directory.
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+# Examples
+
+None.

data/docs/resources/etc_group.md.erb

@@ -0,0 +1,116 @@
+---
+title: About the etc_group Resource
+---
+
+# etc_group
+
+Use the `etc_group` InSpec audit resource to test groups that are defined on Linux and Unix platforms. The `/etc/group` file stores details about each group---group name, password, group identifier, along with a comma-separate list of users that belong to the group.
+
+# Syntax
+
+A `etc_group` resource block declares a collection of properties to be tested:
+
+    describe etc_group('path') do
+      its('matcher') { should eq 'some_value' }
+    end
+
+or:
+
+    describe etc_group.where(item: 'value', item: 'value') do
+      its('gids') { should_not contain_duplicates }
+      its('groups') { should include 'user_name' }
+      its('users') { should include 'user_name' }
+    end
+
+where
+
+* `('path')` is the non-default path to the `inetd.conf` file
+* `.where()` may specify a specific item and value, to which the matchers are compared
+* `'gids'`, `'groups'`, and `'users'` are valid matchers for this resource
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## gids
+
+The `gids` matcher tests if the named group identifier is present or if it contains duplicates:
+
+    its('gids') { should_not contain_duplicates }
+
+## groups
+
+The `groups` matcher tests all groups for the named user:
+
+    its('groups') { should include 'my_group' }
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+## users
+
+The `users` matcher tests all groups for the named user:
+
+    its('users') { should include 'my_user' }
+
+## where
+
+The `where` matcher allows the test to be focused to one (or more) specific items:
+
+    etc_group.where(item: 'value', item: 'value')
+
+where `item` may be one (or more) of:
+
+* `name: 'name'`
+* `group_name: 'group_name'`
+* `password: 'password'`
+* `gid: 'gid'`
+* `group_id: 'gid'`
+* `users: 'user_name'`
+* `members: 'member_name'`
+
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test group identifiers (GIDs) for duplicates
+
+    describe etc_group do
+      its('gids') { should_not contain_duplicates }
+    end
+
+## Test all groups to see if a specific user belongs to one (or more) groups
+
+    describe etc_group do
+      its('groups') { should include 'my_group' }
+    end
+
+## Test all groups for a specific user name
+
+    describe etc_group do
+      its('users') { should include 'my_user' }
+    end
+
+## Filter a list of groups for a specific user
+
+    describe etc_group.where(name: 'my_group') do
+      its('users') { should include 'my_user' }
+    end

data/docs/resources/etc_passwd.md.erb

@@ -0,0 +1,155 @@
+---
+title: About the passwd Resource
+---
+
+# 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
+
+# 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)
+
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## 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 '/' }
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## 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
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+## 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'] }
+
+# 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/etc_shadow.md.erb

@@ -0,0 +1,149 @@
+---
+title: About the shadow Resource
+---
+
+# shadow
+
+Use the `shadow` InSpec audit resource to test the contents of `/etc/shadow`, which contains password details that are only readable by the `root` user. The format for `/etc/shadow` includes:
+
+* A username
+* The password for that user (on newer systems passwords should be stored in `/etc/shadow` )
+* The last time a password was changed
+* The minimum number of days a password must exist, before it may be changed
+* The maximum number of days after which a password must be changed
+* The number of days a user is warned about an expiring password
+* The number of days a user must be inactive before the user account is disabled
+* The number of days a user account has been disabled
+
+These entries are defined as a colon-delimited row in the file, one row per user:
+
+    dannos:Gb7crrO5CDF.:10063:0:99999:7:::
+
+# Syntax
+
+A `shadow` resource block declares one (or more) users and associated user information to be tested:
+
+    describe shadow do
+      its('users') { should_not include 'forbidden_user' }
+    end
+
+or with a filter:
+
+    describe shadow.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)
+
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## count
+
+The `count` matcher tests the number of times the named user appears in `/etc/shadow`:
+
+    its('count') { should eq 1 }
+
+TThis matcher is best used in conjunction with filters. For example:
+
+    describe shadow.users('dannos') do
+       its('count') { should eq 1 }
+    end
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## expiry_dates
+
+The `expiry_dates` matcher tests the number of days a user account has been disabled:
+
+    its('expiry_dates') { should eq '' }
+
+## inactive_days
+
+The `inactive_days` matcher tests the number of days a user must be inactive before the user account is disabled:
+
+    its('inactive_days') { should eq '' }
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## last_changes
+
+The `last_changes` matcher tests the last time a password was changed:
+
+    its('last_changes') { should eq '' }
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+## max_days
+
+The `max_days` matcher tests the maximum number of days after which a password must be changed:
+
+    its('max_days') { should eq 90 }
+
+## min_days
+
+The `min_days` matcher tests the minimum number of days a password must exist, before it may be changed:
+
+    its('min_days') { should eq 0 }
+
+## 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 '*' }
+
+## users
+
+The `users` matcher tests if the user name exists `/etc/shadow`:
+
+    its('users') { should eq 'root' }
+
+## warn_days
+
+The `warn_days` matcher tests the number of days a user is warned about an expiring password:
+
+    its('warn_days') { should eq 7 }
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test for a forbidden user
+
+    describe shadow do
+      its('users') { should_not include 'forbidden_user' }
+    end
+
+## Test that a user appears one time
+
+    describe shadow.users('bin') do
+      its('passwords') { should cmp 'x' }
+      its('count') { should eq 1 }
+    end