inspec-core 2.1.67

data/docs/resources/postgres_session.md.erb

@@ -0,0 +1,69 @@
+---
+title: About the postgres_session Resource
+platform: os
+---
+
+# postgres_session
+
+Use the `postgres_session` InSpec audit resource to test SQL commands run against a PostgreSQL database.
+
+<br>
+
+## Syntax
+
+A `postgres_session` resource block declares the username and password to use for the session, and then the command to be run:
+
+    # Create a PostgreSQL session:
+    sql = postgres_session('username', 'password', 'host')
+
+    # default values:
+    #   username: 'postgres'
+    #   host: 'localhost'
+
+    # Run an SQL query with an optional database to execute
+    sql.query('sql_query', ['database_name'])`
+
+A full example is:
+
+    sql = postgres_session('username', 'password', 'host')
+    describe sql.query('SELECT * FROM pg_shadow WHERE passwd IS NULL;') do
+      its('output') { should eq '' }
+    end
+
+where `its('output') { should eq '' }` compares the results of the query against the expected result in the test
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test the PostgreSQL shadow password
+
+    sql = postgres_session('my_user', 'password', '192.168.1.2')
+
+    describe sql.query('SELECT * FROM pg_shadow WHERE passwd IS NULL;', ['testdb']) do
+      its('output') { should eq('') }
+    end
+
+### Test for risky database entries
+
+    describe postgres_session('my_user', 'password').query('SELECT count (*)
+                  FROM pg_language
+                  WHERE lanpltrusted = \'f\'
+                  AND lanname!=\'internal\'
+                  AND lanname!=\'c\';', ['postgres']) do
+      its('output') { should eq '0' }
+    end
+
+<br>
+
+## Matchers
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### output
+
+The `output` matcher tests the results of the query:
+
+    its('output') { should eq(/^0/) }

data/docs/resources/powershell.md.erb

@@ -0,0 +1,102 @@
+---
+title: About the powershell Resource
+platform: windows
+---
+
+# powershell
+
+Use the `powershell` InSpec audit resource to test a Powershell script on the Windows platform.
+
+<br>
+
+## Syntax
+
+A `powershell` resource block declares a Powershell script to be tested, and then compares the output of that command to the matcher in the test:
+
+    script = <<-EOH
+      # a PowerShell script
+    EOH
+
+    describe powershell(script) do
+      its('property') { should eq 'output' }
+    end
+
+where
+
+* `'script'` must specify a Powershell script to be run
+* `'matcher'` is one of `exit_status`, `stderr`, or `stdout`
+* `'output'` tests the output of the command run on the system versus the output value stated in the test
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Get all groups of Administrator user
+
+    script = <<-EOH
+      # find user
+      $user = Get-WmiObject Win32_UserAccount -filter "Name = 'Administrator'"
+      # get related groups
+      $groups = $user.GetRelated('Win32_Group') | Select-Object -Property Caption, Domain, Name, LocalAccount, SID, SIDType, Status
+      $groups | ConvertTo-Json
+    EOH
+
+    describe powershell(script) do
+      its('stdout') { should_not eq '' }
+    end
+
+### Write-Output 'hello'
+
+The following Powershell script:
+
+    script = <<-EOH
+      Write-Output 'hello'
+    EOH
+
+can be tested in the following ways.
+
+For a newline:
+
+    describe powershell(script) do
+      its('stdout') { should eq "hello\r\n" }
+      its('stderr') { should eq '' }
+    end
+
+Removing whitespace `\r\n` from `stdout`:
+
+    describe powershell(script) do
+      its('strip') { should eq "hello" }
+    end
+
+No newline:
+
+    describe powershell("'hello' | Write-Host -NoNewLine") do
+      its('stdout') { should eq 'hello' }
+      its('stderr') { should eq '' }
+    end
+
+<br>
+
+## Matchers
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### exit_status
+
+The `exit_status` matcher tests the exit status for the command:
+
+    its('exit_status') { should eq 123 }
+
+### stderr
+
+The `stderr` matcher tests results of the command as returned in standard error (stderr):
+
+    its('stderr') { should eq 'error' }
+
+### stdout
+
+The `stdout` matcher tests results of the command as returned in standard output (stdout):
+
+    its('stdout') { should eq '/^1$/' }

data/docs/resources/processes.md.erb

@@ -0,0 +1,109 @@
+---
+title: About the processes Resource
+platform: os
+---
+
+# processes
+
+Use the `processes` InSpec audit resource to test properties for programs that are running on the system.
+
+<br>
+
+## 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. If left blank, all processes will be returned.
+* `property_name` may be used to test user (`its('users')`) and state properties (`its('states')`)
+
+<br>
+
+## 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 specific 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|
+
+<br>
+
+## Matchers
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### property_name
+
+The `property_name` matcher tests the named property for the specified value:
+
+    its('property_name') { should eq ['property_value'] }

data/docs/resources/rabbitmq_config.md.erb

@@ -0,0 +1,41 @@
+---
+title: About the rabbitmq_config Resource
+platform: linux
+---
+
+# 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.
+
+<br>
+
+## 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
+
+<br>
+
+## 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
+
+<br>
+
+## Matchers
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).

data/docs/resources/registry_key.md.erb

@@ -0,0 +1,158 @@
+---
+title: About the registry_key Resource
+platform: windows
+---
+
+# registry_key
+
+Use the `registry_key` InSpec audit resource to test key values in the Windows registry.
+
+<br>
+
+## 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.
+
+Use a registry key name and path:
+
+    describe registry_key('Task Scheduler','HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\Schedule') do
+      its('Start') { should eq 2 }
+    end
+
+Use only a registry key path:
+
+    describe registry_key('Task Scheduler','HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\Schedule') do
+      its('Start') { should eq 2 }
+    end
+
+Or use a Ruby Hash:
+
+    describe registry_key({
+      name: 'Task Scheduler',
+      hive: 'HKEY_LOCAL_MACHINE',
+      key: '\SYSTEM\CurrentControlSet\services\Schedule'
+    }) do
+      its('Start') { should eq 2 }
+    end
+
+
+### 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:
+
+    HKCU\SOFTWARE\Policies\Microsoft\Windows\CurrentVersion\Themes
+
+may be enclosed in a single-quoted string with a single backslash:
+
+    'HKCU\SOFTWARE\path\to\key\Themes'
+
+or may be enclosed in a double-quoted string with an extra backslash as an escape character:
+
+    "HKCU\\SOFTWARE\\path\\to\\key\\Themes"
+
+
+<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
+
+<br>
+
+## Examples
+
+The following examples show how to use this InSpec audit resource.
+
+### Test the start time for the Schedule service
+
+    describe registry_key('Task Scheduler','HKEY_LOCAL_MACHINE\...\Schedule') do
+      its('Start') { should eq 2 }
+    end
+
+where `'HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\services\Schedule'` is the full path to the setting.
+
+### Use a regular expression in responses
+
+    describe registry_key({
+      hive: 'HKEY_LOCAL_MACHINE',
+      key: 'SOFTWARE\Microsoft\Windows NT\CurrentVersion'
+    }) do
+      its('ProductName') { should match /^[a-zA-Z0-9\(\)\s]*2012\s[rR]2[a-zA-Z0-9\(\)\s]*$/ }
+    end
+
+<br>
+
+## Matchers
+
+For a full list of available matchers, please visit our [matchers page](https://www.inspec.io/docs/reference/matchers/).
+
+### children
+
+The `children` matcher return all of the child items of a registry key. A regular expression may be used to filter child items:
+
+    describe registry_key('Key Name', '\path\to\key').children(regex)
+      ...
+    end
+
+For example, to get all child items for a registry key:
+
+    describe registry_key('Task Scheduler','HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet').children do
+      it { should_not eq [] }
+    end
+
+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|
+        describe registry_key(key) do
+          its('AlwaysInstallElevated') { should eq 'value' }
+        end
+      }
+
+### exist
+
+The `exist` matcher tests if the registry key is present:
+
+    it { should exist }
+
+### have_property
+
+The `have_property` matcher tests if a property exists for a registry key:
+
+    it { should 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
+
+The `have_value` matcher tests if a value exists for a registry key:
+
+    it { should have_value 'value' }
+
+### name
+
+The `name` matcher tests the value for the specified registry setting:
+
+    its('name') { should eq 'value' }
+
+
+<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') }