inspec 0.34.1 → 1.0.0

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

data/docs/resources/xinetd_conf.md.erb

@@ -0,0 +1,170 @@
+---
+title: About the xinetd_conf Resource
+---
+
+# xinetd_conf
+
+Use the `xinetd_conf` InSpec audit resource to test services under `/etc/xinet.d` on Linux and Unix platforms. xinetd---the extended Internet service daemon---listens on all ports, and then loads the appropriate program based on a request. The `xinetd.conf` file is typically located at `/etc/xinetd.conf` and contains a list of Internet services associated to the ports on which that service will listen. Only enabled services may handle a request; only services that are required by the system should be enabled.
+
+# Syntax
+
+An `xinetd_conf` resource block declares settings found in a `xinetd.conf` file for the named service:
+
+    describe xinetd_conf('service_name') do
+      it { should be_enabled } # or be_disabled
+      its('setting') { should eq 'value' }
+    end
+
+where
+
+* `'service_name'` is a service located under `/etc/xinet.d`
+* `('setting')` is a setting in the `xinetd.conf` file
+* `should eq 'value'` is the value that is expected
+
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## be_enabed
+
+The `be_enabled` matcher tests if a service listed under `/etc/xinet.d` is enabled:
+
+    it { should be_enabled }
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## ids
+
+The `ids` matcher tests if the named service is located under `/etc/xinet.d`:
+
+    its('ids') { should include 'service_name' }
+
+For example:
+
+    its('ids') { should include 'chargen-stream chargen-dgram'}
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+## services
+
+The `services` matcher tests if the named service is listed under `/etc/xinet.d`:
+
+    its('services') { should include 'service_name' }
+
+## socket_types
+
+The `socket_types` matcher tests if a service listed under `/etc/xinet.d` is configured to use the named socket type:
+
+    its('socket_types') { should eq 'socket' }
+
+where `socket` is one of `dgram`, `raw`, or `stream`. For a UDP-based service:
+
+    its('socket_types') { should eq 'dgram' }
+
+For a raw socket (such as a service using a non-standard protocol or a service that requires direct access to IP):
+
+    its('socket_types') { should eq 'raw' }
+
+For a TCP-based service:
+
+    its('socket_types') { should eq 'stream' }
+
+## types
+
+The `types` matcher tests the service type:
+
+    its('type') { should eq 'TYPE' }
+
+where `'TYPE'` is `INTERNAL` (for a service provided by xinetd), `RPC` (for a service based on remote procedure call), or `UNLISTED` (for services not under `/etc/services` or `/etc/rpc`).
+
+## wait
+
+The `wait` matcher tests how a service handles incoming connections.
+
+For UDP (`dgram`) socket types the `wait` matcher should test for `yes`:
+
+    its('socket_types') { should eq 'dgram' }
+    its('wait') { should eq 'yes' }
+
+For TCP (`stream`) socket types the `wait` matcher should test for `no`:
+
+    its('socket_types') { should eq 'stream' }
+    its('wait') { should eq 'no' }
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test a socket_type
+
+The network socket type: `dgram` (a datagram-based service), `raw` (a service that requires direct access to an IP address), `stream` (a stream-based service), or `seqpacket` (a service that requires a sequenced packet).
+
+    describe xinetd_conf.services('service_name') do
+       its('socket_types') { should include 'dgram' }
+    end
+
+## Test a service type
+
+The type of service: `INTERNAL` (a service provided by xinetd), `RPC` (an RPC-based service), `TCPMUX` (a service that is started on a well-known TPCMUX port), or `UNLISTED` (a service that is not listed in a standard system file location).
+
+    describe xinetd_conf.services('service_name') do
+       its('type') { should include 'RPC' }
+    end
+
+## Test the telnet service
+
+For example, a `telnet` file under `/etc/xinet.d` contains the following settings:
+
+    service telnet
+    {
+      disable         = yes
+      flags           = REUSE
+      socket_type     = stream
+      wait            = no
+      user            = root
+      server          = /usr/sbin/in.telnetd
+      log_on_failure  += USERID
+    }
+
+Some examples of tests that can be run against that file include:
+
+    describe xinetd_conf.services('telnet') do
+      it { should be_disabled }
+    end
+
+and
+
+    describe xinetd_conf.services('telnet') do
+      its('socket_type') { should include 'stream' }
+    end
+
+and
+
+    describe xinetd_conf.services('telnet') do
+      its('wait') { should eq 'no' }
+    end
+
+All three settings can be tested in the same block as well:
+
+    describe xinetd_conf.services('telnet') do
+      it { should be_disabled }
+      its('socket_type') { should include 'stream' }
+      its('wait') { should eq 'no' }
+    end

data/docs/resources/yaml.md.erb

@@ -0,0 +1,69 @@
+---
+title: About the yaml Resource
+---
+
+# yaml
+
+Use the `yaml` InSpec audit resource to test configuration data in a Yaml file.
+
+# Syntax
+
+A `yaml` resource block declares the configuration data to be tested. Assume the following Yaml file:
+
+    name: foo
+    array:
+      - zero
+      - one
+
+This file can be queried using:
+
+    describe yaml do
+      its('name') { should eq 'foo' }
+      its(['array', 1]) { should eq 'one' }
+    end
+
+where
+
+* `name` is a configuration setting in a Yaml file
+* `should eq 'foo'` tests a value of `name` as read from a Yaml 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 Yaml 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 kitchen.yml file driver
+
+    describe yaml('.kitchen.yaml') do
+      its('driver.name') { should eq('vagrant') }
+    end

data/docs/resources/yum.md.erb

@@ -0,0 +1,103 @@
+---
+title: About the yum Resource
+---
+
+# yum
+
+Use the `yum` InSpec audit resource to test packages in the Yum repository.
+
+# Syntax
+
+A `yum` resource block declares a package repo, tests if the package repository is present, and if it that package repository is a valid package source (i.e. "is enabled"):
+
+    describe yum.repo('name') do
+      it { should exist }
+      it { should be_enabled }
+    end
+
+where
+
+* `repo('name')` is the (optional) name of a package repo, using either a full identifier (`'updates/7/x86_64'`) or a short identifier (`'updates'`)
+
+# Matchers
+
+This InSpec audit resource has the following matchers:
+
+## be
+
+<%= partial "/shared/matcher_be" %>
+
+## be_enabled
+
+The `be_enabled` matcher tests if the package repository is a valid package source:
+
+    it { should be_enabled }
+
+## cmp
+
+<%= partial "/shared/matcher_cmp" %>
+
+## eq
+
+<%= partial "/shared/matcher_eq" %>
+
+## exist
+
+The `exist` matcher tests if the package repository exists:
+
+    it { should exist }
+
+## include
+
+<%= partial "/shared/matcher_include" %>
+
+## match
+
+<%= partial "/shared/matcher_match" %>
+
+## repo('name')
+
+The `repo('name')` matcher names a specific package repository:
+
+    describe yum.repo('epel') do
+      ...
+    end
+
+## repos
+
+The `repos` matcher tests if a named repo, using either a full identifier (`'updates/7/x86_64'`) or a short identifier (`'updates'`), is included in the Yum repo:
+
+    its('repos') { should include 'some_repo' }
+
+## shortname
+
+The `shortname` matcher names a specific package repository's group identifier. For example, if a repository's group name is "Directory Server", the corresponding group idenfier is typically "directory-server":
+
+    describe yum.repo('Directory Server') do
+      its('shortname') { should eq 'directory-server' }
+    end
+
+# Examples
+
+The following examples show how to use this InSpec audit resource.
+
+## Test if the yum repo exists
+
+    describe yum do
+      its('repos') { should exist }
+    end
+
+## Test if the 'base/7/x86_64' repo exists and is enabled
+
+    describe yum do
+      its('repos') { should include 'base/7/x86_64' }
+      its('epel') { should exist }
+      its('epel') { should be_enabled }
+    end
+
+## Test if a specific yum repo exists
+
+    describe yum.repo('epel') do
+      it { should exist }
+      it { should be_enabled }
+    end