inspec 1.0.0 → 1.35.1

data/docs/resources/processes.md.erb

@@ -0,0 +1,123 @@
+---
+title: About the processes Resource
+---
+
+# processes
+
+Use the `processes` InSpec audit resource to test properties for programs that are running on the system.
+
+## Syntax
+
+A `processes` resource block declares the name of the process to be tested, and then declares one (or more) property/value pairs:
+
+    describe processes('process_name') do
+      its('property_name') { should eq ['property_value'] }
+    end
+
+where
+
+* `processes('process_name')` specifies the name of a process to check. If this is a string, it will be converted to a Regexp. For more specificity, pass a Regexp directly.
+* `property_name` may be used to test user (`its('users')`) and state properties (`its('states')`)
+
+
+## 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" %>
+
+### property_name
+
+The `property_name` matcher tests the named property for the specified value:
+
+    its('property_name') { should eq ['property_value'] }
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test if the list length for the mysqld process is 1
+
+    describe processes('mysqld') do
+      its('list.length') { should eq 1 }
+    end
+
+### Test if the process is owned by a specifc user
+
+    describe processes('init') do
+      its('users') { should eq ['root'] }
+    end
+
+    describe processes('winlogon') do
+      its('users') { should cmp "NT AUTHORITY\\SYSTEM" }
+    end
+
+
+### Test if a high-priority process is running
+
+    describe processes('linux_process') do
+      its('states') { should eq ['R<'] }
+    end
+
+    describe processes('windows_process') do
+      its('labels') { should cmp "High" }
+    end
+
+### Test if a process exists on the system
+
+    describe processes('some_process') do
+      it { should exist }
+    end
+
+### Test for a process using a specific Regexp
+
+If the process name is too common for a string to uniquely find it,
+you may use a regexp. Inclusion of whitespace characters may be
+needed.
+
+    describe processes(Regexp.new("/usr/local/bin/swap -d")) do
+      its('list.length') { should eq 1 }
+    end
+
+### Notes for auditing Windows systems
+
+Sometimes with system properties there isn't a direct comparison between different operating systems.
+Most of the `property_name`'s do align between the different OS's.  
+
+There are however some exception's, for example, within linux `states` offers multiple properties. 
+Windows doesn't have direct comparison that is a single property so instead `states` is mapped to the property of `Responding`, This is a boolean true/false flag to help determine if the process is hung.
+
+Below is a mapping table to help you understand what property the unix field maps to the windows `Get-Process` Property
+
+| *unix ps field* | *windows PowerShell Property* |
+|:---------------:|:-----------------------------:|
+|labels           |PriorityClass|
+|pids             |Id|
+|cpus             |CPU|
+|mem              |PM|
+|vsz              |VirtualMemorySize|
+|rss              |NPM|
+|tty              |SessionId|
+|states           |Responding|
+|start            |StartTime|
+|time             |TotalProcessorTime|
+|users            |UserName|
+|commands         |Path|

data/docs/resources/rabbitmq_config.md.erb

@@ -0,0 +1,55 @@
+---
+title: About the rabbitmq_config Resource
+---
+
+# rabbitmq_config
+
+Use the `rabbitmq_config` InSpec audit resource to test configuration data for the RabbitMQ daemon located at `/etc/rabbitmq/rabbitmq.config` on Linux and Unix platforms.
+
+## Syntax
+
+A `rabbitmq_config` resource block declares the RabbitMQ configuration data to be tested:
+
+    describe rabbitmq_config.params('rabbit', 'ssl_listeners') do
+      it { should cmp 5671 }
+    end
+
+where
+
+* `params` is the list of parameters configured in the RabbitMQ config file
+* `{ should cmp 5671 }` tests the value of `rabbit.ssl_listeners` as read from `rabbitmq.config` 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" %>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test the list of TCP listeners
+
+    describe rabbitmq_config.params('rabbit', 'tcp_listeners') do
+      it { should eq [5672] }
+    end

data/docs/resources/registry_key.md.erb

@@ -6,7 +6,7 @@ title: About the registry_key Resource
 
 Use the `registry_key` InSpec audit resource to test key values in the Windows registry.
 
-# Syntax
+## Syntax
 
 A `registry_key` resource block declares the item in the Windows registry, the path to a setting under that item, and then one (or more) name/value pairs to be tested.
 
@@ -27,13 +27,13 @@ Or use a Ruby Hash:
     describe registry_key({
       name: 'Task Scheduler',
       hive: 'HKEY_LOCAL_MACHINE',
-      key: ''\SYSTEM\CurrentControlSet\services\Schedule'
+      key: '\SYSTEM\CurrentControlSet\services\Schedule'
     }) do
       its('Start') { should eq 2 }
     end
 
 
-## Registry Key Path Separators
+### Registry Key Path Separators
 
 A Windows registry key can be used as a string in Ruby code, such as when a registry key is used as the name of a recipe. In Ruby, when a registry key is enclosed in a double-quoted string (`" "`), the same backslash character (`\`) that is used to define the registry key path separator is also used in Ruby to define an escape character. Therefore, the registry key path separators must be escaped when they are enclosed in a double-quoted string. For example, the following registry key:
 
@@ -48,15 +48,28 @@ or may be enclosed in a double-quoted string with an extra backslash as an escap
     "HKCU\\SOFTWARE\\path\\to\\key\\Themes"
 
 
-# Matchers
+<p class="warning">
+Please make sure that you use backslashes instead of forward slashes. Forward slashes will not work for registry keys.
+</p>
+
+    # The following will not work:
+    # describe registry_key('HKLM/SOFTWARE/Microsoft/NET Framework Setup/NDP/v4/Full/1033') do
+    #   its('Release') { should eq 378675 }
+    # end
+    # You should use:
+    describe registry_key('HKLM\SOFTWARE\Microsoft\NET Framework Setup\NDP\v4\Full\1033') do
+      its('Release') { should eq 378675 }
+    end
+
+## Matchers
 
 This InSpec audit resource has the following matchers:
 
-## be
+### be
 
 <%= partial "/shared/matcher_be" %>
 
-## children
+### children
 
 The `children` matcher return all of the child items of a registry key. A regular expression may be used to filter child items:
 
@@ -73,65 +86,75 @@ For example, to get all child items for a registry key:
 The following example shows how find a property that may exist against multiple registry keys, and then test that property for every registry key in which that property is located:
 
     describe registry_key({
-      hive: HKEY_USERS
-    }).children(/^S-1-5-21-[0-9]+-[0-9]+-[0-9]+-[0-9]{3,}\\Software\\Policies\\Microsoft\\Windows\\Installer/).each
-      { |key|
+      hive: 'HKEY_USERS'
+    }).children(/^S-1-5-21-[0-9]+-[0-9]+-[0-9]+-[0-9]{3,}\\Software\\Policies\\Microsoft\\Windows\\Installer/).each { |key|
         describe registry_key(key) do
           its('AlwaysInstallElevated') { should eq 'value' }
         end
       }
 
-## cmp
+### cmp
 
 <%= partial "/shared/matcher_cmp" %>
 
-## eq
+### eq
 
 <%= partial "/shared/matcher_eq" %>
 
-## exist
+### exist
 
 The `exist` matcher tests if the registry key is present:
 
     it { should exist }
 
-## have_property
+### have_property
 
 The `have_property` matcher tests if a property exists for a registry key:
 
     it { should have_property 'value' }
 
-## have_property_value
+### have\_property\_value
 
 The `have_property_value` matcher tests if a property value exists for a registry key:
 
     it { should have_property_value 'value' }
 
-## have_value
+### have_value
 
 The `have_value` matcher tests if a value exists for a registry key:
 
     it { should have_value 'value' }
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-## name
+### name
 
 The `name` matcher tests the value for the specified registry setting:
 
     its('name') { should eq 'value' }
 
-# Examples
+
+<p class="warning">
+Any name with a dot will not work as expected: <code>its('explorer.exe') { should eq 'test' }</code>. This issue is tracked in <a href="https://github.com/chef/inspec/issues/1281">https://github.com/chef/inspec/issues/1281</a>
+</p>
+
+    # instead of:
+    # its('explorer.exe') { should eq 'test' }
+    # use the following solution:
+    it { should have_property_value('explorer.exe', :string, 'test') }
+
+
+## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-## Test the start time for the Schedule service
+### Test the start time for the Schedule service
 
     describe registry_key('Task Scheduler','HKEY_LOCAL_MACHINE\...\Schedule') do
       its('Start') { should eq 2 }
@@ -139,7 +162,7 @@ The following examples show how to use this InSpec audit resource.
 
 where `'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\Schedule'` is the full path to the setting.
 
-## Use a regular expression in responses
+### Use a regular expression in responses
 
     describe registry_key({
       hive: 'HKEY_LOCAL_MACHINE',

data/docs/resources/runit_service.md.erb

@@ -6,7 +6,7 @@ title: About the runit_service Resource
 
 Use the `runit_service` InSpec audit resource to test a service using runit.
 
-# Syntax
+## Syntax
 
 A `runit_service` resource block declares the name of a service and then one (or more) matchers to test the state of the service:
 
@@ -29,48 +29,48 @@ The path to the service manager's control may be specified for situations where
       it { should be_running }
     end
 
-# Matchers
+## Matchers
 
 This InSpec audit resource has the following matchers:
 
-## be
+### be
 
 <%= partial "/shared/matcher_be" %>
 
-## be_enabled
+### be_enabled
 
 The `be_enabled` matcher tests if the named service is enabled:
 
     it { should be_enabled }
 
-## be_installed
+### be_installed
 
 The `be_installed` matcher tests if the named service is installed:
 
     it { should be_installed }
 
-## be_running
+### be_running
 
 The `be_running` matcher tests if the named service is running:
 
     it { should be_running }
 
-## cmp
+### cmp
 
 <%= partial "/shared/matcher_cmp" %>
 
-## eq
+### eq
 
 <%= partial "/shared/matcher_eq" %>
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-# Examples
+## Examples
 
 None.

data/docs/resources/security_policy.md.erb

@@ -6,7 +6,7 @@ title: About the security_policy Resource
 
 Use the `security_policy` InSpec audit resource to test security policies on the Windows platform.
 
-# Syntax
+## Syntax
 
 A `security_policy` resource block declares the name of a security policy and the value to be tested:
 
@@ -20,41 +20,41 @@ where
 * `{ should eq 'value' }` tests the value of `policy_name` against the value declared in the test
 
 
-# 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" %>
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-## policy_name
+### policy_name
 
 The `policy_name` matcher must be the name of a security policy:
 
     its('SeNetworkLogonRight') { should eq '*S-1-5-11' }
 
-# Examples
+## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-## Verify that only the Administrators group has remote access
+### Verify that only the Administrators group has remote access
 
     describe security_policy do
       its('SeRemoteInteractiveLogonRight') { should eq '*S-1-5-32-544' }

data/docs/resources/service.md.erb

@@ -6,9 +6,9 @@ title: About the service Resource
 
 Use the `service` InSpec audit resource to test if the named service is installed, running and/or enabled.
 
-Under some circumstances, it may be necessary to specify the service manager by using one of the following service manager-specific resources: `bsd_service`, `launchd_service`, `runit_service`, `systemd_service`, `sysv_service`, oe `upstart_service`. These resources are based on the `service` resource.
+Under some circumstances, it may be necessary to specify the service manager by using one of the following service manager-specific resources: `bsd_service`, `launchd_service`, `runit_service`, `systemd_service`, `sysv_service`, or `upstart_service`. These resources are based on the `service` resource.
 
-# Syntax
+## Syntax
 
 A `service` resource block declares the name of a service and then one (or more) matchers to test the state of the service:
 
@@ -24,67 +24,67 @@ where
 * `be_installed`, `be_enabled`, and `be_running` are valid matchers for this resource
 
 
-# Matchers
+## Matchers
 
 This InSpec audit resource has the following matchers:
 
-## be
+### be
 
 <%= partial "/shared/matcher_be" %>
 
-## be_enabled
+### be_enabled
 
 The `be_enabled` matcher tests if the named service is enabled:
 
     it { should be_enabled }
 
-## be_installed
+### be_installed
 
 The `be_installed` matcher tests if the named service is installed:
 
     it { should be_installed }
 
-## be_running
+### be_running
 
 The `be_running` matcher tests if the named service is running:
 
     it { should be_running }
 
-## cmp
+### cmp
 
 <%= partial "/shared/matcher_cmp" %>
 
-## eq
+### eq
 
 <%= partial "/shared/matcher_eq" %>
 
-## include
+### include
 
 <%= partial "/shared/matcher_include" %>
 
-## match
+### match
 
 <%= partial "/shared/matcher_match" %>
 
-# Examples
+## Examples
 
 The following examples show how to use this InSpec audit resource.
 
-## Test if the postgresql service is both running and enabled
+### Test if the postgresql service is both running and enabled
 
     describe service('postgresql') do
       it { should be_enabled }
       it { should be_running }
     end
 
-## Test if the mysql service is both running and enabled
+### Test if the mysql service is both running and enabled
 
     describe service('mysqld') do
       it { should be_enabled }
       it { should be_running }
     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 }
@@ -97,7 +97,7 @@ The following examples show how to use this InSpec audit resource.
       it { should_not be_running }
     end
 
-## Test Unix System V run levels
+### Test Unix System V run levels
 
 On targets that are using SystemV services, the existing run levels can also be checked:
 
@@ -109,7 +109,7 @@ On targets that are using SystemV services, the existing run levels can also be
       it { should be_enabled }
     end
 
-## Override the service manager
+### Override the service manager
 
 Under some circumstances, it may be required to override the logic in place to select the right service manager. For example, to check a service managed by Upstart:
 
@@ -127,7 +127,7 @@ This is also possible with `systemd_service`, `runit_service`, `sysv_service`, `
       it { should be_running }
     end
 
-## Verify that IIS is running
+### Verify that IIS is running
 
     describe service('W3SVC') do
       it { should be_installed }