inspec 1.0.0.beta2 → 1.0.0.beta3

data/docs/resources/user.md.erb

@@ -0,0 +1,154 @@
+---
+title: About the user Resource
+---
+
+# user
+
+Use the `user` InSpec audit resource to test user profiles for a single, known/expected local user, including the groups to which that user belongs, the frequency of required password changes, and the directory paths to home and shell.
+
+# Syntax
+
+A `user` resource block declares a user name, and then one (or more) matchers:
+
+    describe user('root') do
+      it { should exist }
+      its('uid') { should eq 1234 }
+      its('gid') { should eq 1234 }
+      its('group') { should eq 'root' }
+      its('groups') { should eq ['root', 'other']}
+      its('home') { should eq '/root' }
+      its('shell') { should eq '/bin/bash' }
+      its('mindays') { should eq 0 }
+      its('maxdays') { should eq 90 }
+      its('warndays') { should eq 8 }
+    end
+
+where
+
+* `('root')` is the user to be tested
+* `it { should exist }` tests if the user exists
+* `gid`, `group`, `groups`, `home`, `maxdays`, `mindays`, `shell`, `uid`, and `warndays` 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" %>
+
+## exist
+
+The `exist` matcher tests if the named user exists:
+
+    it { should exist }
+
+## gid
+
+The `gid` matcher tests the group identifier:
+
+    its('gid') { should eq 1234 } }
+
+where `1234` represents the user identifier.
+
+## group
+
+The `group` matcher tests the group to which the user belongs:
+
+    its('group') { should eq 'root' }
+
+where `root` represents the group.
+
+## groups
+
+The `groups` matcher tests two (or more) groups to which the user belongs:
+
+    its('groups') { should eq ['root', 'other']}
+
+## home
+
+The `home` matcher tests the home directory path for the user:
+
+    its('home') { should eq '/root' }
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+## maxdays
+
+The `maxdays` matcher tests the maximum number of days between password changes:
+
+    its('maxdays') { should eq 99 }
+
+where `99` represents the maximum number of days.
+
+## mindays
+
+The `mindays` matcher tests the minimum number of days between password changes:
+
+    its('mindays') { should eq 0 }
+
+where `0` represents the maximum number of days.
+
+## shell
+
+The `shell` matcher tests the path to the default shell for the user:
+
+    its('shell') { should eq '/bin/bash' }
+
+## uid
+
+The `uid` matcher tests the user identifier:
+
+    its('uid') { should eq 1234 } }
+
+where `1234` represents the user identifier.
+
+## warndays
+
+The `warndays` matcher tests the number of days a user is warned before a password must be changed:
+
+    its('warndays') { should eq 5 }
+
+where `5` represents the number of days a user is warned.
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Verify available users for the MySQL server
+
+    describe user('root') do
+      it { should exist }
+      it { should belong_to_group 'root' }
+      its('uid') { should eq 0 }
+      its('groups') { should eq ['root'] }
+    end
+
+    describe user('mysql') do
+     it { should_not exist }
+    end
+
+## Test users on multiple platforms
+
+The `nginx` user is typically `www-data`, but on CentOS it's `nginx`. The following example shows how to test for the `nginx` user with a single test, but accounting for all platforms:
+
+    web_user = 'www-data'
+    web_user = 'nginx' if os[:family] == 'centos'
+
+    describe user(web_user) do
+      it { should exist }
+    end

data/docs/resources/users.md.erb

@@ -0,0 +1,140 @@
+---
+title: About the users Resource
+---
+
+# users
+
+Use the `users` InSpec audit resource to look up all local users available on the system, and then test specific properties of those users. This resource does not return information about users that may be located on other systems, such as LDAP or Active Directory.
+
+# Syntax
+
+A `users` resource block declares a user name, and then one (or more) matchers:
+
+    describe users.where(uid: 0).entries do
+      it { should eq ['root'] }
+      its('uids') { should eq [1234] }
+      its('gids') { should eq [1234] }
+    end
+
+where
+
+* `gid`, `group`, `groups`, `home`, `maxdays`, `mindays`, `shell`, `uid`, and `warndays` are valid matchers for this resource
+* `where(uid: 0).entries` represents a filter that runs the test only against matching users
+
+For example:
+
+    describe users.where { username =~ /.*/ } do
+      it { should exist }
+    end
+
+or:
+
+    describe users.where { uid =~ /^S-1-5-[0-9-]+-501$/ } do
+      it { should exist }
+    end
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## exist
+
+The `exist` matcher tests if the named user exists:
+
+    it { should exist }
+
+## gid
+
+The `gid` matcher tests the group identifier:
+
+    its('gid') { should eq 1234 } }
+
+where `1234` represents the user identifier.
+
+## group
+
+The `group` matcher tests the group to which the user belongs:
+
+    its('group') { should eq 'root' }
+
+where `root` represents the group.
+
+## groups
+
+The `groups` matcher tests two (or more) groups to which the user belongs:
+
+    its('groups') { should eq ['root', 'other']}
+
+## home
+
+The `home` matcher tests the home directory path for the user:
+
+    its('home') { should eq '/root' }
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+## maxdays
+
+The `maxdays` matcher tests the maximum number of days between password changes:
+
+    its('maxdays') { should eq 99 }
+
+where `99` represents the maximum number of days.
+
+## mindays
+
+The `mindays` matcher tests the minimum number of days between password changes:
+
+    its('mindays') { should eq 0 }
+
+where `0` represents the maximum number of days.
+
+## shell
+
+The `shell` matcher tests the path to the default shell for the user:
+
+    its('shell') { should eq '/bin/bash' }
+
+## uid
+
+The `uid` matcher tests the user identifier:
+
+    its('uid') { should eq 1234 } }
+
+where `1234` represents the user identifier.
+
+## warndays
+
+The `warndays` matcher tests the number of days a user is warned before a password must be changed:
+
+    its('warndays') { should eq 5 }
+
+where `5` represents the number of days a user is warned.
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Use a regular expression to find users
+
+    describe users.where { uid =~ /S\-1\-5\-21\-\d+\-\d+\-\d+\-500/ } do
+      it { should exist }
+    end

data/docs/resources/vbscript.md.erb

@@ -0,0 +1,69 @@
+---
+title: About the vbscript Resource
+---
+
+# vbscript
+
+Use the `vbscript` InSpec audit resource to test a VBScript on the Windows platform.
+
+# Syntax
+
+A `vbscript` resource block tests the output of a VBScript on the Windows platform:
+
+    describe vbscript('script_name') do
+      its('stdout') { should eq 'output' }
+    end
+
+where
+
+* `'script_name'` is the name of the VBScript to test
+* `('output')` is the expected output of the VBScript
+
+
+# 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" %>
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test a VBScript
+
+A VBScript file similar to:
+
+    vbscript = <<-EOH
+      WScript.Echo "hello"
+    EOH
+
+may be tested for multiple lines:
+
+    describe vbscript(vbscript) do
+      its('stdout') { should eq "hello\r\n" }
+    end
+
+and tested for whitespace removal from standard output:
+
+    describe vbscript(vbscript) do
+      its('strip') { should eq "hello" }
+    end

data/docs/resources/windows_feature.md.erb

@@ -0,0 +1,61 @@
+---
+title: About the windows_feature Resource
+---
+
+# windows_feature
+
+Use the `windows_feature` InSpec audit resource to test features on Windows via the `Get-WindowsFeature` cmdlet.
+
+# Syntax
+
+A `windows_feature` resource block declares the name of the Windows feature, tests if that feature is installed, and then returns information about that feature:
+
+    describe windows_feature('feature_name') do
+      it { should be_installed }
+    end
+
+where
+
+* `('feature_name')` must specify a Windows feature name, such as `DHCP Server` or `IIS-Webserver`
+* `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 Windows feature is installed:
+
+    it { should be_installed }
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test the DHCP Server feature
+
+    describe windows_feature('DHCP Server') do
+      it{ should be_installed }
+    end

data/docs/resources/wmi.md.erb

@@ -0,0 +1,95 @@
+---
+title: About the wmi Resource
+---
+
+# wmi
+
+Use the `wmi` InSpec audit resource to test WMI settings on the Windows platform.
+
+# Syntax
+
+A `wmi` resource block tests WMI settings on the Windows platform:
+
+    describe wmi({
+      class: 'class_name'
+      namespace: 'path\\to\\setting'
+      filter: 'filter'
+      query: 'query'
+    }) do
+      its('setting_name') { should eq '' }
+    end
+
+where
+
+* `class`, `namespace`, `filter`, and `query` comprise a Ruby Hash of the WMI object
+* `('class')` is the WMI class to which the setting belongs, such as `win32_service`
+* `('namespace')` is path to that object, such as `root\\cimv2`
+* Use `('filter')` fine-tune the information defined by the WMI class, such as to find a specific service (`filter: "name like '%winrm%'")`, to find a specific setting (`filter: 'KeyName = \'MinimumPasswordAge\' And precedence=1'`), and so on
+* Use `('query')` to run a query that returns data to be tested, such as `"SELECT Setting FROM RSOP_SecuritySettingBoolean WHERE KeyName='LSAAnonymousNameLookup' AND Precedence=1"`
+* `('setting_name')` is a setting in the WMI object to be tested, and then `should eq ''` is the expected value for that setting
+
+For example, both of the following tests will verify if WinRM is present on the target node. The first tests if WinRM belongs to the list of services running under the `win32_service` class:
+
+    describe wmi({class: 'win32_service'}) do
+      its('DisplayName') { should include 'Windows Remote Management (WS-Management)'}
+    end
+
+and the second uses a filter in the Ruby Hash to first identify WinRM, and then perform additional tests:
+
+    describe wmi({
+      class: 'win32_service',
+      filter: "name like '%winrm%'"
+    }) do
+      its('Status') { should cmp 'ok' }
+      its('State') { should cmp 'Running' }
+      its('ExitCode') { should cmp 0 }
+      its('DisplayName') { should eq 'Windows Remote Management (WS-Management)'}
+    end
+
+
+# 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" %>
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test a password expiration policy
+
+    describe wmi({
+      class: 'RSOP_SecuritySettingNumeric',
+      namespace: 'root\\rsop\\computer',
+      filter: 'KeyName = \'MinimumPasswordAge\' And precedence=1'
+    }) do
+       its('Setting') { should eq 1 }
+    end
+
+## Test if an anonymous user can query the Local Security Authority (LSA)
+
+    describe wmi({
+      namespace: 'root\rsop\computer',
+      query: "SELECT Setting FROM RSOP_SecuritySettingBoolean WHERE KeyName='LSAAnonymousNameLookup' AND Precedence=1"
+    }) do
+      its('Setting') { should eq false }
+    end